Scenes API

The tuix.core.scene package owns scene lifecycle, selection, focus, modal state, transactions, stats, and cold scene compaction.

Method	How to use it	Why it exists
scene.tuix_scene_init(name: bytes) -> int	Allocates a new named scene in the native registry.	Must be called before adding buffers or objects. Returns TUIX_RC_OK (0).
scene.tuix_scene_free(name: bytes) -> None	Destroys a scene and deallocates all its buffers and objects.	Releases native memory when a scene is no longer needed.
scene.tuix_scene_clear(name: bytes) -> None	Clears all buffers from the scene while keeping the scene allocation active.	Use for dynamic scene reset without re-creating scene metadata.
scene.tuix_scene_get(name: bytes) -> int	Returns native pointer handle to the scene structure.	Internal pointer resolution for native bridge operations.
scene.tuix_scene_get_all() -> list[bytes]	Returns list of all active scene names in the registry.	Enables introspection and multi-scene management.
scene.tuix_scene_select(name: bytes) -> None	Selects the active scene for rendering and input routing.	Switches visible UI screen.
scene.tuix_scene_focus_set(scene_name: bytes, uid: int) -> int	Sets active keyboard focus to the specified object UID.	Routes keystrokes to the focused interactive widget.
scene.tuix_scene_focus_previous(scene_name: bytes) -> int	Restores previously focused widget UID.	Useful for dialog dismissal or tab focus return.
scene.tuix_scene_modal_activate(scene_name: bytes, uid: int) -> int	Activates modal input trapping for the specified dialog UID.	Prevents input from reaching underlying background widgets.
scene.tuix_scene_modal_deactivate(scene_name: bytes, uid: int) -> int	Deactivates modal state and restores normal scene input routing.	Closes modal trap when dialog dismisses.
scene.tuix_scene_modal_get_active(scene_name: bytes) -> int	Returns UID of currently active modal widget in scene, or 0.	Queries active modal overlay state.
scene.tuix_scene_transaction_begin(scene_name: bytes) -> None	Begins an atomic transaction on scene buffers.	Batches multiple widget mutations before rendering.
scene.tuix_scene_transaction_commit(scene_name: bytes) -> None	Commits the open transaction and triggers compositor recalculation.	Applies all buffered scene mutations atomically.
scene.tuix_scene_force_redraw(scene_name: bytes) -> None	Forces an unconditional full redraw of the scene on next frame.	Invalidates cached compositing and screen buffer state.
scene.tuix_scene_get_stats(scene_name: bytes) -> dict	Returns dictionary of scene statistics (buffer_count, focus_uid, modal_uid, pixel_bytes).	Enables memory profiling and live UI diagnostics.
scene.tuix_scene_compact_pixels(scene_name: bytes) -> int	Reclaims unused pixel buffer allocations in the scene.	Returns total bytes of memory freed.
scene.tuix_scene_compact_cold(cold_frames: int, min_pixel_bytes: int = 0, keep_active_scene: bool = True) -> int	Compacts pixel storage for scenes that have not been active for cold_frames.	Automated background memory maintenance for multi-screen applications.

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.

dialog_uid = objects.create_object(content_builder.DIALOG, b'Main', 0.7, 0.5, 0.2, 0.15)
dialog = objects.get_object_by_uid(dialog_uid)
objects.tuix_dialog_activate(dialog, b'Main')

while running:
    core.main_loop()
    if objects.tuix_dialog_take_close_requested(dialog):
        objects.tuix_dialog_deactivate(dialog, b'Main')
        break

Scenes API

Stats Keys

Modal Example