The scenes module (tuix.core.scenes) manages scene lifecycle, scene queries, and focus routing between interactive widgets.
scenes.init_scene(name)
from tuix.core import scenes
result = scenes.init_scene(b"main")
Parameter
Type
Description
name
bytes
Unique scene name
Returns
Description
int
0 on success, 1 if scene name already exists
Creates a new scene with the given name. Scenes use exponential growth for their internal buffer arrays (initial capacity 4, doubling on overflow). Duplicate names are rejected.
scenes.free_scene(name)
scenes.free_scene(b"main")
Parameter
Type
Description
name
bytes
Scene name to destroy
Destroys a scene and frees all its buffers and associated memory. The scene cannot be used after this call.
scenes.clear_scene(name)
scenes.clear_scene(b"main")
Parameter
Type
Description
name
bytes
Scene name to clear
Frees all buffers in the scene but keeps the scene structure allocated. Use this to remove all widgets from a scene without destroying the scene itself. New widgets can be added to the scene after clearing.
scenes.get_scene(name)
scene_ptr = scenes.get_scene(b"main")
Parameter
Type
Description
name
bytes | str
Scene name to look up
Returns
Description
int
Native scene pointer address (0 if not found)
scenes.get_scenes()
all_scenes = scenes.get_scenes()
Returns a Python-side view of the native scenes collection exposed by the Cython bridge.
scenes.set_focus(scene_name, uid)
scenes.set_focus(b"main", input_uid)
Parameter
Type
Description
scene_name
bytes | str
Target scene
uid
int
Widget UID that should receive input focus
Returns
Description
int
0 on success, non-zero on failure
Focus routing is scene-local. Use this when multiple interactive widgets share one scene and only one should handle keyboard events.
scenes.set_previous_focus(scene_name)
scenes.set_previous_focus(b"main")
Restores the previous focused widget for the given scene.
Example: Scene Switching
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")