10 unstable releases (3 breaking)
new 0.4.2 | Mar 25, 2025 |
---|---|
0.4.1 | Mar 25, 2025 |
0.3.1 | Feb 14, 2025 |
0.2.2 | Feb 1, 2025 |
0.1.1 | Jan 22, 2025 |
#175 in Command-line interface
297 downloads per month
Used in 4 crates
86KB
2K
SLoC
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 the conversion methods provided by the integration crates to convert to and
from from terminput
's event types.
use crossterm::event::read;
use std::io;
use terminput::Event;
use terminput_crossterm::{to_crossterm, to_terminput};
fn main() -> io::Result<()> {
let crossterm_event = read()?;
let event: Result<Event, _> = to_terminput(crossterm_event);
println!("{event:?}");
if let Ok(event) = event {
// Conversions work both ways
let event2: Result<crossterm::event::Event, _> = to_crossterm(event);
println!("{event2:?}");
}
Ok(())
}
Event Matching
Some helpers for matching on events are included. See the
match_event
example.
Backends
The following backends are currently supported via separate integration crates:
crossterm
-terminput-crossterm
termion
-terminput-termion
termwiz
-terminput-termwiz
egui
-terminput-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]);
}
Dependencies
~75–265KB