Skip to content

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 ​

cpp
WidgetRef& group(const char* id)

Puts the widget into a group card declared earlier with ui.group().

cpp
ui.gauge("temp", "Temp", 0, 120).group("sensors");

page ​

cpp
WidgetRef& page(const char* id)

Puts the widget on a page (default: the page declared last, else the first).

cpp
ui.text("note", "Note").page("setup");

row ​

cpp
WidgetRef& row(const char* id)

Puts the widget into a row declared earlier with ui.row().

cpp
ui.sw("pump", "Pump").row("r1");

size ​

cpp
WidgetRef& size(float w, int h = 0)

Relative width inside a row (default 1) and an optional fixed height in px.

ArgumentTypeDefaultMeaning
wfloat–
hint0
cpp
ui.slider("target", "Target", 0, 100).row("r1").size(3);
ui.log("term", "Log").size(1, 240);

square ​

cpp
WidgetRef& square(bool on = true)

Square aspect ratio (joysticks, images).

ArgumentTypeDefaultMeaning
onbooltrue
cpp
ui.joystick("joy", "Valve").square();

Appearance ​

hint ​

cpp
WidgetRef& hint(const char* text)

Help text shown on long-press / hover.

cpp
ui.button("reset", "Reset").hint("Clears the error latch");

icon ​

cpp
WidgetRef& icon(const char* name)

Icon name from the shared set (see Icons).

cpp
ui.page("main", "Boiler").icon("home");

color ​

cpp
WidgetRef& color(const char* hex)

Accent color #rrggbb (button, switch, slider, progress, led).

cpp
ui.button("erase", "Erase").color("#ff0000");

Behaviour ​

disabled ​

cpp
WidgetRef& disabled(bool on = true)

Greyed out and not settable (dis).

ArgumentTypeDefaultMeaning
onbooltrue
cpp
ui.button("reset", "Reset").disabled();

readOnly ​

cpp
WidgetRef& readOnly(bool on = true)

Rendered but not settable (ro); set from a client is answered with err 7.

ArgumentTypeDefaultMeaning
onbooltrue
cpp
ui.label("rssi", "Signal").readOnly();

hold ​

cpp
WidgetRef& hold(bool on = true)

Momentary button: onEvent gets 1 on press and 0 on release.

ArgumentTypeDefaultMeaning
onbooltrue
cpp
ui.button("horn", "Horn").hold().onEvent([](int v) { digitalWrite(HORN, v); });

Type-specific props ​

unit ​

cpp
WidgetRef& unit(const char* u)

Unit suffix.

cpp
ui.number("p", "Pressure", 0, 10).unit("bar");

step ​

cpp
WidgetRef& step(float s)

Step for slider / number.

cpp
ui.slider("t", "Target", 0, 100).step(0.5);

range ​

cpp
WidgetRef& range(float min, float max)

Min/max for slider, number, gauge, progress.

cpp
ui.add(WType::Gauge, "p", "Pressure").range(0, 10);

spin ​

cpp
WidgetRef& spin(bool on = true)

Number input with +/- buttons.

ArgumentTypeDefaultMeaning
onbooltrue
cpp
ui.number("n", "Cycles", 0, 10).spin();

secret ​

cpp
WidgetRef& secret(bool on = true)

Masked text input.

ArgumentTypeDefaultMeaning
onbooltrue
cpp
ui.text("pw", "Password", 64).secret();

regex ​

cpp
WidgetRef& regex(const char* re)

Client-side validation regex for text inputs.

cpp
ui.text("name", "Name", 32).regex("^[A-Za-z ]*$");

labels ​

cpp
WidgetRef& labels(const char* on, const char* off)

State labels of a switch.

cpp
ui.sw("pump", "Pump").labels("ON", "OFF");

style ​

cpp
WidgetRef& style(const char* s)

Style per type: select list|seg, gauge arc|round|linear, chart line|bar|area.

cpp
ui.gauge("temp", "Temp", 0, 120).style("round");
ui.select("mode", "Mode", {"Off", "On"}).style("seg");

fmt ​

cpp
WidgetRef& fmt(const char* f)

printf-style format for label values, or the clock format.

cpp
ui.label("v", "Voltage", "V").fmt("%.2f");

fold ​

cpp
WidgetRef& fold(bool on = true)

Collapsible group (state lives in the client).

ArgumentTypeDefaultMeaning
onbooltrue
cpp
ui.group("adv", "Advanced").fold();

center ​

cpp
WidgetRef& center(bool on = true)

Joystick auto-return / bipolar progress bar.

ArgumentTypeDefaultMeaning
onbooltrue
cpp
ui.progress("bal", "Balance", -100, 100).center();

legend ​

cpp
WidgetRef& legend(bool on)

Chart legend on/off (default on).

cpp
ui.chart("c", "Chart").series("a", "A").legend(false);

values ​

cpp
WidgetRef& values(bool on)

Chart shows the current value of each series next to the legend.

cpp
ui.chart("c", "Chart").series("a", "A").values(true);

exp ​

cpp
WidgetRef& exp(bool on = true)

Exponential joystick response.

ArgumentTypeDefaultMeaning
onbooltrue
cpp
ui.joystick("joy", "Drive").exp();

rgb ​

cpp
WidgetRef& rgb(bool on = true)

LED whose value is a 0xRRGGBB color instead of a bool.

ArgumentTypeDefaultMeaning
onbooltrue
cpp
ui.led("status", "Status").rgb();

mode ​

cpp
WidgetRef& mode(const char* m)

Datetime mode date, time or datetime.

cpp
ui.datetime("d", "Day").mode("date");

zone ​

cpp
WidgetRef& zone(float from, float to, const char* color)

Colored range on a gauge; call it once per zone.

cpp
ui.gauge("temp", "Temp", 0, 120).zone(0, 60, "#2f7df6").zone(90, 120, "#ff0000");

series ​

cpp
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.

ArgumentTypeDefaultMeaning
idconst char*–
lblconst char*nullptr
colorconst char*nullptr
cpp
ui.chart("tchart", "Temp", 600).series("temp", "Temp", "#ff8800").series("target", "Target");

column ​

cpp
WidgetRef& column(const char* lbl, float w = 1, const char* align = "left")

Adds a table column with relative width and alignment (left|center|right).

ArgumentTypeDefaultMeaning
lblconst char*–
wfloat1
alignconst char*"left"
cpp
ui.table("tbl", "Zones").column("Zone", 2).column("°C", 1, "right");

maxlen ​

cpp
WidgetRef& maxlen(int n)

Maximum length of a text input.

cpp
ui.text("name", "Name").maxlen(16);

Values and persistence ​

persist ​

cpp
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.

cpp
ui.slider("target", "Target", 20, 90).persist().onChange([](float v) { target = v; });

value ​

cpp
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).

cpp
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 ​

cpp
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&.

cpp
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 ​

cpp
WidgetRef& onClick(std::function<void()> fn)

Button press.

cpp
ui.button("reset", "Reset").onClick([] { err = 0; });

onEvent ​

cpp
WidgetRef& onEvent(EventFn fn)

Raw event: hold buttons get 1/0, dpad gets 'u','d','l','r','c' and 0 on release.

cpp
ui.dpad("pad", "Move").onEvent([](int k) { move(k); });

onMove ​

cpp
WidgetRef& onMove(MoveFn fn)

Joystick position, each axis -100..100.

cpp
ui.joystick("joy", "Valve").onMove([](int x, int y) { drive(x, y); });

bind ​

cpp
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.

cpp
bool pumpOn = false;
float target = 60;
ui.sw("pump", "Pump").bind(pumpOn);
ui.slider("target", "Target", 20, 90).bind(target);

Other ​

index ​

cpp
uint16_t index() const

Internal widget index.

cpp
ui.slider("target", "Target", 20, 90).index();

MIT licensed. Firmware, web renderer and apps.