Struct TerminalWindow

pub struct TerminalWindow;

Implementations

impl TerminalWindow

pub fn main_event_loop<'a, S, AS>( app: BoxedSafeApp<S, AS>, exit_keys: &'a [InputEvent], state: S, ) -> Result<MainEventLoopFuture<'a, S, AS>>

where S: Display + Debug + Default + Clone + Sync + Send + 'a, AS: Debug + Default + Clone + Sync + Send + 'static,

This is the public API for the main event loop of the terminal window.

This is the public API, and not the internal API super::main_event_loop_impl(). This separation exists to allow for testing using dependency injection.

This function handles the synchronous initialization (getting terminal size, creating input/output devices) and then returns a MainEventLoopFuture that contains the actual async event loop implementation.

The main event loop is responsible for handling all input events, and dispatching them to the crate::App for processing. It is also responsible for rendering the crate::App after each input event. It is also responsible for handling all signals sent from the crate::App to the main event loop (eg: request_shutdown, re-render, apply app signal, etc).

Arguments

• app - The BoxedSafeApp instance that will handle input events and signals.
• exit_keys - A slice of InputEvents that will trigger application exit.
• state - The initial application state.

Returns

Returns a miette::Result containing a MainEventLoopFuture that resolves to a CommonResult with:

• global_data - The final GlobalData state after the event loop exits.
• event_stream - The InputDevice used for input events.
• stdout - The OutputDevice used for output.

Performance Note

The state type S must implement Display for telemetry logging. This implementation is called after EVERY render cycle in the main event loop, so it must be lightweight and efficient. Avoid expensive operations like:

• Deep recursive traversal of data structures.
• Memory size calculations.
• Complex string formatting.

Instead, implement a simple summary format that shows only essential metrics. For example:

use std::fmt::Display;

struct MyState {
    buffers: Vec<String>,
    active_id: usize,
}

impl Display for MyState {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "State[buffers={}, active={}]", self.buffers.len(), self.active_id)
    }
}

Errors

Returns miette::Error if there are errors during:

• Terminal initialization (getting initial size).

The returned future may produce miette::Error during:

• Input/output device creation.
• Event loop execution (input processing, rendering, signal handling).
• Terminal cleanup and restoration.

Trait Implementations

impl Debug for TerminalWindow

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.