Core engine a probing terminálu

Balíček `tuix.core.core` spravuje životní cyklus runtime na úrovni procesu, smyčky vykonávání, synchronizaci vláken a cachování scén. Balíček `tuix.core.tuix` poskytuje probing terminálu, detekci schopností, měření buněk Unicode grafémů a runtime konfiguraci terminálu.

Životní cyklus Core Engine

Funkce	Popis	Účel a návratová hodnota
core.tuix_core_init() -> int	Inicializuje nativní engine, registr a paměťové fondy.	Musí být zavoláno před tvorbou scén nebo builderů. Vrací TUIX_RC_OK (0).
core.tuix_core_shutdown() -> int	Ukončí nativní engine a uklidí prostředky registru.	Volejte při ukončení aplikace po zastavení listenerů.
core.tuix_core_loop_run() -> None	Vykoná jednu kompletní iteraci snímku: směrování vstupu, řešení layoutu, aktualizace builderů, kompozici a delta vykreslování.	Klíčový krok vykonávání v synchronních aplikačních smyčkách.
core.tuix_core_pipeline_tick(scene_name: bytes) -> int	Spustí jeden tick pipeline pro konkrétní scénu.	Umožňuje vlastním orchestrátorům provádět tick jednotlivých scén bez globální smyčky.
core.tuix_core_lock() -> None	Zamkne globální mutex nativního jádra.	Zaručuje vláknovou bezpečnost při úpravách stromů scén nebo objektů z vedlejších pracovních vláken.
core.tuix_core_unlock() -> None	Odemkne globální mutex nativního jádra.	Uvolní mutex po úpravách z vedlejšího vlákna.
core.tuix_cache_scenes() -> None	Vytvoří snapshot aktivních scén do nativní mezipaměti.	Uloží stav scén před přepnutím na modální scénu.
core.tuix_restore_scenes() -> None	Obnoví scény z nativní mezipaměti.	Obnoví předchozí hierarchii scén.
core.tuix_core_time_now_us() -> int	Vrací monotónní čas ve vysokém rozlišení v mikrosekundách.	Používá se pro přesné časování snímků, profilování a animace.
core.tuix_core_loop_get_stats() -> dict	Vrací detailní slovník výkonnostních metrik z vykonání posledního snímku.	Obsahuje frame_counter, batch_commit_ms, buffer_ms, composite_ms, total_ms, traversal_cache_hit, traversal_cache_miss atd.
core.tuix_mouse_capture_start(uid: int) -> None	Spustí výhradní zachycení událostí myši pro dané UID widgetu.	Směruje události ukazatele výhradně do zachytávajícího widgetu během přetahování.
core.tuix_mouse_capture_stop(uid: int) -> None	Ukončí výhradní zachycení událostí myši pro dané UID widgetu.	Uvolní capture, aby se obnovilo běžné směrování hitmapy.
core.tuix_mouse_capture_get_uid() -> int	Vrátí UID widgetu, který aktuálně zachytává události myši, nebo 0.	Zjišťuje aktivní stav zachycení.

Probing a konfigurace terminálu (tuix.core.tuix)

Balíček `tuix.core.tuix` komunikuje přímo s emulátorem terminálu pro zjištění podporovaných funkcí (šířky širokých znaků, vykreslování emoji, RGB truecolor, dotazy na pozici kurzoru a politiky ASCII fallbacku).

Funkce	Popis	Účel
tuix.tuix_terminal_prepare() -> int	Připraví terminál pro raw režim, zapne alternativní obrazovku a vypne echo.	Inicializuje prostředí terminálu před spuštěním UI smyčky.
tuix.tuix_terminal_probe() -> int	Odešle escape sekvence pro zjištění rozměrů terminálu, odezvy kurzoru a schopností Unicode.	Dynamicky přizpůsobuje renderovací strategie schopnostem terminálu.
tuix.tuix_terminal_select_policy() -> int	Vybere politiku renderování a fallbacku symbolů na základě výsledků probingu.	Zajišťuje, aby široké/emoji znaky nerozbíjely layout terminálu.
tuix.tuix_terminal_get_info() -> dict	Vrací slovník s informacemi o detekovaném emulátoru terminálu, kódování a příznacích probingu.	Diagnostické dotazování na schopnosti a prostředí.
tuix.tuix_terminal_config_set_probe_mode(mode: int)	Nakonfiguruje režim probingu terminálu (např. striktní, rychlý nebo vypnutý).	Řídí režii probingu při spouštění.
tuix.tuix_terminal_config_set_ascii_fallback(enabled: bool)	Vynutí fallback na ASCII znaky pro rámečky a okraje, pokud terminál nepodporuje Unicode.	Zaručuje čitelné zobrazení na legacy terminálech.
tuix.tuix_terminal_restore() -> None	Obnoví původní stav terminálu, viditelnost kurzoru a opustí alternativní obrazovku.	Musí být spuštěno při ukončení aplikace.

Unicode a probing kódových bodů

Funkce	Popis
tuix.tuix_codepoint_cell_width(cp: int) -> int	Vrátí šířku v buňkách terminálu (0, 1 nebo 2) pro daný Unicode kódový bod.
tuix.tuix_text_cell_count(s: bytes) -> int	Spočítá celkovou viditelnou šířku v buňkách pro UTF-8 kódovaný řetězec.
tuix.tuix_codepoint_is_box(cp: int) -> int	Vrátí nenulovou hodnotu, pokud je kódový bod znakem pro kreslení rámečků.
tuix.tuix_codepoint_is_wide(cp: int) -> int	Vrátí nenulovou hodnotu, pokud kódový bod zabírá 2 buňky terminálu (East Asian Wide / Fullwidth).
tuix.tuix_codepoint_is_emoji(cp: int) -> int	Vrátí nenulovou hodnotu, pokud je kódový bod emoji symbolem.
tuix.tuix_codepoint_is_combining(cp: int) -> int	Vrátí nenulovou hodnotu, pokud je kódový bod kombinujícím znaménkem nebo diakritikou s nulovou šířkou.

Standardní spouštěcí sekvence aplikace

from tuix.core import core, scene, content_builder, input, tuix

# 1. Prepare terminal & probe environment
tuix.tuix_terminal_prepare()
tuix.tuix_terminal_probe()

# 2. Initialize core engine & builders
core.tuix_core_init()
content_builder.tuix_builder_register_standard()

# 3. Setup scenes & input
scene.tuix_scene_init(b'Main')
scene.tuix_scene_select(b'Main')
input.tuix_input_start()

# 4. Main loop execution
while running:
    core.tuix_core_loop_run()

# 5. Clean teardown
input.tuix_input_stop()
core.tuix_core_shutdown()
tuix.tuix_terminal_restore()