Builders API

The builders module (tuix.core.builders) provides constants for the four built-in widget types and registration helpers. In v0.3, builders also process input natively via their callbacks.

builders.register_standard()

from tuix.core import builders

result = builders.register_standard()

Registers all four built-in widget builders with the engine. Must be called after engine.init() and before creating any widgets. In v0.3, these builders are input-aware and integrate with automatic input handling in the frame loop.

Returns	Description
int	0 on success, -1 on failure

Builder Constants

These byte string constants identify widget types when calling objects.create_object():

Constant	Value	Widget Type
builders.CANVAS	b"CanvasBuilder"	Free-draw surface with pixel-level control
builders.CHOICE	b"ChoiceBuilder"	Keyboard-navigable selection menu
builders.INPUT	b"InputBuilder"	Single-line text entry with cursor
builders.PROGRESSBAR	b"ProgressBarBuilder"	Animated fill bar with customizable styling

Usage

from tuix.core import builders, objects

# Create one of each widget type
progressbar_uid = objects.create_object(builders.PROGRESSBAR, b"main", 0.5, 0.1, 0.0, 0.25)
choice_uid      = objects.create_object(builders.CHOICE,      b"main", 0.4, 0.5, 0.2, 0.3)
input_uid       = objects.create_object(builders.INPUT,       b"main", 0.4, 0.1, 0.8, 0.3)
canvas_uid      = objects.create_object(builders.CANVAS,      b"main", 1.0, 1.0, 0.0, 0.0)

Builder Internals

Each builder is a C struct (TuixBuilder) with metadata and five callback function pointers:

Callback	Purpose
create_state	Allocate and initialize per-widget state
destroy_state	Free per-widget state
handler_func	Per-frame update logic, including native input processing
build_content	Render widget state into a pixel buffer
on_resize	Optional: called when terminal dimensions change

v0.3 Input ModelManual calls such as objects.tuix_choice_feed_input() and objects.tuix_input_feed_input() remain available for compatibility, but the standard v0.3 flow is automatic input handling through builder callbacks.

Builders are looked up by name via linear search (tuix_get_builder_by_name). With only four built-in builders, this is effectively O(1).