Getting Started with TUIX Core

This guide shows the standard v0.6 flow: initialize core, register builders via content_builder, create/select a scene, start input for interactive apps, create widgets, run frames, and clean up.

Recommended Reading Order

1. Install TUIX Core and verify imports.
2. Build the first widget example.
3. Read Widgets, Layout API, and Input Handling before composing larger screens.

Prerequisites

• Python 3.10 or newer.
• A terminal with ANSI escape support.
• Cython 0.29 or newer and a C compiler only when building from source.

Import Pattern

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

Standard Workflow

1. Call core.init().
2. Call content_builder.register_standard() before creating objects.
3. Create a scene with scene.init_scene(b"Main") and select it with scene.select_scene(b"Main").
4. Start input.listen() for interactive widgets.
5. Create objects with objects.create_object(...).
6. Run core.main_loop() once per frame in your application loop.
7. Stop input and shut the engine down during cleanup.

Minimal Example

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

core.init()
content_builder.register_standard()

scene.init_scene(b'Main')
scene.select_scene(b'Main')
input.listen()

uid = objects.create_object(content_builder.TEXT, b'Main', 0.5, 0.1, 0.05, 0.05)
obj = objects.get_object_by_uid(uid)
objects.tuix_text_set_text(obj, 'Hello from TUIX 0.6')
objects.tuix_text_set_fg(obj, 120, 220, 160)

for _ in range(5):
    core.main_loop()

input.stop()
core.shutdown()

What Happens Each Frame

• Input is read from native queues and routed to focused, captured, modal, or hitmap-picked widgets.
• Geometry is resolved from proportional modifiers, parent layout results, layout slots, and grid placements.
• Builders update state and provide pixels, governed by TuixPixelReturnPolicy (persistent or core-owned temporary buffers).
• The compositor clips viewports, builds a hitmap, composites buffers with paint-mask awareness, and the renderer writes terminal-visible differences.