Ui builder
Generated
This page is generated by docs/site/scripts/gen-api.mjs from firmware/src/ui/Ui.h; descriptions and examples live in docs/site/scripts/api-notes.json.
face.ui() returns the default Ui; face.addUi("setup") creates another one that a transport can serve instead. Builder methods return a WidgetRef for chaining; widgets declared after page() belong to that page. The tables below are the overview from the firmware README; the sections that follow list every method.
Every method returns a WidgetRef for chaining. Widgets declared after page() belong to that page.
| Method | Widget | Value |
|---|---|---|
page(id, lbl) | page (tab) | – |
header(lbl) | header | – |
group(id, lbl) | group card; widgets join it via .group(id) | – |
row(id) | row; widgets join it via .row(id).size(w) | – |
spacer(id, w=1, h=8) | spacer | – |
label(id, lbl, unit=0) | label (output) | number or string |
button(id, lbl) | button; .hold() for press/release | onClick / onEvent(int) |
sw(id, lbl) | switch; .labels(on, off) | bool |
slider(id, lbl, min, max, step=1, unit=0) | slider | float |
number(id, lbl, min, max, step=1, unit=0) | number input; .spin() | float |
text(id, lbl, maxlen=64) | text input; .secret(), .regex(re) | string |
textarea(id, lbl, maxlen=256, rows=4) | multi-line text | string |
select(id, lbl, {opts}) | dropdown; .style("seg") | int index |
flags(id, lbl, {opts}) | checkbox set (max 32) | int bitmask |
color(id, lbl) | colour picker | int 0xRRGGBB |
datetime(id, lbl, mode="datetime") | date/time picker; .mode("date"|"time"|"datetime") | int unix seconds |
joystick(id, lbl) | joystick; .center(), .exp() | pair, onMove(x, y) each -100..100 |
dpad(id, lbl) | direction pad | onEvent(int): 'u' 'd' 'l' 'r' 'c' on press, 0 on release |
gauge(id, lbl, min, max, unit=0) | gauge (output); .style("arc"|"round"|"linear"), .zone(from, to, color) | float |
progress(id, lbl, min=0, max=100) | bar (output); .center() for bipolar | float |
display(id, lbl, digits=4, unit=0) | 7-segment readout (output) | number or string |
led(id, lbl, color=0) | LED (output); .rgb() makes the value a colour | bool, or int 0xRRGGBB with .rgb() |
chart(id, lbl, win=300, unit=0) | chart; .series(id, lbl, color), .style(), .legend(), .values() | face.push(chart, series, v) |
log(id, lbl, cap=200, rows=8) | log view | face.log(id, msg, color) |
table(id, lbl) | table (output); .column(lbl, w=1, align="left"), at least one | setRows(id, json) |
image(id, lbl, src) | image; prop(id).src(url) to change | – |
stream(id, lbl, src) | MJPEG stream | – |
clock(id, lbl, fmt=0) | clock (output); the library pushes the device time every minute | int unix seconds |
map(id, lbl, zoom=12) | map (output) | setPoints(id, json) |
textblock(id, text) | static paragraph | – |
add(WType, id, lbl=0) | any type, no defaults | per type |
Common chain modifiers: .group(id), .page(id), .row(id), .size(w, h=0), .square(), .disabled(), .readOnly(), .hint(text), .icon(name), .color(hex), .unit(u), .range(min, max), .step(s), .value(v), .persist() (NVS, restored before setup() returns), .bind(var) (two-way with a bool/int/float/String), .onChange(lambda) (argument type picks the conversion: bool, int, uint32_t, float, const String&, const Value&).
| Runtime call | Effect |
|---|---|
face.set(id, v) | update a value (bool, int, uint32_t, float, const char*); joystick: set(id, x, y) |
face.setRows(id, "[[\"Kitchen\",21.5],[\"Bath\",23]]") | table rows as a raw JSON array of rows |
face.setPoints(id, "[[52.52,13.4,\"Home\"]]") | map points [lat, lon, lbl] |
face.push(chart, series, v) | chart point |
face.log(msg) / face.log(id, msg, color) | log line, optionally to one log widget |
face.toast(lvl, msg) | info, warn, err toast on all clients |
face.ui().prop(id).label(..).color(..).src(..).min(..).disabled(..).visible(..).options({..}) | runtime prop change without rebuild |
face.ui().show(id, bool) | hide/show |
face.ui().confirm(id, msg, cb) / prompt(id, msg, cb, def) | dialogs on all clients, first answer wins |
face.ui().rebuild() | resend the UI after structural changes |
face.time() / face.setTime(unix) | unix time from NTP, the client clock or an RTC |
Builder
Each call appends one widget; ids must match ^[A-Za-z0-9_]{1,15}$ and be unique within the UI. A group, page or row must be declared before the widgets that reference it.
page
WidgetRef page(const char* id, const char* lbl)Starts a page (tab / bottom-nav entry); widgets declared afterwards belong to it until the next page().
ui.page("main", "Boiler").icon("home");
ui.page("setup", "Setup").icon("settings");header
WidgetRef header(const char* lbl)Section heading (no value).
ui.header("Boiler");group
WidgetRef group(const char* id, const char* lbl)Group card; widgets join it with .group(id). .fold() makes it collapsible.
ui.group("sensors", "Sensors").fold();
ui.gauge("temp", "Temp", 0, 120).group("sensors");row
WidgetRef row(const char* id)Row; widgets join it with .row(id).size(w) and sit side by side with relative widths.
ui.row("r1").group("control");
ui.sw("pump", "Pump").row("r1").size(1);
ui.slider("target", "Target", 20, 90).row("r1").size(3);spacer
WidgetRef spacer(const char* id, float w = 1, int h = 8)Empty space with relative width w and height h px.
| Argument | Type | Default | Meaning |
|---|---|---|---|
id | const char* | – | |
w | float | 1 | |
h | int | 8 |
ui.spacer("sp", 1, 16);label
WidgetRef label(const char* id, const char* lbl, const char* unit = nullptr)Read-only text or number; .fmt("%.1f") formats numbers.
| Argument | Type | Default | Meaning |
|---|---|---|---|
id | const char* | – | |
lbl | const char* | – | |
unit | const char* | nullptr |
ui.label("rssi", "Signal", "dBm").fmt("%d");
face.set("rssi", WiFi.RSSI());button
WidgetRef button(const char* id, const char* lbl)Button; onClick for a press, .hold() + onEvent for press (1) and release (0).
ui.button("reset", "Reset error").hint("Clears the error latch").onClick([] { err = 0; });
ui.button("horn", "Horn").hold().onEvent([](int v) { digitalWrite(HORN, v); });sw
WidgetRef sw(const char* id, const char* lbl)Switch (bool); .labels(on, off) sets state labels, .icon() without a label gives an icon-only toggle.
ui.sw("pump", "Pump").labels("ON", "OFF").onChange([](bool v) { digitalWrite(PUMP, v); });slider
WidgetRef slider(const char* id, const char* lbl, float min, float max, float step = 1, const char* unit = nullptr)Slider (float) with range, step and unit.
| Argument | Type | Default | Meaning |
|---|---|---|---|
id | const char* | – | |
lbl | const char* | – | |
min | float | – | |
max | float | – | |
step | float | 1 | |
unit | const char* | nullptr |
ui.slider("target", "Target", 20, 90, 1, "°C").persist().onChange([](float v) { target = v; });number
WidgetRef number(const char* id, const char* lbl, float min, float max, float step = 1, const char* unit = nullptr)Numeric input; .spin() adds +/- buttons.
| Argument | Type | Default | Meaning |
|---|---|---|---|
id | const char* | – | |
lbl | const char* | – | |
min | float | – | |
max | float | – | |
step | float | 1 | |
unit | const char* | nullptr |
ui.number("n", "Cycles", 0, 10).spin().onChange([](int v) { cycles = v; });text
WidgetRef text(const char* id, const char* lbl, int maxlen = 64)Single-line text input; .secret() masks it, .regex() validates client-side.
| Argument | Type | Default | Meaning |
|---|---|---|---|
id | const char* | – | |
lbl | const char* | – | |
maxlen | int | 64 |
ui.text("name", "Name", 32).regex("^[A-Za-z ]*$").onChange([](const String& s) { name = s; });select
WidgetRef select(const char* id, const char* lbl, const std::vector<const char*>& opts)Dropdown (value = option index); .style("seg") renders segmented buttons.
ui.select("mode", "Mode", {"Off", "Auto", "Manual"}).style("seg").onChange([](int i) { mode = i; });gauge
WidgetRef gauge(const char* id, const char* lbl, float min, float max, const char* unit = nullptr)Gauge (output); .style("arc"|"round"|"linear"), .zone(from, to, color) colored ranges.
| Argument | Type | Default | Meaning |
|---|---|---|---|
id | const char* | – | |
lbl | const char* | – | |
min | float | – | |
max | float | – | |
unit | const char* | nullptr |
ui.gauge("temp", "Temperature", 0, 120, "°C").style("round").zone(90, 120, "#ff0000");progress
WidgetRef progress(const char* id, const char* lbl, float min = 0, float max = 100)Bar (output); .center() draws a bipolar bar from the middle.
| Argument | Type | Default | Meaning |
|---|---|---|---|
id | const char* | – | |
lbl | const char* | – | |
min | float | 0 | |
max | float | 100 |
ui.progress("level", "Tank");
ui.progress("bal", "Balance", -100, 100).center();led
WidgetRef led(const char* id, const char* lbl, const char* color = nullptr)Indicator (bool); .rgb() makes the value a 0xRRGGBB color.
| Argument | Type | Default | Meaning |
|---|---|---|---|
id | const char* | – | |
lbl | const char* | – | |
color | const char* | nullptr |
ui.led("ok", "OK", "#00ff00");
ui.led("rgb", "Status").rgb();
face.set("rgb", (uint32_t)0x0000ff);chart
WidgetRef chart(const char* id, const char* lbl, int winSeconds = 300, const char* unit = nullptr)Live chart with a client-side ring buffer of winSeconds; add series with .series(id, lbl, color), feed with face.push().
| Argument | Type | Default | Meaning |
|---|---|---|---|
id | const char* | – | |
lbl | const char* | – | |
winSeconds | int | 300 | |
unit | const char* | nullptr |
ui.chart("tchart", "Temp history", 600, "°C").series("temp", "Temp", "#ff8800").series("target", "Target").values(true);
face.push("tchart", "temp", t);textblock
WidgetRef textblock(const char* id, const char* text)Static multi-line paragraph (instructions).
ui.textblock("help", "Set the target and enable the pump.\nThe horn button is momentary.");log
WidgetRef log(const char* id, const char* lbl, int cap = 200, int rows = 8)Log view with a client ring buffer of cap lines and rows visible lines; feed with face.log(id, msg, color). ESPFACE_LOG_HISTORY lines are replayed on connect.
| Argument | Type | Default | Meaning |
|---|---|---|---|
id | const char* | – | |
lbl | const char* | – | |
cap | int | 200 | |
rows | int | 8 |
ui.log("term", "Log", 200, 8);
face.log("term", "pump on");textarea
WidgetRef textarea(const char* id, const char* lbl, int maxlen = 256, int rows = 4)Multi-line text input.
| Argument | Type | Default | Meaning |
|---|---|---|---|
id | const char* | – | |
lbl | const char* | – | |
maxlen | int | 256 | |
rows | int | 4 |
ui.textarea("notes", "Notes", 512, 4).persist();flags
WidgetRef flags(const char* id, const char* lbl, const std::vector<const char*>& opts)Checkbox set; the value is a bitmask (bit i = option i, max 32).
ui.flags("days", "Days", {"Mo", "Tu", "We", "Th", "Fr", "Sa", "Su"}).onChange([](uint32_t m) { days = m; });color
WidgetRef color(const char* id, const char* lbl)Color picker; the value is 0xRRGGBB.
ui.color("col", "Light").onChange([](uint32_t rgb) { strip.fill(rgb); });datetime
WidgetRef datetime(const char* id, const char* lbl, const char* mode = "datetime")Date/time picker (unix seconds); mode is date, time or datetime.
| Argument | Type | Default | Meaning |
|---|---|---|---|
id | const char* | – | |
lbl | const char* | – | |
mode | const char* | "datetime" |
ui.datetime("start", "Start", "time").onChange([](int t) { startAt = t; });joystick
WidgetRef joystick(const char* id, const char* lbl)Joystick; .center() auto-returns, .exp() exponential response; onMove(x, y) each -100..100.
ui.joystick("joy", "Valve").center().square().onMove([](int x, int y) { drive(x, y); });dpad
WidgetRef dpad(const char* id, const char* lbl)Direction pad; onEvent gets 'u', 'd', 'l', 'r', 'c' on press and 0 on release.
ui.dpad("pad", "Move").onEvent([](int k) { if (k == 'u') forward(); if (k == 0) stop(); });display
WidgetRef display(const char* id, const char* lbl, int digits = 4, const char* unit = nullptr)7-segment style readout (output) with digits and unit.
| Argument | Type | Default | Meaning |
|---|---|---|---|
id | const char* | – | |
lbl | const char* | – | |
digits | int | 4 | |
unit | const char* | nullptr |
ui.display("disp", "Pressure", 5, "bar");
face.set("disp", 1.85f);table
WidgetRef table(const char* id, const char* lbl)Table (output); add at least one .column(lbl, w, align), fill with face.setRows().
ui.table("tbl", "Zones").column("Zone", 2).column("°C", 1, "right");
face.setRows("tbl", "[[\"Kitchen\",21.5],[\"Bath\",23]]");image
WidgetRef image(const char* id, const char* lbl, const char* src)Image from a URL the client can reach; change it with ui.prop(id).src(url).
ui.image("img", "Diagram", "http://192.168.1.60/diagram.png");stream
WidgetRef stream(const char* id, const char* lbl, const char* src)MJPEG stream from a URL.
ui.stream("cam", "Camera", "http://192.168.1.60:81/stream");clock
WidgetRef clock(const char* id, const char* lbl, const char* fmt = nullptr)Clock (output); the library pushes the device time every minute and the client ticks locally. fmt tokens: YYYY MM DD HH mm ss.
| Argument | Type | Default | Meaning |
|---|---|---|---|
id | const char* | – | |
lbl | const char* | – | |
fmt | const char* | nullptr |
ui.clock("now", "Device time", "HH:mm:ss");map
WidgetRef map(const char* id, const char* lbl, int zoom = 12)Map (output, online tiles in the clients); fill with face.setPoints().
| Argument | Type | Default | Meaning |
|---|---|---|---|
id | const char* | – | |
lbl | const char* | – | |
zoom | int | 12 |
ui.map("pos", "Location", 14);
face.setPoints("pos", "[[52.52,13.405,\"Boiler\"]]");add
WidgetRef add(WType ty, const char* id, const char* lbl = nullptr)Any widget type without the convenience defaults (e.g. for props set entirely by chain calls).
| Argument | Type | Default | Meaning |
|---|---|---|---|
ty | WType | – | |
id | const char* | – | |
lbl | const char* | nullptr |
ui.add(WType::Gauge, "p", "Pressure").range(0, 10).unit("bar");Runtime
set
bool set(const char* id, const Value& v)
bool set(const char* id, bool v)
bool set(const char* id, float v)
bool set(const char* id, int v)
bool set(const char* id, uint32_t v)
bool set(const char* id, const char* v)
bool set(const char* id, int x, int y)Updates a value from the sketch and pushes it (same as face.set()); returns false for unknown ids or invalid values.
face.ui().set("temp", 21.5f);setRows
bool setRows(const char* id, const char* rowsJson)Table rows as a raw JSON array.
face.ui().setRows("tbl", "[[\"Kitchen\",21.5]]");setPoints
bool setPoints(const char* id, const char* pointsJson)Map points as a raw JSON array.
face.ui().setPoints("pos", "[[52.52,13.4,\"Home\"]]");tickClocks
void tickClocks(uint32_t unix)Pushes unix to every clock widget; the core calls it every minute, sketches rarely need it.
face.ui().tickClocks(face.time());get
const Value* get(const char* id) constCurrent value of a widget (nullptr when unknown).
const Value* v = face.ui().get("target");
if (v) target = v->asFloat();prop
PropRef prop(const char* id)Starts a runtime prop update (see PropRef); sent when the statement ends.
face.ui().prop("temp").color("#f00").label("Temp (HOT)");show
void show(const char* id, bool visible)Hides or shows a widget (vis prop).
face.ui().show("reset", err != 0);rebuild
void rebuild()Bumps rev and resends the whole UI to all clients after structural changes (new widgets added at runtime).
face.ui().label("late", "Added later");
face.ui().rebuild();Dialogs and streams
confirm
void confirm(const char* id, const char* msg, DialogFn cb, const char* title = nullptr, uint16_t timeoutS = 60)Opens a confirm dialog on every client; the first answer wins, others are dismissed; without an answer the callback gets ok = false after timeoutS.
| Argument | Type | Default | Meaning |
|---|---|---|---|
id | const char* | – | |
msg | const char* | – | |
cb | DialogFn | – | |
title | const char* | nullptr | |
timeoutS | uint16_t | 60 |
face.ui().confirm("d1", "Shut down the pump?", [](bool ok, const Str&) { if (ok) digitalWrite(PUMP, 0); });prompt
void prompt(const char* id, const char* msg, DialogFn cb, const char* def = nullptr, const char* title = nullptr, uint16_t timeoutS = 60)Opens a text prompt on every client; the callback gets the typed text.
| Argument | Type | Default | Meaning |
|---|---|---|---|
id | const char* | – | |
msg | const char* | – | |
cb | DialogFn | – | |
def | const char* | nullptr | |
title | const char* | nullptr | |
timeoutS | uint16_t | 60 |
face.ui().prompt("d2", "New device name", [](bool ok, const Str& text) { if (ok) rename(text); }, "Boiler");push
void push(const char* chartId, const char* seriesId, float v, uint64_t tsMs = 0)Appends a chart point; tsMs 0 = now (unix ms when known, else uptime ms).
| Argument | Type | Default | Meaning |
|---|---|---|---|
chartId | const char* | – | |
seriesId | const char* | – | |
v | float | – | |
tsMs | uint64_t | 0 |
face.ui().push("tchart", "temp", t);logLine
void logLine(const char* logId, const char* msg, const char* color = nullptr)Log line to a log widget (logId), or to the clients' console view when logId is nullptr.
| Argument | Type | Default | Meaning |
|---|---|---|---|
logId | const char* | – | |
msg | const char* | – | |
color | const char* | nullptr |
face.ui().logLine("term", "overheat", "#f00");Per-UI PIN
pin
Ui& pin(const char* p)Overrides the device PIN for this UI: "" makes it open, any string sets its own PIN; without a call the global face.setPin() applies.
face.addUi("setup").pin("");hasPinOverride
bool hasPinOverride() constTrue after pin() was called.
face.ui().hasPinOverride();pinOverride
const char* pinOverride() constThe overriding PIN (empty = open).
face.ui().pinOverride();Other
Ui
Ui(const char* name = "main")
Ui(const Ui& )Constructed by EspFace; sketches use face.ui() / face.addUi().
| Argument | Type | Default | Meaning |
|---|---|---|---|
name | const char* | "main" |
auto& ui = face.ui();name
const char* name() constThe UI's name (main for the default one).
face.ui().name();