Choice Widget
A keyboard-navigable selection menu. Users move through options with Up/Down arrow keys and confirm with Enter.
Creating a Choice Widget
from tuix.core import builders, objects, buffers
uid = objects.create_object(
builders.CHOICE, b"main",
0.4, 0.5, # width: 40%, height: 50%
0.25, 0.3 # margin_top: 25%, margin_left: 30%
)
buf = buffers.get_buffer_by_uid(uid)
obj = buf.contents.obj.contentsAPI Functions
tuix_choice_set_options(obj, labels)
Sets the list of selectable options. Labels are deep-copied by the C layer.
| Parameter | Type | Description |
|---|---|---|
| obj | TuixObject | Object pointer |
| labels | list[bytes] | List of byte string labels for each option |
objects.tuix_choice_set_options(obj, [b"Red", b"Green", b"Blue"])tuix_choice_feed_input(obj, snapshot)
Compatibility API: manually processes an input snapshot. Handles Up/Down arrow keys for navigation and Enter for confirmation. In standard v0.3 flows, this is handled automatically in the frame pipeline.
| Parameter | Type | Description |
|---|---|---|
| obj | TuixObject | Object pointer |
| snapshot | TuixInputSnapshot | Input snapshot from input.get_snapshot() |
tuix_choice_is_confirmed(obj)
Returns whether the user has confirmed a selection by pressing Enter.
| Returns | Description |
|---|---|
| bool | True if Enter was pressed, False otherwise |
tuix_choice_get_selected(obj)
Returns the 0-based index of the currently highlighted option.
| Returns | Description |
|---|---|
| int | 0-based index of the selected option, or -1 if no selection |
tuix_choice_get_result(obj)
Returns the confirmed selection index. Only valid after is_confirmed returns True.
| Returns | Description |
|---|---|
| int | 0-based index of the confirmed option, or -1 if not yet confirmed |
tuix_choice_reset(obj)
Resets the widget: clears confirmation state and moves selection back to index 0. Useful for reusing the same choice widget for multiple selections.
Complete Example
from tuix.core import engine, builders, scenes, registry, objects, buffers, input
engine.init()
builders.register_standard()
scenes.init_scene(b"main")
registry.registry.current_scene_name = b"main"
input.listen()
uid = objects.create_object(builders.CHOICE, b"main", 0.4, 0.5, 0.25, 0.3)
buf = buffers.get_buffer_by_uid(uid)
obj = buf.contents.obj.contents
options = [b"Red", b"Green", b"Blue", b"Yellow", b"Cyan"]
objects.tuix_choice_set_options(obj, options)
# Automatic input handling in v0.3
while True:
engine.main_loop()
if objects.tuix_choice_is_confirmed(obj):
break
selected = objects.tuix_choice_get_selected(obj)
print(f"Selected: {options[selected].decode()}")
buffers.free_buffer(b"main", uid)
scenes.free_scene(b"main")
input.stop()
engine.shutdown()