Struct ratatui::backend::TermwizBackend

pub struct TermwizBackend { /* private fields */ }

Available on crate feature termwiz only.

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

The TermwizBackend struct is a wrapper around a BufferedTerminal, 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 TermwizBackend directly, but will instead use the Terminal struct, which provides a more ergonomic interface.

This backend automatically enables raw mode and switches to the alternate screen when it is created using the TermwizBackend::new method (and disables raw mode and returns to the main screen when dropped). Use the TermwizBackend::with_buffered_terminal to create a new instance with a custom BufferedTerminal if this is not desired.

Example

use ratatui::prelude::*;

let backend = TermwizBackend::new()?;
let mut terminal = Terminal::new(backend)?;

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

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

Implementations

impl TermwizBackend

pub fn new() -> Result<Self, Box<dyn Error>>

Creates a new Termwiz backend instance.

The backend will automatically enable raw mode and enter the alternate screen.

Errors

Returns an error if unable to do any of the following:

• query the terminal capabilities.
• enter raw mode.
• enter the alternate screen.
• create the system or buffered terminal.

Example

let backend = TermwizBackend::new()?;

Examples found in repository

examples/demo/termwiz.rs (line 15)

pub fn run(tick_rate: Duration, enhanced_graphics: bool) -> Result<(), Box<dyn Error>> {
    let backend = TermwizBackend::new()?;
    let mut terminal = Terminal::new(backend)?;
    terminal.hide_cursor()?;

    // create app and run it
    let app = App::new("Termwiz Demo", enhanced_graphics);
    let res = run_app(&mut terminal, app, tick_rate);

    terminal.show_cursor()?;
    terminal.flush()?;

    if let Err(err) = res {
        println!("{err:?}");
    }

    Ok(())
}

pub const fn with_buffered_terminal( instance: BufferedTerminal<SystemTerminal> ) -> Self

Creates a new Termwiz backend instance with the given buffered terminal.

pub const fn buffered_terminal(&self) -> &BufferedTerminal<SystemTerminal>

Returns a reference to the buffered terminal used by the backend.

pub fn buffered_terminal_mut(&mut self) -> &mut BufferedTerminal<SystemTerminal>

Returns a mutable reference to the buffered terminal used by the backend.

Examples found in repository

examples/demo/termwiz.rs (line 45)

fn run_app(
    terminal: &mut Terminal<TermwizBackend>,
    mut app: App,
    tick_rate: Duration,
) -> Result<(), Box<dyn Error>> {
    let mut last_tick = Instant::now();
    loop {
        terminal.draw(|f| ui::draw(f, &mut app))?;

        let timeout = tick_rate.saturating_sub(last_tick.elapsed());
        if let Some(input) = terminal
            .backend_mut()
            .buffered_terminal_mut()
            .terminal()
            .poll_input(Some(timeout))?
        {
            match input {
                InputEvent::Key(key_code) => match key_code.key {
                    KeyCode::UpArrow | KeyCode::Char('k') => app.on_up(),
                    KeyCode::DownArrow | KeyCode::Char('j') => app.on_down(),
                    KeyCode::LeftArrow | KeyCode::Char('h') => app.on_left(),
                    KeyCode::RightArrow | KeyCode::Char('l') => app.on_right(),
                    KeyCode::Char(c) => app.on_key(c),
                    _ => {}
                },
                InputEvent::Resized { cols, rows } => {
                    terminal
                        .backend_mut()
                        .buffered_terminal_mut()
                        .resize(cols, rows);
                }
                _ => {}
            }
        }

        if last_tick.elapsed() >= tick_rate {
            app.on_tick();
            last_tick = Instant::now();
        }
        if app.should_quit {
            return Ok(());
        }
    }
}

Trait Implementations

impl Backend for TermwizBackend

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 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.

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

Insert n line breaks to the terminal screen.

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

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