Getting Started with TUIX Core

This guide covers prerequisites, the basic import pattern, and the standard workflow for building terminal UIs with TUIX Core v0.2.1.

Recommended Reading Order

1. Install the package and verify that engine.init() works on your machine.
2. Read the workflow on this page so you understand the scene -> widget -> main loop model.
3. Build the Choice example from First Widget before diving into the lower-level API pages.

Prerequisites

• Python 3.10 or later
• A terminal that supports ANSI escape sequences (most modern terminals)
• Truecolor (24-bit RGB) support recommended; ANSI256 and ANSI16 fallback is automatic

Import Pattern

TUIX Core exposes its API through individual modules under tuix.core. There is no single top-level class — you import the modules you need.

from tuix.core import engine, builders, scenes, registry, objects, buffers, input

Standard Workflow

Every TUIX application follows this sequence:

1. Initialize the engine with engine.init()
2. Register built-in widget types with builders.register_standard()
3. Create a scene with scenes.init_scene(b"scene_name")
4. Set the active scene via registry.registry.current_scene_name = b"scene_name"
5. Start the input listener with input.listen()
6. Create widgets with objects.create_object(builder, scene, width, height, margin_top, margin_left)
7. Configure widgets using their specific API functions
8. Run engine.main_loop() in a loop to render frames and process input
9. Clean up: free buffers, stop input, shut down the engine

Minimal Example

from tuix.core import engine, builders, scenes, registry, objects, buffers, input
import time

# 1. Initialize
engine.init()
builders.register_standard()

# 2. Create and select a scene
scenes.init_scene(b"main")
registry.registry.current_scene_name = b"main"

# 3. Start input
input.listen()

# 4. Create a progressbar widget (full width, 10% height, centered at top)
uid = objects.create_object(
    builders.PROGRESSBAR, b"main",
    0.5, 0.1,   # width_mod, height_mod
    0.1, 0.25   # margin_top_mod, margin_left_mod
)

# 5. Get the object pointer for widget operations
buf = buffers.get_buffer_by_uid(uid)
obj = buf.contents.obj.contents

# 6. Set progress value
objects.tuix_progressbar_set_value(obj, 0.5)

# 7. Render loop
for i in range(100):
    objects.tuix_progressbar_set_value(obj, i / 100.0)
    engine.main_loop()
    time.sleep(0.03)

# 8. Cleanup
buffers.free_buffer(b"main", uid)
input.stop()
engine.shutdown()

What Happens Each Frame

Each call to engine.main_loop() executes this pipeline in C:

1. Read terminal dimensions (resize detection)
2. Commit any pending batch commands
3. Execute subcycle handlers for enabled widgets (state updates, input processing)
4. Resolve geometry: multiply widget modifiers by terminal size
5. Call each widget's build_content to produce pixel buffers
6. Composite all scene buffers into the final framebuffer
7. Delta-render changed rows to the terminal

Next Steps

Head to Installation for setup instructions, then follow the First Widget tutorial to build an interactive choice menu from scratch.