Styles System

The Styles class manages visual theming for your TUIX application. Accessible via engine.styles, it supports preset styles, custom overrides, and style caching for the render pipeline.

Style Types

TUIX supports two rendering types: 'adaptive' and 'strict'. Set the active type with engine.styles.set_type(type).

engine.styles.set_type('strict')  # default

Preset Styles

The built-in preset is 'classic'. Switch presets with engine.styles.set_style(name). The classic preset uses white borders and text on a black background.

Classic Preset Values

Custom Styles

Override any style property using set_custom_style(). Custom values take precedence over preset values. The style cache is automatically rebuilt after each change.

RGB-Only Properties

These properties accept only RGB tuples: background, prompt_background, border, text_color, unselected_text, selected_background, selected_text.

engine.styles.set_custom_style(key='border', value=(0, 200, 100))
engine.styles.set_custom_style(key='selected_background', value=(50, 50, 200))

Boolean/RGB Properties

These accept either a boolean or RGB tuple: shadow, text_background, unselected_background. Setting shadow to True auto-computes a blended color between background and prompt_background using blend_shadow(). text_background and unselected_background cannot be set to True — only False or an RGB tuple.

engine.styles.set_custom_style(key='shadow', value=True)
engine.styles.set_custom_style(key='unselected_background', value=(30, 30, 30))

Text Options

The 'text' key has sub-options (bold, italic, underline, dim) that accept boolean values.

engine.styles.set_custom_style(key='text', option='bold', value=True)
engine.styles.set_custom_style(key='text', option='underline', value=True)

Removing Custom Styles

Reset custom overrides with remove_custom_style(). Pass a single key string, a list of keys, or for the 'text' key, pass the option(s) to reset.

engine.styles.remove_custom_style('border')
engine.styles.remove_custom_style(['shadow', 'selected_background'])
engine.styles.remove_custom_style('text', option='bold')
engine.styles.remove_custom_style('text', option=['bold', 'italic'])

Defining Custom Presets

Create entirely new style presets with define_style(). The config dict must contain exactly the same keys as the classic preset. Once defined, switch to it with set_style().

engine.styles.define_style(name='dark', config={
    'shadow': True,
    'background': 0,
    'prompt_background': (20, 20, 30),
    'border': (100, 100, 200),
    'text_color': (200, 200, 255),
    'text_background': False,
    'unselected_background': False,
    'unselected_text': (150, 150, 200),
    'selected_background': (100, 100, 200),
    'selected_text': (255, 255, 255),
    'text': {'bold': False, 'italic': False, 'underline': False, 'dim': False}
})

engine.styles.set_style('dark')

Style Cascade

Styles resolve in two layers: (1) the active preset provides base values, (2) custom_styles overrides any non-None values. The resolved result is cached in engine.styles.cached_styles and used by the RenderEngine. The cache is rebuilt automatically after any call to set_custom_style(), remove_custom_style(), set_style(), or define_style().

Full Workflow Example

from tuix.core import TuixEngine

engine = TuixEngine()

# Use classic preset (default)
engine.styles.set_style('classic')
engine.styles.set_type('strict')

# Override specific colors
engine.styles.set_custom_style(key='border', value=(0, 200, 100))
engine.styles.set_custom_style(key='selected_background', value=(50, 50, 200))
engine.styles.set_custom_style(key='text', option='bold', value=True)

# Check resolved styles
print(engine.styles.cached_styles['border'])  # (0, 200, 100)

# Reset border to preset default
engine.styles.remove_custom_style('border')
print(engine.styles.cached_styles['border'])  # (255, 255, 255)