Struct TerminalSession 

pub struct TerminalSession { /* private fields */ }

A terminal session that manages raw mode and cleanup.

This struct owns the terminal configuration and ensures cleanup on drop. It tracks all enabled modes and disables them in reverse order when dropped.

Contract

• Exclusive ownership: Only one TerminalSession should exist at a time. Creating multiple sessions will cause undefined terminal behavior.

• Raw mode entry: Creating a session automatically enters raw mode. This disables line buffering and echo.

• Cleanup guarantee: When dropped (normally or via panic), all enabled modes are disabled and the terminal is restored to its previous state.

State Tracking

Each optional mode has a corresponding _enabled flag. These flags are set when a mode is successfully enabled and cleared during cleanup. This ensures we only disable modes that were actually enabled.

Example

use ftui_core::terminal_session::{TerminalSession, SessionOptions};

fn run_app() -> std::io::Result<()> {
    let session = TerminalSession::new(SessionOptions {
        alternate_screen: true,
        mouse_capture: true,
        ..Default::default()
    })?;

    // Application loop
    loop {
        if session.poll_event(std::time::Duration::from_millis(100))? {
            if let Some(event) = session.read_event()? {
                // Handle event...
            }
        }
    }
    // Session cleaned up when dropped
}

Implementations

impl TerminalSession

pub fn new(options: SessionOptions) -> Result<Self>

Enter raw mode and optionally enable additional features.

Errors

Returns an error if raw mode cannot be enabled.

pub fn minimal() -> Result<Self>

Create a minimal session (raw mode only).

pub fn size(&self) -> Result<(u16, u16)>

Get the current terminal size (columns, rows).

pub fn poll_event(&self, timeout: Duration) -> Result<bool>

Poll for an event with a timeout.

Returns Ok(true) if an event is available, Ok(false) if timeout.

pub fn read_event(&self) -> Result<Option<Event>>

Read the next event (blocking until available).

Returns Ok(None) if the event cannot be represented by the ftui canonical event types (e.g. unsupported key codes).

pub fn show_cursor(&self) -> Result<()>

Show the cursor.

pub fn hide_cursor(&self) -> Result<()>

Hide the cursor.

pub fn options(&self) -> &SessionOptions

Get the session options.

Trait Implementations

impl Debug for TerminalSession

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

Formats the value using the given formatter.

impl Drop for TerminalSession

fn drop(&mut self)

Executes the destructor for this type.