Struct Tui 

pub struct Tui {
    pub terminal: Terminal<CrosstermBackend<IO>>,
    pub task: JoinHandle<()>,
    pub cancellation_token: CancellationToken,
    pub event_rx: UnboundedReceiver<Event>,
    pub event_tx: UnboundedSender<Event>,
    pub frame_rate: f64,
    pub tick_rate: f64,
    pub mouse: bool,
    pub paste: bool,
}

The Tui struct represents a terminal user interface.

It encapsulates ratatui::Terminal adding extra functionality:

• Tui::start and Tui::stop to start and stop the event loop
• Tui::enter and Tui::exit to enter and exit the crossterm terminal raw mode
• Mapping of crossterm events to Events
• Emits Event::Tick and Event::Render events at a specified rate

Fields

terminal: Terminal<CrosstermBackend<IO>>

task: JoinHandle<()>

cancellation_token: CancellationToken

event_rx: UnboundedReceiver<Event>

event_tx: UnboundedSender<Event>

frame_rate: f64

tick_rate: f64

mouse: bool

paste: bool

Implementations

impl Tui

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

pub fn tick_rate(self, tick_rate: f64) -> Self

Sets the tick rate for the Tui. The tick rate is the number of times per second that the Tui will emit a Event::Tick event. The default tick rate is 4 ticks per second.

The tick is different from the render rate, which is the number of times per second that the application will be drawn to the screen. The tick rate is useful for updating the application state, performing calculations, run background tasks, and other operations that do not require a per-frame operation.

Tick rate will usually be lower than the frame rate.

pub fn frame_rate(self, frame_rate: f64) -> Self

Sets the frame rate for the Tui. The frame rate is the number of times per second that the Tui will emit a Event::Render event. The default frame rate is 60 frames per second.

The frame rate is the rate at which the application will be drawn to the screen (by calling the draw method of each component).

pub fn mouse(self, mouse: bool) -> Self

Sets whether the Tui should capture mouse events. The default is false.

pub fn paste(self, paste: bool) -> Self

Sets whether the Tui should capture paste events. The default is false.

pub fn start(&mut self)

Starts the Tui event loop.

pub fn stop(&self)

Stops the Tui event loop.

pub fn enter(&mut self) -> Result<(), Error>

Enables cross-term raw mode and enters the alternate screen.

pub fn exit(&mut self) -> Result<(), Error>

Disables cross-term raw mode and exits the alternate screen.

pub fn cancel(&self)

pub fn suspend(&mut self) -> Result<(), Error>

pub fn resume(&mut self) -> Result<(), Error>

pub async fn next(&mut self) -> Option<Event>

Returns the next event from the event channel.

Methods from Deref<Target = Terminal<Backend<IO>>>

pub fn get_frame(&mut self) -> Frame<'_>

Get a Frame object which provides a consistent view into the terminal state for rendering.

pub fn current_buffer_mut(&mut self) -> &mut Buffer

Gets the current buffer as a mutable reference.

pub fn backend(&self) -> &B

Gets the backend

pub fn backend_mut(&mut self) -> &mut B

Gets the backend as a mutable reference

Examples found in repository

examples/widget_grid_selector.rs (line 51)

fn main() -> io::Result<()> {
    let stdout = io::stdout();
    let mut stdout = stdout.lock();
    enable_raw_mode()?;
    execute!(stdout, EnterAlternateScreen)?;
    let backend = CrosstermBackend::new(stdout);
    let mut term = Terminal::new(backend)?;

    // Run the draw loop
    run(&mut term)?;

    disable_raw_mode()?;
    execute!(term.backend_mut(), LeaveAlternateScreen)?;
    term.show_cursor()?;
    Ok(())
}

examples/widget_switch.rs (line 76)

fn main() -> io::Result<()> {
    let stdout = io::stdout();
    let mut stdout = stdout.lock();

    enable_raw_mode()?;
    execute!(stdout, EnterAlternateScreen)?;
    let backend = CrosstermBackend::new(stdout);
    let mut term = Terminal::new(backend)?;
    let mut switch_state = false;

    loop {
        term.draw(|f| {
            // Render the textarea
            let switch =
                Switch::with_status(switch_state).with_color_on(ratatui::style::Color::Green);

            let [horiz] = Layout::horizontal([Constraint::Percentage(100)])
                .flex(Flex::Center)
                .areas(f.area());

            let [verti] = Layout::vertical([Constraint::Length(2)]).flex(Flex::Center).areas(horiz);

            let [centered] =
                Layout::horizontal([Constraint::Length(14)]).flex(Flex::Center).areas(verti);

            f.render_widget(switch, centered);
        })?;
        match event::read()?.into() {
            Input { key: Key::Esc, .. }
            | Input {
                key: Key::Char('c'),
                shift: false,
                ctrl: true,
                alt: false,
            } => break,
            Input {
                key: Key::Enter,
                ctrl: false,
                shift: false,
                alt: false,
            }
            | Input {
                key: Key::Char(' '),
                ..
            } => {
                switch_state = !switch_state;
            }
            _ => {}
        }
    }

    disable_raw_mode()?;
    execute!(term.backend_mut(), LeaveAlternateScreen)?;
    term.show_cursor()?;

    Ok(())
}

examples/widget_text_area.rs (line 72)

fn main() -> io::Result<()> {
    let stdout = io::stdout();
    let mut stdout = stdout.lock();

    enable_raw_mode()?;
    execute!(stdout, EnterAlternateScreen)?;
    let backend = CrosstermBackend::new(stdout);
    let mut term = Terminal::new(backend)?;

    let mut textarea = TextArea::default().with_block(
        Block::default()
            .borders(Borders::ALL)
            .border_type(BorderType::Rounded)
            .title(" Your name ")
            .padding(Padding::horizontal(1)),
    );

    loop {
        term.draw(|f| {
            const MIN_HEIGHT: usize = 1;
            let height = cmp::max(textarea.lines().len(), MIN_HEIGHT) as u16 + 2;
            let layout = Layout::default()
                .direction(Direction::Vertical)
                .constraints([Constraint::Length(height), Constraint::Min(1)])
                .split(f.area());

            // Render the textarea
            f.render_widget(&textarea, layout[0]);
            f.render_widget(Paragraph::new("Press <Esc> to exit"), layout[1]);
        })?;
        match event::read()?.into() {
            Input { key: Key::Esc, .. }
            | Input {
                key: Key::Char('c'),
                shift: false,
                ctrl: true,
                alt: false,
            }
            | Input {
                key: Key::Enter,
                ctrl: false,
                shift: false,
                alt: false,
            } => break,
            input => {
                textarea.input(input);
            }
        }
    }

    disable_raw_mode()?;
    execute!(term.backend_mut(), LeaveAlternateScreen)?;
    term.show_cursor()?;

    println!("Lines: {:?}", textarea.lines());
    Ok(())
}

pub fn flush(&mut self) -> Result<(), Error>

Obtains a difference between the previous and the current buffer and passes it to the current backend for drawing.

pub fn resize(&mut self, area: Rect) -> Result<(), Error>

Updates the Terminal so that internal buffers match the requested area.

Requested area will be saved to remain consistent when rendering. This leads to a full clear of the screen.

pub fn autoresize(&mut self) -> Result<(), Error>

Queries the backend for size and resizes if it doesn’t match the previous size.

pub fn draw<F>( &mut self, render_callback: F, ) -> Result<CompletedFrame<'_>, Error>

where F: FnOnce(&mut Frame<'_>),

Draws a single frame to the terminal.

Returns a CompletedFrame if successful, otherwise a std::io::Error.

If the render callback passed to this method can fail, use try_draw instead.

Applications should call draw or try_draw in a loop to continuously render the terminal. These methods are the main entry points for drawing to the terminal.

This method will:

• autoresize the terminal if necessary
• call the render callback, passing it a Frame reference to render to
• flush the current internal state by copying the current buffer to the backend
• move the cursor to the last known position if it was set during the rendering closure
• return a CompletedFrame with the current buffer and the area of the terminal

The CompletedFrame returned by this method can be useful for debugging or testing purposes, but it is often not used in regular applicationss.

The render callback should fully render the entire frame when called, including areas that are unchanged from the previous frame. This is because each frame is compared to the previous frame to determine what has changed, and only the changes are written to the terminal. If the render callback does not fully render the frame, the terminal will not be in a consistent state.

Examples

use ratatui::widgets::Paragraph;

// with a closure
terminal.draw(|frame| {
    let area = frame.size();
    frame.render_widget(Paragraph::new("Hello World!"), area);
    frame.set_cursor_position(Position { x: 0, y: 0 });
})?;

// or with a function
terminal.draw(render)?;

fn render(frame: &mut ratatui::Frame) {
    frame.render_widget(Paragraph::new("Hello World!"), frame.size());
}

Examples found in repository

examples/widget_switch.rs (lines 35-50)

fn main() -> io::Result<()> {
    let stdout = io::stdout();
    let mut stdout = stdout.lock();

    enable_raw_mode()?;
    execute!(stdout, EnterAlternateScreen)?;
    let backend = CrosstermBackend::new(stdout);
    let mut term = Terminal::new(backend)?;
    let mut switch_state = false;

    loop {
        term.draw(|f| {
            // Render the textarea
            let switch =
                Switch::with_status(switch_state).with_color_on(ratatui::style::Color::Green);

            let [horiz] = Layout::horizontal([Constraint::Percentage(100)])
                .flex(Flex::Center)
                .areas(f.area());

            let [verti] = Layout::vertical([Constraint::Length(2)]).flex(Flex::Center).areas(horiz);

            let [centered] =
                Layout::horizontal([Constraint::Length(14)]).flex(Flex::Center).areas(verti);

            f.render_widget(switch, centered);
        })?;
        match event::read()?.into() {
            Input { key: Key::Esc, .. }
            | Input {
                key: Key::Char('c'),
                shift: false,
                ctrl: true,
                alt: false,
            } => break,
            Input {
                key: Key::Enter,
                ctrl: false,
                shift: false,
                alt: false,
            }
            | Input {
                key: Key::Char(' '),
                ..
            } => {
                switch_state = !switch_state;
            }
            _ => {}
        }
    }

    disable_raw_mode()?;
    execute!(term.backend_mut(), LeaveAlternateScreen)?;
    term.show_cursor()?;

    Ok(())
}

examples/widget_text_area.rs (lines 39-50)

fn main() -> io::Result<()> {
    let stdout = io::stdout();
    let mut stdout = stdout.lock();

    enable_raw_mode()?;
    execute!(stdout, EnterAlternateScreen)?;
    let backend = CrosstermBackend::new(stdout);
    let mut term = Terminal::new(backend)?;

    let mut textarea = TextArea::default().with_block(
        Block::default()
            .borders(Borders::ALL)
            .border_type(BorderType::Rounded)
            .title(" Your name ")
            .padding(Padding::horizontal(1)),
    );

    loop {
        term.draw(|f| {
            const MIN_HEIGHT: usize = 1;
            let height = cmp::max(textarea.lines().len(), MIN_HEIGHT) as u16 + 2;
            let layout = Layout::default()
                .direction(Direction::Vertical)
                .constraints([Constraint::Length(height), Constraint::Min(1)])
                .split(f.area());

            // Render the textarea
            f.render_widget(&textarea, layout[0]);
            f.render_widget(Paragraph::new("Press <Esc> to exit"), layout[1]);
        })?;
        match event::read()?.into() {
            Input { key: Key::Esc, .. }
            | Input {
                key: Key::Char('c'),
                shift: false,
                ctrl: true,
                alt: false,
            }
            | Input {
                key: Key::Enter,
                ctrl: false,
                shift: false,
                alt: false,
            } => break,
            input => {
                textarea.input(input);
            }
        }
    }

    disable_raw_mode()?;
    execute!(term.backend_mut(), LeaveAlternateScreen)?;
    term.show_cursor()?;

    println!("Lines: {:?}", textarea.lines());
    Ok(())
}

examples/widget_grid_selector.rs (line 79)

fn run<B>(term: &mut Terminal<B>) -> io::Result<()>
where
    B: ratatui::backend::Backend,
{
    let items = vec![
        Item::new("feat", "✨"),
        Item::new("fix", "🐛"),
        Item::new("chore", "🧹"),
        Item::new("docs", "📚"),
        Item::new("style", "💅"),
        Item::new("refactor", "🔨"),
        Item::new("perf", "🐎"),
        Item::new("test", "🚨"),
        Item::new("build", "👷"),
        Item::new("ci", "🔧"),
        Item::new("revert", "⏪"),
        Item::new("release", "🚀"),
        Item::new("wip", "🚧"),
    ];

    let mut grid_state = GridSelectorState::new(items).columns(5);

    loop {
        term.draw(|f| draw(f, f.area(), &mut grid_state))?;

        match event::read()? {
            Event::Key(key) => match key {
                KeyEvent {
                    code: KeyCode::Esc, ..
                } => break,
                KeyEvent {
                    code: KeyCode::Right,
                    kind: KeyEventKind::Press,
                    ..
                } => grid_state.move_right(),
                KeyEvent {
                    code: KeyCode::Left,
                    kind: KeyEventKind::Press,
                    ..
                } => grid_state.move_left(),
                KeyEvent {
                    code: KeyCode::Up,
                    kind: KeyEventKind::Press,
                    ..
                } => grid_state.move_up(),
                KeyEvent {
                    code: KeyCode::Down,
                    kind: KeyEventKind::Press,
                    ..
                } => grid_state.move_down(),
                KeyEvent {
                    code: KeyCode::Home,
                    kind: KeyEventKind::Press,
                    ..
                } => grid_state.move_to_row_start(),
                KeyEvent {
                    code: KeyCode::End,
                    kind: KeyEventKind::Press,
                    ..
                } => grid_state.move_to_row_end(),
                // selection
                KeyEvent {
                    code: KeyCode::Enter,
                    kind: KeyEventKind::Press,
                    ..
                } => grid_state.select(),
                _ => false,
            },
            _ => false,
        };
    }

    Ok(())
}

pub fn try_draw<F, E>( &mut self, render_callback: F, ) -> Result<CompletedFrame<'_>, Error>

where F: FnOnce(&mut Frame<'_>) -> Result<(), E>, E: Into<Error>,

Tries to draw a single frame to the terminal.

Returns Result::Ok containing a CompletedFrame if successful, otherwise Result::Err containing the std::io::Error that caused the failure.

This is the equivalent of Terminal::draw but the render callback is a function or closure that returns a Result instead of nothing.

Applications should call try_draw or draw in a loop to continuously render the terminal. These methods are the main entry points for drawing to the terminal.

This method will:

• autoresize the terminal if necessary
• call the render callback, passing it a Frame reference to render to
• flush the current internal state by copying the current buffer to the backend
• move the cursor to the last known position if it was set during the rendering closure
• return a CompletedFrame with the current buffer and the area of the terminal

The render callback passed to try_draw can return any Result with an error type that can be converted into an std::io::Error using the Into trait. This makes it possible to use the ? operator to propagate errors that occur during rendering. If the render callback returns an error, the error will be returned from try_draw as an std::io::Error and the terminal will not be updated.

The CompletedFrame returned by this method can be useful for debugging or testing purposes, but it is often not used in regular applicationss.

The render callback should fully render the entire frame when called, including areas that are unchanged from the previous frame. This is because each frame is compared to the previous frame to determine what has changed, and only the changes are written to the terminal. If the render function does not fully render the frame, the terminal will not be in a consistent state.

Examples

use std::io;

use ratatui::widgets::Paragraph;

// with a closure
terminal.try_draw(|frame| {
    let value: u8 = "not a number".parse().map_err(io::Error::other)?;
    let area = frame.size();
    frame.render_widget(Paragraph::new("Hello World!"), area);
    frame.set_cursor_position(Position { x: 0, y: 0 });
    io::Result::Ok(())
})?;

// or with a function
terminal.try_draw(render)?;

fn render(frame: &mut ratatui::Frame) -> io::Result<()> {
    let value: u8 = "not a number".parse().map_err(io::Error::other)?;
    frame.render_widget(Paragraph::new("Hello World!"), frame.size());
    Ok(())
}

pub fn hide_cursor(&mut self) -> Result<(), Error>

Hides the cursor.

pub fn show_cursor(&mut self) -> Result<(), Error>

Shows the cursor.

Examples found in repository

examples/widget_grid_selector.rs (line 52)

fn main() -> io::Result<()> {
    let stdout = io::stdout();
    let mut stdout = stdout.lock();
    enable_raw_mode()?;
    execute!(stdout, EnterAlternateScreen)?;
    let backend = CrosstermBackend::new(stdout);
    let mut term = Terminal::new(backend)?;

    // Run the draw loop
    run(&mut term)?;

    disable_raw_mode()?;
    execute!(term.backend_mut(), LeaveAlternateScreen)?;
    term.show_cursor()?;
    Ok(())
}

examples/widget_switch.rs (line 77)

fn main() -> io::Result<()> {
    let stdout = io::stdout();
    let mut stdout = stdout.lock();

    enable_raw_mode()?;
    execute!(stdout, EnterAlternateScreen)?;
    let backend = CrosstermBackend::new(stdout);
    let mut term = Terminal::new(backend)?;
    let mut switch_state = false;

    loop {
        term.draw(|f| {
            // Render the textarea
            let switch =
                Switch::with_status(switch_state).with_color_on(ratatui::style::Color::Green);

            let [horiz] = Layout::horizontal([Constraint::Percentage(100)])
                .flex(Flex::Center)
                .areas(f.area());

            let [verti] = Layout::vertical([Constraint::Length(2)]).flex(Flex::Center).areas(horiz);

            let [centered] =
                Layout::horizontal([Constraint::Length(14)]).flex(Flex::Center).areas(verti);

            f.render_widget(switch, centered);
        })?;
        match event::read()?.into() {
            Input { key: Key::Esc, .. }
            | Input {
                key: Key::Char('c'),
                shift: false,
                ctrl: true,
                alt: false,
            } => break,
            Input {
                key: Key::Enter,
                ctrl: false,
                shift: false,
                alt: false,
            }
            | Input {
                key: Key::Char(' '),
                ..
            } => {
                switch_state = !switch_state;
            }
            _ => {}
        }
    }

    disable_raw_mode()?;
    execute!(term.backend_mut(), LeaveAlternateScreen)?;
    term.show_cursor()?;

    Ok(())
}

examples/widget_text_area.rs (line 73)

fn main() -> io::Result<()> {
    let stdout = io::stdout();
    let mut stdout = stdout.lock();

    enable_raw_mode()?;
    execute!(stdout, EnterAlternateScreen)?;
    let backend = CrosstermBackend::new(stdout);
    let mut term = Terminal::new(backend)?;

    let mut textarea = TextArea::default().with_block(
        Block::default()
            .borders(Borders::ALL)
            .border_type(BorderType::Rounded)
            .title(" Your name ")
            .padding(Padding::horizontal(1)),
    );

    loop {
        term.draw(|f| {
            const MIN_HEIGHT: usize = 1;
            let height = cmp::max(textarea.lines().len(), MIN_HEIGHT) as u16 + 2;
            let layout = Layout::default()
                .direction(Direction::Vertical)
                .constraints([Constraint::Length(height), Constraint::Min(1)])
                .split(f.area());

            // Render the textarea
            f.render_widget(&textarea, layout[0]);
            f.render_widget(Paragraph::new("Press <Esc> to exit"), layout[1]);
        })?;
        match event::read()?.into() {
            Input { key: Key::Esc, .. }
            | Input {
                key: Key::Char('c'),
                shift: false,
                ctrl: true,
                alt: false,
            }
            | Input {
                key: Key::Enter,
                ctrl: false,
                shift: false,
                alt: false,
            } => break,
            input => {
                textarea.input(input);
            }
        }
    }

    disable_raw_mode()?;
    execute!(term.backend_mut(), LeaveAlternateScreen)?;
    term.show_cursor()?;

    println!("Lines: {:?}", textarea.lines());
    Ok(())
}

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

👎Deprecated:

the method get_cursor_position indicates more clearly what about the cursor to get

Gets the current cursor position.

This is the position of the cursor after the last draw call and is returned as a tuple of (x, y) coordinates.

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

👎Deprecated:

the method set_cursor_position indicates more clearly what about the cursor to set

Sets the cursor position.

pub fn get_cursor_position(&mut self) -> Result<Position, Error>

Gets the current cursor position.

This is the position of the cursor after the last draw call.

pub fn set_cursor_position<P>(&mut self, position: P) -> Result<(), Error>

where P: Into<Position>,

Sets the cursor position.

pub fn clear(&mut self) -> Result<(), Error>

Clear the terminal and force a full redraw on the next draw call.

pub fn swap_buffers(&mut self)

Clears the inactive buffer and swaps it with the current buffer

pub fn size(&self) -> Result<Size, Error>

Queries the real size of the backend.

pub fn insert_before<F>(&mut self, height: u16, draw_fn: F) -> Result<(), Error>

where F: FnOnce(&mut Buffer),

Insert some content before the current inline viewport. This has no effect when the viewport is not inline.

The draw_fn closure will be called to draw into a writable Buffer that is height lines tall. The content of that Buffer will then be inserted before the viewport.

If the viewport isn’t yet at the bottom of the screen, inserted lines will push it towards the bottom. Once the viewport is at the bottom of the screen, inserted lines will scroll the area of the screen above the viewport upwards.

Before:

+---------------------+
| pre-existing line 1 |
| pre-existing line 2 |
+---------------------+
|       viewport      |
+---------------------+
|                     |
|                     |
+---------------------+

After inserting 2 lines:

+---------------------+
| pre-existing line 1 |
| pre-existing line 2 |
|   inserted line 1   |
|   inserted line 2   |
+---------------------+
|       viewport      |
+---------------------+
+---------------------+

After inserting 2 more lines:

+---------------------+
| pre-existing line 2 |
|   inserted line 1   |
|   inserted line 2   |
|   inserted line 3   |
|   inserted line 4   |
+---------------------+
|       viewport      |
+---------------------+

If more lines are inserted than there is space on the screen, then the top lines will go directly into the terminal’s scrollback buffer. At the limit, if the viewport takes up the whole screen, all lines will be inserted directly into the scrollback buffer.

Examples

Insert a single line before the current viewport

terminal.insert_before(1, |buf| {
    Paragraph::new(Line::from(vec![
        Span::raw("This line will be added "),
        Span::styled("before", Style::default().fg(Color::Blue)),
        Span::raw(" the current viewport"),
    ]))
    .render(buf.area, buf);
});

Trait Implementations

impl Deref for Tui

type Target = Terminal<CrosstermBackend<Stdout>>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl DerefMut for Tui

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl Drop for Tui

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

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

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.