Struct Terminal 

pub struct Terminal<B: Backend> { /* private fields */ }

A double-buffered terminal generic over a Backend.

Owns the current and previous frame grids and exposes a stateful drawing API (put, print, layer, …). Call present once per frame to diff against the previous frame and send only the changed cells to the backend.

Implementations

impl<B: Backend> Terminal<B>

pub fn new(backend: B) -> Self

Create a terminal with the given backend. Grid dimensions are queried from the backend.

pub const fn layer(&mut self, layer: u8) -> &mut Self

Sets the active drawing layer (0-255). Returns &mut Self for chaining.

All subsequent put, put_styled, put_offset, print, and print_styled calls write to this layer until layer() is called again.

pub const fn fg(&mut self, color: Color) -> &mut Self

Sets the foreground color for the stateful API.

pub const fn bg(&mut self, color: Color) -> &mut Self

Sets the background color for the stateful API.

pub fn reset_style(&mut self) -> &mut Self

Resets the drawing style to defaults.

pub const fn style(&self) -> Style

Returns the current drawing style.

pub const fn size(&self) -> Size

Returns the current grid dimensions.

pub const fn area(&self) -> Rect

Returns the full drawing surface as a Rect at the origin.

Equivalent to Rect::new(0, 0, width, height). Handy for passing the whole terminal to layout helpers or region-based drawing.

pub fn resize(&mut self, width: u16, height: u16)

Resize both grids to width × height cells.

Content within the overlapping region is preserved in the current grid. The previous grid is cleared so the next present redraws the entire new surface rather than diffing stale data.

pub fn put(&mut self, x: u16, y: u16, ch: char)

Place a character at (x, y) on the active layer with the current style.

If ch is a wide character (e.g. CJK or emoji) that occupies two columns, the adjacent cell at (x + 1, y) is set to a zero-width continuation marker so it is not rendered independently.

Sub-cell offsets are always visual only — use put_offset for offset writes.

pub fn put_at(&mut self, pos: Pos, ch: char)

Place a character at pos on the active layer with the current style.

Equivalent to put, but takes a Pos to match the Rect/Size-based drawing APIs elsewhere on Terminal.

pub const fn grid(&self) -> &Grid

Returns a reference to the current grid.

pub const fn grid_mut(&mut self) -> &mut Grid

Returns a mutable reference to the current grid.

pub const fn backend(&self) -> &B

Returns a reference to the backend.

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

Returns a mutable reference to the backend.

pub fn clear(&mut self)

Clear the active layer.

pub fn clear_all(&mut self)

Clear every allocated layer.

pub fn clear_region(&mut self, rect: Rect)

Clear a rectangular region.

pub fn put_styled(&mut self, x: u16, y: u16, ch: char, style: Style)

Place a character on the active layer with an explicit style.

pub fn put_offset(&mut self, x: u16, y: u16, dx: i16, dy: i16, ch: char)

Place a character at (x, y) with a sub-cell pixel offset (dx, dy).

Uses the current style and active layer. Sub-cell offsets are visual only — they do not affect grid logic or hit-testing. Backends that cannot represent pixel offsets (e.g. CrosstermBackend) ignore them.

pub fn print(&mut self, x: u16, y: u16, text: &str)

Print a string starting at (x, y) with the current style.

\n advances to the next row at the original x. Wide characters (CJK, emoji) advance the cursor by 2 columns. Characters that would extend beyond the grid width wrap to the next row.

pub fn print_styled(&mut self, x: u16, y: u16, line: &Line)

Print a Line of styled spans starting at (x, y).

Each span’s style is applied independently. The terminal’s current drawing style is not modified. Wide characters advance the cursor by 2 columns. Rendering stops at the grid boundary.

pub fn print_box( &mut self, rect: Rect, line: &Line, h_align: HAlign, v_align: VAlign, )

Render a Line of styled text into a bounded rectangle.

Performs greedy word-wrapping at rect’s width, then positions the resulting lines according to h_align and v_align. Lines that overflow rect’s height are silently clipped.

This is a convenience wrapper around TextLayout.

Only available when the egc feature is enabled.

pub const fn present_count(&self) -> u64

Number of times present has been called so far (successful or not).

Wraps on overflow; intended for detecting whether present was called at all between two points in time (compare a saved count against the current one), not as a precise total. Embedding drivers (e.g. retroglyph-window’s windowed drivers) use this to decide whether application code already presented during a frame, so they can skip a redundant driver-side present – see present’s doc comment for why that redundant call is not a harmless no-op.

pub fn present(&mut self) -> Result<(), <B as Output>::Error>

Present the current frame.

Computes diff, sends changed cells to the backend, flushes, then swaps buffers.

When the backend requires a full frame (see crate::Output::needs_full_frame), all cells from every allocated layer are sent rather than just the diff, so pixel-based backends can clear and redraw to avoid orphaned pixels from sub-cell offsets.

After swap the new current buffer is cleared so the next frame starts empty. Callers should not call clear() before drawing the next frame.

Immediate mode

This is an immediate-mode API (the same trade ratatui makes): the current buffer is wiped after every present, so each frame must redraw its entire scene from scratch. Cells are not retained between frames. The diff only bounds what is sent to the backend (terminal or pixel I/O); it does not bound the CPU cost of your redraw.

Turn-based games that render only when state changes should gate their calls to present on an actual state change rather than presenting on a fixed clock and expecting the previous frame’s cells to persist.

Calling present twice in a row with nothing newly drawn in between is not a harmless no-op: the second call diffs the now-empty current buffer against previous (which still holds the just-presented frame), so every previously-drawn cell is re-sent as a diff entry reverting to its default/blank content – i.e. it erases the frame that was just presented. Use present_count if you need to detect “was present already called this frame” before deciding whether to call it again.

Errors

Propagates errors from the backend’s draw_layers or flush operations.

pub fn poll(&mut self, timeout: Duration) -> Option<Event>

Polls for an input event, waiting up to timeout.

If an event was previously buffered by has_input, it is returned immediately. Otherwise, the backend is polled for a new event.

Event::Resize events are automatically applied: both grids are resized before the event is returned to the caller, so the game loop can immediately redraw at the new size.

pub fn read_blocking(&mut self) -> Event

Reads an input event, blocking indefinitely until one is available.

Only call this on backends that genuinely block (e.g. crossterm, window). Backends that never block (e.g. Headless, which returns immediately regardless of timeout) will panic here once their event queue is empty; use poll or drain_events instead if that is a possibility.

Panics

Panics if the backend’s poll_event returns None even with an unbounded timeout.

pub fn drain_events(&mut self) -> impl Iterator<Item = Event> + use<'_, B>

Drains all available events without blocking.

Returns an iterator that yields every pending event — the internal queued event followed by all events buffered in the backend. The iterator polls the backend with zero timeout repeatedly until None is returned.

This is needed for frame-based game loops (e.g. software backend + WASM, where frames are gated by requestAnimationFrame). Multiple keypresses can arrive between frames; draining all of them ensures accumulated input doesn’t replay in slow motion.

Crossterm and headless backends can also use this, but the single-event poll pattern works for them because their loops aren’t frame-capped.

pub fn has_input(&mut self) -> bool

Checks if a pending input event is available without blocking.

If an event is already buffered, returns true. Otherwise, polls the backend with zero timeout. If the backend returns an event, it is stored in the internal buffer and true is returned; otherwise, returns false.