MojoScale Studio Docs
API Reference

ui

Graphical UI module backed by LVGL.

All modules Open Studio
Studio Docs Displays

import ui

The ui module creates semantic screens, pages, and widgets on supported graphical ESP32 firmware. LVGL, the panel driver, touch controller, SPI setup, draw buffers, and refresh task stay internal. Phase 1 supports these graphical firmware profiles: - hosyond_esp32e_4inch: ESP32-WROOM-32E 4 MB / No Camera UI firmware, SPI ST7796S, 480 x 320. This is the default ESP32 UI profile. - hosyond_28: ESP32 4 MB / No Camera UI firmware, SPI ILI9341, 320 x 240. - esp32_4848s040: ESP32-S3 16 MB / No Camera UI firmware, ST7701S RGB, 480 x 480. ui.screen("main") opens the firmware default physical display when needed. ui.Display("profile_name") is the explicit form when a script wants to choose the hardware profile or backlight brightness. Phase 1 exposes one physical display and one logical screen named main. Multiple pages are supported on that screen; multiple physical displays are not exposed yet. Automatic layout: dashboard pages place widgets in insertion order, wrap them across the available width, and let the page scroll when content exceeds the screen. General pages use the same safe defaults, but set_pos(), set_size(), and align() can be used for manual placement. Manual placement is useful for a few important controls, while dashboards are better for sensor/status grids. Charts are controller-independent LVGL widgets. They work on every graphical UI firmware profile because the screen driver only provides pixels; line, curve, bar, stacked, scatter, sparkline, and pie/donut widgets are built above that layer. Regular charts show X/Y axis labels and stream new values from left to right. Use auto_scale=True for live sensor values that move in a small band, or call chart.set_auto_scale(True, padding) later. Calling chart.set_range() switches the chart back to a fixed manual Y-axis range. Dashboards also support richer controls: tables, dropdowns, text inputs with an automatic on-screen keyboard, alerts, confirmation dialogs, tabs, lists, images, icons, spinners, and LED-style indicators. These are available on every firmware profile that includes the ui module. Event callbacks are no-argument callbacks in this firmware version. Use widget.value() inside the callback to read the current toggle, slider, or arc value. Text style values are intentionally named instead of raw pixel sizes. Use size="small", "medium", "large", or "xlarge". Use color="white", "muted", "primary", "success", "warning", "danger", "cyan", "blue", "green", "yellow", "red", or "black". For metric and status cards, size= and color= style the main value. Use label_size= and label_color= when the small card title needs a different style. Unsupported values fall back to the widget default.

Quick example

import ui

main = ui.screen("main")
page = main.dashboard("Greenhouse")

temperature = page.metric(
    "Temperature",
    value="--",
    unit="C",
    size="large",
    color="success",
)
humidity = page.metric("Humidity", value="--", unit="%")
heap_chart = page.line_chart(
    "Heap",
    min_value=0,
    max_value=9000000,
    x_label="Time",
    y_label="Bytes",
)
accel_chart = page.line_chart(
    "Accel X",
    min_value=-4,
    max_value=4,
    x_label="Sample",
    y_label="g",
    auto_scale=True,
)
usage = page.pie_chart(
    "Energy mix",
    [55, 30, 15],
    labels=["Grid", "Solar", "Battery"],
    colors=["blue", "cyan", "green"],
)
pump = page.toggle("Water Pump", value=False)

def set_pump():
    if pump.value():
        print("pump on")
    else:
        print("pump off")

pump.on_change(set_pump)

temperature.set_value(24.8)
humidity.set_value(61)
heap_chart.add(7300000)
accel_chart.add(0.42)
usage.set_slices([50, 35, 15], labels=["Grid", "Solar", "Battery"])
page.show()

table = page.table(
    columns=["Metric", "Value", "Unit"],
    rows=[
        ["Temperature", "24.3", "C"],
        ["Pressure", "1.2", "bar"],
    ],
)
table.set_cell(0, 1, "25.1")

mode = page.dropdown("Mode", ["Automatic", "Manual", "Off"], "Automatic")
name = page.input("Device name", value="Generator 1")
page.alert("Cloud connected", severity="success")
page.indicator("Alarm", state="off")

importui

Graphical UI module backed by LVGL.

The ui module creates semantic screens, pages, and widgets on supported graphical ESP32 firmware. LVGL, the panel driver, touch controller, SPI setup, draw buffers, and refresh task stay internal. Phase 1 supports these graphical firmware profiles: - hosyond_esp32e_4inch: ESP32-WROOM-32E 4 MB / No Camera UI firmware, SPI ST7796S, 480 x 320. This is the default ESP32 UI profile. - hosyond_28: ESP32 4 MB / No Camera UI firmware, SPI ILI9341, 320 x 240. - esp32_4848s040: ESP32-S3 16 MB / No Camera UI firmware, ST7701S RGB, 480 x 480. ui.screen("main") opens the firmware default physical display when needed. ui.Display("profile_name") is the explicit form when a script wants to choose the hardware profile or backlight brightness. Phase 1 exposes one physical display and one logical screen named main. Multiple pages are supported on that screen; multiple physical displays are not exposed yet. Automatic layout: dashboard pages place widgets in insertion order, wrap them across the available width, and let the page scroll when content exceeds the screen. General pages use the same safe defaults, but set_pos(), set_size(), and align() can be used for manual placement. Manual placement is useful for a few important controls, while dashboards are better for sensor/status grids. Charts are controller-independent LVGL widgets. They work on every graphical UI firmware profile because the screen driver only provides pixels; line, curve, bar, stacked, scatter, sparkline, and pie/donut widgets are built above that layer. Regular charts show X/Y axis labels and stream new values from left to right. Use auto_scale=True for live sensor values that move in a small band, or call chart.set_auto_scale(True, padding) later. Calling chart.set_range() switches the chart back to a fixed manual Y-axis range. Dashboards also support richer controls: tables, dropdowns, text inputs with an automatic on-screen keyboard, alerts, confirmation dialogs, tabs, lists, images, icons, spinners, and LED-style indicators. These are available on every firmware profile that includes the ui module. Event callbacks are no-argument callbacks in this firmware version. Use widget.value() inside the callback to read the current toggle, slider, or arc value. Text style values are intentionally named instead of raw pixel sizes. Use size="small", "medium", "large", or "xlarge". Use color="white", "muted", "primary", "success", "warning", "danger", "cyan", "blue", "green", "yellow", "red", or "black". For metric and status cards, size= and color= style the main value. Use label_size= and label_color= when the small card title needs a different style. Unsupported values fall back to the widget default.

API 93 available

ui.Display(profile: str = None, brightness: int = None) -> ui_display

Open the configured graphical display profile.

Most code should use ui.screen("main"). Display is useful when a script wants to set the physical profile or backlight brightness explicitly. ui.screen("main") uses the firmware default physical display. ESP32 UI firmware defaults to "hosyond_esp32e_4inch"; ESP32-S3 16 MB UI firmware defaults to "esp32_4848s040". ui.Display("hosyond_esp32e_4inch"), ui.Display("hosyond_28"), or ui.Display("esp32_4848s040") gives an explicit display handle first, then display.screen("main") returns the logical screen. Named physical displays are not exposed in Phase 1.

Parameters
Name Type Pass as Required Description
profile str positional or keyword No Optional display profile name. Defaults to the firmware default profile.
brightness int positional or keyword No Optional backlight brightness from 0 through 100. Defaults to 100.
Returns

ui_display ui_display object.

ui.Display().screen(name: str = "main") -> ui_screen

Return the logical screen for this display.

Parameters
Name Type Pass as Required Description
name str positional or keyword No Optional value. Defaults to "main".

ui.Display().width() -> int

Return logical screen width after profile rotation.

ui.Display().height() -> int

Return logical screen height after profile rotation.

ui.Display().has_touch() -> bool

Return True when the active board profile includes touch hardware.

ui.Display().set_brightness(value: int) -> bool

Set backlight brightness from 0 through 100.

Parameters
Name Type Pass as Required Description
value int positional or keyword Yes Required value.

ui.Display().sleep() -> bool

Turn panel output and backlight off without destroying widgets.

ui.Display().wake(brightness: int = 100) -> bool

Restore panel output and backlight.

Parameters
Name Type Pass as Required Description
brightness int positional or keyword No Optional value. Defaults to 100.

ui.Display().info() -> dict

Return display profile, size, controller, and readiness information.

ui.Display().close() -> bool

Close the display handle.

ui.screen(name: str = None) -> ui_screen

Return a logical screen object.

If the display is not already open, this initializes the firmware default profile. Phase 1 exposes the main logical screen. Dashboard pages automatically place widgets in insertion order, wrap across the screen, and scroll when needed. A practical page should stay small: roughly 4 to 8 dashboard widgets on a 2.8 inch 320 x 240 screen. Manual set_pos(), set_size(), and align() calls can override placement for custom control panels. Button, toggle, slider, and arc callbacks are no-argument callbacks. The transpiler accepts a callable and sends its function name to firmware. Inside the callback, call widget.value() to read the current value.

Parameters
Name Type Pass as Required Description
name str positional or keyword No Optional logical screen name. Defaults to "main".
Returns

ui_screen ui_screen object.

ui.screen().page(title: str = "") -> ui_page

Create a general page owned by this screen.

Parameters
Name Type Pass as Required Description
title str positional or keyword No Optional value. Defaults to "".

ui.screen().dashboard(title: str = "") -> ui_page

Create a dashboard-style page with wrapping widget layout.

Parameters
Name Type Pass as Required Description
title str positional or keyword No Optional value. Defaults to "".

ui.screen().active_page() -> ui_page

Return a handle to the currently active page.

ui.screen().width() -> int

Return logical screen width.

ui.screen().height() -> int

Return logical screen height.

ui.screen().has_touch() -> bool

Return True when the screen profile includes touch hardware.

ui.screen().set_brightness(value: int) -> bool

Set backlight brightness from 0 through 100.

Parameters
Name Type Pass as Required Description
value int positional or keyword Yes Required value.

ui.screen().sleep() -> bool

Turn panel output and backlight off.

ui.screen().wake(brightness: int = 100) -> bool

Restore panel output and backlight.

Parameters
Name Type Pass as Required Description
brightness int positional or keyword No Optional value. Defaults to 100.

ui.screen().info() -> dict

Return screen profile and readiness information.

ui.screen().page().show() -> bool

Make this page visible.

ui.screen().page().hide() -> bool

Hide this page without deleting its widgets.

ui.screen().page().destroy() -> bool

Delete this page and its widgets.

ui.screen().page().title(text: str, size: str = "large", color: str = "white") -> bool

Change the page title. size is one of small, medium, large, xlarge. color is one of white, muted, primary, success, warning, danger, cyan, blue, green, yellow, red, black.

Parameters
Name Type Pass as Required Description
text str positional or keyword Yes Required value.
size str positional or keyword No Optional value. Defaults to "large".
color str positional or keyword No Optional value. Defaults to "white".

ui.screen().page().theme(name: str) -> bool

Apply a lightweight page theme name.

Parameters
Name Type Pass as Required Description
name str positional or keyword Yes Required value.

ui.screen().page().label(text: str, size: str = "medium", color: str = "white") -> ui_widget

Add a text label. size is one of small, medium, large, xlarge. color is one of white, muted, primary, success, warning, danger, cyan, blue, green, yellow, red, black.

Parameters
Name Type Pass as Required Description
text str positional or keyword Yes Required value.
size str positional or keyword No Optional value. Defaults to "medium".
color str positional or keyword No Optional value. Defaults to "white".

ui.screen().page().metric(title: str, value: int | float | str = "0", unit: str = "", label_size: str = "medium", value_size: str = "medium", label_color: str = "muted", value_color: str = "white", size: str = None, color: str = None) -> ui_widget

Add a value card for sensor readings. size/color are shorthand for the main value; value_size/value_color are the explicit names.

Parameters
Name Type Pass as Required Description
title str positional or keyword Yes Required value.
value int | float | str positional or keyword No Optional value. Defaults to "0".
unit str positional or keyword No Optional value. Defaults to "".
label_size str positional or keyword No Optional value. Defaults to "medium".
value_size str positional or keyword No Optional value. Defaults to "medium".
label_color str positional or keyword No Optional value. Defaults to "muted".
value_color str positional or keyword No Optional value. Defaults to "white".
size str positional or keyword No Optional value. Defaults to None.
color str positional or keyword No Optional value. Defaults to None.

ui.screen().page().status(title: str, value: str = "ready", label_size: str = "medium", value_size: str = "medium", label_color: str = "muted", value_color: str = "white", size: str = None, color: str = None) -> ui_widget

Add a status card for state text. size/color are shorthand for the main value; value_size/value_color are the explicit names.

Parameters
Name Type Pass as Required Description
title str positional or keyword Yes Required value.
value str positional or keyword No Optional value. Defaults to "ready".
label_size str positional or keyword No Optional value. Defaults to "medium".
value_size str positional or keyword No Optional value. Defaults to "medium".
label_color str positional or keyword No Optional value. Defaults to "muted".
value_color str positional or keyword No Optional value. Defaults to "white".
size str positional or keyword No Optional value. Defaults to None.
color str positional or keyword No Optional value. Defaults to None.

ui.screen().page().button(text: str, callback: callback = None, size: str = "medium", color: str = "white") -> ui_widget

Add a pressable button. The callback receives no arguments.

Parameters
Name Type Pass as Required Description
text str positional or keyword Yes Required value.
callback callback positional or keyword No Optional value. Defaults to None.
size str positional or keyword No Optional value. Defaults to "medium".
color str positional or keyword No Optional value. Defaults to "white".

ui.screen().page().toggle(text: str, value: bool = False, callback: callback = None) -> ui_widget

Add an on/off switch. The callback receives no arguments; call widget.value().

Parameters
Name Type Pass as Required Description
text str positional or keyword Yes Required value.
value bool positional or keyword No Optional value. Defaults to False.
callback callback positional or keyword No Optional value. Defaults to None.

ui.screen().page().slider(min_value: int | float = 0, max_value: int | float = 100, value: int | float = 0, callback: callback = None) -> ui_widget

Add a horizontal slider.

Parameters
Name Type Pass as Required Description
min_value int | float positional or keyword No Optional value. Defaults to 0.
max_value int | float positional or keyword No Optional value. Defaults to 100.
value int | float positional or keyword No Optional value. Defaults to 0.
callback callback positional or keyword No Optional value. Defaults to None.

ui.screen().page().bar(min_value: int | float = 0, max_value: int | float = 100, value: int | float = 0) -> ui_widget

Add a progress bar.

Parameters
Name Type Pass as Required Description
min_value int | float positional or keyword No Optional value. Defaults to 0.
max_value int | float positional or keyword No Optional value. Defaults to 100.
value int | float positional or keyword No Optional value. Defaults to 0.

ui.screen().page().arc(min_value: int | float = 0, max_value: int | float = 100, value: int | float = 0, callback: callback = None) -> ui_widget

Add a circular value control.

Parameters
Name Type Pass as Required Description
min_value int | float positional or keyword No Optional value. Defaults to 0.
max_value int | float positional or keyword No Optional value. Defaults to 100.
value int | float positional or keyword No Optional value. Defaults to 0.
callback callback positional or keyword No Optional value. Defaults to None.

ui.screen().page().chart(kind: str = "line", title: str = "Chart", min_value: int | float = 0, max_value: int | float = 100, points: int = 48, color: str = "primary", x_label: str = "Samples", y_label: str = "Value", auto_scale: bool = False, auto_padding: int | float = 0.15) -> ui_widget

Add a chart. kind is "line", "curve", "bar", "stacked", or "scatter".

Parameters
Name Type Pass as Required Description
kind str positional or keyword No Optional value. Defaults to "line".
title str positional or keyword No Optional value. Defaults to "Chart".
min_value int | float positional or keyword No Optional value. Defaults to 0.
max_value int | float positional or keyword No Optional value. Defaults to 100.
points int positional or keyword No Optional value. Defaults to 48.
color str positional or keyword No Optional value. Defaults to "primary".
x_label str positional or keyword No Optional value. Defaults to "Samples".
y_label str positional or keyword No Optional value. Defaults to "Value".
auto_scale bool positional or keyword No Optional value. Defaults to False.
auto_padding int | float positional or keyword No Optional value. Defaults to 0.15.

ui.screen().page().line_chart(title: str = "Chart", min_value: int | float = 0, max_value: int | float = 100, points: int = 48, color: str = "primary", x_label: str = "Samples", y_label: str = "Value", auto_scale: bool = False, auto_padding: int | float = 0.15) -> ui_widget

Add a streaming line chart.

Parameters
Name Type Pass as Required Description
title str positional or keyword No Optional value. Defaults to "Chart".
min_value int | float positional or keyword No Optional value. Defaults to 0.
max_value int | float positional or keyword No Optional value. Defaults to 100.
points int positional or keyword No Optional value. Defaults to 48.
color str positional or keyword No Optional value. Defaults to "primary".
x_label str positional or keyword No Optional value. Defaults to "Samples".
y_label str positional or keyword No Optional value. Defaults to "Value".
auto_scale bool positional or keyword No Optional value. Defaults to False.
auto_padding int | float positional or keyword No Optional value. Defaults to 0.15.

ui.screen().page().curve_chart(title: str = "Chart", min_value: int | float = 0, max_value: int | float = 100, points: int = 48, color: str = "primary", x_label: str = "Samples", y_label: str = "Value", auto_scale: bool = False, auto_padding: int | float = 0.15) -> ui_widget

Add a smoothed streaming line chart.

Parameters
Name Type Pass as Required Description
title str positional or keyword No Optional value. Defaults to "Chart".
min_value int | float positional or keyword No Optional value. Defaults to 0.
max_value int | float positional or keyword No Optional value. Defaults to 100.
points int positional or keyword No Optional value. Defaults to 48.
color str positional or keyword No Optional value. Defaults to "primary".
x_label str positional or keyword No Optional value. Defaults to "Samples".
y_label str positional or keyword No Optional value. Defaults to "Value".
auto_scale bool positional or keyword No Optional value. Defaults to False.
auto_padding int | float positional or keyword No Optional value. Defaults to 0.15.

ui.screen().page().bar_chart(title: str = "Chart", min_value: int | float = 0, max_value: int | float = 100, points: int = 48, color: str = "primary", x_label: str = "Samples", y_label: str = "Value", auto_scale: bool = False, auto_padding: int | float = 0.15) -> ui_widget

Add a streaming bar chart.

Parameters
Name Type Pass as Required Description
title str positional or keyword No Optional value. Defaults to "Chart".
min_value int | float positional or keyword No Optional value. Defaults to 0.
max_value int | float positional or keyword No Optional value. Defaults to 100.
points int positional or keyword No Optional value. Defaults to 48.
color str positional or keyword No Optional value. Defaults to "primary".
x_label str positional or keyword No Optional value. Defaults to "Samples".
y_label str positional or keyword No Optional value. Defaults to "Value".
auto_scale bool positional or keyword No Optional value. Defaults to False.
auto_padding int | float positional or keyword No Optional value. Defaults to 0.15.

ui.screen().page().stacked_chart(title: str = "Chart", min_value: int | float = 0, max_value: int | float = 100, points: int = 48, color: str = "primary", x_label: str = "Samples", y_label: str = "Value", auto_scale: bool = False, auto_padding: int | float = 0.15) -> ui_widget

Add a stacked bar chart for positive values.

Parameters
Name Type Pass as Required Description
title str positional or keyword No Optional value. Defaults to "Chart".
min_value int | float positional or keyword No Optional value. Defaults to 0.
max_value int | float positional or keyword No Optional value. Defaults to 100.
points int positional or keyword No Optional value. Defaults to 48.
color str positional or keyword No Optional value. Defaults to "primary".
x_label str positional or keyword No Optional value. Defaults to "Samples".
y_label str positional or keyword No Optional value. Defaults to "Value".
auto_scale bool positional or keyword No Optional value. Defaults to False.
auto_padding int | float positional or keyword No Optional value. Defaults to 0.15.

ui.screen().page().scatter_chart(title: str = "Chart", min_value: int | float = 0, max_value: int | float = 100, points: int = 48, color: str = "primary", x_label: str = "X", y_label: str = "Y", auto_scale: bool = False, auto_padding: int | float = 0.15) -> ui_widget

Add an X/Y scatter chart. Use add_xy(x, y).

Parameters
Name Type Pass as Required Description
title str positional or keyword No Optional value. Defaults to "Chart".
min_value int | float positional or keyword No Optional value. Defaults to 0.
max_value int | float positional or keyword No Optional value. Defaults to 100.
points int positional or keyword No Optional value. Defaults to 48.
color str positional or keyword No Optional value. Defaults to "primary".
x_label str positional or keyword No Optional value. Defaults to "X".
y_label str positional or keyword No Optional value. Defaults to "Y".
auto_scale bool positional or keyword No Optional value. Defaults to False.
auto_padding int | float positional or keyword No Optional value. Defaults to 0.15.

ui.screen().page().sparkline(title: str = "Chart", min_value: int | float = 0, max_value: int | float = 100, points: int = 32, color: str = "primary", x_label: str = "Samples", y_label: str = "Value", auto_scale: bool = False, auto_padding: int | float = 0.15) -> ui_widget

Add a compact line chart for dense dashboards.

Parameters
Name Type Pass as Required Description
title str positional or keyword No Optional value. Defaults to "Chart".
min_value int | float positional or keyword No Optional value. Defaults to 0.
max_value int | float positional or keyword No Optional value. Defaults to 100.
points int positional or keyword No Optional value. Defaults to 32.
color str positional or keyword No Optional value. Defaults to "primary".
x_label str positional or keyword No Optional value. Defaults to "Samples".
y_label str positional or keyword No Optional value. Defaults to "Value".
auto_scale bool positional or keyword No Optional value. Defaults to False.
auto_padding int | float positional or keyword No Optional value. Defaults to 0.15.

ui.screen().page().pie_chart(title: str, values: list, labels: list = None, colors: list = None) -> ui_widget

Add a compact pie/donut chart. Values must contain at least one positive number. Optional labels/colors match values by position.

Parameters
Name Type Pass as Required Description
title str positional or keyword Yes Required value.
values list positional or keyword Yes Required value.
labels list positional or keyword No Optional value. Defaults to None.
colors list positional or keyword No Optional value. Defaults to None.

ui.screen().page().table(columns: list = None, rows: list = None, on_select: callback = None) -> ui_widget

Add a text table. When columns are provided, set_cell(row, column, value) addresses data rows, not the header row.

Parameters
Name Type Pass as Required Description
columns list positional or keyword No Optional value. Defaults to None.
rows list positional or keyword No Optional value. Defaults to None.
on_select callback positional or keyword No Optional value. Defaults to None.

ui.screen().page().dropdown(title: str, options: list, value: str | int = None, on_change: callback = None) -> ui_widget

Add a dropdown selector.

Parameters
Name Type Pass as Required Description
title str positional or keyword Yes Required value.
options list positional or keyword Yes Required value.
value str | int positional or keyword No Optional value. Defaults to None.
on_change callback positional or keyword No Optional value. Defaults to None.

ui.screen().page().input(title: str, value: str = "", type: str = "text", on_change: callback = None, placeholder: str = "") -> ui_widget

Add a text input. type can be text, number, numeric, or password. The on-screen keyboard opens automatically on focus.

Parameters
Name Type Pass as Required Description
title str positional or keyword Yes Required value.
value str positional or keyword No Optional value. Defaults to "".
type str positional or keyword No Optional value. Defaults to "text".
on_change callback positional or keyword No Optional value. Defaults to None.
placeholder str positional or keyword No Optional value. Defaults to "".

ui.screen().page().alert(message: str, severity: str = "info") -> ui_widget

Add a full-width message banner. severity can be info, success, warning, critical, danger, or error.

Parameters
Name Type Pass as Required Description
message str positional or keyword Yes Required value.
severity str positional or keyword No Optional value. Defaults to "info".

ui.screen().page().confirm(message: str, on_confirm: callback = None, on_cancel: callback = None, title: str = "Confirm") -> ui_widget

Show a confirmation dialog.

Parameters
Name Type Pass as Required Description
message str positional or keyword Yes Required value.
on_confirm callback positional or keyword No Optional value. Defaults to None.
on_cancel callback positional or keyword No Optional value. Defaults to None.
title str positional or keyword No Optional value. Defaults to "Confirm".

ui.screen().page().tabs(names: list, position: str = "top") -> ui_widget

Add a tab view. Use tabs.page("Status") to get the page object for a tab.

Parameters
Name Type Pass as Required Description
names list positional or keyword Yes Required value.
position str positional or keyword No Optional value. Defaults to "top".

ui.screen().page().list(items: list, on_select: callback = None) -> ui_widget

Add a selectable menu/list. Items can be strings or dicts with text and icon.

Parameters
Name Type Pass as Required Description
items list positional or keyword Yes Required value.
on_select callback positional or keyword No Optional value. Defaults to None.

ui.screen().page().menu(items: list, on_select: callback = None) -> ui_widget

Alias for page().list().

Parameters
Name Type Pass as Required Description
items list positional or keyword Yes Required value.
on_select callback positional or keyword No Optional value. Defaults to None.

ui.screen().page().image(src: str, width: int = None, height: int = None, scale: int = 256) -> ui_widget

Add an LVGL image from a supported image source/path.

Parameters
Name Type Pass as Required Description
src str positional or keyword Yes Required value.
width int positional or keyword No Optional value. Defaults to None.
height int positional or keyword No Optional value. Defaults to None.
scale int positional or keyword No Optional value. Defaults to 256.

ui.screen().page().icon(name: str, color: str = "primary", size: str = "large") -> ui_widget

Add a built-in LVGL symbol icon.

Parameters
Name Type Pass as Required Description
name str positional or keyword Yes Required value.
color str positional or keyword No Optional value. Defaults to "primary".
size str positional or keyword No Optional value. Defaults to "large".

ui.screen().page().spinner(text: str = "Loading", duration_ms: int = 1000, arc_degrees: int = 90) -> ui_widget

Add an indeterminate loading spinner.

Parameters
Name Type Pass as Required Description
text str positional or keyword No Optional value. Defaults to "Loading".
duration_ms int positional or keyword No Optional value. Defaults to 1000.
arc_degrees int positional or keyword No Optional value. Defaults to 90.

ui.screen().page().indicator(title: str, state: str = "off") -> ui_widget

Add a compact LED-style status indicator.

Parameters
Name Type Pass as Required Description
title str positional or keyword Yes Required value.
state str positional or keyword No Optional value. Defaults to "off".

ui.screen().page().info() -> dict

Return page visibility and readiness details.

ui.screen().widget().add(value: int | float) -> bool

Add the next chart value. Works with line, curve, bar, stacked, and sparkline charts.

Parameters
Name Type Pass as Required Description
value int | float positional or keyword Yes Required value.

ui.screen().widget().add_xy(x: int | float, y: int | float) -> bool

Add the next scatter chart point.

Parameters
Name Type Pass as Required Description
x int | float positional or keyword Yes Required value.
y int | float positional or keyword Yes Required value.

ui.screen().widget().set_range(min_value: int | float, max_value: int | float) -> bool

Set chart Y-axis range and disable auto-scale.

Parameters
Name Type Pass as Required Description
min_value int | float positional or keyword Yes Required value.
max_value int | float positional or keyword Yes Required value.

ui.screen().widget().set_auto_scale(enabled: bool = True, padding: int | float = 0.15) -> bool

Enable or disable chart Y-axis auto-scaling using recent values.

Parameters
Name Type Pass as Required Description
enabled bool positional or keyword No Optional value. Defaults to True.
padding int | float positional or keyword No Optional value. Defaults to 0.15.

ui.screen().widget().set_points(points: int) -> bool

Set chart history length. Values are clamped from 2 through 256.

Parameters
Name Type Pass as Required Description
points int positional or keyword Yes Required value.

ui.screen().widget().set_type(kind: str) -> bool

Change chart kind to "line", "curve", "bar", "stacked", or "scatter".

Parameters
Name Type Pass as Required Description
kind str positional or keyword Yes Required value.

ui.screen().widget().clear() -> bool

Blank chart values.

ui.screen().widget().set_slices(values: list, labels: list = None, colors: list = None) -> bool

Replace pie/donut chart slices.

Parameters
Name Type Pass as Required Description
values list positional or keyword Yes Required value.
labels list positional or keyword No Optional value. Defaults to None.
colors list positional or keyword No Optional value. Defaults to None.

ui.screen().widget().set_text(text: str) -> bool

Set label/status text.

Parameters
Name Type Pass as Required Description
text str positional or keyword Yes Required value.

ui.screen().widget().set_value(value: int | float | str | bool) -> bool

Update the widget value. Metrics accept numbers or text; toggles accept bool-like values.

Parameters
Name Type Pass as Required Description
value int | float | str | bool positional or keyword Yes Required value.

ui.screen().widget().set_unit(unit: str) -> bool

Update a metric unit label.

Parameters
Name Type Pass as Required Description
unit str positional or keyword Yes Required value.

ui.screen().widget().set_status(text: str) -> bool

Set status text.

Parameters
Name Type Pass as Required Description
text str positional or keyword Yes Required value.

ui.screen().widget().set_label_style(size: str = "medium", color: str = "muted") -> bool

Style a widget label using named size and color values.

Parameters
Name Type Pass as Required Description
size str positional or keyword No Optional value. Defaults to "medium".
color str positional or keyword No Optional value. Defaults to "muted".

ui.screen().widget().set_value_style(size: str = "medium", color: str = "white") -> bool

Style a metric/status value using named size and color values.

Parameters
Name Type Pass as Required Description
size str positional or keyword No Optional value. Defaults to "medium".
color str positional or keyword No Optional value. Defaults to "white".

ui.screen().widget().set_level(level: str) -> bool

Set visual level such as info, ok, warn, or error.

Parameters
Name Type Pass as Required Description
level str positional or keyword Yes Required value.

ui.screen().widget().set_enabled(enabled: bool) -> bool

Enable or disable interaction.

Parameters
Name Type Pass as Required Description
enabled bool positional or keyword Yes Required value.

ui.screen().widget().set_visible(visible: bool) -> bool

Show or hide the widget.

Parameters
Name Type Pass as Required Description
visible bool positional or keyword Yes Required value.

ui.screen().widget().set_pos(x: int, y: int) -> bool

Manually position the widget.

Parameters
Name Type Pass as Required Description
x int positional or keyword Yes Required value.
y int positional or keyword Yes Required value.

ui.screen().widget().set_size(width: int, height: int) -> bool

Manually size the widget.

Parameters
Name Type Pass as Required Description
width int positional or keyword Yes Required value.
height int positional or keyword Yes Required value.

ui.screen().widget().align(position: str, x: int = 0, y: int = 0) -> bool

Align the widget using positions such as center, top_left, top_right, bottom_left, or bottom_right.

Parameters
Name Type Pass as Required Description
position str positional or keyword Yes Required value.
x int positional or keyword No Optional value. Defaults to 0.
y int positional or keyword No Optional value. Defaults to 0.

ui.screen().widget().on_press(callback: callback) -> bool

Register a no-argument press callback.

Parameters
Name Type Pass as Required Description
callback callback positional or keyword Yes Required value.

ui.screen().widget().on_change(callback: callback) -> bool

Register a no-argument value-change callback.

Parameters
Name Type Pass as Required Description
callback callback positional or keyword Yes Required value.

ui.screen().widget().set_cell(row: int, column: int, value: int | float | str | bool) -> bool

Update a table cell. Header rows are skipped when a table was created with columns.

Parameters
Name Type Pass as Required Description
row int positional or keyword Yes Required value.
column int positional or keyword Yes Required value.
value int | float | str | bool positional or keyword Yes Required value.

ui.screen().widget().cell(row: int, column: int) -> str

Read a table cell.

Parameters
Name Type Pass as Required Description
row int positional or keyword Yes Required value.
column int positional or keyword Yes Required value.

ui.screen().widget().set_column_width(column: int, width: int) -> bool

Set one table column width in pixels.

Parameters
Name Type Pass as Required Description
column int positional or keyword Yes Required value.
width int positional or keyword Yes Required value.

ui.screen().widget().set_options(options: list) -> bool

Replace dropdown options.

Parameters
Name Type Pass as Required Description
options list positional or keyword Yes Required value.

ui.screen().widget().selected() -> dict

Return selected dropdown, table, or list details.

ui.screen().widget().set_placeholder(text: str) -> bool

Update input placeholder text.

Parameters
Name Type Pass as Required Description
text str positional or keyword Yes Required value.

ui.screen().widget().page(name: str | int) -> ui_page

Return a page object for a tab inside a tab view.

Parameters
Name Type Pass as Required Description
name str | int positional or keyword Yes Required value.

ui.screen().widget().set_state(state: str) -> bool

Update alert/indicator state styling.

Parameters
Name Type Pass as Required Description
state str positional or keyword Yes Required value.

ui.screen().widget().open() -> bool

Open a dropdown or show a hidden widget.

ui.screen().widget().close() -> bool

Close a dropdown/dialog or hide a widget.

ui.screen().widget().value() -> any

Return the current toggle, slider, arc, chart, dropdown, input, or indicator value.

ui.screen().widget().info() -> dict

Return widget kind, visibility, and enabled state.

ui.screen().widget().delete() -> bool

Delete the widget.

ui.screens() -> list

List configured logical screen names.

Returns

list list. Screen names available in the active profile.

ui.ready() -> bool

Return whether the graphical UI runtime is initialized.

Returns

bool bool. True when LVGL and the display panel are ready.

ui.info() -> dict

Return display profile information.

Example output includes initialized, profile, controller, bus, width, height, rotation, brightness, and touch_profile. Typical results are: {"initialized": True, "profile": "hosyond_esp32e_4inch", "controller": "st7796s", "bus": "spi", "width": 480, "height": 320, "rotation": 1, "brightness": 100, "touch_profile": True} {"initialized": True, "profile": "hosyond_28", "controller": "ili9341v", "bus": "spi", "width": 320, "height": 240, "rotation": 1, "brightness": 100, "touch_profile": False} {"initialized": True, "profile": "esp32_4848s040", "controller": "st7701s", "bus": "rgb", "width": 480, "height": 480, "rotation": 0, "brightness": 100, "touch_profile": False}

Returns

dict dict. Includes initialized, profile, controller, bus, width, height, brightness, rotation, and touch_profile.