From crossterm 0.6 you are able to use feature flags.

With feature flags, you can pick the features you want which reduces the size of the library and could prevent you from having unnecessary dependencies.

Crossterm provides the following feature flags:

  • input ; reading input events
  • terminal ; terminal actions like resizing
  • style ; styling of the terminal
  • cursor ; moving the terminal cursor
  • screen ; alternate and raw screen

By default, all of those will be enabled.

Cargo.toml

[dependencies]
crossterm = { version="0.9", default-features = false, features = ["screen", "terminal", "cursor", "style", "input"] }

By default all flags are enabled, the types and functions available to use depend on the specified flags.


# #![allow(unused_variables)]
#fn main() {
"cursor" => cursor, BlinkOff, BlinkOn, Down, Goto, Hide, Left, ResetPos, Right, SavePos, Show, TerminalCursor, Up,
"input" => input, AsyncReader, InputEvent, KeyEvent, MouseButton, MouseEvent, SyncReader, TerminalInput
"screen" => AlternateScreen, IntoRawMode, RawScreen
"style" => style, Attribute, Color, Colored, Colorize, ObjectStyle, StyledObject, Styler, color, PrintStyledFont, SetAttr, SetBg, SetFg, TerminalColor
"terminal" => terminal, Clear, ClearType, ScrollDown, ScrollUp, SetSize, Terminal
#}

All modules export types for the ability to use the command api, those are: execute, queue, Command, ExecutableCommand, QueueableCommand

You can also use all the crossterm modules individually by directly referencing the crate.

Command API

The command API makes the use of crossterm much easier and offers more control over when and how a command such as moving the cursor is executed.

The command API offers:

  • Better Performance
  • Complete control over when to flush
  • Complete control over where the ANSI escape commands are executed to
  • Way easier and nicer API

There are two ways to use the API command:

  • By using functions

    The functions can execute commands on types that implement Write. Functions are easier to use and debug. There is a disadvantage, and that is that there is a boilerplate code involved.

  • By using macros

    Macros are generally seen as more difficult but offer an API with less boilerplate code. If you are not afraid of macros, this is a recommendation.

Commands

Crossterm provides the following commands that can be used to perform actions with:

cursor commands

  • Goto (x, y)
  • UP (number of time)
  • Down (number of time)
  • Left (number of time)
  • Right (number of time)
  • SavePos
  • ResetPos
  • Hide
  • Show
  • Blink On
  • Blink Off

style commands

  • SetFg (Color)
  • SetBg (Color)
  • SetAttr (attr)
  • Print Styled Text (text)

terminal command

  • Clear (ClearType)
  • Scroll Up (number of time)
  • Scroll Down (number of time)
  • SetSize (width, height)

other

  • Output (text)

Each crossterm crate provides its command when using crossterm you can use them all at once. When using a single crate or a feature flag, you can only use certain commands.

Before crossterm 10.0 was released, crossterm had some performance issues. It did a flush after each command (cursor movement). A flush is heavy action on the terminal, and if it is done more often the performance will go down quickly.

Linux and Windows 10 systems support ANSI escape codes. Those ANSI escape codes are strings or rather a byte sequence. When we write and flush those to the terminal we can perform some action.

Imports


# #![allow(unused_variables)]
#fn main() {
use crossterm::{execute, queue, ExecutableCommand, QueueableCommand};
#}

Lazy Execution

Because flush is a heavy system call we can instead write the commands to the stdout without flushing. When can do a flush we do want to execute the commands.

If you create a terminal editor or TUI, it is wise to use this option. For example, you can write commands to the terminal stdout and flush the stdout at every frame. By doing this you can make efficient use of the terminal buffer and get better performance because you are not calling flush after every command.

Examples

functions


# #![allow(unused_variables)]
#fn main() {
let mut stdout = stdout();

stdout = stdout.queue(Goto(5,5));

// some other code ...

stdout.flush();
#}

The queue function returns itself, therefore you can use this to queue another command. Like stdout.queue(Goto(5,5)).queue(Clear(ClearType::All))

macro's


# #![allow(unused_variables)]
#fn main() {
let mut stdout = stdout();

queue!(stdout,  Goto(5, 5));

// some other code ...

// flush when you want to execute the 'queued' commands
stdout.flush();
#}

You can pass more than one command into the macro like: queue!(stdout, Goto(5, 5), Clear(ClearType::All));; they will be executed in the given order from left to right.

Direct Execution

If you want to execute commands directly, this is also possible. You don't have to flush the 'stdout', as described above. This is fine if you are not executing lots of commands.

functions


# #![allow(unused_variables)]
#fn main() {
stdout().execute(Goto(5,5));
#}

The execute function returns it self, therefore you are able to use this to execute another command like stdout.execute(Goto(5,5)).execute(Clear(ClearType::All))

macro's


# #![allow(unused_variables)]
#fn main() {
execute!(stdout,  Goto(5, 5));
#}

You can pass more than one command into the macro like: queue!(stdout, Goto(5, 5), Clear(ClearType::All));; they will be executed in the given order from left to right.

Short Examples

Print a rectangle colored with magenta and use both direct execution and lazy execution.

rectangle with command functions


# #![allow(unused_variables)]
#fn main() {
use crossterm::{ExecutableCommand, QueueableCommand, Color, PrintStyledFont, Colorize};
use std::io::stdout();

let mut stdout = stdout();

stdout = stdout.execute(Clear(ClearType::All));

for y in 0..40 {
   for x in 0..150 {
        if (y == 0 || y == 40 - 1) || (x == 0 || x == 150 - 1) {
            stdout = stdout
                .queue(Goto(x,y))
                .queue(PrintStyledFont( "█".magenta()));
        }
   }
   stdout.flush();
}
#}

rectangle with the macros


# #![allow(unused_variables)]
#fn main() {
use crossterm::{execute, queue, Color, PrintStyledFont, Colorize};
use std::io::stdout();

let mut stdout = stdout();

execute!(stdout, Clear(ClearType::All));

for y in 0..40 {
   for x in 0..150 {
        if (y == 0 || y == 40 - 1) || (x == 0 || x == 150 - 1) {
            queue!(stdout, Goto(x,y), PrintStyledFont( "█".magenta()));
        }
   }
   stdout.flush();
} 
#}

Styling Module

Crossterm provides options for you to style your text and terminal. Take for example coloring output and applying attributes.

Color support Windows systems with versions less than 10 will only have support for 16 colors and don't have any support for attributes. Most UNIX-terminal is supporting lots of colors and attributes.

Colors

There are 16 base colors which available for almost all terminals even windows 7 and 8.

Light Variant Dark Variant
Grey Black
Red DarkRed
Green DarkGreen
Yellow DarkYellow
Blue DarkBlue
Magenta DarkMagenta
Cyan DarkCyan
White DarkWhite

In addition to 16 colors, most UNIX terminals and Windows 10 consoles are also supporting more colors. Those colors could be: True color (24-bit) coloring scheme, which allows you to use RGB, and 256 (Xterm, 8-bit) colors. Checkout the examples on how to use this feature.

Attributes

Only UNIX and Windows 10 terminals are supporting attributes on top of the text. Crossterm allows you to add attributes to the text. Not all attributes are widely supported for all terminals, keep that in mind when working with this.

Crossterm implements almost all attributes shown in this Wikipedia-list.

Attribute Support Note
Reset Windows, UNIX This will reset all current set attributes.
Bold Windows, UNIX This will increase the text sensitivity also known as bold.
Dim Windows, UNIX This will decrease the text sensitivity also known as bold.
Italic Not widely supported, sometimes treated as inverse. This will make the text italic.
Underlined Windows, UNIX A line under a word, especially in order to show its importance.
SlowBlink Not widely supported, sometimes treated as inverse. less than 150 per minute
RapidBlink Not widely supported MS-DOS ANSI.SYS; 150+ per minute;
Reverse Windows, UNIX foreground and background colors
Hidden Windows, UNIX Also known as 'Conceal'
Fraktur UNIX characters legible, but marked for deletion.
DefaultForegroundColor Unknown Implementation defined (according to standard)
DefaultBackgroundColor Unknown Implementation defined (according to standard)
Framed Not widely supported Framed text.
Encircled Unknown This will turn on the encircled attribute.
OverLined Unknown This will draw a line at the top of the text.

(There are a few attributes who disable one of the above attributes, I did not write those down to keep the list short).

Now we have covered the basics of styling lets go over to some examples.

Example

setup the basics

extern crate crossterm;

use crossterm::{Colored, Color, Attribute, Styler, Colorize};

fn main() {
    /* your code here */
}

There are a couple of ways to style the terminal output with crossterm. The most important part of the styling module is StyledObject.

A StyledObject is just a wrapper crossterm uses to store the text and style together. A StyledObject implements Display and thus you could use it inside print!, println! etc.

Without further ado let's get straight into it.

Coloring

There are a few ways to do the coloring, the first one is by using the Colored enum.

Using Enum


# #![allow(unused_variables)]
#fn main() {
println!("{} Red foreground color", Colored::Fg(Color::Red));
println!("{} Blue background color", Colored::Bg(Color::Blue));
#}

Colored::Bg will set the background color, and Colored::Fg will set the foreground color to the provided color. The provided color is of type Color and has a bunch of enum values you could choose out.

Because Colored implements Display you are able to use it inside any write statement.

Using Methods

You can do the same as the above in a slightly different way. Instead of enabling it for all text you could also color the only piece of text. (Make sure to include the crossterm::Coloring trait).


# #![allow(unused_variables)]
#fn main() {
let styled_text = "Red forground color on blue background.".red().on_blue();
println!("{}", styled_text);
#}

As you see in the above example you could call coloring methods on a string. How is this possible you might ask..? Well, the trait Coloring, who you need to include, is implemented for &'static str. When calling a method on this string crossterm transforms it into a StyledObject who you could use in your write statements.

RGB

Most UNIX terminals and all Windows 10 consoles are supporting True color(24-bit) coloring scheme. You can set the color of the terminal by using Color::RGB(r,g,b).

// custom rgb value (Windows 10 and UNIX systems)
println!("{}{} 'Light green' text on 'Black' background", Colored::Fg(Color::Rgb { r: 0, g: 255, b: 128 }), Colored::Bg(Color::Rgb {r: 0, g: 0, b: 0}));

This will print some light green text on black background.

Custom ANSI color value

When working on UNIX or Windows 10 you could also specify a custom ANSI value ranging up from 0 to 256. See 256 (Xterm, 8-bit) colors for more information.

// custom ansi color value (Windows 10 and UNIX systems)
println!("{} some colored text", Colored::Fg(Color::AnsiValue(10)));

Attributes

When working with UNIX or Windows 10 terminals you could also use attributes to style your text. For example, you could cross your text with a line and make it bold. See this for more information.

Using Enum

You could use the Attribute enum for styling text with attributes. Attribute implements Display, thus crossterm will enable the attribute style when using it in any writing operation.

println!(
    "{} Underlined {} No Underline",
    Attribute::Underlined,
    Attribute::NoUnderline
);

Using Method

You can do the same as the above in a slightly different way. Instead of enabling it for all text you could also style only one piece of text. (Make sure to include the crossterm::Styler trait).

println!("{}", "Bold text".bold();
println!("{}", "Underlined text".underlined();
println!("{}", "Negative text".negative();

As you see in the above example you could call attributes methods on a string. How is this possible you might ask..? Well, the trait Styling, who you need to include, is implemented for &'static str. When calling a method on any string crossterm transforms will transform it into a StyledObject who you could use in your write statements.


More examples could be found at this link.

Crossterm provides a way to work with the terminal input. We will not cover the basic usage but instead asynchronous and synchronous reading of input. Please check out these examples for reading a line or a character from the user.

Differences Synchronous and Asynchronous

Crossterm provides two ways to read user input, synchronous and asynchronous.

Synchronous reading

Read the input synchronously from the user, the reads performed will be blocking calls. Using synchronous over asynchronous reading has the benefit that it is using fewer resources than the asynchronous because background thread and queues are left away.

You can get asynchronous event reader by calling: TerminalInput::read_sync.

Asynchronous reading

Read the input asynchronously, input events are gathered in the background and will be queued for you to read. Using asynchronous reading has the benefit that input events are queued until you read them. You can poll for occurred events, and the reads won't block your program.

You can get a synchronous event reader by calling: TerminalInput::read_async, TerminalInput::read_async_until.

Technical details

On UNIX systems crossterm reads from the TTY, on Windows, it uses ReadConsoleInputW. For asynchronous reading, a background thread will be fired up to read input events, occurred events will be queued on an MPSC-channel, and the user can iterate over those events.

The terminal has to be in raw mode, raw mode prevents the input of the user to be displayed on the terminal screen, see screen for more info.

Example

In the following example, we will create a small program that will listen for mouse and keyboard input. On the press of the 'escape' key, the program will be stopped.

So let's start by setting up the basics.

use std::{thread, time::Duration};
use crossterm::{input, InputEvent, KeyEvent};

fn main() {
    println!("Press 'ESC' to quit.");

    /* next code here */
}

Next, we need to put the terminal into raw mode. We do this because we don't want the user input to be printed to the terminal screen.


# #![allow(unused_variables)]
#fn main() {
// enable raw mode
let screen = RawScreen::into_raw_mode();

// create a input from our screen
let input = input();

/* next code here */
#}

Now that we constructed a TerminalInput instance we can go ahead an start the reading. Do this by calling input.read_async(), which returns an AsyncReader. This is an iterator over the input events that you could as any other iterator.


# #![allow(unused_variables)]
#fn main() {
let mut async_stdin = input.read_async();

loop {
    if let Some(key_event) = async_stdin.next() {
        /* next code here */
    }
    thread::sleep(Duration::from_millis(50));
}
#}

The AsyncReader iterator will return None when nothing is there to read, Some(InputEvent) if there are events to read. I use a thread delay to prevent spamming the iterator.

Next up we can start pattern matching to see if there are input events we'd like to catch. In our case, we want to catch the Escape Key.


# #![allow(unused_variables)]
#fn main() {
 match key_event {
    InputEvent::Keyboard(event) => match event {
        KeyEvent::Esc => {
            println!("Program closing ...");
            break
        }
        _ => println!("Key {:?} was pressed!", event)
    }
    InputEvent::Mouse(event) => { /* Mouse Event */ }
    _ => { }
}
#}

As you see, we check if the KeyEvent::Esc was pressed, if that's true we stop the program by breaking out of the loop.

final code

use std::{thread, time::Duration};
use crossterm::{input, InputEvent, KeyEvent};

fn main() {
    println!("Press 'ESC' to quit.");

    // enable raw mode
    let screen = RawScreen::into_raw_mode();

    // create a input from our screen.
    let input = input();

    // create async reader
    let mut async_stdin = input.read_async();

    loop {
        // try to get the next input event.
        if let Some(key_event) = async_stdin.next() {
            match key_event {
                InputEvent::Keyboard(event) => match event {
                    KeyEvent::Esc => {
                        println!("Program closing ...");
                        break
                    }
                    _ => println!("Key {:?} was pressed!", event)
                }
                InputEvent::Mouse(event) => { /* Mouse Event */ }
                _ => { }
            }
        }
        thread::sleep(Duration::from_millis(50));
    }
} // <=== background reader will be disposed when dropped.s

More robust and complete examples on all input aspects like mouse, keys could be found here.

Screen Buffer

A screen buffer is a two-dimensional array of characters and color data to be output in a console window. A terminal can have multiple of those screen buffers, and the active screen buffer is the one that is displayed on the screen.

Crossterm allows you to switch between those buffers; the screen you are working in is called the 'main screen'. We call the other screen the 'alternate screen'. One note to take is that crossterm does not support the creation and switching between several buffers.

Alternate Screen

Normally you are working on the main screen but an alternate screen is somewhat different from a normal screen. For example, it has the exact dimensions of the terminal window, without any scrollback region. An example of this is vim when it is launched from bash.

Vim uses the entirety of the screen to edit the file, then exits to bash leaving the original buffer unchanged.

Crossterm provides the ability to switch to the alternate screen, make some changes, and then go back to the main screen. The main screen will still have its original data since we made all the edits on the alternate screen.

Raw screen

To understand the concept of a 'raw screen' let's look at the following points:

No line buffering. Normally the terminals use line buffering. This means that the input will be sent to the terminal line by line. With raw mode, the input will send one byte at a time.

Input

All input has to be written to the screen buffer manually by the programmer.

Characters

The characters are not processed by the terminal driver. Also, special character has no meaning. For example, backspace will not be interpreted as backspace but instead will be sent directly to the terminal.

Escape Characters Note that in raw mode \n \r will move the cursor to a new line but it will be at the same position as it was on the previous line.

example of what I mean

some text
         some text

To start at the beginning of the next line, use \n\r.


More examples could be found over here.