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 třináct vestavěných builderů, registrovaných voláním builders.register_standard(). Konstanty builderů jsou byte stringy používané při vytváření widgetů:
| Konstanta | Hodnota | Typ widgetu |
|---|---|---|
| builders.PROGRESSBAR | b"ProgressBarBuilder" | Horizontální plnící pruh s vlastními znaky a barvami |
| builders.CHOICE | b"ChoiceBuilder" | Seznamové menu ovládané klávesnicí |
| builders.INPUT | b"InputBuilder" | Jednořádkový textový vstup s podporou placeholderu |
| builders.CANVAS | b"CanvasBuilder" | Volná kreslicí plocha pro pixely, čáry, obdélníky, kruhy, text a sprity |
| builders.TEXT | b"TextBuilder" | Vložený text s průběžnou aktualizací fg/bg barev |
| builders.BOX | b"BoxBuilder" | Rámovaný kontejner s titulkem a ovládáním barev |
| builders.DIVIDER | b"DividerBuilder" | Horizontální nebo vertikální oddělovač s vlastním symbolem a barvou |
| builders.BADGE | b"BadgeBuilder" | Kompaktní štítek s paletou popředí/pozadí |
| builders.BUTTON | b"ButtonBuilder" | Klikatelné tlačítko aktivovatelné klávesnicí |
| builders.ICON | b"IconBuilder" | Vycentrovaný symbol/ikona s nastavitelnými barvami |
| builders.TAG | b"TagBuilder" | Štítek ve stylu chipu s nastavitelnými závorkami |
| builders.STATUS | b"StatusBuilder" | Widget pro zobrazení stavu IDLE/OK/WARN/ERROR |
| builders.MENU | b"MenuBuilder" | Interaktivní menu s výběrem klávesnicí a myší |
| builders.SCROLL_CONTAINER | b"ScrollContainerBuilder" | Posuvné okno nad virtuálním obsahem |
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_modTo 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
- Create: objects.create_object() → alokuje objekt, buffer a registruje subcycle handler
- Configure: volejte widget-specific set funkce (set_options, set_value, set_placeholder atd.)
- Render: engine.main_loop() vypočítá geometrii, zavolá build_content, zkomponuje a vyrenderuje
- Input: ve v0.4 je pro vestavěné buildery zpracován automaticky ve frame loopu
- Query: zkontrolujte is_confirmed/is_submitted, get_selected/get_text/get_result
- Reset (volitelné): widget-specific reset() pro opětovné použití bez znovuvytvoření
- Destroy: buffers.free_buffer(scene, uid) uvolní buffer a stav
Interní frame handlery
Každý widget má interní handler callback spouštěný v každém snímku. Řídí aktualizace stavu, signalizaci překreslení a chování zpracování vstupu builderu. Tyto řídicí objekty jsou ve v0.4 interní implementační detail.