Začínáme s TUIX Core

Tento průvodce pokrývá předpoklady, základní způsob importu a standardní workflow pro tvorbu terminálových UI s TUIX Core v0.2.0.

Doporučené pořadí čtení

1. Nainstalujte balíček a ověřte, že engine.init() na vašem systému funguje.
2. Projďte si workflow na této stránce, abyste pochopili model scéna -> widget -> hlavní smyčka.
3. Než se ponoříte do low-level API stránek, postavte si Choice příklad z Prvního widgetu.

Předpoklady

• Python 3.10 nebo novější
• Terminál, který podporuje ANSI escape sekvence (většina moderních terminálů)
• Doporučuje se podpora Truecolor (24-bit RGB); automaticky je k dispozici fallback na ANSI256 a ANSI16

Způsob importu

TUIX Core vystavuje API přes jednotlivé moduly pod tuix.core. Neexistuje jediná top-level třída — importujete jen moduly, které potřebujete.

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

Standardní workflow

Každá aplikace TUIX postupuje v této sekvenci:

1. Inicializujte engine pomocí engine.init()
2. Zaregistrujte vestavěné typy widgetů pomocí builders.register_standard()
3. Vytvořte scénu pomocí scenes.init_scene(b"scene_name")
4. Nastavte aktivní scénu přes registry.registry.current_scene_name = b"scene_name"
5. Spusťte posluchač vstupu pomocí input.listen()
6. Vytvořte widgety pomocí objects.create_object(builder, scene, width, height, margin_top, margin_left)
7. Nakonfigurujte widgety pomocí jejich specifických API funkcí
8. Spusťte engine.main_loop() ve smyčce pro renderování snímků a zpracování vstupu
9. Uklid: uvolněte buffery, zastavte vstup a ukončete engine

Minimální příklad

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

# 1. Initialize
engine.init()
builders.register_standard()

# 2. Create and select a scene
scenes.init_scene(b"main")
registry.registry.current_scene_name = b"main"

# 3. Start input
input.listen()

# 4. Create a progressbar widget (full width, 10% height, centered at top)
uid = objects.create_object(
    builders.PROGRESSBAR, b"main",
    0.5, 0.1,   # width_mod, height_mod
    0.1, 0.25   # margin_top_mod, margin_left_mod
)

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

# 6. Set progress value
objects.tuix_progressbar_set_value(obj, 0.5)

# 7. Render loop
for i in range(100):
    objects.tuix_progressbar_set_value(obj, i / 100.0)
    engine.main_loop()
    time.sleep(0.03)

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

Co se děje v každém snímku

Každé volání engine.main_loop() spouští v C tento pipeline:

1. Načíst rozměry terminálu (detekce změny velikosti)
2. Potvrdit čekající dávkové příkazy
3. Spustit subcycle handlery pro aktivní widgety (stavové aktualizace, zpracování vstupu)
4. Vyřešit geometrii: vynásobit modifikátory widgetů velikostí terminálu
5. Zavolat build_content každého widgetu pro vytvoření pixelových bufferů
6. Zkompozitovat všechny buffery scén do finálního framebufferu
7. Delta-renderovat změněné řádky do terminálu

Další kroky

Přejděte na Instalaci pro instrukce nastavení a poté pokračujte tutoriálem První widget, kde vytvoříte interaktivní výběrové menu od nuly.