API scén

Modul scenes (tuix.core.scenes) spravuje životní cyklus scén, dotazy nad scénami a směrování fokusu mezi interaktivními widgety.

scenes.init_scene(name)

from tuix.core import scenes

result = scenes.init_scene(b"main")

Parametr	Typ	Popis
name	bytes	Unikátní název scény

Návratová hodnota	Popis
int	0 při úspěchu, 1 pokud název scény již existuje

Vytvoří novou scénu se zadaným názvem. Scény používají exponenciální růst pro interní pole bufferů (počáteční kapacita 4, zdvojnásobení při přetečení). Duplicitní názvy jsou odmítnuty.

scenes.free_scene(name)

scenes.free_scene(b"main")

Parametr	Typ	Popis
name	bytes	Název scény k odstranění

Zruší scénu a uvolní všechny její buffery a související paměť. Po tomto volání nelze scénu použít.

scenes.clear_scene(name)

scenes.clear_scene(b"main")

Parametr	Typ	Popis
name	bytes	Název scény k vyčištění

Uvolní všechny buffery ve scéně, ale ponechá strukturu scény alokovanou. Použijte to pro odstranění všech widgetů ze scény bez zrušení samotné scény. Po vyčištění lze do scény přidat nové widgety.

scenes.get_scene(name)

scene_ptr = scenes.get_scene(b"main")

Parametr	Typ	Popis
name	bytes \| str	Název scény k vyhledání

Návratová hodnota	Popis
int	Adresa nativního ukazatele na scénu (0 pokud nebyla nalezena)

scenes.get_scenes()

all_scenes = scenes.get_scenes()

Vrátí Python pohled na kolekci scén z nativní vrstvy, kterou zpřístupňuje Cython most.

scenes.set_focus(scene_name, uid)

scenes.set_focus(b"main", input_uid)

Parametr	Typ	Popis
scene_name	bytes \| str	Cílová scéna
uid	int	UID widgetu, který má dostat fokus vstupu

Návratová hodnota	Popis
int	0 při úspěchu, nenulová hodnota při chybě

Směrování fokusu je lokální pro scénu. Použijte to, když je v jedné scéně více interaktivních widgetů a vstup z klávesnice má zpracovat jen jeden z nich.

scenes.set_previous_focus(scene_name)

scenes.set_previous_focus(b"main")

Obnoví předchozí fokusovaný widget v dané scéně.

scenes.get_scene_stats(scene_name)

stats = scenes.get_scene_stats(b"main")

Návratová hodnota	Popis
dict \| None	Slovník statistik scény obsahující: buffer_count, active, current_focus, last_active_frame, last_compacted_frame, pixel_bytes, approx_heap_bytes

scenes.compact_scene_pixels(scene_name)

freed_bytes = scenes.compact_scene_pixels(b"main")

Návratová hodnota	Popis
int	Počet pixelových bajtů uvolněných konzervativní kompaktací scény

scenes.compact_cold_scenes(cold_frames, min_pixel_bytes, keep_active_scene=True)

count = scenes.compact_cold_scenes(120, 64 * 1024, keep_active_scene=True)

Parametr	Typ	Popis
cold_frames	int	Minimální okno neaktivity ve framech
min_pixel_bytes	int	Kompaktovat pouze scény s alespoň tímto počtem pixelových bajtů
keep_active_scene	bool	Pokud je True, přeskočit aktuálně aktivní scénu

Návratová hodnota	Popis
int	Počet kompaktovaných scén

Data-first cache strategiev0.3 preferuje měření a kompaktaci studených scén před eager globální cache. Začněte get_scene_stats() a pak kompakujte selektivně.

Příklad: přepínání scén

from tuix.core import scenes, registry

# Create scenes
scenes.init_scene(b"menu")
scenes.init_scene(b"form")

# ... create widgets and remember their UIDs ...
choice_uid = 101
input_uid = 102

# Start with menu scene
registry.registry.current_scene_name = b"menu"
scenes.set_focus(b"menu", choice_uid)

# Later switch focus to input widget
scenes.set_focus(b"menu", input_uid)

# Switch scene
registry.registry.current_scene_name = b"form"

# Restore prior focus in menu when returning
registry.registry.current_scene_name = b"menu"
scenes.set_previous_focus(b"menu")

# Clean up
scenes.free_scene(b"menu")
scenes.free_scene(b"form")