Styles API Reference
Full API reference for the Styles class, accessible via engine.styles.
set_type(type: str)
Sets the rendering type. Valid values: 'adaptive', 'strict'. Raises ValueError for unknown types.
set_style(style: str)
Switches the active preset style. The default preset is 'classic'. Additional presets can be registered with define_style(). Raises ValueError for unknown styles.
set_custom_style(*, key, option=None, value)
Overrides a single style property. The behavior depends on the key:
| Key Category | Keys | Accepted Values |
|---|---|---|
| RGB-only | background, prompt_background, border, text_color, unselected_text, selected_background, selected_text | RGB tuple (r, g, b) |
| Bool/RGB | shadow, text_background, unselected_background | False, or RGB tuple. shadow also accepts True (auto-computes blend) |
| Options | text | Requires option param ('bold', 'italic', 'underline', 'dim') + bool value |
Automatically triggers style cache rebuild.
remove_custom_style(key, option=None)
Resets custom overrides back to None (falling through to preset values). Accepts a single key string or list of keys. For the 'text' key, pass option as a string or list of option names.
engine.styles.remove_custom_style('border')
engine.styles.remove_custom_style(['shadow', 'selected_text'])
engine.styles.remove_custom_style('text', option=['bold', 'dim'])define_style(*, name, config)
Registers a new preset style. The config dict must have exactly the same keys as the classic preset. Raises ValueError if keys don't match. The name must not conflict with an existing preset.
cached_styles
A read-only dictionary containing the fully resolved styles (preset + custom overrides merged). This is what the RenderEngine reads when drawing components. Updated automatically by _cache_styles() after any style change.
Utility Functions
These module-level functions support the style system:
| Function | Signature | Description |
|---|---|---|
| text_color | text_color(r, g, b) -> str | Returns ANSI escape code for 24-bit foreground color |
| background_color | background_color(r, g, b) -> str | Returns ANSI escape code for 24-bit background color |
| is_rgb | is_rgb(value) -> bool | Validates that value is a 3-tuple of ints/floats in range 0–255 |
| blend_shadow | blend_shadow(bg, fg, intensity=0.3) -> tuple | Blends two RGB colors for shadow effects |
| visual_width | visual_width(s) -> int | Returns display width of string using wcwidth (handles CJK, emoji) |