TUIX v0.5Beta
Scenes API
The scenes module owns scene lifecycle, selection, focus, modal state, transactions, stats, and compaction.
| Method | How to use it | Why it exists |
|---|---|---|
| scenes.init_scene(name: bytes | str) -> int | Create each named screen before adding objects to it. | Allocates a scene container for buffers, focus, modal state, and stats. |
| scenes.free_scene(name: bytes | str) -> None | Call when a scene is no longer needed. | Removes the scene and frees its native resources. |
| scenes.clear_scene(name: bytes | str) -> None | Use to remove all buffers but keep the scene name reusable. | Resets scene contents without destroying the scene object. |
| scenes.get_scene(name: bytes | str) -> int | Use only for advanced diagnostics that need the native pointer value. | Provides escape-hatch access for low-level integrations. |
| scenes.get_scenes() -> list | Read when building scene switchers or debugging scene lifecycle. | Reports registered scene names. |
| scenes.select_scene(name: bytes | str) -> int | Switch active rendering and input target to a scene. | Makes scene switching explicit and avoids direct registry mutation. |
| scenes.set_focus(scene_name: bytes | str, uid: int) -> int | Set keyboard focus before expecting a widget to handle keys. | Separates keyboard routing from visual hitmap picking. |
| scenes.set_previous_focus(scene_name: bytes | str) -> int | Restore focus after temporary controls or modals. | Keeps focus history in the scene instead of duplicating it in app code. |
| scenes.activate_modal(scene_name: bytes | str, uid: int) -> int | Activate a dialog or modal container UID. | Constrains input and focus routing to the active modal flow. |
| scenes.deactivate_modal(scene_name: bytes | str, uid: int) -> int | Call when the modal closes or should release focus. | Restores normal scene routing after modal interaction. |
| scenes.get_active_modal(scene_name: bytes | str) -> int | Check whether a scene currently has an active modal UID. | Supports modal diagnostics and application-level coordination. |
| scenes.begin_transaction(scene_name: bytes | str) -> int | Start before applying a batch of related widget updates. | Groups state changes so the scene can commit them coherently. |
| scenes.commit_transaction(scene_name: bytes | str) -> int | Call after the batched updates are complete. | Ends the grouped-update phase before subsequent frames. |
| scenes.get_scene_stats(scene_name: bytes | str) -> dict | None | Read periodically for diagnostics, memory decisions, or dashboards. | Exposes buffer count, focus, activity, and memory estimates safely. |
| scenes.compact_scene_pixels(scene_name: bytes | str) -> int | Call when a scene should release compactable pixel storage. | Lets applications reclaim memory without destroying the scene. |
| scenes.compact_cold_scenes(cold_frames: int, min_pixel_bytes: int, keep_active_scene: bool = True) -> int | Run as maintenance for inactive scenes above a memory threshold. | Implements data-first memory cleanup based on age and pixel bytes. |
Stats Keys
get_scene_stats() returns a dict when supported. Expected keys include buffer_count, active, current_focus, last_active_frame, last_compacted_frame, pixel_bytes, and approx_heap_bytes.
Modal Example
dialog_uid = objects.create_object(builders.DIALOG, 'Main', 0.7, 0.5, 0.2, 0.15)
dialog = objects.get_object_by_uid(dialog_uid)
objects.tuix_dialog_activate(dialog, 'Main')
while running:
engine.main_loop()
if objects.tuix_dialog_take_close_requested(dialog):
objects.tuix_dialog_deactivate(dialog, 'Main')
break