Crossterm Input

This crate allows you to read the user input cross-platform. It supports all UNIX and windows terminals down to windows 7 (not all terminals are tested see Tested Terminals for more info)

This crate is a sub-crate of crossterm to read the user input and can be used individually.

Other sub-crates are:

• crossterm_style
• crossterm_terminal
• crossterm_screen
• crossterm_cursor

When you want to use other modules as well you might want to use crossterm with feature flags.

Table of contents:

• Getting started
• Useful links
• Features
• Examples
• Tested Terminals
• Authors
• License

Getting Started

All examples of how crossterm_input works can be found in the examples repository.

Add the crossterm_input package to your Cargo.toml file.

[dependencies]
crossterm_input = "0.4"

Import the crossterm_input modules you want to use.

pub use crossterm_input::{input, AsyncReader, InputEvent, KeyEvent, MouseButton, MouseEvent, SyncReader, TerminalInput};

Useful Links

• Documentation
• Crates.io
• Book
• Examples

Features

These are the features of this crate:

• Cross-platform
• Multi-threaded (send, sync)
• Detailed Documentation
• Few Dependencies
• Input
  • Read character
  • Read line
  • Read key input events (async / sync)
  • Read mouse input events (press, release, position, button)
  • RawScreen (from crossterm_screen)

Examples

The examples repository has more complete and verbose examples.

Simple Readings

let mut input = input();

 match input.read_char() {
    Ok(s) => println!("char typed: {}", s),
    Err(e) => println!("char error : {}", e),
 }
 
 match input.read_line() {
     Ok(s) => println!("string typed: {}", s),
     Err(e) => println!("error: {}", e),
 }

Read input events synchronously or asynchronously.

// make sure to enable raw mode, this will make sure key events won't be handled by the terminal
// it's self and allows crossterm to read the input and pass it back to you.
let screen = RawScreen::into_raw_mode();
    
let mut input = input();

// either read the input synchronously 
let stdin = input.read_sync();
 
// or asynchronously
let stdin = input.read_async();

if let Some(key_event) = stdin.next() {
     match key_event {
         InputEvent::Keyboard(event: KeyEvent) => match event { /* check key event */ }
         InputEvent::Mouse(event: MouseEvent) => match event { /* check mouse event */ }
     }
 }

Enable mouse input events.

let input = input();

// enable mouse events to be captured.
input.enable_mouse_mode().unwrap();

// disable mouse events to be captured.
input.disable_mouse_mode().unwrap();

Tested terminals

• Windows Powershell
  • Windows 10 (pro)
• Windows CMD
  • Windows 10 (pro)
  • Windows 8.1 (N)
• Ubuntu Desktop Terminal
  • Ubuntu 17.10
• (Arch, Manjaro) KDE Konsole
• Linux Mint

This crate supports all Unix terminals and windows terminals down to Windows 7 but not all of them have been tested. If you have used this library for a terminal other than the above list without issues feel free to add it to the above list, I really would appreciate it.

Authors

• Timon Post - Project Owner & creator
• Dave Ho - Contributor

License

This project is licensed under the MIT License - see the LICENSE.md file for details