Crate terminput

terminput

A library to abstract over various backends that provide input events, such as key presses and mouse clicks. This was mainly created as a common interface to the terminal backends that Ratatui supports.

Many TUI libraries want to support input from multiple backends, but mapping each backend’s input structure into a common interface can be tedious. This library aims to provide a uniform interface to these types.

Additionally, we supply methods for parsing and encoding ANSI escape sequences for events.

Usage

Use try_into to convert to and from terminput’s event types.

use crossterm::event::read;
use std::io;
use terminput::Event;

fn main() -> io::Result<()> {
    let crossterm_event = read()?;
    let event: Result<Event, _> = crossterm_event.try_into();
    println!("{event:?}");

    if let Ok(event) = event {
        // Conversions work both ways
        let event2: Result<crossterm::event::Event, _> = event.try_into();
        println!("{event2:?}");
    }

    Ok(())
}

Backends

The following backends are currently supported. All backends are disabled by default and each can be enabled with a feature flag of the same name.

• crossterm
• termion
• termwiz
• egui

The Event struct provided by this library is an attempt to create a superset of all supported backend functionality that TUI apps may be interested in.

The following table shows the matrix of supported features:

	crossterm	termion	termwiz	egui
key press	✓	✓	✓	✓
key release/repeat	✓			✓
mouse down	✓	✓	✓	✓
mouse up	✓	✓		✓
mouse move	✓		✓	✓
mouse drag	✓	✓
focus	✓			✓
paste	✓		✓	✓
resize	✓		✓

Parsing

Use the Event::parse_from method to parse an ANSI-encoded sequence of bytes into an event struct. This can be helpful for usage with SSH or other situations where you need to read raw input from something other than a normal TTY device.

The input parser used here was extracted from crossterm’s implementation.

use terminput::Event;

fn read_input(input: &[u8]) {
    let event = Event::parse_from(input);

    match event {
        Ok(Some(event)) => {
            println!("Successfully parsed input: {event:?}");
        }
        Ok(None) => {
            println!("More input required");
        }
        Err(e) => {
            println!("Unable to parse input: {e:?}");
        }
    }
}

Encoding

Input structs can also be encoded into ANSI escape sequences using Event::encode. This can be useful if you’re controlling a child pty and need to send it some encoded input.

use terminput::{Encoding, Event, KeyCode, KeyEvent, KittyFlags};

let event = Event::Key(KeyEvent::new(KeyCode::Char('a')));
let mut buf = [0; 16];

// Legacy encoding
let written = event.encode(&mut buf, Encoding::Xterm);
if let Ok(written) = written {
    println!("Encoded: {:?}", &buf[..written]);
}

// Kitty encoding
let mut buf = [0; 16];
let written = event.encode(&mut buf, Encoding::Kitty(KittyFlags::all()));
if let Ok(written) = written {
    println!("Encoded: {:?}", &buf[..written]);
}

Structs

KeyEvent

A key input event.

KeyEventState

Represents extra state about the key event.

KeyModifiers

Represents key modifiers (shift, control, alt, etc.).

KittyFlags

Controls which keyboard enhancement flags will be considered during encoding. These flags are described in Kitty’s documentation on progressive enhancement.

MouseEvent

A mouse event.

ScrollDelta

Represents the change that should be applied to the content in response to a scroll event.

UnsupportedEvent

The supplied event could not be converted into the requested type.

Enums

Encoding

Encoding protocol used to control the output of Event::encode

Event

An application event.

KeyCode

Represents a key.

KeyEventKind

Type of key event. Repeat and release events may not be emitted if the input source is not configured to do so.

MediaKeyCode

Media keys.

ModifierDirection

Represents whether the modifier came from the left or right side of the keyboard, where applicable.

ModifierKeyCode

A modifier key event.

MouseButton

The mouse button used for this event.

MouseEventKind

The type of mouse event.

ScrollDirection

Mouse scroll direction.