Trait ratatui::backend::Backend

source ·

pub trait Backend {
    // Required methods
    fn draw<'a, I>(&mut self, content: I) -> Result<()>
       where I: Iterator<Item = (u16, u16, &'a Cell)>;
    fn hide_cursor(&mut self) -> Result<()>;
    fn show_cursor(&mut self) -> Result<()>;
    fn get_cursor(&mut self) -> Result<(u16, u16)>;
    fn set_cursor(&mut self, x: u16, y: u16) -> Result<()>;
    fn clear(&mut self) -> Result<()>;
    fn size(&self) -> Result<Rect>;
    fn window_size(&mut self) -> Result<WindowSize>;
    fn flush(&mut self) -> Result<()>;

    // Provided methods
    fn append_lines(&mut self, _n: u16) -> Result<()> { ... }
    fn clear_region(&mut self, clear_type: ClearType) -> Result<()> { ... }
}

Expand description

The Backend trait provides an abstraction over different terminal libraries. It defines the methods required to draw content, manipulate the cursor, and clear the terminal screen.

Most applications should not need to interact with the Backend trait directly as the Terminal struct provides a higher level interface for interacting with the terminal.

Required Methods§

source

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.

The content is provided as an iterator over (u16, u16, &Cell) tuples, where the first two elements represent the x and y coordinates, and the third element is a reference to the Cell to be drawn.

source

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

Hide the cursor on the terminal screen.

§Example

backend.hide_cursor()?;
// do something with hidden cursor
backend.show_cursor()?;

source

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

Show the cursor on the terminal screen.

See hide_cursor for an example.

source

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

Get the current cursor position on the terminal screen.

The returned tuple contains the x and y coordinates of the cursor. The origin (0, 0) is at the top left corner of the screen.

See set_cursor for an example.

source

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.

The origin (0, 0) is at the top left corner of the screen.

§Example

backend.set_cursor(10, 20)?;
assert_eq!(backend.get_cursor()?, (10, 20));

source

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

Clears the whole terminal screen

§Example

backend.clear()?;

source

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

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

The returned Rect contains the width and height of the terminal screen.

§Example

let backend = TestBackend::new(80, 25);
assert_eq!(backend.size()?, Rect::new(0, 0, 80, 25));

source

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

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

The reason for this not returning only the pixel size, given the redundancy with the size() method, is that the underlying backends most likely get both values with one syscall, and the user is also most likely to need columns and rows along with pixel size.

source

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

Flush any buffered content to the terminal screen.

Provided Methods§

source

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

Insert n line breaks to the terminal screen.

This method is optional and may not be implemented by all backends.

source

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

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

This method is optional and may not be implemented by all backends. The default implementation calls clear if the clear_type is ClearType::All and returns an error otherwise.

§Example

backend.clear_region(ClearType::All)?;

§Errors

This method will return an error if the terminal screen could not be cleared. It will also return an error if the clear_type is not supported by the backend.