Object Lifecycle & Management API (tuix.core.object)

The `tuix.core.object` package provides native object lifecycle allocation, unique UID management, pointer resolution, memory deallocation, snapshot diagnostics, and buffer binding. Per-widget setters and getters are categorized under the Built-in Widgets documentation.

Object Creation & Lifecycle

Function	Parameters & Description	Return & Notes
objects.create_object(builder_name, scene_name, width_mod, height_mod, margin_top_mod=0.0, margin_left_mod=0.0) -> int	Allocates a new object with the specified builder in a scene with proportional float dimensions (0.0 to 1.0).	Returns positive integer object UID (> 0), or 0 on failure.
objects.create_object_ex(builder_name, scene_name, width_mod, height_mod, margin_top_mod, margin_left_mod, user_data=0) -> int	Extended object creation function allowing custom native user_data pointer binding.	Returns positive integer object UID, or 0 on failure.
objects.get_object_by_uid(uid: int)	Resolves integer object UID to native object pointer (`obj_ptr`).	Pass the returned `obj_ptr` to per-widget setter and getter APIs.
objects.tuix_object_free_ptr(obj_ptr) -> None	Explicitly frees native object memory and releases its associated buffer.	Use for dynamic widget destruction inside scenes.

Object Diagnostics & Buffer Inspection

Function	Description
objects.get_object_snapshot_by_uid(uid: int) -> dict	Returns thread-safe dictionary snapshot of object metadata (uid, builder_name, scene_name, buffer_uid, visible, enabled).
objects.get_object_snapshot(obj_ptr) -> dict	Returns dictionary snapshot by object pointer.
objects.tuix_object_get_buffer(obj_ptr) -> int	Returns native buffer handle address associated with this object.
objects.tuix_object_get_uid(obj_ptr) -> int	Reads unique UID from native object pointer.
objects.tuix_object_get_scene(obj_ptr) -> bytes	Returns scene name bytes owning this object.

Usage Example

from tuix.core import object as objects, content_builder, scene

# Create object in scene
uid = objects.create_object(content_builder.BUTTON, b'Main', 0.3, 0.1, 0.1, 0.1)
btn = objects.get_object_by_uid(uid)

# Inspect snapshot
snap = objects.get_object_snapshot_by_uid(uid)
print('Object snapshot:', snap)

# Free object when done
objects.tuix_object_free_ptr(btn)