Pie Chart

A pie chart shows how parts contribute to a whole, such as market share or the distribution of storage usage. In ESP-DASH v5, pie charts are created with the dash::PieChart<X, Y> class template, where X is the label type and Y is the value type.

In a pie chart, the X-axis holds the segment labels and the Y-axis holds the segment values. Labels are set with setX() and values with setY().

ConstructorCopy Anchor Link

dash::PieChart<X, Y> chart(ESPDash& dashboard, const char* name);
dash::PieChart<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

// Text labels, integer values
dash::PieChart<const char*, int> share(dashboard, "Market Share");

// Numeric labels, floating-point values
dash::PieChart<int, float> distribution(dashboard, "Distribution");

MethodsCopy Anchor Link

setXCopy Anchor Link

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

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

const char* products[] = {"A", "B", "C"};
share.setX(products, 3);

setYCopy Anchor Link

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

Sets the segment values. Each value is drawn in proportion to the sum of all values. The element type of arr_y must match the template parameter Y. The chart stores a pointer to the array and marks the values as changed; the data is sent on the next call to dashboard.sendUpdates(). Always returns true.

int shares[] = {40, 30, 30};
share.setY(shares, 3);

x and yCopy Anchor Link

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

Return a pointer to the current labels or values array, or nullptr if it has not been set.

const char* const* labels = share.x();
const int* values = share.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* Labels[] = {"A", "B", "C"};
int Values[] = {40, 30, 30};

dash::PieChart<const char*, int> share(dashboard, "Market Share");

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());

  share.setX(Labels, 3);
  share.setY(Values, 3);

  server.begin();
}

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

    for (int i = 0; i < 3; i++) {
      Values[i] = (int)random(10, 50);
    }

    // Mark the values as changed, then push the update to all clients
    share.setY(Values, 3);
    dashboard.sendUpdates();
  }
}

NotesCopy Anchor Link

• Data lifetime. Charts do not copy labels or values. 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.