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,
    pub async_message_budget: usize,
}

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);

async_message_budget: usize

Maximum number of external async messages delivered to one frame.

Messages beyond this count remain queued in FIFO order for later frames. Defaults to the async channel capacity (100).

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 async_message_budget(self, messages: usize) -> Self

Set the maximum number of external async messages delivered per frame.

Values below one are normalized to one so queued messages always make progress.

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.