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
  • Tested Terminals
• Getting Started
  • Feature Flags
• Other Resources
• Used By
• Contributing

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)
• Ubuntu Desktop Terminal
  • Ubuntu 17.10
  • Pop!_OS ( Ubuntu ) 20.04
• (Arch, Manjaro) KDE Konsole
• (Arch) Kitty
• Linux Mint

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.

```rust use std::io::{stdout, Write};

use crossterm::{ execute, style::{Color, Print, ResetColor, SetBackgroundColor, SetForegroundColor}, ExecutableCommand, Result, event, };

fn main() -> 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

To optional feature flags.

toml [dependencies.crossterm] version = "0.17" features = ["event-stream"]

| Feature | Description | | :----- | :----- | | event-stream | futures::Stream producing Result<Event>.|

Dependency Justification

| Dependency | Used for | Included | | :----- | :----- | :----- | bitflags | KeyModifiers, those are differ based on input.| always | lazy_static | original console color, original terminal mode, saved cursor position, supports ANSI on windows, single event reader per application.| always | parking_lot | used for an RW LOCK. | always | libc | UNIX terminalsize/raw modes/settitle and several other lowlevel functionality. | UNIX only | Mio | event readiness polling, waking up poller | UNIX only | signal-hook| signalhook is used to handle terminal resize SIGNAL with Mio. | UNIX only | winapi| Used for low-level windows system calls which ANSI codes can't replace| windows only | futures| Can be used to for async stream of events | only with a feature flag | serde| Se/dese/realizing of events | only with a feature flag

Other Resources

• API documentation
• Deprecated examples repository

Used By

• Broot
• Cursive
• TUI
• Rust-sloth

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.