Zpět na projekty
TUIX v0.2.0Beta

Naposledy aktualizováno: 2026-05-20

Váš první widget

Tento tutoriál vytváří kompletní interaktivní výběrové menu od nuly — inicializace enginu, vytvoření widgetu, práce se vstupem a získání výsledku.

Co postavíte

  • Scénu s jedním Choice widgetem
  • Vstupní smyčku reagující na šipky a Enter
  • Korektní ukončení, které uvolní buffery, scény i posluchač vstupu
Než příklad spustíteUjistěte se, že už máte za sebou stránku Instalace a že vám v terminálu funguje krátký ověřovací snippet s engine.init().

Krok 1: Inicializujte engine

from tuix.core import engine, builders, scenes, registry, objects, buffers, input

engine.init()
builders.register_standard()

engine.init() inicializuje C jádro a globální registry. builders.register_standard() zaregistruje čtyři vestavěné typy widgetů: ProgressBarBuilder, ChoiceBuilder, InputBuilder a CanvasBuilder.

Krok 2: Vytvořte scénu

scenes.init_scene(b"main")
registry.registry.current_scene_name = b"main"

Scény jsou kontejnery pro widgety. Před vytvořením widgetů musíte vytvořit alespoň jednu scénu a nastavit ji jako aktivní. Názvy scén jsou bajtové řetězce.

Krok 3: Spusťte posluchač vstupu

input.listen()

Tímto se spustí vlákno na pozadí, které zachytává události klávesnice a myši. Události se ukládají do fronty a během main loopu se zpracovávají jako snímky.

Krok 4: Vytvořte widget Volba

uid = objects.create_object(
    builders.CHOICE,   # Widget type
    b"main",           # Scene name
    0.4,               # width_mod: 40% of terminal width
    0.5,               # height_mod: 50% of terminal height
    0.25,              # margin_top_mod: 25% from top
    0.3                # margin_left_mod: 30% from left
)

# Get the object pointer for widget-specific operations
buf = buffers.get_buffer_by_uid(uid)
obj = buf.contents.obj.contents

create_object vrací unikátní celé číslo UID. Všechny rozměry jsou proporční modifikátory (0.0–1.0) aktuální velikosti terminálu. Pro volání funkcí specifických pro widget získejte ukazatel na objekt přes get_buffer_by_uid.

Krok 5: Nastavte možnosti

options = [b"Red", b"Green", b"Blue", b"Yellow", b"Cyan"]
objects.tuix_choice_set_options(obj, options)

Možnosti se předávají jako seznam bajtových řetězců. C vrstva popisky hluboce zkopíruje, takže Python seznam můžete po volání zahodit.

Krok 6: Render smyčka se vstupem

while True:
    snap = input.get_snapshot()
    objects.tuix_choice_feed_input(obj, snap)
    engine.main_loop()

    if objects.tuix_choice_is_confirmed(obj):
        break

V každé iteraci: získejte snímek vstupu, předejte ho widgetu Volba (zpracuje šipky a Enter), spusťte render pipeline a zkontrolujte potvrzení volby.

Častá chybaNeukončujte program hned po skončení smyčky bez úklidu. Bezpečné pořadí je: uvolnit buffer widgetu, uvolnit scénu, zastavit vstup a až potom vypnout engine.

Krok 7: Získejte výsledek a ukliďte

selected = objects.tuix_choice_get_selected(obj)
print(f"Selected index: {selected}")
print(f"Selected option: {options[selected].decode()}")

buffers.free_buffer(b"main", uid)
scenes.free_scene(b"main")
input.stop()
engine.shutdown()

tuix_choice_get_selected vrací index potvrzené volby od 0. Před ukončením vždy uvolněte buffery i scény.

Kompletní kód

from tuix.core import engine, builders, scenes, registry, objects, buffers, input

# Initialize
engine.init()
builders.register_standard()
scenes.init_scene(b"main")
registry.registry.current_scene_name = b"main"
input.listen()

# Create choice widget
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

# Configure options
options = [b"Red", b"Green", b"Blue", b"Yellow", b"Cyan"]
objects.tuix_choice_set_options(obj, options)

# Render loop
while True:
    snap = input.get_snapshot()
    objects.tuix_choice_feed_input(obj, snap)
    engine.main_loop()
    if objects.tuix_choice_is_confirmed(obj):
        break

# Result
selected = objects.tuix_choice_get_selected(obj)
print(f"You chose: {options[selected].decode()}")

# Cleanup
buffers.free_buffer(b"main", uid)
scenes.free_scene(b"main")
input.stop()
engine.shutdown()

Další kroky

Prozkoumejte přehled Widgetů, kde najdete všechny čtyři typy, nebo přejděte rovnou na Canvas API pro volnou kresbu.

Jste připraveni na referenční stránkyJakmile vám tento příklad dává smysl, API stránky se čtou mnohem snáz, protože už rozumíte běhovému flow: init -> scéna -> widget -> vstup -> main_loop -> cleanup.