[go: up one dir, main page]
ratatui::backend

Trait Backend

Source 
pub trait Backend {

Show 15 methods    // 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_position(&mut self) -> Result<Position>;
    fn set_cursor_position<P: Into<Position>>(
        &mut self,
        position: P,
    ) -> Result<()>;
    fn clear(&mut self) -> Result<()>;
    fn size(&self) -> Result<Size>;
    fn window_size(&mut self) -> Result<WindowSize>;
    fn flush(&mut self) -> Result<()>;
    fn scroll_region_up(
        &mut self,
        region: Range<u16>,
        line_count: u16,
    ) -> Result<()>;
    fn scroll_region_down(
        &mut self,
        region: Range<u16>,
        line_count: u16,
    ) -> Result<()>;

    // Provided methods
    fn append_lines(&mut self, _n: u16) -> Result<()> { ... }
    fn get_cursor(&mut self) -> Result<(u16, u16)> { ... }
    fn set_cursor(&mut self, x: u16, y: 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.

See also show_cursor.

§Example
use ratatui::backend::Backend;

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_position(&mut self) -> Result<Position>

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_position for an example.

Source

fn set_cursor_position<P: Into<Position>>(&mut self, position: P) -> 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
use ratatui::{backend::Backend, layout::Position};

backend.set_cursor_position(Position { x: 10, y: 20 })?;
assert_eq!(backend.get_cursor_position()?, Position { x: 10, y: 20 });
Source

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

Clears the whole terminal screen

§Example
use ratatui::backend::Backend;

backend.clear()?;
Source

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

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

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

§Example
use ratatui::{backend::Backend, layout::Size};

assert_eq!(backend.size()?, Size::new(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.

Source

fn scroll_region_up( &mut self, region: Range<u16>, line_count: u16, ) -> Result<()>

Available on crate feature scrolling-regions only.

Scroll a region of the screen upwards, where a region is specified by a (half-open) range of rows.

Each row in the region is replaced by the row line_count rows below it, except the bottom line_count rows, which are replaced by empty rows. If line_count is equal to or larger than the number of rows in the region, then all rows are replaced with empty rows.

If the region includes row 0, then line_count rows are copied into the bottom of the scrollback buffer. These rows are first taken from the old contents of the region, starting from the top. If there aren’t sufficient rows in the region, then the remainder are empty rows.

The position of the cursor afterwards is undefined.

The behavior is designed to match what ANSI terminals do when scrolling regions are established. With ANSI terminals, a scrolling region can be established with the “^[[X;Yr” sequence, where X and Y define the lines of the region. The scrolling region can be reset to be the whole screen with the “^[[r” sequence.

When a scrolling region is established in an ANSI terminal, various operations’ behaviors are changed in such a way that the scrolling region acts like a “virtual screen”. In particular, the scrolling sequence “^[[NS”, which scrolls lines up by a count of N.

On an ANSI terminal, this method will probably translate to something like: “^[[X;Yr^[[NS^[[r”. That is, set the scrolling region, scroll up, then reset the scrolling region.

For examples of how this function is expected to work, refer to the tests for TestBackend::scroll_region_up.

Source

fn scroll_region_down( &mut self, region: Range<u16>, line_count: u16, ) -> Result<()>

Available on crate feature scrolling-regions only.

Scroll a region of the screen downwards, where a region is specified by a (half-open) range of rows.

Each row in the region is replaced by the row line_count rows above it, except the top line_count rows, which are replaced by empty rows. If line_count is equal to or larger than the number of rows in the region, then all rows are replaced with empty rows.

The position of the cursor afterwards is undefined.

See the documentation for Self::scroll_region_down for more information about how this is expected to be implemented for ANSI terminals. All of that applies, except the ANSI sequence to scroll down is “^[[NT”.

This function is asymmetrical with regards to the scrollback buffer. The reason is that this how terminals seem to implement things.

For examples of how this function is expected to work, refer to the tests for TestBackend::scroll_region_down.

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 get_cursor(&mut self) -> Result<(u16, u16)>

👎Deprecated: the method get_cursor_position indicates more clearly what about the cursor to get

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.

Source

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

👎Deprecated: the method set_cursor_position indicates more clearly what about the cursor to set

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.

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
use ratatui::backend::{Backend, ClearType};

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.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors§

Source§

impl Backend for TermwizBackend

Available on crate feature termwiz only.
Source§

impl Backend for TestBackend

Source§

impl<W> Backend for CrosstermBackend<W>
where W: Write,

Available on crate feature crossterm only.
Source§

impl<W> Backend for TermionBackend<W>
where W: Write,

Available on non-Windows and crate feature termion only.