Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Input

Input is everything a person does that a program needs to hear about: keys, mouse events, focus changes and pastes. All of it reaches the program the same way, as bytes on the pty. These functions produce those bytes.

The catch is that the right bytes keep changing. The up arrow is ESC [ A until a program turns on cursor key application mode, and then it’s ESC O A. A program can turn on the Kitty keyboard protocol and get a different encoding for its keys. A click is nothing at all until a program turns on mouse tracking, and then it’s one of five formats. A paste is framed differently under bracketed paste.

So an encoder has to follow the terminal’s modes, or it writes the wrong bytes.

If you have a Terminal, following its modes takes one call per encoder. That’s the first section, and it’s the one thing on this page you have to get right. If you only feed a terminal output and read the result, you can skip this page. You need it as soon as a person can type into your terminal.

Following the terminal’s modes

Each kind of input follows the terminal in its own way:

InputHow it follows the terminal
Keyskey::Encoder::set_options_from_terminal copies the modes into the encoder.
Mousemouse::Encoder::set_options_from_terminal copies the tracking mode and format into the encoder.
FocusThere’s no encoder. You check the mode yourself.
PasteTerminal::paste reads the modes itself.

The two set_options_from_terminal calls read the terminal’s state when you make them. They don’t stay attached to it, and a program can change its modes in any write. So sync the encoder after you write to the terminal, or right before you encode.

// Create a terminal and feed it some VT data that changes modes.
let mut terminal = Terminal::new(80, 24)?;

// The program might enable the Kitty keyboard protocol here.
terminal.vt_write(data);

// Create an encoder and sync its options from the terminal.
let encoder = key::Encoder::new()?;
encoder.set_options_from_terminal(&terminal);

// Encode a key event using the terminal's modes.
let mut buf = [0u8; 128];
let written = encoder.encode(event, &mut buf)?;

The mouse works the same way with mouse::Encoder::new, mouse::Encoder::set_options_from_terminal and mouse::Encoder::encode.

Each sync leaves some options to you:

  • The key sync replaces all of the encoder’s options. That covers cursor key application mode, keypad mode, ignoring the keypad with numlock, the alt escape prefix, backarrow key mode, modifyOtherKeys state and the Kitty keyboard flags. It can’t know your macOS option key setting, so it resets key::Encoder::set_macos_option_as_alt to key::OptionAsAlt::False. If you use that option, set it again after every sync.
  • The mouse sync sets the tracking mode and output format. It doesn’t touch the size or whether a button is held. Those are yours. See Mouse.

Without a terminal, there’s nothing to follow. Set the options yourself with the various setters on key::Encoder and mouse::Encoder, as the examples below do.

Keys

We encode keys with the legacy encoding or the Kitty keyboard protocol, depending on the encoder’s options.

  1. Create an encoder with key::Encoder::new.
  2. Configure it with key::Encoder::set_options_from_terminal, or with other setters if you don’t have a terminal.
  3. For each key event, create an event with key::Event::new, set its action, key, modifiers and so on, and encode it with key::Encoder::encode. Then drop it, or change its properties and use it again.

This one has no terminal, so it turns on the Kitty keyboard protocol by hand:

use libghostty_vt::{error::Error, key};

fn main() -> Result<(), Error> {
    // Create encoder
    let mut encoder = key::Encoder::new()?;

    // Enable Kitty keyboard protocol with all features
    encoder.set_kitty_flags(key::KittyKeyFlags::ALL);

    // Create and configure key event for Ctrl+C press
    let mut event = key::Event::new()?;
    event
        .set_action(key::Action::Press)
        .set_key(key::Key::C)
        .set_mods(key::Mods::CTRL)
        .set_unshifted_codepoint('c');

    // Encode the key event
    let mut buf = [0u8; 128];
    let len = encoder.encode(&event, &mut buf)?;

    // Use the encoded sequence (e.g., write to terminal)
    println!("{}", buf[0..len].escape_ascii());
    Ok(())
}

Full program: rust-vt-encode-key/src/main.rs

Not every key event produces output. An unmodified modifier key usually doesn’t, for example. Those events return Ok(0), so check the count before you write to the pty.

Most sequences are short, so a fixed buffer of 128 bytes usually does. If it’s too small, you get Error::OutOfSpace with the size you need. Discard what’s in the buffer and encode again with a bigger one.

Mouse

We encode mouse events in the X10, UTF-8, SGR, URxvt and SGR-Pixels formats. The steps are the same as for keys:

  1. Create an encoder with mouse::Encoder::new.
  2. Configure it with mouse::Encoder::set_options_from_terminal, or with other setters if you don’t have a terminal.
  3. For each mouse event, create an event with mouse::Event::new, set its action, button, modifiers and position, and encode it with mouse::Encoder::encode. Then drop it or reuse it.

Event positions are in surface-space pixels, so the encoder has to know your geometry to turn them into cells. Set it with mouse::Encoder::set_size. The default is a 1x1 pixel screen with 1x1 pixel cells, which is never what you have. Call mouse::Encoder::set_any_button_pressed as well, to say whether a button is held. Neither one comes from the terminal.

use libghostty_vt::{error::Error, mouse};

fn main() -> Result<(), Error> {
    // Create encoder
    let mut encoder = mouse::Encoder::new()?;

    // Configure SGR format with normal tracking
    encoder
        .set_tracking_mode(mouse::TrackingMode::Normal)
        .set_format(mouse::Format::Sgr);

    // Set terminal geometry for coordinate mapping
    encoder.set_size(mouse::EncoderSize {
        screen_width: 800,
        screen_height: 600,
        cell_width: 10,
        cell_height: 20,
        ..mouse::EncoderSize::default()
    })?;

    // Create and configure a left button press event
    let mut event = mouse::Event::new()?;
    event
        .set_action(mouse::Action::Press)
        .set_button(Some(mouse::Button::Left))
        .set_position(mouse::Position { x: 50.0, y: 40.0 });

    // Encode the mouse event
    let mut buf = [0u8; 128];
    let len = encoder.encode(&event, &mut buf)?;

    // Use the encoded sequence (e.g., write to terminal)
    println!("{}", buf[0..len].escape_ascii());
    Ok(())
}

Full program: rust-vt-encode-mouse/src/main.rs

As with keys, not every event produces output, so check the count. And as with keys, a 128-byte buffer is enough for typical events.

If you call mouse::Encoder::set_track_last_cell with true, the encoder deduplicates motion by the last cell. mouse::Encoder::reset clears that state.

Focus

A program that turns on focus reporting (mode 1004) wants to know when your terminal gains or loses focus. focus::Event::encode encodes that as CSI I or CSI O. There’s no encoder to create and no options to set.

It also doesn’t look at the terminal, so it’s up to you to check the mode first:

if terminal.mode(Mode::FOCUS_EVENT).ok_or(false) {
  // Encode the event and write it to the pty.
}

If the buffer is too small, you get Error::OutOfSpace and the size you need.

use libghostty_vt::focus;

fn main() {
    let mut buf = [0u8; 8];
    if let Ok(len) = focus::Event::Gained.encode(&mut buf) {
        println!("Encoded {} bytes: {}", len, buf[0..len].escape_ascii());
    }
}

Full program: rust-vt-encode-focus/src/main.rs

Paste

What a paste writes to the pty depends on the terminal’s state, so the way to paste is Terminal::paste. You give it the MIME types the clipboard holds (just text/plain for an ordinary paste), a MIME reader callback that produces the data of any one of them, and where the paste came from. The terminal decides how its current modes apply.

The bytes come out of the Terminal::on_pty_write callback, so you need one installed. See Effects.

What gets written

The terminal sends the program a paste event instead of the data if all three of these are true:

A paste event lists the clipboard’s MIME types with a one-time password. No data is read for it. The program then reads what it wants through your clipboard read callback, which arrives with granted set, so you don’t need to ask for permission.

Otherwise the terminal writes the first text representation. Unsafe control bytes are replaced with spaces. If mode 2004 (Mode::BRACKETED_PASTE) is on, the text is wrapped in bracketed paste sequences. If it’s off, newlines are converted to carriage returns.

We only pull data through the MIME reader when a representation is actually pasted, so a clipboard holding a large image next to some text costs nothing. The encoded bytes stream to your callback in chunks as they’re produced, never in one piece. It may run several times for one paste, and you have to write the pieces to the pty in order.

Unsafe pastes

Some text could inject commands: a newline or carriage return when the paste isn’t bracketed, or the bracketed paste terminator when it is. We refuse that text with Error::Rejected and write nothing, unless GhosttyPaste::allow_unsafe is set.

The usual flow is to call once, confirm with the person on Error::Rejected, and call again with allow_unsafe set. Each call reads the text at most once and buffers it whole while the rule is applied. So your source doesn’t have to stay the same between reads. The confirmed retry just pastes whatever the source holds by then, and a refused or failed paste writes nothing at all.

/// What the clipboard holds. A real embedder would keep a handle to the
/// pasteboard or its items here; the data is only produced on demand.
struct Clipboard {
    text: &'static str,
}

impl Clipboard {
    /// Produces the data of one representation when the terminal needs it.
    /// Only the text is ever read: the image is listed on a paste event
    /// but never requested, so a large image costs nothing to paste.
    /// Nothing written to the writer is retained, so the data can be
    /// streamed from anywhere in pieces of any size.
    fn read(&self, mime: &[u8], writer: &mut dyn Write) -> io::Result<()> {
        match mime {
            b"text/plain" => {
                // Stream the text in small pieces just to show that it works.
                for chunk in self.text.as_bytes().chunks(4) {
                    writer.write_all(chunk)?;
                }
                Ok(())
            }
            _ => Err(io::Error::other(
                "image read requested, which never happens",
            )),
        }
    }
}

// Paste whatever the clipboard holds. The terminal applies its own
// state: bracketed paste framing (mode 2004) or a Kitty paste event
// (mode 5522) instead of the text.
fn paste_clipboard(terminal: &mut Terminal<'_, '_>, text: &'static str) {
    let clipboard = Clipboard { text };

    let options = paste::Options::new()
        .with_location(effect::ClipboardLocation::Standard)
        .with_source(paste::Source::Clipboard);

    let mimes = &[
        // The first text representation is what a text paste writes.
        effect::ClipboardMime::new(b"text/plain"),
        // Listed on a paste event, never read.
        effect::ClipboardMime::new(b"image/png"),
    ];

    let mut result = terminal.paste(options, mimes, |mime, writer| clipboard.read(mime, writer));

    if let Err(Error::Rejected) = result {
        // The text could inject commands (e.g. a newline outside of a
        // bracketed paste). Nothing was written; ask, then retry.

        if !confirm_with_user() {
            return;
        }
        result = terminal.paste(options.with_allow_unsafe(true), mimes, |mime, writer| {
            clipboard.read(mime, writer)
        });
    }

    match result {
        // Whether the pty got the text or a paste event depends on the
        // terminal's modes; either way it went through write_pty above, in
        // chunks as the text was read.
        Ok(true) => println!("  written"),
        Ok(false) => println!("  nothing to paste"),
        Err(e) => eprintln!("paste failed: {e}"),
    }
}

Full program: rust-vt-paste/src/main.rs

Without a terminal

If you encode without a terminal, there are two building blocks. paste::is_safe checks whether paste data contains potentially dangerous sequences. It’s conservative, and it ignores terminal state.

fn safety_example() {
    if paste::is_safe(b"hello world") {
        println!("Safe to paste");
    }

    if paste::is_safe(b"rm -rf /\n") {
        println!("Unsafe! Contains newline");
    }
}

Full program: rust-vt-paste/src/main.rs

paste::encode encodes paste data for the pty, including bracketed paste wrapping and unsafe byte stripping. It modifies your input buffer in place.

fn encode_example() {
    let mut buf = [0u8; 64];
    // The input buffer is modified in place (unsafe bytes are stripped).
    let mut data = *b"hello\nworld";

    if let Ok(len) = paste::encode(&mut data, true, &mut buf) {
        println!("Encoded {len} bytes: {}", buf[0..len].escape_ascii());
    }
}

Full program: rust-vt-paste/src/main.rs