Module terminal

Available on crate features dep_crossterm and std only.

A module to work with the terminal.

Terminal

The terminal module provides functionality to work with the terminal.

This documentation does not contain a lot of examples. The reason is that it’s fairly obvious how to use this crate. Although, we do provide examples repository to demonstrate the capabilities.

Most terminal actions can be performed with commands. Please have a look at command documentation for a more detailed documentation.

Screen Buffer

A screen buffer is a two-dimensional array of character and color data which is displayed in a terminal screen.

The terminal has several of those buffers and is able to switch between them. The default screen in which you work is called the ‘main screen’. The other screens are called the ‘alternative screen’.

It is important to understand that crossterm does not yet support creating screens, or switch between more than two buffers, and only offers the ability to change between the ‘alternate’ and ‘main screen’.

Alternate Screen

By default, you will be working on the main screen. There is also another screen called the ‘alternative’ screen. This screen is slightly different from the main screen. For example, it has the exact dimensions of the terminal window, without any scroll-back area.

Crossterm offers the possibility to switch to the ‘alternative’ screen, make some modifications, and move back to the ‘main’ screen again. The main screen will stay intact and will have the original data as we performed all operations on the alternative screen.

An good example of this is Vim. When it is launched from bash, a whole new buffer is used to modify a file. Then, when the modification is finished, it closes again and continues on the main screen.

Raw Mode

By default, the terminal functions in a certain way. For example, it will move the cursor to the beginning of the next line when the input hits the end of a line. Or that the backspace is interpreted for character removal.

Sometimes these default modes are irrelevant, and in this case, we can turn them off. This is what happens when you enable raw modes.

Those modes will be set when enabling raw modes:

• Input will not be forwarded to screen
• Input will not be processed on enter press
• Input will not be line buffered (input sent byte-by-byte to input buffer)
• Special keys like backspace and CTRL+C will not be processed by terminal driver
• New line character will not be processed therefore println! can’t be used, use write! instead

Raw mode can be enabled/disabled with the enable_raw_mode and disable_raw_mode functions.

Examples

use std::io::{self, Write};
use crossterm::{execute, terminal::{ScrollUp, SetSize, size}};

fn main() -> io::Result<()> {
    let (cols, rows) = size()?;
    // Resize terminal and scroll up.
    execute!(
        io::stdout(),
        SetSize(10, 10),
        ScrollUp(5)
    )?;

    // Be a good citizen, cleanup
    execute!(io::stdout(), SetSize(cols, rows))?;
    Ok(())
}

For manual execution control check out crossterm::queue.

Structs

BeginSynchronizedUpdate

A command that instructs the terminal emulator to begin a synchronized frame.

Clear

A command that clears the terminal screen buffer.

DisableLineWrap

Disables line wrapping.

EnableLineWrap

Enable line wrapping.

EndSynchronizedUpdate

A command that instructs the terminal to end a synchronized frame.

EnterAlternateScreen

A command that switches to alternate screen.

LeaveAlternateScreen

A command that switches back to the main screen.

ScrollDown

A command that scrolls the terminal screen a given number of rows down.

ScrollUp

A command that scrolls the terminal screen a given number of rows up.

SetSize

A command that sets the terminal buffer size (columns, rows).

SetTitle

A command that sets the terminal title

WindowSize

Enums

ClearType

Different ways to clear the terminal buffer.

Functions

disable_raw_mode

Disables raw mode.

enable_raw_mode

Enables raw mode.

is_raw_mode_enabled

Tells whether the raw mode is enabled.

size

Returns the terminal size (columns, rows).

supports_keyboard_enhancement

Queries the terminal’s support for progressive keyboard enhancement.

window_size

Returns the terminal size [WindowSize].