Area Chart

An area chart is a line chart with the region below the line filled, which emphasizes magnitude and cumulative totals over time or across categories. In ESP-DASH v5, area charts are created with the dash::AreaChart<X, Y> class template, where X and Y define the data types of the two axes.

ConstructorCopy Anchor Link

dash::AreaChart<X, Y> chart(ESPDash& dashboard, const char* name);
dash::AreaChart<X, Y> chart(const char* name);

The first form creates the chart and adds it to dashboard. The second form creates the chart without adding it to a dashboard; add it later with dashboard.add(chart).

Template parametersCopy Anchor Link

dash::string is an alias for Arduino String, or for std::string when DASH_USE_STL_STRING is defined. Any other type for X or Y fails to compile.

Constructor parametersCopy Anchor Link

// Category labels on the X-axis, integer values on the Y-axis
dash::AreaChart<const char*, int> rainfall(dashboard, "Cumulative Rainfall");

// Numeric X-axis, floating-point Y-axis
dash::AreaChart<int, float> growth(dashboard, "Growth");

MethodsCopy Anchor Link

setXCopy Anchor Link

bool setX(X arr_x[], size_t x_size);

Sets the X-axis data. The element type of arr_x must match the template parameter X. The chart stores a pointer to the array and marks the X-axis as changed; the data is sent on the next call to dashboard.sendUpdates(). Always returns true.

const char* months[] = {"Jan", "Feb", "Mar", "Apr"};
rainfall.setX(months, 4);

setYCopy Anchor Link

bool setY(Y arr_y[], size_t y_size);

Sets the Y-axis data. The element type of arr_y must match the template parameter Y. The chart stores a pointer to the array and marks the Y-axis as changed; the data is sent on the next call to dashboard.sendUpdates(). Always returns true.

int totals[] = {10, 25, 40, 60};
rainfall.setY(totals, 4);

x and yCopy Anchor Link

const X* x() const;
const Y* y() const;

Return a pointer to the current X-axis or Y-axis array, or nullptr if it has not been set.

const int* current = rainfall.y();

xSize and ySizeCopy Anchor Link

size_t xSize() const;
size_t ySize() const;

Return the number of elements passed to the last setX() or setY() call, or 0 if it has not been set.

setNameCopy Anchor Link

bool setName(const char* name);

Changes the chart title. Returns false if the new title is identical to the current one; otherwise marks the title as changed and returns true. As with the constructor, the pointer is stored and must remain valid.

ExampleCopy Anchor Link

#include <Arduino.h>
#include <WiFi.h>
#include <AsyncTCP.h>
#include <ESPAsyncWebServer.h>
#include <ESPDashPro.h>

const char* ssid = "";
const char* password = "";

AsyncWebServer server(80);
ESPDash dashboard(server);

// Chart data must outlive the chart, so it is declared at global scope
const char* XAxis[] = {"Jan", "Feb", "Mar", "Apr"};
int YAxis[] = {10, 25, 40, 60};

dash::AreaChart<const char*, int> rainfall(dashboard, "Cumulative Rainfall");

void setup() {
  Serial.begin(115200);

  WiFi.mode(WIFI_STA);
  WiFi.begin(ssid, password);
  if (WiFi.waitForConnectResult() != WL_CONNECTED) {
    Serial.println("WiFi connection failed");
    return;
  }
  Serial.println(WiFi.localIP());

  rainfall.setX(XAxis, 4);
  rainfall.setY(YAxis, 4);

  server.begin();
}

void loop() {
  static unsigned long lastUpdate = 0;
  if (millis() - lastUpdate >= 5000) {
    lastUpdate = millis();

    // Add new rainfall to the latest month
    YAxis[3] += (int)random(0, 5);

    // Mark the Y-axis as changed, then push the update to all clients
    rainfall.setY(YAxis, 4);
    dashboard.sendUpdates();
  }
}

NotesCopy Anchor Link

• Data lifetime. Charts do not copy axis data. setX() and setY() store a pointer to your array, and the array is read each time the chart is serialized for a client. Declare the arrays at global scope or as static, never as local variables of the function that calls setX() or setY().
• Array constness. setX() and setY() take a non-const pointer, so the array elements themselves cannot be const (for example, const int values[] does not compile). An array of const char* labels is valid because the elements are pointers.
• Matching sizes. Pass the same number of elements to setX() and setY() so that each value has a corresponding label.
• Layout options. Charts also support setSize(), setIndex(), setDisplay() and assignment to tabs. To disable chart animations globally, see Toggle Chart Animations.