2019-09-25 03:45:59 +10:00
< h1 align = "center" > < img width = "440" src = "docs/crossterm_full.png" / > < / h1 >
2019-09-26 00:09:16 +10:00
[![Donate ](https://img.shields.io/badge/Donate-PayPal-green.svg )](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick& hosted_button_id=Z8QK6XU749JB2) ![Travis][s7] [![Latest Version][s1]][l1] [![MIT][s2]][l2] [![docs][s3]][l3] ![Lines of Code][s6] [![Join us on Discord][s5]][l5]
2018-07-15 07:37:21 +10:00
2019-09-26 00:09:16 +10:00
# cross-platform terminal manipulating library.
2019-09-13 05:39:39 +10:00
2019-04-12 04:36:41 +10:00
Have you ever been disappointed when a terminal library for rust was only written for UNIX systems?
2019-09-26 00:09:16 +10:00
Crossterm provides clearing, input handling, styling, cursor movement, and terminal actions for both
Windows and UNIX systems.
2018-07-31 05:35:35 +10:00
Crossterm aims to be simple and easy to call in code.
2018-11-26 00:17:11 +11:00
Through the simplicity of Crossterm, you do not have to worry about the platform you are working with.
2018-07-31 05:35:35 +10:00
2019-09-26 00:09:16 +10:00
This crate supports all UNIX and Windows terminals down to Windows 7 (not all terminals are tested
see [Tested Terminals ](#tested-terminals ) for more info).
2018-07-31 05:35:35 +10:00
2019-09-26 00:09:16 +10:00
This crate consists of five modules that are provided behind
[feature flags ](https://crossterm-rs.github.io/crossterm/docs/feature_flags.html ) so that you can define
which features you'd like to have; by default, all features are enabled.
- [crossterm_style ](https://crates.io/crates/crossterm_style )
- [crossterm_input ](https://crates.io/crates/crossterm_input )
- [crossterm_screen ](https://crates.io/crates/crossterm_screen )
- [crossterm_cursor ](https://crates.io/crates/crossterm_cursor )
- [crossterm_terminal ](https://crates.io/crates/crossterm_terminal )
2019-01-28 07:16:14 +11:00
2018-07-31 05:35:35 +10:00
## Table of contents:
2019-09-26 00:09:16 +10:00
2018-11-26 00:17:11 +11:00
- [Getting started ](#getting-started )
- [Useful links ](#useful-links )
- [Features ](#features )
- [Examples ](#examples )
2019-06-22 02:10:46 +10:00
- [Styled Text ](#styled-text )
2019-05-03 05:47:39 +10:00
- [Cursor ](#cursor )
- [Terminal ](#terminal )
- [Input Reading ](#input-reading )
2018-11-26 00:17:11 +11:00
- [Tested Terminals ](#tested-terminals )
- [Contributing ](#contributing )
- [Authors ](#authors )
- [License ](#license )
2018-07-31 05:35:35 +10:00
## Getting Started
2019-09-26 00:09:16 +10:00
All [examples ](https://github.com/crossterm-rs/examples ) of how crossterm works can be found in the example repository.
2018-07-31 05:35:35 +10:00
Add the Crossterm package to your `Cargo.toml` file.
```
[dependencies]
2019-09-26 00:09:16 +10:00
crossterm = "0.11"
2018-07-31 05:35:35 +10:00
```
2018-11-26 00:17:11 +11:00
### Useful Links
2018-07-31 05:35:35 +10:00
2019-09-26 00:09:16 +10:00
- [Book ](https://crossterm-rs.github.io/crossterm/docs/ )
2018-11-26 00:17:11 +11:00
- [Documentation ](https://docs.rs/crossterm/ )
- [Crates.io ](https://crates.io/crates/crossterm )
2019-09-26 00:09:16 +10:00
- [Examples ](https://github.com/crossterm-rs/examples )
2018-07-31 05:35:35 +10:00
2018-09-23 06:55:30 +10:00
## Features
2018-07-31 05:35:35 +10:00
2018-11-26 00:17:11 +11:00
- Cross-platform
2019-09-26 00:09:16 +10:00
- Multi-threaded (send, sync)
2019-04-11 07:46:30 +10:00
- Detailed Documentation
- Few Dependencies
- Cursor
- Moving _n_ times (up, down, left, right)
- Position (set/get)
- Store cursor position and resetting to that later
- Hiding/Showing
2019-04-12 04:36:41 +10:00
- Blinking Cursor (supported by only some terminals)
2018-07-31 05:35:35 +10:00
- Styled output
2019-04-11 07:46:30 +10:00
- 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)
2019-09-25 03:45:59 +10:00
- Text Attributes: bold, italic, underscore and crossed word and [more ](https://crossterm-rs.github.io/crossterm/docs//styling.html#attributes ) (Windows 10 and UNIX only)
2018-07-31 05:35:35 +10:00
- Terminal
- Clearing (all lines, current line, from cursor down and up, until new line)
2019-04-11 07:46:30 +10:00
- Scrolling (up, down)
- Terminal Size (get/set)
- Alternate Screen
- Raw Screen
- Exit Current Process
2018-08-15 05:40:07 +10:00
- Input
- Read character
- Read line
2019-04-11 07:46:30 +10:00
- Read key input events (async / sync)
- Read mouse input events (press, release, position, button)
2018-07-31 05:35:35 +10:00
2018-09-23 06:55:30 +10:00
## Examples
2019-09-26 00:09:16 +10:00
These are some basic examples demonstrating how to use this crate. See the
[examples ](https://github.com/crossterm-rs/examples ) repository.
2018-09-23 06:55:30 +10:00
2019-07-25 04:10:27 +10:00
### Command API
2019-09-26 00:09:16 +10:00
My first recommendation is to use the [command API ](https://crossterm-rs.github.io/crossterm/docs/command.html )
because this might replace some of the existing API in the future. It is more convenient, faster, and easier to use.
2019-07-25 04:10:27 +10:00
2019-06-22 02:10:46 +10:00
### Styled Text
2019-09-26 00:09:16 +10:00
2019-06-22 02:10:46 +10:00
This module enables you to style the terminal text.
2019-02-23 01:20:24 +11:00
2019-09-26 00:09:16 +10:00
Good documentation can be found at the following places: [docs ](https://docs.rs/crossterm_style/ ),
[book ](https://crossterm-rs.github.io/crossterm/docs/styling.html )
2019-10-01 16:54:40 +10:00
and [examples ](https://github.com/crossterm-rs/examples/blob/master/examples/src/bin/key_events.rs ).
2019-03-22 02:00:30 +11:00
2019-06-22 02:10:46 +10:00
_style text with attributes_
2019-09-26 00:09:16 +10:00
2019-03-22 02:00:30 +11:00
```rust
2019-09-25 03:45:59 +10:00
use crossterm::{Colored, Color, Colorize, Styler, Attribute};
2019-03-22 02:00:30 +11:00
// pass any `Attribute` value to the formatting braces.
println!("{} Underlined {} No Underline", Attribute::Underlined, Attribute::NoUnderline);
// you could also call different attribute methods on a `&str` and keep on chaining if needed.
let styled_text = "Bold Underlined".bold().underlined();
println!("{}", styled_text);
```
2019-06-22 02:10:46 +10:00
_style text with colors_
2019-09-26 00:09:16 +10:00
2019-03-22 02:00:30 +11:00
```rust
println!("{} Red foreground color", Colored::Fg(Color::Red));
println!("{} Blue background color", Colored::Bg(Color::Blue));
// you can also call different coloring methods on a `&str` .
let styled_text = "Bold Underlined".red().on_blue();
println!("{}", styled_text);
```
2019-09-26 00:09:16 +10:00
2019-06-22 02:10:46 +10:00
_style text with RGB and ANSI Value_
2019-09-26 00:09:16 +10:00
2019-03-22 02:00:30 +11:00
```rust
// custom rgb value (Windows 10 and UNIX systems)
println!("{} some colored text", Colored::Fg(Color::Rgb {
2018-08-15 05:40:07 +10:00
r: 10,
g: 10,
b: 10
2018-11-26 00:17:11 +11:00
}));
2018-08-15 05:40:07 +10:00
2019-01-03 02:53:47 +11:00
// custom ansi color value (Windows 10 and UNIX systems)
2019-03-22 02:00:30 +11:00
println!("{} some colored text", Colored::Fg(Color::AnsiValue(10)));
2018-07-31 05:35:35 +10:00
```
2019-03-22 02:00:30 +11:00
2019-03-11 10:09:41 +11:00
### Cursor
2019-09-26 00:09:16 +10:00
2019-04-12 04:36:41 +10:00
This module enables you to work with the terminal cursor.
2018-07-31 05:35:35 +10:00
2019-09-26 00:09:16 +10:00
Good documentation could be found on the following places: [docs ](https://docs.rs/crossterm_cursor/ ) and
[examples ](https://github.com/crossterm-rs/examples ).
2019-03-11 10:09:41 +11:00
2018-07-31 05:35:35 +10:00
```rust
2018-08-22 02:05:53 +10:00
use crossterm::cursor;
2018-07-31 05:35:35 +10:00
2018-11-26 00:17:11 +11:00
let mut cursor = cursor();
2018-07-31 05:35:35 +10:00
2018-08-15 05:40:07 +10:00
/// Moving the cursor
2018-07-31 05:35:35 +10:00
// Set the cursor to position X: 10, Y: 5 in the terminal
cursor.goto(10,5);
2018-08-15 05:40:07 +10:00
// Move the cursor up,right,down,left 3 cells.
2018-07-31 05:35:35 +10:00
cursor.move_up(3);
cursor.move_right(3);
cursor.move_down(3);
cursor.move_left(3);
2018-08-15 05:40:07 +10:00
/// Safe the current cursor position to recall later
2018-07-31 05:35:35 +10:00
// Goto X: 5 Y: 5
cursor.goto(5,5);
// Safe cursor position: X: 5 Y: 5
cursor.save_position();
// Goto X: 5 Y: 20
cursor.goto(5,20);
// Print at X: 5 Y: 20.
print!("Yea!");
// Reset back to X: 5 Y: 5.
2019-09-21 07:50:53 +10:00
cursor.restore_position();
2018-07-31 05:35:35 +10:00
// Print 'Back' at X: 5 Y: 5.
print!("Back");
// hide cursor
cursor.hide();
// show cursor
cursor.show();
// blink or not blinking of the cursor (not widely supported)
cursor.blink(true)
```
2019-03-11 10:09:41 +11:00
### Terminal
2019-09-26 00:09:16 +10:00
2019-04-12 04:36:41 +10:00
This module enables you to work with the terminal in general.
2018-07-31 05:35:35 +10:00
2019-09-26 00:09:16 +10:00
Good documentation could be found on the following places: [docs ](https://docs.rs/crossterm_terminal/ ) and
[examples ](https://github.com/crossterm-rs/examples ).
2019-03-11 10:09:41 +11:00
2018-07-31 05:35:35 +10:00
```rust
2019-01-28 07:16:14 +11:00
use crossterm::{terminal,ClearType};
2018-07-31 05:35:35 +10:00
2018-11-26 00:17:11 +11:00
let mut terminal = terminal();
2018-07-31 05:35:35 +10:00
// Clear all lines in terminal;
terminal.clear(ClearType::All);
// Clear all cells from current cursor position down.
terminal.clear(ClearType::FromCursorDown);
// Clear all cells from current cursor position down.
terminal.clear(ClearType::FromCursorUp);
// Clear current line cells.
terminal.clear(ClearType::CurrentLine);
// Clear all the cells until next line.
terminal.clear(ClearType::UntilNewLine);
// Get terminal size
2018-08-15 05:40:07 +10:00
let (width, height) = terminal.terminal_size();
print!("X: {}, y: {}", width, height);
2018-07-31 05:35:35 +10:00
2018-08-15 05:40:07 +10:00
// Scroll down, up 10 lines.
2018-07-31 05:35:35 +10:00
terminal.scroll_down(10);
terminal.scroll_up(10);
2018-08-15 05:40:07 +10:00
// Set terminal size (width, height)
2018-07-31 05:35:35 +10:00
terminal.set_size(10,10);
// exit the current process.
terminal.exit();
// write to the terminal whether you are on the main screen or alternate screen.
terminal.write("Some text\n Some text on new line");
```
2019-03-11 10:09:41 +11:00
### Input Reading
2019-09-26 00:09:16 +10:00
2019-04-12 04:36:41 +10:00
This module enables you to read user input events.
2019-03-11 10:09:41 +11:00
2019-09-26 00:09:16 +10:00
Good documentation could be found on the following places: [docs ](https://docs.rs/crossterm_input/ ),
[book ](https://crossterm-rs.github.io/crossterm/docs/input.html ) and
[examples ](https://github.com/crossterm-rs/examples ).
2019-03-11 10:09:41 +11:00
_available imports_
```rust
use crossterm_input::{
input, InputEvent, KeyEvent, MouseButton, MouseEvent, TerminalInput, AsyncReader, SyncReader, Screen
};
```
_Simple Readings_
2019-09-26 00:09:16 +10:00
2019-03-11 10:09:41 +11:00
```rust
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._
2019-09-26 00:09:16 +10:00
2019-03-11 10:09:41 +11:00
```rust
2019-09-26 00:09:16 +10:00
// 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.
2019-04-11 07:46:30 +10:00
let screen = RawScreen::into_raw_mode();
2019-03-11 10:09:41 +11:00
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._
2019-09-26 00:09:16 +10:00
2019-03-11 10:09:41 +11:00
```rust
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();
```
2018-11-26 00:17:11 +11:00
### Alternate and Raw Screen
2018-07-31 05:35:35 +10:00
2019-09-26 00:09:16 +10:00
These concepts are a little more complex and would take over the README, please check out
the [docs ](https://docs.rs/crossterm_screen/ ), [book ](https://crossterm-rs.github.io/crossterm/docs/screen.html )
and [examples ](https://github.com/crossterm-rs/examples ).
## Used by
2019-06-08 19:28:32 +10:00
- [Broot ](https://dystroy.org/broot/ )
- [Cursive ](https://github.com/gyscos/Cursive )
- [TUI ](https://github.com/fdehau/tui-rs )
- [Rust-sloth ](https://github.com/jonathandturner/rust-sloth/tree/crossterm-port )
2018-07-31 05:35:35 +10:00
## Tested terminals
- Windows Powershell
- Windows 10 (pro)
- Windows CMD
- Windows 10 (pro)
2018-08-22 02:05:53 +10:00
- Windows 8.1 (N)
2018-07-31 05:35:35 +10:00
- Ubuntu Desktop Terminal
- Ubuntu 17.10
2018-11-26 00:17:11 +11:00
- (Arch, Manjaro) KDE Konsole
- Linux Mint
2018-07-31 05:35:35 +10:00
2019-09-26 00:09:16 +10:00
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!
2018-07-31 05:35:35 +10:00
## Contributing
2019-04-12 04:36:41 +10:00
I highly appreciate it when you contribute to this crate.
2019-07-25 04:10:27 +10:00
Please visit the discord or issue list for more information
2018-07-31 05:35:35 +10:00
## Authors
* **Timon Post** - *Project Owner & creator*
2019-05-05 05:19:44 +10:00
## Support
2019-09-25 03:45:59 +10:00
Would you like crossterm to be even more gorgeous and beautiful? You can help with this by donating.
2019-05-05 05:19:44 +10:00
[![paypal ](https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif )](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick& hosted_button_id=Z8QK6XU749JB2)
2018-07-31 05:35:35 +10:00
## License
2019-09-26 00:09:16 +10:00
This project, crossterm and all it's sub-modules: crossterm_screen, crossterm_cursor, crossterm_style,
crossterm_input, crossterm_terminal, crossterm_winapi, crossterm_utils are licensed under the MIT License - see
the [LICENSE ](https://github.com/crossterm-rs/crossterm/blob/master/LICENSE ) file for details
[s1]: https://img.shields.io/crates/v/crossterm.svg
[l1]: https://crates.io/crates/crossterm
[s2]: https://img.shields.io/badge/license-MIT-blue.svg
[l2]: crossterm/LICENSE
[s3]: https://docs.rs/crossterm/badge.svg
[l3]: https://docs.rs/crossterm/
[s3]: https://docs.rs/crossterm/badge.svg
[l3]: https://docs.rs/crossterm/
[s5]: https://img.shields.io/discord/560857607196377088.svg?logo=discord
[l5]: https://discord.gg/K4nyTDB
[s6]: https://tokei.rs/b1/github/crossterm-rs/crossterm?category=code
[s7]: https://travis-ci.org/crossterm-rs/crossterm.svg?branch=master