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 content_builder.register_standard() after core.init() to register all built-in builders under the `tuix` namespace. Builder constants are bytes matching the native builder names, for example content_builder.TEXT or content_builder.GRID.

uid = objects.create_object(
    content_builder.BUTTON,
    b'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 with grapheme awareness.
Interactive controls	BUTTON, CLICKABLE_TEXT, CHOICE, INPUT, CHECKBOX, MENU	Keyboard and mouse aware widgets with query/take state APIs.
Drawing	CANVAS	Manual pixel, line, rect, circle, text, and sprite drawing APIs.
Viewport widgets	SCROLL_CONTAINER, LIST_VIEW, TEXT_AREA	Widgets that own scroll offsets, content size, and clipping behavior.
Layout parents	ROW, COLUMN, SPLIT_PANE, 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 process keyboard and pointer input during the native frame loop. Application logic queries and consumes widget event states using one-shot getters (such as `tuix_button_take_pressed()`, `tuix_checkbox_take_changed()`, `tuix_choice_is_confirmed()`, `tuix_input_is_submitted()`, or `tuix_listview_take_activated()`).

Snapshots

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