mirror of
https://github.com/crossterm-rs/crossterm.git
synced 2025-05-05 15:32:57 +00:00
e063091312
* Add is_ and as_ methods to the event enums
Often application code only cares about a small subset of possible
events. These methods make it simpler to write code which checks whether
an event is a particular event type or converts events into the specific
type (returning an Option).
This can help simplify some nested match blocks. E.g.:
```rust
match event {
Event::Key(key) if key.kind == KeyEventKind::Press => { ... }
}
```
becomes:
```rust
if let Some(key) = event.as_key_press() { ... }
```
Similar flexible methods are aded across all the event enums:
- `Event::is_focus_gained()`
- `Event::is_focus_lost()`
- `Event::is_key()`
- `Event::is_mouse()`
- `Event::is_paste()`
- `Event::is_resize()`
- `Event::is_key_press()`
- `Event::as_key_press() -> Option<&KeyEvent>`
- `MouseEventKind::is_*()`
- `MouseButton::is_*()`
- `KeyEventKind::is_*()`
- `KeyEvent::is_press()`
- `KeyEvent::is_release()`
- `KeyEvent::is_repeat()`
- `KeyCode::is_*()`
- `KeyCode::is_function_key(n)`
- `KeyCode::is_char(c)`
- `KeyCode::as_char() -> Option<char>`
- `KeyCode::is_media_key(media)`
- `KeyCode::is_modifier(modifier)`
- add is_key_release() and is_key_repeat() checks
- add as_key_event()
- rename as_key_press() to as_key_press_event()
- add as_key_repeat_event()
- add as_key_release_event()
- add as_mouse_event()
- add as_paste_event()
- more tests
- update event-match and key-display examples
Cross-platform Terminal Manipulation Library
Crossterm is a pure-rust, terminal manipulation library that makes it possible to write cross-platform text-based interfaces (see features). It supports all UNIX and Windows terminals down to Windows 7 (not all terminals are tested, see Tested Terminals for more info).
Table of Contents
Features
- Cross-platform
- Multi-threaded (send, sync)
- Detailed documentation
- Few dependencies
- Full control over writing and flushing output buffer
- Is tty
- Cursor
- Move the cursor N times (up, down, left, right)
- Move to previous / next line
- Move to column
- Set/get the cursor position
- Store the cursor position and restore to it later
- Hide/show the cursor
- Enable/disable cursor blinking (not all terminals do support this feature)
- Styled output
- Foreground color (16 base colors)
- Background color (16 base colors)
- 256 (ANSI) color support (Windows 10 and UNIX only)
- RGB color support (Windows 10 and UNIX only)
- Text attributes like bold, italic, underscore, crossed, etc
- Terminal
- Clear (all lines, current line, from cursor down and up, until new line)
- Scroll up, down
- Set/get the terminal size
- Exit current process
- Alternate screen
- Raw screen
- Set terminal title
- Enable/disable line wrapping
- Event
- Input Events
- Mouse Events (press, release, position, button, drag)
- Terminal Resize Events
- Advanced modifier (SHIFT | ALT | CTRL) support for both mouse and key events and
- futures Stream (feature 'event-stream')
- Poll/read API
Tested Terminals
- Console Host
- Windows 10 (Pro)
- Windows 8.1 (N)
- Windows Terminal
- Windows 10 x86_64 (Enterprise)
- Windows 11 arm64 (Enterprise)
- Ubuntu Desktop Terminal
- Ubuntu 23.04 64-bit
- Ubuntu 17.10
- Pop!_OS ( Ubuntu ) 20.04
- (Arch, Manjaro) KDE Konsole
- (Arch, NixOS) Kitty
- Linux Mint
- (OpenSuse) Alacritty
- (Chrome OS) Crostini
- Apple
- macOS Monterey 12.7.1 (Intel-Chip)
- macOS Sonama 14.4 (M1 Max, Apple Silicon-Chip)
This crate supports all UNIX terminals and Windows terminals down to Windows 7; however, not all of the terminals have been tested. If you have used this library for a terminal other than the above list without issues, then feel free to add it to the above list - I really would appreciate it!
Getting Started
see the examples directory and documentation for more advanced examples.
Click to show Cargo.toml.
[dependencies]
crossterm = "0.27"
use std::io::{stdout, Write};
use crossterm::{
execute,
style::{Color, Print, ResetColor, SetBackgroundColor, SetForegroundColor},
ExecutableCommand,
event,
};
fn main() -> std::io::Result<()> {
// using the macro
execute!(
stdout(),
SetForegroundColor(Color::Blue),
SetBackgroundColor(Color::Red),
Print("Styled text here."),
ResetColor
)?;
// or using functions
stdout()
.execute(SetForegroundColor(Color::Blue))?
.execute(SetBackgroundColor(Color::Red))?
.execute(Print("Styled text here."))?
.execute(ResetColor)?;
Ok(())
}
Checkout this list with all possible commands.
Feature Flags
[dependencies.crossterm]
version = "0.27"
features = ["event-stream"]
| Feature | Description |
|---|---|
event-stream |
futures::Stream producing Result<Event>. |
serde |
(De)serializing of events. |
events |
Reading input/system events (enabled by default) |
filedescriptor |
Use raw filedescriptor for all events rather then mio dependency |
To use crossterm as a very thin layer you can disable the events feature or use filedescriptor feature.
This can disable mio / signal-hook / signal-hook-mio dependencies.
Dependency Justification
| Dependency | Used for | Included |
|---|---|---|
bitflags |
KeyModifiers, those are differ based on input. |
always |
parking_lot |
locking RwLocks with a timeout, const mutexes. |
always |
libc |
UNIX terminal_size/raw modes/set_title and several other low level functionality. | optional (events feature), UNIX only |
Mio |
event readiness polling, waking up poller | optional (events feature), UNIX only |
signal-hook |
signal-hook is used to handle terminal resize SIGNAL with Mio. | optional (events feature),UNIX only |
winapi |
Used for low-level windows system calls which ANSI codes can't replace | windows only |
futures-core |
For async stream of events | only with event-stream feature flag |
serde |
serializing and deserializing of events | only with serde feature flag |
Other Resources
Used By
Contributing
We highly appreciate when anyone contributes to this crate. Before you do, please, read the Contributing guidelines.
Authors
- Timon Post - Project Owner & creator
License
This project, crossterm and all its sub-crates: crossterm_screen, crossterm_cursor, crossterm_style,
crossterm_input, crossterm_terminal, crossterm_winapi, crossterm_utils are licensed under the MIT
License - see the LICENSE file for details.