Struct ratatui::backend::CrosstermBackend

pub struct CrosstermBackend<W: Write> { /* private fields */ }

Available on crate feature crossterm only.

A Backend implementation that uses Crossterm to render to the terminal.

The CrosstermBackend struct is a wrapper around a writer implementing Write, which is used to send commands to the terminal. It provides methods for drawing content, manipulating the cursor, and clearing the terminal screen.

Most applications should not call the methods on CrosstermBackend directly, but will instead use the Terminal struct, which provides a more ergonomic interface.

Usually applications will enable raw mode and switch to alternate screen mode after creating a CrosstermBackend. This is done by calling crossterm::terminal::enable_raw_mode and crossterm::terminal::EnterAlternateScreen (and the corresponding disable/leave functions when the application exits). This is not done automatically by the backend because it is possible that the application may want to use the terminal for other purposes (like showing help text) before entering alternate screen mode.

Example

use std::io::{stderr, stdout};

use crossterm::{
    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
    ExecutableCommand,
};
use ratatui::prelude::*;

let mut backend = CrosstermBackend::new(stdout());
// or
let backend = CrosstermBackend::new(stderr());
let mut terminal = Terminal::new(backend)?;

enable_raw_mode()?;
stdout().execute(EnterAlternateScreen)?;

terminal.clear()?;
terminal.draw(|frame| {
    // -- snip --
})?;

stdout().execute(LeaveAlternateScreen)?;
disable_raw_mode()?;

See the the Examples directory for more examples. See the backend module documentation for more details on raw mode and alternate screen.

Implementations

impl<W> CrosstermBackend<W>

where W: Write,

pub const fn new(writer: W) -> Self

Creates a new CrosstermBackend with the given writer.

Example

let backend = CrosstermBackend::new(stdout());

Examples found in repository

examples/canvas.rs (line 206)

fn init_terminal() -> io::Result<Terminal<CrosstermBackend<Stdout>>> {
    enable_raw_mode()?;
    stdout().execute(EnterAlternateScreen)?;
    Terminal::new(CrosstermBackend::new(stdout()))
}

examples/ratatui-logo.rs (line 77)

fn init() -> io::Result<Terminal<impl Backend>> {
    enable_raw_mode()?;
    let options = TerminalOptions {
        viewport: Viewport::Inline(3),
    };
    Terminal::with_options(CrosstermBackend::new(stdout()), options)
}

examples/constraint-explorer.rs (line 637)

fn init_terminal() -> Result<Terminal<impl Backend>> {
    enable_raw_mode()?;
    stdout().execute(EnterAlternateScreen)?;
    let backend = CrosstermBackend::new(stdout());
    let terminal = Terminal::new(backend)?;
    Ok(terminal)
}

examples/flex.rs (line 541)

fn init_terminal() -> Result<Terminal<impl Backend>> {
    enable_raw_mode()?;
    stdout().execute(EnterAlternateScreen)?;
    let backend = CrosstermBackend::new(stdout());
    let terminal = Terminal::new(backend)?;
    Ok(terminal)
}

examples/gauge.rs (line 234)

fn init_terminal() -> color_eyre::Result<Terminal<impl Backend>> {
    enable_raw_mode()?;
    stdout().execute(EnterAlternateScreen)?;
    let backend = CrosstermBackend::new(stdout());
    let terminal = Terminal::new(backend)?;
    Ok(terminal)
}

examples/list.rs (line 94)

fn init_terminal() -> color_eyre::Result<Terminal<impl Backend>> {
    enable_raw_mode()?;
    stdout().execute(EnterAlternateScreen)?;
    let backend = CrosstermBackend::new(stdout());
    let terminal = Terminal::new(backend)?;
    Ok(terminal)
}

Additional examples can be found in:

• examples/tabs.rs
• examples/block.rs
• examples/colors_rgb.rs
• examples/panic.rs
• examples/hello_world.rs
• examples/demo2/term.rs
• examples/custom_widget.rs
• examples/layout.rs
• examples/popup.rs
• examples/table.rs
• examples/user_input.rs
• examples/calendar.rs
• examples/inline.rs
• examples/barchart.rs
• examples/chart.rs
• examples/paragraph.rs
• examples/sparkline.rs
• examples/scrollbar.rs
• examples/demo/crossterm.rs

Trait Implementations

impl<W> Backend for CrosstermBackend<W>

where W: Write,

fn draw<'a, I>(&mut self, content: I) -> Result<()>

where I: Iterator<Item = (u16, u16, &'a Cell)>,

Draw the given content to the terminal screen.

fn hide_cursor(&mut self) -> Result<()>

Hide the cursor on the terminal screen.

fn show_cursor(&mut self) -> Result<()>

Show the cursor on the terminal screen.

fn get_cursor(&mut self) -> Result<(u16, u16)>

Get the current cursor position on the terminal screen.

fn set_cursor(&mut self, x: u16, y: u16) -> Result<()>

Set the cursor position on the terminal screen to the given x and y coordinates.

fn clear(&mut self) -> Result<()>

Clears the whole terminal screen

fn clear_region(&mut self, clear_type: ClearType) -> Result<()>

Clears a specific region of the terminal specified by the ClearType parameter

fn append_lines(&mut self, n: u16) -> Result<()>

Insert n line breaks to the terminal screen.

fn size(&self) -> Result<Rect>

Get the size of the terminal screen in columns/rows as a Rect.

fn window_size(&mut self) -> Result<WindowSize>

Get the size of the terminal screen in columns/rows and pixels as a WindowSize.

fn flush(&mut self) -> Result<()>

Flush any buffered content to the terminal screen.

impl<W: Clone + Write> Clone for CrosstermBackend<W>

fn clone(&self) -> CrosstermBackend<W>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<W: Debug + Write> Debug for CrosstermBackend<W>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<W: Default + Write> Default for CrosstermBackend<W>

fn default() -> CrosstermBackend<W>

Returns the “default value” for a type.

impl<W: Hash + Write> Hash for CrosstermBackend<W>

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<W: PartialEq + Write> PartialEq for CrosstermBackend<W>

fn eq(&self, other: &CrosstermBackend<W>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<W> Write for CrosstermBackend<W>

where W: Write,

fn write(&mut self, buf: &[u8]) -> Result<usize>

Writes a buffer of bytes to the underlying buffer.

fn flush(&mut self) -> Result<()>

Flushes the underlying buffer.

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Writer has an efficient write_vectored implementation.

fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this writer.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

🔬This is a nightly-only experimental API. (write_all_vectored)

Attempts to write multiple buffers into this writer.

fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Write.

impl<W: Eq + Write> Eq for CrosstermBackend<W>

impl<W: Write> StructuralPartialEq for CrosstermBackend<W>