TUIX v0.3Beta
Engine API
The engine module (tuix.core.engine) provides three functions that control the lifecycle of the TUIX runtime.
engine.init()
from tuix.core import engine
result = engine.init()Initializes the C core and the global registry. This is a two-phase call: tuix_init() followed by tuix_init_registry(). Must be called before any other TUIX operation.
| Returns | Description |
|---|---|
| int | 0 on success |
engine.main_loop()
engine.main_loop()Executes one frame of the rendering pipeline. Call this in a loop to drive the UI. Each call performs the following steps in the C core:
- Read terminal dimensions (detect resize)
- Commit pending batch commands
- Cache active scene pointer (avoids string comparison per frame)
- Execute internal control handlers for all enabled widgets (including automatic input processing in v0.3)
- Resolve geometry for each widget buffer
- Call on_resize if terminal dimensions changed
- Call build_content for each widget that needs redraw
- Composite scene buffers into the final framebuffer
- Stream-render changed rows to the terminal
Performancemain_loop() prefers the Cython path for maximum speed. In v0.3, lock scope around builder callbacks in the buffer generation path was reduced to lower contention while preserving lock-safe snapshot operations.
engine.shutdown()
engine.shutdown()Shuts down the engine and destroys the global registry. Frees all scenes, buffers, subcycles, and builders. Destroys the cross-platform lock. Call this as the last TUIX operation.
| Returns | Description |
|---|---|
| int | 0 on success |
Typical Usage
from tuix.core import engine, builders
# Startup
engine.init()
builders.register_standard()
# ... create scenes, widgets, start input ...
# Render loop
while running:
engine.main_loop()
# Shutdown
engine.shutdown()