TUIX v0.4Beta
Builders API
The builders module (tuix.core.builders) provides constants for the built-in widget types and registration helpers. In v0.4, builders also process input natively via their callbacks.
builders.register_standard()
from tuix.core import builders
result = builders.register_standard()Registers all built-in widget builders with the engine. Must be called after engine.init() and before creating any widgets. In v0.4, 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.PROGRESSBAR | b"ProgressBarBuilder" | Horizontal fill bar with custom chars and colours |
| builders.CHOICE | b"ChoiceBuilder" | Keyboard-navigable list menu |
| builders.INPUT | b"InputBuilder" | Single-line text input with placeholder support |
| builders.CANVAS | b"CanvasBuilder" | Free-draw surface for pixels, lines, rects, circles, text, and sprites |
| builders.TEXT | b"TextBuilder" | Inline text content with runtime fg/bg updates |
| builders.BOX | b"BoxBuilder" | Framed container with title and color controls |
| builders.DIVIDER | b"DividerBuilder" | Horizontal or vertical divider with custom symbol and color |
| builders.BADGE | b"BadgeBuilder" | Compact label with foreground/background palette |
| builders.BUTTON | b"ButtonBuilder" | Clickable and keyboard-activatable button state |
| builders.ICON | b"IconBuilder" | Centered symbol/icon with configurable colours |
| builders.TAG | b"TagBuilder" | Chip-style label with configurable brackets |
| builders.STATUS | b"StatusBuilder" | IDLE/OK/WARN/ERROR status display widget |
| builders.MENU | b"MenuBuilder" | Interactive menu with keyboard and mouse selection |
| builders.SCROLL_CONTAINER | b"ScrollContainerBuilder" | Scrollable viewport over virtual content |
Usage
from tuix.core import builders, objects
# Create a mix of built-in widget types
text_uid = objects.create_object(builders.TEXT, b"main", 0.3, 0.1, 0.0, 0.0)
box_uid = objects.create_object(builders.BOX, b"main", 0.4, 0.3, 0.1, 0.1)
button_uid = objects.create_object(builders.BUTTON, b"main", 0.2, 0.1, 0.5, 0.1)
menu_uid = objects.create_object(builders.MENU, b"main", 0.3, 0.4, 0.1, 0.5)
scroll_uid = objects.create_object(builders.SCROLL_CONTAINER, b"main", 0.5, 0.5, 0.4, 0.3)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.4 Input ModelManual calls such as objects.tuix_choice_feed_input() and objects.tuix_input_feed_input() remain available for compatibility, but the standard v0.4 flow is automatic input handling through builder callbacks and hitmap-based focus routing.
Builders are looked up by name via linear search (tuix_get_builder_by_name). With a small fixed set of built-in builders, this is effectively O(1).