Struct TerminalView 

pub struct TerminalView { /* private fields */ }

The main terminal view component for GPUI applications.

TerminalView is a GPUI entity that implements the Render trait, providing a complete terminal emulator that can be embedded in any GPUI application.

Responsibilities

• Terminal State: Manages the grid, cursor, and colors via TerminalState
• I/O Streams: Reads from PTY stdout and writes to PTY stdin
• Event Handling: Processes keyboard, mouse, and resize events
• Rendering: Paints text, backgrounds, and cursor via TerminalRenderer
• Callbacks: Dispatches events to user-provided callbacks

Creating a Terminal

Use TerminalView::new within a GPUI entity context:

let terminal = cx.new(|cx| {
    TerminalView::new(writer, reader, config, cx)
        .with_resize_callback(resize_callback)
        .with_exit_callback(|_, cx| cx.quit())
});

Focus

The terminal must be focused to receive keyboard input:

terminal.read(cx).focus_handle().focus(window);

Callbacks

Configure behavior through builder methods:

• with_resize_callback - PTY size changes
• with_exit_callback - Process exit
• with_key_handler - Key event interception
• with_bell_callback - Terminal bell
• with_title_callback - Title changes
• with_clipboard_store_callback - Clipboard writes

Thread Safety

TerminalView is not Send as it contains GPUI handles. The stdin writer is internally wrapped in Arc<parking_lot::Mutex<>> for safe concurrent access.

Implementations

impl TerminalView

pub fn new<W, R>( stdin_writer: W, stdout_reader: R, config: TerminalConfig, cx: &mut Context<'_, Self>, ) -> Self

where W: Write + Send + 'static, R: Read + Send + 'static,

Create a new terminal with provided I/O streams.

This method initializes a new terminal emulator with the given stdin writer and stdout reader. It spawns a background task to read from stdout and process incoming bytes through the VTE parser.

Arguments

• stdin_writer - Writer for sending input bytes to the terminal process
• stdout_reader - Reader for receiving output bytes from the terminal process
• config - Terminal configuration (dimensions, font, etc.)
• cx - GPUI context for this view

Returns

A new TerminalView instance ready to be rendered.

Examples

// In a GPUI window context:
let terminal = cx.new(|cx| {
    TerminalView::new(stdin_writer, stdout_reader, TerminalConfig::default(), cx)
});

pub fn with_resize_callback( self, callback: impl Fn(usize, usize) + Send + Sync + 'static, ) -> Self

Set a callback to be invoked when the terminal is resized.

This callback should resize the underlying PTY to match the new dimensions. The callback receives (cols, rows) as arguments.

Arguments

• callback - A function that will be called with (cols, rows) on resize

pub fn with_key_handler( self, handler: impl Fn(&KeyDownEvent) -> bool + Send + Sync + 'static, ) -> Self

Set a callback to intercept key events before terminal processing.

The callback receives the key event and should return true to consume the event (prevent the terminal from processing it), or false to allow normal terminal processing.

Arguments

• handler - A function that receives key events and returns whether to consume them

Example

terminal.with_key_handler(|event| {
    // Handle Ctrl++ to increase font size
    if event.keystroke.modifiers.control && event.keystroke.key == "+" {
        // Handle the event
        return true; // Consume the event
    }
    false // Let terminal handle it
})

pub fn with_bell_callback( self, callback: impl Fn(&mut Window, &mut Context<'_, TerminalView>) + 'static, ) -> Self

Set a callback to be invoked when the terminal bell is triggered.

The callback receives a mutable reference to the window and context, allowing you to play a sound or show a visual indicator.

Arguments

• callback - A function that will be called when the bell is triggered

Example

terminal.with_bell_callback(|window, cx| {
    // Play a sound or flash the screen
})

pub fn with_title_callback( self, callback: impl Fn(&mut Window, &mut Context<'_, TerminalView>, &str) + 'static, ) -> Self

Set a callback to be invoked when the terminal title changes.

The callback receives a mutable reference to the window and context, along with the new title string.

Arguments

• callback - A function that will be called with the new title

Example

terminal.with_title_callback(|window, cx, title| {
    // Update window title or tab title
})

pub fn with_clipboard_store_callback( self, callback: impl Fn(&mut Window, &mut Context<'_, TerminalView>, &str) + 'static, ) -> Self

Set a callback to be invoked when the terminal wants to store data to the clipboard.

The callback receives a mutable reference to the window and context, along with the text to store. This is typically triggered by OSC 52 escape sequences.

Arguments

• callback - A function that will be called with the text to store

Example

terminal.with_clipboard_store_callback(|window, cx, text| {
    // Store text to system clipboard
})

pub fn with_exit_callback( self, callback: impl Fn(&mut Window, &mut Context<'_, TerminalView>) + 'static, ) -> Self

Set a callback to be invoked when the terminal process exits.

The callback receives a mutable reference to the window and context, allowing you to close the terminal view or show an exit message.

Arguments

• callback - A function that will be called when the process exits

Example

terminal.with_exit_callback(|window, cx| {
    // Close the terminal tab or show exit message
})

pub fn dimensions(&self) -> (usize, usize)

Get the current terminal dimensions.

Returns

A tuple of (columns, rows).

pub fn resize(&mut self, cols: usize, rows: usize)

Resize the terminal to new dimensions.

This method should be called when the terminal view size changes. It updates the internal grid and notifies the terminal process of the new size.

Arguments

• cols - New number of columns
• rows - New number of rows

pub fn config(&self) -> &TerminalConfig

Get the current terminal configuration.

Returns

A reference to the current configuration.

pub fn focus_handle(&self) -> &FocusHandle

Get the focus handle for this terminal view.

Returns

A reference to the focus handle.

pub fn update_config( &mut self, config: TerminalConfig, cx: &mut Context<'_, Self>, )

Update the terminal configuration.

This method updates the terminal’s configuration, including font settings, padding, and color palette. Changes take effect on the next render.

Arguments

• config - The new configuration to apply
• cx - The context for triggering a repaint

Trait Implementations

impl Render for TerminalView

fn render( &mut self, window: &mut Window, cx: &mut Context<'_, Self>, ) -> impl IntoElement

Render this view into an element tree.