Builders API

The builders module (tuix.core.builders) provides constants for the four built-in widget types and a function to register them with the engine.

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.

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 (subcycle handler)
build_content	Render widget state into a pixel buffer
on_resize	Optional: called when terminal dimensions change

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).