type DebuggerTerminal = Terminal<CrosstermBackend<Stdout>>;Aliased Type§
struct DebuggerTerminal { /* private fields */ }Layout§
Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.
Size: 120 bytes
Implementations
§impl<B> Terminal<B>where
B: Backend,
impl<B> Terminal<B>where
B: Backend,
pub fn new(backend: B) -> Result<Terminal<B>, Error>
pub fn new(backend: B) -> Result<Terminal<B>, Error>
Creates a new [Terminal] with the given [Backend] with a full screen viewport.
§Example
use std::io::stdout;
use ratatui::{backend::CrosstermBackend, Terminal};
let backend = CrosstermBackend::new(stdout());
let terminal = Terminal::new(backend)?;pub fn with_options(backend: B, options: Options) -> Result<Terminal<B>, Error>
pub fn with_options(backend: B, options: Options) -> Result<Terminal<B>, Error>
Creates a new [Terminal] with the given [Backend] and [TerminalOptions].
§Example
use std::io::stdout;
use ratatui::{backend::CrosstermBackend, layout::Rect, Terminal, TerminalOptions, Viewport};
let backend = CrosstermBackend::new(stdout());
let viewport = Viewport::Fixed(Rect::new(0, 0, 10, 10));
let terminal = Terminal::with_options(backend, TerminalOptions { viewport })?;pub fn get_frame(&mut self) -> Frame<'_>
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
pub fn current_buffer_mut(&mut self) -> &mut Buffer
Gets the current buffer as a mutable reference.
pub fn backend_mut(&mut self) -> &mut B
pub fn backend_mut(&mut self) -> &mut B
Gets the backend as a mutable reference
pub fn flush(&mut self) -> Result<(), Error>
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>
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>
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<'_>),
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::{layout::Position, widgets::Paragraph};
// with a closure
terminal.draw(|frame| {
let area = frame.area();
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.area());
}pub fn try_draw<F, E>(
&mut self,
render_callback: F,
) -> Result<CompletedFrame<'_>, Error>
pub fn try_draw<F, E>( &mut self, render_callback: F, ) -> Result<CompletedFrame<'_>, 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.area();
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.area());
Ok(())
}pub fn hide_cursor(&mut self) -> Result<(), Error>
pub fn hide_cursor(&mut self) -> Result<(), Error>
Hides the cursor.
pub fn show_cursor(&mut self) -> Result<(), Error>
pub fn show_cursor(&mut self) -> Result<(), Error>
Shows the cursor.
pub fn get_cursor(&mut self) -> Result<(u16, u16), Error>
pub fn get_cursor(&mut self) -> Result<(u16, u16), Error>
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>
pub fn set_cursor(&mut self, x: u16, y: u16) -> Result<(), Error>
Sets the cursor position.
pub fn get_cursor_position(&mut self) -> Result<Position, Error>
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>,
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>
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)
pub fn swap_buffers(&mut self)
Clears the inactive buffer and swaps it with the current buffer
pub fn insert_before<F>(&mut self, height: u16, draw_fn: F) -> Result<(), Error>where
F: FnOnce(&mut Buffer),
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
use ratatui::{
backend::TestBackend,
style::{Color, Style},
text::{Line, Span},
widgets::{Paragraph, Widget},
Terminal,
};
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);
});