Functions
void	ui_widget_mgr_init (lv_obj_t *parent)
	Called by ipc_ui_init() itself — never call it directly.
void	ui_widget_mgr_set_parent (lv_obj_t *parent)
	Clears all widgets and sets the new parent; called only via ipc_ui_set_container().
bool	ui_widget_mgr_needs_container (void)
	True while the parent is NULL; no caller anywhere.
int	ui_widget_mgr_create (const ipc_ui_create_t *cfg)
	Creates a widget from a config; handle 0-31, -1 table full, -2 invalid type.
int	ui_widget_mgr_create_sprite (const lv_image_dsc_t *dsc, int16_t x, int16_t y)
	Creates an image sprite in the same handle table.
void	ui_widget_mgr_set_sprite_image (int handle, const lv_image_dsc_t *dsc)
	Swaps a sprite's image; the descriptor comes from game_sprite_lookup().
void	ui_widget_mgr_delete (int handle)
	Deletes one widget and frees its handle.
void	ui_widget_mgr_clear_all (void)
	Deletes every widget and resets the handle table.
void	ui_widget_mgr_set_text (int handle, const char *text)
	Sets a widget's text; the switch arms fast drain after it.
void	ui_widget_mgr_set_value (int handle, int32_t value)
	Sets a numeric value; arms fast drain so dashboards are not pinned to 5 FPS.
void	ui_widget_mgr_set_position (int handle, int16_t x, int16_t y)
	Moves a widget; arms fast drain for gameplay frame rate.
void	ui_widget_mgr_set_size (int handle, int16_t w, int16_t h)
	Resizes a widget.
void	ui_widget_mgr_set_color (int handle, uint32_t color)
	Sets the primary colour, 0xRRGGBB.
void	ui_widget_mgr_set_visible (int handle, bool visible)
	Shows or hides one widget.
void	ui_widget_mgr_set_all_visible (bool visible)
	Shows or hides every managed widget; the Playground console toggle's view switch.
int32_t	ui_widget_mgr_get_value (int handle)
	Reads the widget's current value; 0 also means bad handle.
void	ui_widget_mgr_set_dotmatrix (int handle, const uint8_t *bitmap, uint8_t len)
	Loads a bitmap into a DotMatrix widget.
void	ui_widget_mgr_set_image (int handle, uint16_t offset, const uint8_t *data, uint8_t len)
	Chunked RGB565 transfer into an Image widget's canvas.
void	ui_widget_mgr_event_push (uint8_t handle, uint8_t event_type, int32_t value)
	Producer side of the event ring; internal LVGL event callbacks only.
int	ui_widget_mgr_event_drain (ipc_ui_event_t *out, int max_events)
	Drains events for POLL_EVENTS — the ui.poll() backend.
int	ui_widget_mgr_count (void)
	Number of live handles; zero callers anywhere.
int	ui_widget_mgr_list (ipc_ui_widget_info_t *out, int max_items)
	Handle + type of every active widget — the ui.list() backend.
lv_obj_t *	ui_widget_mgr_get_parent (void)
	Nullable current parent; every call site null-checks it.
void	ui_widget_mgr_set_screen (int16_t width, int16_t height)
	Sets screen dimensions and resets the auto-layout grid.
int	ui_widget_mgr_chart_add_series (int handle, uint32_t color)
	Adds a series to a Chart; returns index 0-3 or -1.
void	ui_widget_mgr_chart_set_next (int handle, uint8_t series_idx, int32_t value)
	Appends the next value to one chart series.
int	ui_widget_mgr_item_add (const ipc_ui_item_add_t *it)
	Appends one item; overloaded returns, dual-implementation rule.
void	ui_widget_mgr_item_clear (int handle)
	Empties a collection widget.
void	ui_widget_mgr_set_prop (int handle, uint8_t prop_id, int32_t value)
	Sets one UI_PROP_* property; how .listen() subscribes to events.
lv_obj_t *	ui_widget_mgr_get_object (int handle)
	LVGL object behind a handle; the GET_TEXT route for typed text.

Detailed Description

Header: ui_widget_mgr.h. Implementation: archived ui_widget_mgr.c (libbento_ipc.a). "Widget handle table and LVGL widget lifecycle manager. Maps handle IDs (0-31) to lv_obj_t* pointers. Creates, modifies, deletes LVGL widgets in GFX task context" (ui_widget_mgr.h).

Read this first — who actually calls these. These primitives are not application-facing in C. Inside the archive their sole caller is the IPC command switch process_ui_command() in ipc_ui.c (definition at :393, drained from the 50 ms LVGL timer at :875). The real callers are MicroPython scripts on CM33_NS: each ui.* call in modui.c packs a payload, sends it over the pipe, and the switch below unpacks it and calls one primitive. Documenting them as "call this from your page code" would misrepresent the architecture — a page that calls ui_widget_mgr_create() directly is bypassing the handle table's owner and will race the next script's CLEAR_ALL.

Every entry therefore gives three things: the pinned dispatch site in the switch (case label and call line, read from the source in the pin-extraction pass), the MicroPython ui.* surface that reaches it, and the contract. Four cases — CREATE, DELETE, SET_TEXT, SET_VALUE — are replicated verbatim in the Tier-2 excerpt; the remaining cases are deliberately not replicated (disclosure minimisation) and are cited as text. Two primitives are called from outside the switch (init by ipc_ui_init(), set_parent by ipc_ui_set_container()), two have no caller anywhere (count, needs_container), and two are called from the template's own Playground page (clear_all, set_all_visible).

Variant: mtb-mpy and mtb-only (all thirty)

The representative dispatch excerpt

Origin: Lifted from BENTO-TESAIoT-libraries/claw/common/modules/ipc_ui/ipc_ui.c:393-394 and 418-477 (compiled into the prebuilt archive; not shipped as source).

Function Documentation

◆ ui_widget_mgr_init()

void ui_widget_mgr_init ( lv_obj_t * parent )

Called by ipc_ui_init() itself — never call it directly.

Initialize the widget manager.

Parameters

parent The LVGL parent object (UX/UI tab scrollable container).

Contract: Called by ipc_ui_init() itself, as its first statement (ipc_ui.c:890, inside ipc_ui_init() at :885) — never call it directly. Not a switch case. Takes the deferred-binding NULL at boot; the page supplies the real parent later through ipc_ui_set_container().

MicroPython surface: None — bring-up only.

Dispatch pin: ipc_ui.c:890 — ui_widget_mgr_init(parent); under the comment "Initialize widget manager with parent container".

Variant: mtb-mpy and mtb-only

◆ ui_widget_mgr_set_parent()

void ui_widget_mgr_set_parent ( lv_obj_t * parent )

Clears all widgets and sets the new parent; called only via ipc_ui_set_container().

Update the parent container (for page-based navigation). Clears all existing widgets and sets new parent.

Parameters

parent New LVGL parent object, or NULL to invalidate.

Contract: "Clears all existing widgets and sets new parent" (ui_widget_mgr.h); pass NULL to invalidate. Its sole caller is ipc_ui_set_container() (ipc_ui.c:918-921) — page-based navigation, not the dispatch switch. A design revision recorded this correction: the blanket "sole caller is the IPC command switch" claim is wrong for this one row. Consumers call ipc_ui_set_container(), never this. GFX-task context; void.

MicroPython surface: None — the page binds the container, the script cannot.

Dispatch pin: ipc_ui.c:920 — the whole body of ipc_ui_set_container() is ui_widget_mgr_set_parent(parent);. The template call sites of that wrapper are on UI containers.

Variant: mtb-mpy and mtb-only

◆ ui_widget_mgr_needs_container()

bool ui_widget_mgr_needs_container ( void )

True while the parent is NULL; no caller anywhere.

Check if the widget manager has no parent container.

Returns: true if parent is NULL (needs container before creating widgets).

Contract: True while the parent is NULL — between ipc_ui_set_container(NULL) on page destroy and the next page's bind — i.e. while CREATE would fail. No caller anywhere. The authored example relates it to the deferred-binding contract: a page that wants to know whether a script's widgets can land yet asks this, in GFX-task context.

MicroPython surface: None.

Variant: mtb-mpy and mtb-only

Example (authored — no shipped call site)

__attribute__((used))
static void bento_ex_ui_widget_mgr_needs_container(void)
{
    if (ui_widget_mgr_needs_container()) {
        /* No page has bound a container (or the page just died and
         * correctly NULLed it). Do not create widgets; retry on the
         * next tick after a page binds. */
        return;
    }
 
    /* Safe window: a container is bound — widget creation commands
     * (ui_widget_mgr_create / the IPC CREATE path) have a live parent. */
}

◆ ui_widget_mgr_create()

int ui_widget_mgr_create ( const ipc_ui_create_t * cfg )

Creates a widget from a config; handle 0-31, -1 table full, -2 invalid type.

Create a widget from IPC CREATE payload.

Parameters

cfg	Parsed CREATE payload.

Returns: Handle ID (0-31) on success, -1 if table full, -2 if invalid type.

Contract: Returns a handle 0-31, -1 when the table is full, -2 for an invalid type. The switch maps those to UI_STATUS_OK / UI_STATUS_TABLE_FULL / UI_STATUS_INVALID_TYPE in a bidirectional response, arms fast drain (ui_arm_fast_mode()), and on the first CREATE hides the container until POLL_EVENTS or a timeout unhides it (so a burst of creates appears at once). GFX-task context.

MicroPython surface: Every widget constructor — ui.Button(...), ui.Label(...), ui.Slider(...), ui.Chart(...) and the rest of the ui class table (modui.c:1226, bidirectional).

Dispatch pin: ipc_ui.c:420 case IPC_CMD_UI_CREATE: / :422 int handle = ui_widget_mgr_create(cfg); — replicated in the representative excerpt on Widget manager (IPC dispatch).

Variant: mtb-mpy and mtb-only

◆ ui_widget_mgr_create_sprite()

int ui_widget_mgr_create_sprite	(	const lv_image_dsc_t *	dsc,
		int16_t	x,
		int16_t	y )

Creates an image sprite in the same handle table.

Create an image sprite from a compiled C descriptor. Reuses the widget handle table so position/visibility/delete work through the normal ops.

Parameters

dsc	Compiled sprite descriptor (resolved per-project from a SPR id).

Returns: Handle ID (0-31), -1 if table full, -2 if invalid/no sprite engine.

Contract: Creates an image sprite from a compiled descriptor and files it in the same handle table, so position / visibility / delete work through the normal ops. Returns 0-31, -1 table full, -2 invalid or no sprite engine — the latter is what the weak game_sprite_create default produces (see Weak hooks (implement, don't call)). GFX-task context.

MicroPython surface: ui.sprite(id, x, y) (modui.c:1731, bidirectional).

Dispatch pin: ipc_ui.c:758 case IPC_CMD_UI_SPRITE_NEW: / :763 int handle = ui_widget_mgr_create_sprite(dsc, s->x, s->y);.

Variant: mtb-mpy and mtb-only

◆ ui_widget_mgr_set_sprite_image()

void ui_widget_mgr_set_sprite_image	(	int	handle,
		const lv_image_dsc_t *	dsc )

Swaps a sprite's image; the descriptor comes from game_sprite_lookup().

Swap a sprite's image (directional head, enemy kind, explosion frame). No-op on invalid handle or NULL descriptor.

Contract: Swaps a sprite's image (directional head, enemy kind, explosion frame); no-op on an invalid handle or NULL descriptor. The descriptor comes from the project's game_sprite_lookup() override, called one line earlier in the switch. GFX-task context.

MicroPython surface: w.frame(sprite_id) on a sprite handle (modui.c:651).

Dispatch pin: ipc_ui.c:819 case IPC_CMD_UI_SPRITE_FRAME: / :822 game_sprite_lookup(item->data[1]) / :823 ui_widget_mgr_set_sprite_image(handle, dsc);.

Variant: mtb-mpy and mtb-only

◆ ui_widget_mgr_delete()

void ui_widget_mgr_delete ( int handle )

Deletes one widget and frees its handle.

Delete a widget by handle.

Parameters

handle Handle ID (0-31).

Contract: Deletes one widget and frees its handle. Fire-and-forget from the script's side; no response. GFX-task context.

MicroPython surface: w.delete() (modui.c:506).

Dispatch pin: ipc_ui.c:453 case IPC_CMD_UI_DELETE: / :455 ui_widget_mgr_delete(handle); — replicated in the representative excerpt on Widget manager (IPC dispatch).

Variant: mtb-mpy and mtb-only

◆ ui_widget_mgr_clear_all()

void ui_widget_mgr_clear_all ( void )

Deletes every widget and resets the handle table.

Delete all widgets and reset the handle table.

Contract: Deletes every widget and resets the handle table. Two callers: the switch's CLEAR_ALL case (new script), and the template's Playground page, from an LVGL LV_EVENT_CLICKED callback — GFX-task context. In the page the widgets are torn down before the IPC restart command is sent, so CM33_NS cannot push new widgets into a half-cleared table. Void; no error path. The destructive variant at page_playground.c:105 clears, sends IPC_CMD_DELETE_MAIN_PY, then resets the MCU.

MicroPython surface: ui.clear() (modui.c:1553), also issued by ui.program() and the IDE deploy path (:1641, :1975).

Dispatch pin: ipc_ui.c:553 case IPC_CMD_UI_CLEAR_ALL: / :554 ui_widget_mgr_clear_all(); followed by the auto-navigate reset.

Variant: mtb-mpy and mtb-only

Example — soft restart (template): /* ...context: inside uxui_ctrl_event_cb() - GFX task context ... */

if (cmd == UXUI_CTRL_RESTART) {

/* Soft restart: clear widgets, then tell CM33_NS to re-run main.py.

* No NVIC_SystemReset — CM55/WiFi/sensors stay alive. */

ui_widget_mgr_clear_all();

send_ipc_cmd(IPC_CMD_RESTART_SCRIPT);

}

◆ ui_widget_mgr_set_text()

void ui_widget_mgr_set_text	(	int	handle,
		const char *	text )

Sets a widget's text; the switch arms fast drain after it.

Set text on a widget.

Contract: Sets a widget's text; the switch arms fast drain after it so a label that is updated in a loop repaints at 5 ms cadence. Text arrives NUL-terminated in the payload after the handle byte. GFX-task context.

MicroPython surface: w.text("...") (modui.c:396; also :527 and :1261 for constructor-time text). Note the 95-byte constructor and 126-byte .text() payload limits enforced on the CM33_NS side.

Dispatch pin: ipc_ui.c:459 case IPC_CMD_UI_SET_TEXT: / :462 ui_widget_mgr_set_text(handle, text); + :463 ui_arm_fast_mode(); — replicated in the representative excerpt on Widget manager (IPC dispatch).

Variant: mtb-mpy and mtb-only

◆ ui_widget_mgr_set_value()

void ui_widget_mgr_set_value	(	int	handle,
		int32_t	value )

Sets a numeric value; arms fast drain so dashboards are not pinned to 5 FPS.

Set numeric value on a widget.

Contract: Sets a numeric value (slider, bar, arc, seg7 ...). The switch arms fast drain here too — the in-source comment records why: without it every sensor dashboard was pinned to the 200 ms idle drain (~5 FPS) while games ran at 5 ms. GFX-task context.

MicroPython surface: w.value(n) (modui.c:424).

Dispatch pin: ipc_ui.c:467 case IPC_CMD_UI_SET_VALUE: / :471 ui_widget_mgr_set_value(handle, value); — replicated in the representative excerpt on Widget manager (IPC dispatch).

Variant: mtb-mpy and mtb-only

◆ ui_widget_mgr_set_position()

void ui_widget_mgr_set_position	(	int	handle,
		int16_t	x,
		int16_t	y )

Moves a widget; arms fast drain for gameplay frame rate.

Set position of a widget.

Contract: Moves a widget; the switch arms fast drain "to keep full frame rate during gameplay". GFX-task context.

MicroPython surface: w.pos(x, y) (modui.c:442).

Dispatch pin: ipc_ui.c:479 case IPC_CMD_UI_SET_POSITION: / :484 ui_widget_mgr_set_position(handle, x, y); + :485 ui_arm_fast_mode();.

Variant: mtb-mpy and mtb-only

◆ ui_widget_mgr_set_size()

void ui_widget_mgr_set_size	(	int	handle,
		int16_t	w,
		int16_t	h )

Resizes a widget.

Set size of a widget.

Contract: Resizes a widget. GFX-task context.

MicroPython surface: w.size(w, h) (modui.c:460).

Dispatch pin: ipc_ui.c:489 case IPC_CMD_UI_SET_SIZE: / :494 ui_widget_mgr_set_size(handle, w, h);.

Variant: mtb-mpy and mtb-only

◆ ui_widget_mgr_set_color()

void ui_widget_mgr_set_color	(	int	handle,
		uint32_t	color )

Sets the primary colour, 0xRRGGBB.

Set primary color of a widget.

Contract: Sets the primary colour, 0xRRGGBB. GFX-task context.

MicroPython surface: w.color(0xRRGGBB) (modui.c:476).

Dispatch pin: ipc_ui.c:499 case IPC_CMD_UI_SET_COLOR: / :503 ui_widget_mgr_set_color(handle, color);.

Variant: mtb-mpy and mtb-only

◆ ui_widget_mgr_set_visible()

void ui_widget_mgr_set_visible	(	int	handle,
		bool	visible )

Shows or hides one widget.

Show or hide a widget.

Contract: Shows or hides one widget. GFX-task context.

MicroPython surface: w.show() / w.hide() (modui.c:486, :496).

Dispatch pin: ipc_ui.c:508 case IPC_CMD_UI_SET_VISIBLE: / :511 ui_widget_mgr_set_visible(handle, visible);.

Variant: mtb-mpy and mtb-only

◆ ui_widget_mgr_set_all_visible()

void ui_widget_mgr_set_all_visible ( bool visible )

Shows or hides every managed widget; the Playground console toggle's view switch.

Show or hide ALL managed widgets at once. Used by Console/UI toggle to switch between widget view and console view.

Contract: Shows or hides every managed widget at once. Not a switch case — its callers are the template's Playground console toggle (both branches). Widgets hidden if and only if the console is shown; see the asymmetric ordering on LCD console & panel. GFX-task context; void.

MicroPython surface: None — it is the CM55 page's own view switch.

Variant: mtb-mpy and mtb-only

static void console_toggle_cb(lv_event_t *e)
{
    (void)e;
    s_console_mode = !s_console_mode;
 
    if (s_console_mode) {
        /* Switch to Console view — clear unread badge */
        ipc_lcd_clear_unread();
        if (s_console_badge) {
            lv_obj_add_flag(s_console_badge, LV_OBJ_FLAG_HIDDEN);
        }
        ui_widget_mgr_set_all_visible(false);
        if (!ipc_lcd_is_panel_visible()) {
            ipc_lcd_toggle_panel();
        }
    } else {
        /* Switch to UI view */
        if (ipc_lcd_is_panel_visible()) {
            ipc_lcd_toggle_panel();
        }
        ui_widget_mgr_set_all_visible(true);
    }
 
    /* Update button icon */
    if (s_console_btn_lbl) {
        lv_label_set_text(s_console_btn_lbl,
                          s_console_mode ? LV_SYMBOL_EYE_OPEN : LV_SYMBOL_LIST);
    }
}

◆ ui_widget_mgr_get_value()

int32_t ui_widget_mgr_get_value ( int handle )

Reads the widget's current value; 0 also means bad handle.

Get current value of a widget.

Returns: Widget value or 0 if invalid handle.

Contract: Returns the widget's current value, or 0 on an invalid handle — the script cannot distinguish "0" from "bad handle"; the bidirectional response status can. GFX-task context.

MicroPython surface: w.value() with no argument (modui.c:409, bidirectional).

Dispatch pin: ipc_ui.c:586 case IPC_CMD_UI_GET_VALUE: / :588 int32_t value = ui_widget_mgr_get_value(handle);.

Variant: mtb-mpy and mtb-only

◆ ui_widget_mgr_set_dotmatrix()

void ui_widget_mgr_set_dotmatrix	(	int	handle,
		const uint8_t *	bitmap,
		uint8_t	len )

Loads a bitmap into a DotMatrix widget.

Set dot matrix bitmap data.

Contract: Loads a bitmap into a DotMatrix widget; len bytes follow the handle in the payload. GFX-task context.

MicroPython surface: w.set_pixels(bytes) on a ui.DotMatrix (modui.c:589).

Dispatch pin: ipc_ui.c:578 case IPC_CMD_UI_SET_DOTMATRIX: / :582 ui_widget_mgr_set_dotmatrix(handle, bitmap, len);.

Variant: mtb-mpy and mtb-only

◆ ui_widget_mgr_set_image()

void ui_widget_mgr_set_image	(	int	handle,
		uint16_t	offset,
		const uint8_t *	data,
		uint8_t	len )

Chunked RGB565 transfer into an Image widget's canvas.

Set image pixel data (chunked RGB565 transfer).

Parameters

handle	Widget handle (must be UI_WIDGET_IMAGE).
offset	Byte offset into the canvas pixel buffer.
data	Chunk of RGB565 pixel data.
len	Chunk length in bytes.

Contract: Chunked RGB565 transfer into an Image widget's canvas: offset is the byte offset into the pixel buffer, len the chunk length. The handle must be a UI_WIDGET_IMAGE. The script side loops chunks of at most the payload budget. GFX-task context.

MicroPython surface: w.set_image(data) on a ui.Image (modui.c:558, one IPC message per chunk).

Dispatch pin: ipc_ui.c:647 case IPC_CMD_UI_SET_IMAGE: / :656 ui_widget_mgr_set_image(handle, offset, pixel_data, chunk_len);.

Variant: mtb-mpy and mtb-only

◆ ui_widget_mgr_event_push()

void ui_widget_mgr_event_push	(	uint8_t	handle,
		uint8_t	event_type,
		int32_t	value )

Producer side of the event ring; internal LVGL event callbacks only.

Push an event into the ring buffer (called from LVGL event callbacks).

Contract: Producer side of the event ring drained by ui_widget_mgr_event_drain(). Called from LVGL event callbacks inside the archived widget manager — two sites, both internal: the generic widget event callback (ui_widget_mgr.c:333, guarded if (event_type != 0)) and the input event callback for the twelve input events (:406), which first checks the per-widget subscription mask (s_widget_event_mask[handle] & UI_EVENT_MASK(event_type)) and returns without pushing when the script did not .listen() for that event. It is also where ipc_ui_input_activity() is raised. GFX-task context.

MicroPython surface: Indirect: w.listen("pressed", cb) and w.bind(...) set the mask that lets a push through; ui.poll() drains it.

Origin: BENTO-TESAIoT-libraries/claw/common/modules/ipc_ui/ui_widget_mgr.c:333 and :406 (compiled into the prebuilt archive; not shipped as source) — pinned, not replicated.

Variant: mtb-mpy and mtb-only

◆ ui_widget_mgr_event_drain()

int ui_widget_mgr_event_drain	(	ipc_ui_event_t *	out,
		int	max_events )

Drains events for POLL_EVENTS — the ui.poll() backend.

Drain events from the ring buffer.

Parameters

out	Output array.
max_events	Maximum events to drain.

Returns: Number of events drained.

Contract: Drains up to max_events events into a caller-owned array and returns the count; the switch answers POLL_EVENTS with exactly those bytes. The same case also unhides the container hidden by the first CREATE — through the null-checked ui_widget_mgr_get_parent() — so a script's widgets appear all at once. GFX-task context.

MicroPython surface: ui.poll() (modui.c:1324, bidirectional) — the call every event loop makes; .listen() callbacks fire from its result.

Dispatch pin: ipc_ui.c:516 case IPC_CMD_UI_POLL_EVENTS: / :527 int count = ui_widget_mgr_event_drain(events, UI_MAX_EVENTS_PER_POLL);.

Variant: mtb-mpy and mtb-only

Origin: Lifted from BENTO-TESAIoT-libraries/claw/common/modules/ipc_ui/ipc_ui.c:516-532 (compiled into the prebuilt archive; not shipped as source).

◆ ui_widget_mgr_count()

int ui_widget_mgr_count ( void )

Number of live handles; zero callers anywhere.

Get current widget count.

Contract: Returns the number of live handles. Reclassified AUTHORED in the pin-extraction pass: across all three library variants and the template the only hits are the declaration (ui_widget_mgr.h:142) and three definitions — zero callers. The authored example reads it in GFX-task context after clear_all(), as a teardown assertion; a count read from another task races the dispatch path.

MicroPython surface: None (ui.list() uses ui_widget_mgr_list(), not this).

Variant: mtb-mpy and mtb-only

Example (authored — no shipped call site)

__attribute__((used))
static void bento_ex_ui_widget_mgr_count(void)
{
    /* Teardown path (GFX task): widgets down BEFORE the IPC restart
     * command, then verify the table is really empty. */
    ui_widget_mgr_clear_all();
 
    int live = ui_widget_mgr_count();
    if (live != 0) {
        /* Something re-created a widget between clear and check — the
         * clear-before-restart ordering was violated. Surface it; do
         * not silently continue into the restart. */
        return;
    }
 
    /* Table empty (0 of 32 handles) — safe to let CM33_NS repopulate. */
}

◆ ui_widget_mgr_list()

int ui_widget_mgr_list	(	ipc_ui_widget_info_t *	out,
		int	max_items )

Handle + type of every active widget — the ui.list() backend.

List all active widgets (handle + type).

Parameters

out	Output array of ipc_ui_widget_info_t.
max_items	Maximum items to fill.

Returns: Number of active widgets written to out.

Contract: Fills handle + type for every active widget, up to max_items (UI_MAX_WIDGETS in the switch), and returns the count written. GFX-task context.

MicroPython surface: ui.list() (modui.c:1432, bidirectional) and ui.get(id) (:1519), plus the internal re-sync in modui.c:138-153 and :291.

Dispatch pin: ipc_ui.c:660 case IPC_CMD_UI_LIST: / :664 int count = ui_widget_mgr_list(info, UI_MAX_WIDGETS);.

Variant: mtb-mpy and mtb-only

◆ ui_widget_mgr_get_parent()

lv_obj_t * ui_widget_mgr_get_parent ( void )

Nullable current parent; every call site null-checks it.

Get the current parent container object.

Returns: The LVGL parent object, or NULL if not set.

Contract: Nullable — every one of the five call sites null-checks the result. It is NULL whenever no page has bound a container: between ipc_ui_set_container(NULL) on destroy and the next page's bind. The identical three-line guard recurs at ipc_ui.c:443 (hide on first CREATE), :519 (unhide on POLL_EVENTS), :560 and :859 (the safety-timeout unhide when POLL_EVENTS never arrives). GFX-task context.

MicroPython surface: None — internal to the container-hiding protocol.

Variant: mtb-mpy and mtb-only

Origin: Lifted from BENTO-TESAIoT-libraries/claw/common/modules/ipc_ui/ipc_ui.c:516-524 (compiled into the prebuilt archive; not shipped as source).

◆ ui_widget_mgr_set_screen()

void ui_widget_mgr_set_screen	(	int16_t	width,
		int16_t	height )

Sets screen dimensions and resets the auto-layout grid.

Set screen dimensions and reset auto-layout grid.

Parameters

width	Screen width in pixels (auto-layout wraps at width - 100).
height	Screen height in pixels (reserved for future use).

Contract: Sets the screen dimensions and resets the auto-layout grid (auto-layout wraps at width - 100; height reserved). GFX-task context.

MicroPython surface: ui.screen(w, h) (modui.c:1647).

Dispatch pin: ipc_ui.c:672 case IPC_CMD_UI_SET_SCREEN: / :676 ui_widget_mgr_set_screen(w, h);.

Variant: mtb-mpy and mtb-only

◆ ui_widget_mgr_chart_add_series()

int ui_widget_mgr_chart_add_series	(	int	handle,
		uint32_t	color )

Adds a series to a Chart; returns index 0-3 or -1.

Add a series to a chart widget.

Parameters

handle	Widget handle (must be UI_WIDGET_CHART).
color	Series color (0xRRGGBB).

Returns: Series index (0-3) on success, -1 on error.

Contract: Adds a series to a Chart widget; returns the series index 0-3 or -1. The handle must be a UI_WIDGET_CHART. Bidirectional so the script learns the index. GFX-task context.

MicroPython surface: w.add_series(color) on a ui.Chart (modui.c:605, bidirectional).

Dispatch pin: ipc_ui.c:686 case IPC_CMD_UI_CHART_ADD_SERIES: / :691 int idx = ui_widget_mgr_chart_add_series(handle, color);.

Variant: mtb-mpy and mtb-only

◆ ui_widget_mgr_chart_set_next()

void ui_widget_mgr_chart_set_next	(	int	handle,
		uint8_t	series_idx,
		int32_t	value )

Appends the next value to one chart series.

Set next value for a specific chart series.

Parameters

handle	Widget handle (must be UI_WIDGET_CHART).
series_idx	Series index (0-3).
value	Data value.

Contract: Appends the next value to one chart series (index 0-3). GFX-task context.

MicroPython surface: w.set_next(series, value) (modui.c:631).

Dispatch pin: ipc_ui.c:700 case IPC_CMD_UI_CHART_SET_NEXT: / :706 ui_widget_mgr_chart_set_next(handle, series_idx, value);.

Variant: mtb-mpy and mtb-only

◆ ui_widget_mgr_item_add()

int ui_widget_mgr_item_add ( const ipc_ui_item_add_t * it )

Appends one item; overloaded returns, dual-implementation rule.

Append one item to a collection or container widget.

Parameters

it	Parsed ITEM_ADD payload; the meaning of a/b/flags/text is per widget type and is tabulated beside ui_widget_type_t.

Returns: >= 0 handle of the child page a container created (Tabview / Tileview / Win), UI_ITEM_ADD_OK_NO_CHILD item appended, no child object, -1 handle table full, -2 bad handle, wrong widget type, or the item could not be added.

Contract: Appends one item to a collection or container widget. Return values are overloaded and must be read in this order: >= 0 is the handle of a child page a container created (Tabview / Tileview / Win); UI_ITEM_ADD_OK_NO_CHILD (-3) means the item was appended with no child object; -1 table full; -2 bad handle, wrong type, or the item could not be added. The header's block comment is binding: this function "MUST exist, and behave the same way for the same widget type, in BOTH ui_widget_mgr.c implementations — claw's and game's", because the Game kits compile claw's ipc_ui.c against game's widget manager and a type served in one and not the other returns UI_STATUS_INVALID_TYPE on some boards with no build error anywhere. GFX-task context.

MicroPython surface: w.add_item, w.add_row, w.add_option, w.add_button, w.add_point, w.add_tab, w.add_tile, w.add_page, w.add_span, w.row, w.section, w.separator (modui.c:686 fire-and-forget, :694 bidirectional for the container forms).

Dispatch pin: ipc_ui.c:772 case IPC_CMD_UI_ITEM_ADD: / :782 int child = ui_widget_mgr_item_add(it);.

Variant: mtb-mpy and mtb-only

◆ ui_widget_mgr_item_clear()

void ui_widget_mgr_item_clear ( int handle )

Empties a collection widget.

Empty a collection widget (all rows / options / buttons / list entries). No-op on a bad handle or a widget type with no collection.

Contract: Empties a collection widget (all rows / options / buttons / list entries); no-op on a bad handle or a type with no collection. Same dual-implementation rule as item_add. GFX-task context.

MicroPython surface: w.clear_items() (modui.c:836).

Dispatch pin: ipc_ui.c:804 case IPC_CMD_UI_ITEM_CLEAR: / :805 ui_widget_mgr_item_clear(item->data[0]);.

Variant: mtb-mpy and mtb-only

◆ ui_widget_mgr_set_prop()

void ui_widget_mgr_set_prop	(	int	handle,
		uint8_t	prop_id,
		int32_t	value )

Sets one UI_PROP_* property; how .listen() subscribes to events.

Set one per-widget property.

Parameters

handle	Widget handle.
prop_id	UI_PROP_*.
value	Property value; two props carry a hi16/lo16 pair (see header).

Contract: Sets one per-widget property (UI_PROP_*); two props carry a hi16/lo16 pair in value. Same dual-implementation rule as item_add. The UI_PROP_EVENT_MASK property is how .listen() subscribes a widget to input events. GFX-task context.

MicroPython surface: w.prop(ui.PROP_*, value) and the named helpers w.ticks(), w.digits(), w.col_width(), w.listen(), w.opens(), w.pen(), w.month() (modui.c:856).

Dispatch pin: ipc_ui.c:810 case IPC_CMD_UI_SET_PROP: / :814 ui_widget_mgr_set_prop(p->handle, p->prop_id, value);.

Variant: mtb-mpy and mtb-only

◆ ui_widget_mgr_get_object()

lv_obj_t * ui_widget_mgr_get_object ( int handle )

LVGL object behind a handle; the GET_TEXT route for typed text.

The LVGL object behind a handle, or NULL if the slot is empty.

The manager IS the handle table, so answering this is its job. Nothing on the device calls it — it exists so a host harness can drive an object the way a finger would (lv_obj_send_event), which is the only way to photograph behaviour that only a tap can start, such as a menu row loading its page.

Contract: Returns the LVGL object behind a handle, or NULL for an empty slot. Two facts, both true and to be read together: the header says "Nothing on the device calls it — it exists so a host harness can drive an object the way a finger would"; and the pin-extraction pass found it dispatched from the GET_TEXT handler at ipc_ui.c:606 — not from a GET_OBJECT opcode — where the object is used to read the text a user typed into a textarea. The handler's own comment describes that route as "the only route by which anything a user TYPED reaches MicroPython" (ipc_ui.c:595-596). GFX-task context.

MicroPython surface: w.text() with no argument (modui.c:366, bidirectional) on a ui.Textarea / keyboard-backed widget.

Dispatch pin: ipc_ui.c:594 case IPC_CMD_UI_GET_TEXT: / :606 lv_obj_t *obj = ui_widget_mgr_get_object((int)handle);.

Variant: mtb-mpy and mtb-only

Functions

Detailed Description

Function Documentation

◆ ui_widget_mgr_init()

◆ ui_widget_mgr_set_parent()

◆ ui_widget_mgr_needs_container()

◆ ui_widget_mgr_create()

◆ ui_widget_mgr_create_sprite()

◆ ui_widget_mgr_set_sprite_image()

◆ ui_widget_mgr_delete()

◆ ui_widget_mgr_clear_all()

◆ ui_widget_mgr_set_text()

◆ ui_widget_mgr_set_value()

◆ ui_widget_mgr_set_position()

◆ ui_widget_mgr_set_size()

◆ ui_widget_mgr_set_color()

◆ ui_widget_mgr_set_visible()

◆ ui_widget_mgr_set_all_visible()

◆ ui_widget_mgr_get_value()

◆ ui_widget_mgr_set_dotmatrix()

◆ ui_widget_mgr_set_image()

◆ ui_widget_mgr_event_push()

◆ ui_widget_mgr_event_drain()

◆ ui_widget_mgr_count()

◆ ui_widget_mgr_list()

◆ ui_widget_mgr_get_parent()

◆ ui_widget_mgr_set_screen()

◆ ui_widget_mgr_chart_add_series()

◆ ui_widget_mgr_chart_set_next()

◆ ui_widget_mgr_item_add()

◆ ui_widget_mgr_item_clear()

◆ ui_widget_mgr_set_prop()

◆ ui_widget_mgr_get_object()