Struct Terminal 

pub struct Terminal<B: Backend> {
    current: Grid,
    previous: Grid,
    backend: B,
    drawing_style: Style,
    queued_event: Option<Event>,
    active_layer: u8,
}

The main entry point for rg.

Generic over the backend. Owns a double-buffered grid and provides a stateful drawing API.

Fields

current: Grid

previous: Grid

backend: B

drawing_style: Style

queued_event: Option<Event>

active_layer: u8

The layer that put, put_styled, and put_offset write to.

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, and put_offset calls write to this layer until layer() is called again.

print and print_styled currently target layer 0 only.

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 const fn modifier(&mut self, modifier: CellModifier) -> &mut Self

Sets text modifiers 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 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.

Wide-character handling and grapheme clusters are supported on layer 0. On layers > 0, wide characters are stored as a single tile (no spacer). Sub-cell offsets are always visual only — use put_offset for offset writes.

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.

Wide characters are handled identically to put.

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 fn present(&mut self)

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::Backend::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.

Note

The back buffer is not cleared automatically after presentation. If you want a blank frame, call clear() at the start of your loop.

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(&mut self) -> Event

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

Panics

Panics if no event is available. This matches the expected behavior for headless backend tests when the event queue is empty.

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.

fn print_str_egc(&mut self, x: u16, y: u16, text: &str, style: Style)

String printing implementation used when egc is enabled.