Struct Tui 

pub struct Tui {
    terminal: Option<DefaultTerminal>,
    event_rx: UnboundedReceiver<Event>,
    event_tx: UnboundedSender<Event>,
    task: Option<JoinHandle<()>>,
    cancellation_token: CancellationToken,
    tick_rate: f64,
    frame_rate: f64,
}

Terminal UI wrapper managing lifecycle and event delivery.

The lifecycle is split into two phases:

1. Tui::new() — creates channels and config; no terminal side effects
2. Tui::enter() — initializes the terminal, enters raw mode, spawns event task

This split ensures config loading and stderr output happen before the terminal is taken over.

Fields

terminal: Option<DefaultTerminal>

The ratatui terminal instance (initialized in enter()).

event_rx: UnboundedReceiver<Event>

Receiver for events from the event handler task.

event_tx: UnboundedSender<Event>

Sender for events (cloned into the event task).

task: Option<JoinHandle<()>>

Handle to the spawned event handler task.

cancellation_token: CancellationToken

Cancellation token to stop the event handler task.

tick_rate: f64

Target tick rate (ticks per second).

frame_rate: f64

Target frame rate (frames per second).

Implementations

impl Tui

pub fn new(tick_rate: f64, frame_rate: f64) -> Self

Create a new TUI instance without initializing the terminal.

No side effects — the terminal remains in normal mode. Call Tui::enter to activate raw mode and start the event handler task.

pub fn enter(&mut self) -> Result<()>

Initialize the terminal and enter raw mode.

This enables raw mode, alternate screen, mouse capture, focus change events, and bracketed paste. It also installs a panic hook that restores the terminal before displaying the error report, and spawns the async event handler task.

Errors

Returns an error if terminal setup fails (instead of panicking).

pub async fn next(&mut self) -> Result<Event>

Wait for the next event from the event handler task.

Errors

Returns an error if the event channel is closed unexpectedly.

pub fn exit(&mut self) -> Result<()>

Exit raw mode and restore the terminal.

Cancels the event handler task and restores the terminal state.

Errors

Returns an error if terminal restoration fails.

pub fn draw(&mut self, f: impl FnOnce(&mut Frame<'_>)) -> Result<()>

Draw a frame using the provided rendering closure.

Errors

Returns an error if the terminal is not initialized or drawing fails.

pub fn suspend(&mut self) -> Result<()>

Temporarily suspend the TUI for an external process (e.g., editor).

Leaves alternate screen and disables raw mode so the subprocess can interact with the terminal normally. Call resume() after the subprocess exits.

Errors

Returns an error if terminal state cannot be changed.

pub fn resume(&mut self) -> Result<()>

Resume the TUI after a suspend() call.

Re-enters raw mode and alternate screen. The event handler task is still running — it will resume delivering events.

Errors

Returns an error if terminal state cannot be restored.

fn drain_events(&mut self)

Discard all queued events from the event channel.

Called by resume to prevent stale input that accumulated during a suspend from being interpreted as TUI commands. The background event handler task keeps running during suspend, so its EventStream can race with the child process for stdin and capture keypresses (e.g., q to quit an editor) that would otherwise cause unintended actions like quitting the app.

fn reset() -> Result<()>

Reset terminal state (used by both exit and panic hook).

Trait Implementations

impl Drop for Tui

fn drop(&mut self)

Executes the destructor for this type.