Struct RunConfig 

#[non_exhaustive]
pub struct RunConfig {
    pub tick_rate: Duration,
    pub mouse: bool,
    pub kitty_keyboard: bool,
    pub report_all_keys: bool,
    pub theme: Theme,
    pub color_depth: Option<ColorDepth>,
    pub max_fps: Option<u32>,
    pub scroll_speed: u32,
    pub title: Option<String>,
    pub widget_theme: WidgetTheme,
    pub handle_ctrl_c: bool,
    pub handle_suspend: bool,
}

Configuration for a TUI run loop.

Pass to run_with or run_inline_with to customize behavior. Use Default::default() for sensible defaults (16ms tick / 60fps, no mouse, dark theme). This type is #[non_exhaustive], so prefer builder methods instead of struct literals.

Example

use slt::{RunConfig, Theme};
use std::time::Duration;

let config = RunConfig::default()
    .tick_rate(Duration::from_millis(50))
    .mouse(true)
    .theme(Theme::light())
    .max_fps(60);

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

tick_rate: Duration

How long to wait for input before triggering a tick with no events.

Lower values give smoother animations at the cost of more CPU usage. Defaults to 16ms (60fps).

mouse: bool

Whether to enable mouse event reporting.

When true, the terminal captures mouse clicks, scrolls, and movement. Defaults to false.

kitty_keyboard: bool

Whether to enable the Kitty keyboard protocol for enhanced input.

When true, enables disambiguated key events, key release events, and modifier-only key reporting on supporting terminals (kitty, Ghostty, WezTerm). Terminals that don’t support it silently ignore the request. Defaults to false.

report_all_keys: bool

Whether to request modifier-only key events (bare Ctrl/Shift/Alt/Super presses and releases, with no accompanying character).

Has no effect unless kitty_keyboard is also true: it OR-es the Kitty REPORT_ALL_KEYS_AS_ESCAPE_CODES progressive-enhancement flag into the pushed flag set. On supporting terminals (kitty, Ghostty, WezTerm) this makes bare modifier presses arrive as KeyCode::Modifier events; other terminals never emit them.

Kept opt-in to avoid flooding apps with modifier events they don’t want. Defaults to false.

Since 0.21.0.

theme: Theme

The color theme applied to all widgets automatically.

Defaults to Theme::dark().

color_depth: Option<ColorDepth>

Color depth override.

None means auto-detect from $COLORTERM and $TERM environment variables. Set explicitly to force a specific color depth regardless of terminal capabilities.

max_fps: Option<u32>

Optional maximum frame rate.

None means unlimited frame rate. Some(fps) sleeps at the end of each loop iteration to target that frame time.

scroll_speed: u32

Lines scrolled per mouse scroll event. Defaults to 1.

title: Option<String>

Optional terminal window title (set via OSC 2).

widget_theme: WidgetTheme

Default colors applied to all instances of each widget type.

Per-callsite _colored() overrides still take precedence. Defaults to all-None (use theme colors).

handle_ctrl_c: bool

Whether the runtime intercepts Ctrl+C and exits the loop cleanly.

When true (the default), Ctrl+C is treated as a quit signal — matching the v0.19 behavior. When false, the Ctrl+C key event flows through to the frame closure as a regular Event::Key, matching RataTUI’s raw-mode semantics. The user is then responsible for deciding whether to call Context::quit or treat it as any other shortcut (e.g. clear input, cancel current operation).

Set this to false when migrating code from RataTUI that already handles Ctrl+C explicitly, or when implementing a graceful-shutdown prompt (e.g. “save unsaved changes?”).

Example

slt::run_with(RunConfig::default().handle_ctrl_c(false), |ui| {
    // Ctrl+C now reaches your closure as a normal key event.
    if ui.key_mod('c', KeyModifiers::CONTROL) {
        // Decide what to do — clear input, prompt to save, quit, etc.
        ui.quit();
    }
}).unwrap();

handle_suspend: bool

Whether the runtime restores the terminal on Ctrl+Z (SIGTSTP) and re-enters it on resume (SIGCONT).

When true (the default) on Unix, pressing Ctrl+Z runs the full session teardown — leave the alternate screen (fullscreen only), show the cursor, disable raw mode / bracketed paste / focus / mouse / kitty — before the process is suspended, so the shell prompt returns to a clean terminal. Resuming with fg re-enters the same session and forces a full redraw. This matches helix/zellij/bubbletea job-control behavior.

When false, no signal handler is installed and Ctrl+Z falls through to crossterm as a regular key event in raw mode (the pre-0.21 behavior).

Unix only; ignored on Windows, WASM, and non-crossterm builds where there is no SIGTSTP. Defaults to true.

Example

use slt::RunConfig;
// Opt out: let Ctrl+Z reach the frame closure as a key event.
let cfg = RunConfig::default().handle_suspend(false);
assert!(!cfg.handle_suspend);

Implementations

impl RunConfig

pub fn tick_rate(self, rate: Duration) -> Self

Set the tick rate (input polling interval).

pub fn mouse(self, enabled: bool) -> Self

Enable or disable mouse event reporting.

pub fn kitty_keyboard(self, enabled: bool) -> Self

Enable or disable Kitty keyboard protocol.

pub fn report_all_keys(self, enabled: bool) -> Self

Enable or disable modifier-only key reporting (Kitty REPORT_ALL_KEYS_AS_ESCAPE_CODES).

Requires kitty_keyboard(true) to have any effect. When enabled on a supporting terminal, bare modifier presses and releases arrive as KeyCode::Modifier events. Defaults to false.

Since 0.21.0.

Example

use slt::RunConfig;
let cfg = RunConfig::default().kitty_keyboard(true).report_all_keys(true);
assert!(cfg.report_all_keys);

pub fn theme(self, theme: Theme) -> Self

Set the color theme.

pub fn color_depth(self, depth: ColorDepth) -> Self

Override the color depth.

pub fn max_fps(self, fps: u32) -> Self

Set the maximum frame rate.

pub fn no_fps_cap(self) -> Self

Disable the frame rate cap (unlimited FPS).

By default, RunConfig caps rendering at 60 fps. Call this to remove the cap entirely — useful when controlling external sleep/vsync.

Example

slt::run_with(
    slt::RunConfig::default().no_fps_cap(),
    |ui| { ui.text("uncapped"); },
).unwrap();

pub fn scroll_speed(self, lines: u32) -> Self

Set the scroll speed (lines per scroll event).

pub fn title(self, title: impl Into<String>) -> Self

Set the terminal window title.

pub fn widget_theme(self, widget_theme: WidgetTheme) -> Self

Set default widget colors for all widget types.

pub fn handle_ctrl_c(self, enabled: bool) -> Self

Configure whether the runtime auto-exits on Ctrl+C.

Defaults to true (current v0.19 behavior). Set to false to receive Ctrl+C as a regular Event::Key inside the frame closure — see RunConfig::handle_ctrl_c for the full migration story.

Example

use slt::RunConfig;
let cfg = RunConfig::default().handle_ctrl_c(false);
assert!(!cfg.handle_ctrl_c);

pub fn handle_suspend(self, enabled: bool) -> Self

Configure whether the runtime restores the terminal on Ctrl+Z (SIGTSTP) and re-enters it on resume (SIGCONT).

Defaults to true. Set to false to disable the suspend handler so Ctrl+Z falls through to crossterm as a regular key event — see RunConfig::handle_suspend for the full behavior. Unix only; ignored elsewhere.

Example

use slt::RunConfig;
let cfg = RunConfig::default().handle_suspend(false);
assert!(!cfg.handle_suspend);

Trait Implementations

impl Default for RunConfig

fn default() -> Self

Returns the “default value” for a type.