Widgety

Widgety jsou interaktivní prvky renderované do terminálu. Každý widget je instancí builder typu, žije ve scéně a má unikátní celočíselné UID.

Systém builderů

Typy widgetů jsou definované pomocí builderů — polymorfního vzoru implementovaného v C. Každý builder poskytuje pět callbacků: create_state (alokace stavu widgetu), destroy_state (uvolnění stavu), handler_func (logika aktualizace na snímek), build_content (render stavu do pixelového bufferu) a on_resize (volitelné oznámení změny geometrie).

TUIX obsahuje čtyři vestavěné buildery, registrované voláním builders.register_standard(). Konstanty builderů jsou byte stringy používané při vytváření widgetů:

Vytvoření widgetu

uid = objects.create_object(
    builders.CHOICE,   # builder name (bytes)
    b"main",           # scene name (bytes)
    0.4,               # width_mod: fraction of terminal width
    0.5,               # height_mod: fraction of terminal height
    0.25,              # margin_top_mod: fraction from top
    0.3                # margin_left_mod: fraction from left
)

Všech šest parametrů je povinných. Čtyři float modifikátory (width_mod, height_mod, margin_top_mod, margin_left_mod) jsou proporční hodnoty mezi 0.0 a 1.0, vynásobené rozměry terminálu v každém snímku.

Proporcionální geometrie

Rozměry widgetů nejsou pevné počty pixelů. Jsou to zlomky velikosti terminálu, vypočítávané každý snímek řešičem geometrie:

buffer.width       = terminal_width  × object.width_mod
buffer.height      = terminal_height × object.height_mod
buffer.margin_left = terminal_width  × object.margin_left_mod
buffer.margin_top  = terminal_height × object.margin_top_mod

To znamená, že se widgety automaticky přizpůsobí změně velikosti terminálu. Widget s width_mod=0.5 vždy zabírá polovinu šířky terminálu.

Přístup k objektům widgetů

Pro volání funkcí specifických pro widget (set options, feed input atd.) potřebujete ukazatel TuixObject. Získáte ho přes buffer:

buf = buffers.get_buffer_by_uid(uid)
obj = buf.contents.obj.contents

# Now use widget-specific functions
objects.tuix_choice_set_options(obj, [b"A", b"B", b"C"])

Životní cyklus widgetu

1. Create: objects.create_object() → alokuje objekt, buffer a registruje subcycle handler
2. Configure: volejte widget-specific set funkce (set_options, set_value, set_placeholder atd.)
3. Render: engine.main_loop() vypočítá geometrii, zavolá build_content, zkomponuje a vyrenderuje
4. Input: vezměte snapshot přes input.get_snapshot(), pošlete do widgetu přes feed_input()
5. Query: zkontrolujte is_confirmed/is_submitted, get_selected/get_text/get_result
6. Reset (volitelné): widget-specific reset() pro opětovné použití bez znovuvytvoření
7. Destroy: buffers.free_buffer(scene, uid) uvolní buffer a stav

Obsluhy subcyklů

Každý widget má handler funkci, která běží každý snímek v rámci systému subcyklů. Handler vrací TuixHandlerResponse s příznakem requires_redraw. Pokud handler označí potřebu překreslení (např. po změně stavu), buffer widgetu se v tom snímku znovu vygeneruje. Jinak se použije předchozí pixelový buffer.