WidgetRef
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.
The chainable handle every builder call returns. All methods return WidgetRef&; the reference stays valid for the lifetime of the Ui (widgets are never removed).
Layout
group
WidgetRef& group(const char* id)Puts the widget into a group card declared earlier with ui.group().
ui.gauge("temp", "Temp", 0, 120).group("sensors");page
WidgetRef& page(const char* id)Puts the widget on a page (default: the page declared last, else the first).
ui.text("note", "Note").page("setup");row
WidgetRef& row(const char* id)Puts the widget into a row declared earlier with ui.row().
ui.sw("pump", "Pump").row("r1");size
WidgetRef& size(float w, int h = 0)Relative width inside a row (default 1) and an optional fixed height in px.
| Argument | Type | Default | Meaning |
|---|---|---|---|
w | float | – | |
h | int | 0 |
ui.slider("target", "Target", 0, 100).row("r1").size(3);
ui.log("term", "Log").size(1, 240);square
WidgetRef& square(bool on = true)Square aspect ratio (joysticks, images).
| Argument | Type | Default | Meaning |
|---|---|---|---|
on | bool | true |
ui.joystick("joy", "Valve").square();Appearance
hint
WidgetRef& hint(const char* text)Help text shown on long-press / hover.
ui.button("reset", "Reset").hint("Clears the error latch");icon
WidgetRef& icon(const char* name)Icon name from the shared set (see Icons).
ui.page("main", "Boiler").icon("home");color
WidgetRef& color(const char* hex)Accent color #rrggbb (button, switch, slider, progress, led).
ui.button("erase", "Erase").color("#ff0000");Behaviour
disabled
WidgetRef& disabled(bool on = true)Greyed out and not settable (dis).
| Argument | Type | Default | Meaning |
|---|---|---|---|
on | bool | true |
ui.button("reset", "Reset").disabled();readOnly
WidgetRef& readOnly(bool on = true)Rendered but not settable (ro); set from a client is answered with err 7.
| Argument | Type | Default | Meaning |
|---|---|---|---|
on | bool | true |
ui.label("rssi", "Signal").readOnly();hold
WidgetRef& hold(bool on = true)Momentary button: onEvent gets 1 on press and 0 on release.
| Argument | Type | Default | Meaning |
|---|---|---|---|
on | bool | true |
ui.button("horn", "Horn").hold().onEvent([](int v) { digitalWrite(HORN, v); });Type-specific props
unit
WidgetRef& unit(const char* u)Unit suffix.
ui.number("p", "Pressure", 0, 10).unit("bar");step
WidgetRef& step(float s)Step for slider / number.
ui.slider("t", "Target", 0, 100).step(0.5);range
WidgetRef& range(float min, float max)Min/max for slider, number, gauge, progress.
ui.add(WType::Gauge, "p", "Pressure").range(0, 10);spin
WidgetRef& spin(bool on = true)Number input with +/- buttons.
| Argument | Type | Default | Meaning |
|---|---|---|---|
on | bool | true |
ui.number("n", "Cycles", 0, 10).spin();secret
WidgetRef& secret(bool on = true)Masked text input.
| Argument | Type | Default | Meaning |
|---|---|---|---|
on | bool | true |
ui.text("pw", "Password", 64).secret();regex
WidgetRef& regex(const char* re)Client-side validation regex for text inputs.
ui.text("name", "Name", 32).regex("^[A-Za-z ]*$");labels
WidgetRef& labels(const char* on, const char* off)State labels of a switch.
ui.sw("pump", "Pump").labels("ON", "OFF");style
WidgetRef& style(const char* s)Style per type: select list|seg, gauge arc|round|linear, chart line|bar|area.
ui.gauge("temp", "Temp", 0, 120).style("round");
ui.select("mode", "Mode", {"Off", "On"}).style("seg");fmt
WidgetRef& fmt(const char* f)printf-style format for label values, or the clock format.
ui.label("v", "Voltage", "V").fmt("%.2f");fold
WidgetRef& fold(bool on = true)Collapsible group (state lives in the client).
| Argument | Type | Default | Meaning |
|---|---|---|---|
on | bool | true |
ui.group("adv", "Advanced").fold();center
WidgetRef& center(bool on = true)Joystick auto-return / bipolar progress bar.
| Argument | Type | Default | Meaning |
|---|---|---|---|
on | bool | true |
ui.progress("bal", "Balance", -100, 100).center();legend
WidgetRef& legend(bool on)Chart legend on/off (default on).
ui.chart("c", "Chart").series("a", "A").legend(false);values
WidgetRef& values(bool on)Chart shows the current value of each series next to the legend.
ui.chart("c", "Chart").series("a", "A").values(true);exp
WidgetRef& exp(bool on = true)Exponential joystick response.
| Argument | Type | Default | Meaning |
|---|---|---|---|
on | bool | true |
ui.joystick("joy", "Drive").exp();rgb
WidgetRef& rgb(bool on = true)LED whose value is a 0xRRGGBB color instead of a bool.
| Argument | Type | Default | Meaning |
|---|---|---|---|
on | bool | true |
ui.led("status", "Status").rgb();mode
WidgetRef& mode(const char* m)Datetime mode date, time or datetime.
ui.datetime("d", "Day").mode("date");zone
WidgetRef& zone(float from, float to, const char* color)Colored range on a gauge; call it once per zone.
ui.gauge("temp", "Temp", 0, 120).zone(0, 60, "#2f7df6").zone(90, 120, "#ff0000");series
WidgetRef& series(const char* id, const char* lbl = nullptr, const char* color = nullptr)Adds a chart series (id used in face.push()), with optional label and color.
| Argument | Type | Default | Meaning |
|---|---|---|---|
id | const char* | – | |
lbl | const char* | nullptr | |
color | const char* | nullptr |
ui.chart("tchart", "Temp", 600).series("temp", "Temp", "#ff8800").series("target", "Target");column
WidgetRef& column(const char* lbl, float w = 1, const char* align = "left")Adds a table column with relative width and alignment (left|center|right).
| Argument | Type | Default | Meaning |
|---|---|---|---|
lbl | const char* | – | |
w | float | 1 | |
align | const char* | "left" |
ui.table("tbl", "Zones").column("Zone", 2).column("°C", 1, "right");maxlen
WidgetRef& maxlen(int n)Maximum length of a text input.
ui.text("name", "Name").maxlen(16);Values and persistence
persist
WidgetRef& persist()Stores the input value in NVS (changes are coalesced: at most one write per ESPFACE_PERSIST_MS, default 2 s, and pending writes are flushed before a reboot) and restores it before begin() returns; onChange fires once with the restored value. Each UI keeps its values in its own NVS namespace (efv_<ui name>) with the widget id as the key, so ids never clash with the library's settings or another UI.
ui.slider("target", "Target", 20, 90).persist().onChange([](float v) { target = v; });value
WidgetRef& value(const Value& v)
WidgetRef& value(bool v)
WidgetRef& value(float v)
WidgetRef& value(int v)
WidgetRef& value(const char* v)Initial value (overridden by a persisted one).
ui.slider("target", "Target", 20, 90).value(60.0f);
ui.sw("pump", "Pump").value(false);Callbacks and bindings
Callbacks run inside face.loop() (or the networking task) when a client sends set/ev; keep them short.
onChange
template <class F> WidgetRef& onChange(F fn)Called when a client sets the widget; the lambda's argument type selects the conversion: bool, int, uint32_t, float, double, const String&, const char* or const Value&.
ui.sw("pump", "Pump").onChange([](bool on) { digitalWrite(PUMP, on); });
ui.slider("t", "Target", 0, 100).onChange([](float v) { target = v; });
ui.text("name", "Name").onChange([](const String& s) { name = s; });onClick
WidgetRef& onClick(std::function<void()> fn)Button press.
ui.button("reset", "Reset").onClick([] { err = 0; });onEvent
WidgetRef& onEvent(EventFn fn)Raw event: hold buttons get 1/0, dpad gets 'u','d','l','r','c' and 0 on release.
ui.dpad("pad", "Move").onEvent([](int k) { move(k); });onMove
WidgetRef& onMove(MoveFn fn)Joystick position, each axis -100..100.
ui.joystick("joy", "Valve").onMove([](int x, int y) { drive(x, y); });bind
WidgetRef& bind(bool& v)
WidgetRef& bind(int& v)
WidgetRef& bind(float& v)
WidgetRef& bind(Str& v)Two-way binding to a variable: client changes write it, and face.loop() pushes it when the sketch changes it.
bool pumpOn = false;
float target = 60;
ui.sw("pump", "Pump").bind(pumpOn);
ui.slider("target", "Target", 20, 90).bind(target);Other
index
uint16_t index() constInternal widget index.
ui.slider("target", "Target", 20, 90).index();