Examples

Complete, runnable code samples that demonstrate TUIX Core features. Copy any example, save it as a .py file, and run from a terminal.

Basic Choice Menu

The simplest possible interactive menu – a centered box with two buttons.

from tuix.core import TuixEngine

engine = TuixEngine()

# Create a choice component
engine.component.create("menu", "choice")

# Set the label and choices
engine.component.set_property("menu", "text", "Do you like TUIX?")
engine.component.set_property("menu", "choices", [
    [{"name": "Yes"}, {"name": "No"}]
])

# Render – blocks until user presses Enter
engine.render.draw()

Custom-Styled Menu

Apply a preset style and override specific colours with custom values.

from tuix.core import TuixEngine

engine = TuixEngine()

# Switch to the classic preset
engine.styles.set_style("classic")

# Override the selection highlight colour (RGB)
engine.styles.set_custom_style("selected_color", (0, 200, 255))

# Override the border colour (RGB)
engine.styles.set_custom_style("border_color", (255, 165, 0))

# Create a choice component
engine.component.create("styled_menu", "choice")
engine.component.set_property("styled_menu", "text", "Pick a colour scheme:")
engine.component.set_property("styled_menu", "choices", [
    [{"name": "Ocean"}, {"name": "Sunset"}, {"name": "Forest"}]
])

engine.render.draw()

Multi-Row Button Layout

Pass multiple inner lists to choices to create rows of buttons. Navigation works both horizontally (left/right) and vertically (up/down).

from tuix.core import TuixEngine

engine = TuixEngine()

engine.component.create("grid", "choice")
engine.component.set_property("grid", "text", "Select a difficulty:")
engine.component.set_property("grid", "choices", [
    [{"name": "Easy"}, {"name": "Medium"}, {"name": "Hard"}],
    [{"name": "Nightmare"}, {"name": "Custom"}]
])

engine.render.draw()

Custom Dimensions & Margins

Override the default centered layout and set explicit size and position.

from tuix.core import TuixEngine

engine = TuixEngine()

# Create a component
engine.component.create("panel", "choice")
engine.component.set_property("panel", "text", "Settings")
engine.component.set_property("panel", "choices", [
    [{"name": "Audio"}, {"name": "Video"}],
    [{"name": "Controls"}, {"name": "Back"}]
])

# Make it 60% wide, 40% tall
engine.layout.set_dimensions("panel", 0.6, 0.4)

# Pin it 10% from top, 5% from left
engine.layout.margin_mode("panel", "custom", 0.1, 0.05)

engine.render.draw()

Reacting to User Selection

After engine.render.draw() returns, the selected button can be identified from the engine state. The InputHandler stores the final selected_row and selected_index.

from tuix.core import TuixEngine
import os

engine = TuixEngine()

choices = [
    [{"name": "New Game"}, {"name": "Load Game"}],
    [{"name": "Settings"}, {"name": "Quit"}]
]

engine.component.create("main", "choice")
engine.component.set_property("main", "text", "Main Menu")
engine.component.set_property("main", "choices", choices)

engine.render.draw()

# After draw() returns, read the selection
row = engine.render.selected_row
idx = engine.render.selected_index
selected_name = choices[row][idx]["name"]

os.system("cls" if os.name == "nt" else "clear")
print(f"You selected: {selected_name}")

Using Utility Functions

TUIX Core exports helper functions for working with ANSI strings and colour validation.

from tuix.core import is_rgb, is_bool, visual_width

# Validate an RGB tuple
print(is_rgb((255, 128, 0)))   # True
print(is_rgb((300, 0, 0)))     # False – values must be 0-255
print(is_rgb("red"))            # False – must be a tuple

# Check boolean type
print(is_bool(True))           # True
print(is_bool(1))              # False – int is not bool

# Measure visible width (ignores ANSI escape codes)
plain = "Hello"
styled = "\x1b[31mHello\x1b[0m"   # red text
print(visual_width(plain))     # 5
print(visual_width(styled))    # 5