Struct TerminalHandle 

pub struct TerminalHandle { /* private fields */ }

Available on crate feature terminal only.

Handle to a running terminal instance.

The handle allows you to write input to the terminal and resize it. Multiple Terminal components can share the same handle.

The PTY is automatically closed when the handle is dropped.

Implementations

impl TerminalHandle

pub fn new( id: TerminalId, command: CommandBuilder, scrollback_length: Option<usize>, ) -> Result<TerminalHandle, TerminalError>

Create a new terminal with the specified command and default scrollback size (1000 lines).

Example

use freya_terminal::prelude::*;
use portable_pty::CommandBuilder;

let mut cmd = CommandBuilder::new("bash");
cmd.env("TERM", "xterm-256color");

let handle = TerminalHandle::new(TerminalId::new(), cmd, None).unwrap();

pub fn write(&self, data: &[u8]) -> Result<(), TerminalError>

Write data to the terminal.

Example

handle.write(b"ls -la\n").unwrap();

pub fn paste(&self, text: &str) -> Result<(), TerminalError>

Write text to the PTY as a paste operation.

If bracketed paste mode is enabled, wraps the text with \x1b[200~ … \x1b[201~.

pub fn resize(&self, rows: u16, cols: u16)

Resize the terminal to the specified rows and columns.

Example

handle.resize(24, 80);

pub fn scroll(&self, delta: i32)

Scroll the terminal by the specified delta.

Example

handle.scroll(-3); // Scroll up 3 lines
handle.scroll(3); // Scroll down 3 lines

pub fn scroll_to_bottom(&self)

Scroll the terminal to the bottom.

Example

handle.scroll_to_bottom();

pub fn scrollback_position(&self) -> usize

Get the current scrollback position (scroll offset from buffer).

Example

let position = handle.scrollback_position();

pub fn cwd(&self) -> Option<PathBuf>

Get the current working directory reported by the shell via OSC 7.

Returns None if the shell hasn’t reported a CWD yet.

pub fn title(&self) -> Option<String>

Get the window title reported by the shell via OSC 0 or OSC 2.

Returns None if the shell hasn’t reported a title yet.

pub fn send_wheel_to_pty(&self, row: usize, col: usize, delta_y: f64)

Send a wheel event to the PTY.

This sends mouse wheel events as escape sequences to the running process. Uses the currently active mouse protocol encoding based on what the application has requested via DECSET sequences.

pub fn mouse_move(&self, row: usize, col: usize)

Send a mouse move/drag event to the PTY based on the active mouse mode.

• AnyMotion (DECSET 1003): sends motion events regardless of button state.
• ButtonMotion (DECSET 1002): sends motion events only while a button is held.

When dragging, the held button is encoded in the motion event so TUI apps can implement their own text selection.

If shift is held and a button is pressed, updates the text selection instead of sending events to the PTY.

pub fn mouse_down(&self, row: usize, col: usize, button: TerminalMouseButton)

Handle a mouse button press event.

When the running application has enabled mouse tracking (e.g. vim, helix, htop), this sends the press escape sequence to the PTY. Otherwise it starts a text selection.

If shift is held, text selection is always performed regardless of the application’s mouse tracking state.

pub fn mouse_up(&self, row: usize, col: usize, button: TerminalMouseButton)

Handle a mouse button release event.

When the running application has enabled mouse tracking, this sends the release escape sequence to the PTY. Only PressRelease, ButtonMotion, and AnyMotion modes receive release events — Press mode does not. Otherwise it ends the current text selection.

If shift is held, always ends the text selection instead of sending events to the PTY.

pub fn release(&self)

Handle a mouse button release from outside the terminal viewport.

Clears the pressed state and ends any active text selection without sending an encoded event to the PTY.

pub fn wheel(&self, delta_y: f64, row: usize, col: usize)

Handle a wheel event intelligently.

The behavior depends on the terminal state:

• If viewing scrollback history: scrolls the scrollback buffer.
• If mouse tracking is enabled (e.g., vim, helix): sends wheel escape sequences to the PTY.
• If on the alternate screen without mouse tracking (e.g., gitui, less): sends arrow key sequences to the PTY (alternate scroll mode, like wezterm/kitty/alacritty).
• Otherwise (normal shell): scrolls the scrollback buffer.

pub fn read_buffer(&self) -> Ref<'_, TerminalBuffer>

Read the current terminal buffer.

pub fn output_received(&self) -> impl Future<Output = ()>

Returns a future that completes when new output is received from the PTY.

Can be called repeatedly in a loop to detect ongoing output activity.

pub fn title_changed(&self) -> impl Future<Output = ()>

Returns a future that completes when the window title changes via OSC 0 or OSC 2.

Can be called repeatedly in a loop to react to title updates from the shell.

pub fn last_write_elapsed(&self) -> Duration

pub fn closed(&self) -> impl Future<Output = ()>

Returns a future that completes when the terminal/PTY closes.

This can be used to detect when the shell process exits and update the UI accordingly.

Example

use_future(move || async move {
    terminal_handle.closed().await;
    // Terminal has exited, update UI state
});

pub fn id(&self) -> TerminalId

Returns the unique identifier for this terminal instance.

pub fn shift_pressed(&self, pressed: bool)

Track whether shift is currently pressed.

This should be called from your key event handlers to track shift state for shift+drag text selection.

pub fn get_selection(&self) -> Option<TerminalSelection>

Get the current text selection.

pub fn set_selection(&self, selection: Option<TerminalSelection>)

Set the text selection.

pub fn start_selection(&self, row: usize, col: usize)

pub fn update_selection(&self, row: usize, col: usize)

pub fn end_selection(&self)

pub fn clear_selection(&self)

Clear the current selection.

pub fn get_selected_text(&self) -> Option<String>

Trait Implementations

impl Clone for TerminalHandle

fn clone(&self) -> TerminalHandle

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl PartialEq for TerminalHandle

fn eq(&self, other: &TerminalHandle) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.