Widgets

Widgets are native builders plus per-object state. Python creates objects and calls typed setter/getter APIs; the C builder owns per-frame event handling, layout, resize, and pixel generation.

Builder System

Call builders.register_standard() after engine.init() to register all built-in builders. Builder constants are bytes matching the native builder names, for example builders.TEXT or builders.GRID.

uid = objects.create_object(
    builders.BUTTON,
    'Main',
    0.25, 0.08,  # width_mod, height_mod
    0.1, 0.1     # margin_top_mod, margin_left_mod
)
button = objects.get_object_by_uid(uid)
objects.tuix_button_set_label(button, 'Run')

Proportional Geometry

For normal objects, width_mod, height_mod, margin_top_mod, and margin_left_mod are fractions of the terminal. For layout children, parent builders can override final rectangles through layout slots, grid placement, and layout rect APIs.

Widget Categories

Category	Builders	Notes
Basic display	TEXT, BOX, DIVIDER, BADGE, TAG, STATUS	Labels, frames, dividers, and simple styled text.
Interactive controls	BUTTON, CHOICE, INPUT, CHECKBOX, MENU	Keyboard and mouse aware widgets with query/take state APIs.
Drawing	CANVAS	Manual pixel and primitive drawing APIs.
Viewport widgets	SCROLL_CONTAINER, LISTVIEW, TEXTAREA	Widgets that own scroll offsets, content size, and clipping behavior.
Layout parents	ROW, COLUMN, SPLITPANE, GRID	Native containers that place child buffers.
Modal UI	DIALOG	Dialog body, backdrop, focus trapping, and close request state.

Input Handling

Built-in interactive widgets are handled by the frame loop. Compatibility feed_input functions still exist for older code, but normal v0.5 usage starts input.listen(), sets focus where needed, and calls engine.main_loop().

Snapshots

Use buffers.get_buffer_snapshot(...), buffers.get_buffer_snapshot_by_uid(...), and objects.get_object_snapshot_by_uid(...) for read-only inspection. Avoid relying on raw native pointers for diagnostics.