Struct Screen 

pub struct Screen { /* private fields */ }

A rows x cols grid of Cells plus a Cursor, both 0-based.

Implementations

impl Screen

pub fn new(rows: usize, cols: usize) -> Self

A blank screen (all default cells, cursor at the origin).

pub fn with_history(rows: usize, cols: usize, history: usize) -> Self

A blank screen that keeps up to history lines scrolled off its top (see Screen::history_len). Only a scroll of the whole screen feeds the history, as in other terminals; a scroll region does not.

pub fn visible(&self) -> Screen

The same visible rows and cursor, without the history: what a renderer or a synchronized-output snapshot needs, at the cost of the visible cells only.

pub fn history_len(&self) -> usize

Lines of history held (at most the capacity given to Screen::with_history).

pub fn history_capacity(&self) -> usize

The history capacity, in lines.

pub fn set_history_bytes(&mut self, max: usize)

Hold at most max bytes of memory in history (0: no cap), dropping the oldest lines past it: a bound however wide or colourful lines are, on top of the line capacity. It may run over by up to one 96 KiB chunk.

pub fn history_bytes(&self) -> usize

Memory the history holds: its buffers’ capacity.

pub fn scrolled_lines(&self) -> u64

Lines that have ever entered the history, including ones since dropped: a monotonic count to anchor a scrolled-back view on.

pub fn history_cell(&self, age: usize, col: usize) -> Cell

A cell of the history: age 0 is the line that most recently left the top of the screen. Out of range returns a default cell. Each call decodes into the stored line; for whole rows use Screen::history_row.

pub fn history_row(&self, age: usize, out: &mut Vec<Cell>) -> bool

History line age (0 the newest) as this screen’s cols cells, into out, replacing its contents. Returns false, leaving out empty, when the line is not held.

pub fn history_wrapped(&self, age: usize) -> bool

Whether history line age (0 the newest) wrapped onto the next line; false when not held.

pub fn row_wrapped(&self, row: usize) -> bool

Whether row wrapped onto the row below (autowrap), so the two are one line of output. Out of range is false.

pub fn set_row_wrapped(&mut self, row: usize, wrapped: bool)

Mark row as wrapped onto the row below, or not; the emulator sets it when a line autowraps. Out of range is ignored.

pub fn clear_history(&mut self)

Forget the history (as ESC [3J asks).

pub fn copy_history_from(&mut self, other: &Screen)

Copy other’s history (oldest first) into this screen’s, each line cut or padded to this width: used to keep scrollback across a resize.

pub fn rows(&self) -> usize

pub fn cols(&self) -> usize

pub fn cursor(&self) -> Cursor

Where the cursor rests after rendering.

pub fn set_cursor(&mut self, cursor: Cursor)

Move the cursor, clamped onto the grid: a row or column past the edge lands on the last row or column (the origin on an empty screen). The renderers park the terminal cursor here.

pub fn clear(&mut self)

Reset all cells to default and the cursor to the origin, reusing the existing allocation. The caller must ensure the screen is already the right size; use Screen::new when the size changes.

pub fn cell(&self, row: usize, col: usize) -> Cell

The cell at (row, col); out of bounds returns a default cell.

pub fn row_cells(&self, row: usize) -> (&[Cell], Cell)

Row row without a copy: the cells written so far, and the cell every column past them reads as (the row’s blank). The two together are what Screen::cell returns column by column, so a compositor or a diff walks a row as one slice and one fill instead of cols lookups. Out of range: an empty slice and a default cell.

pub fn set(&mut self, row: usize, col: usize, cell: Cell)

Set one cell. Out-of-bounds writes are ignored.

pub fn write_str(&mut self, row: usize, col: usize, text: &str, style: Style)

Write a string across a row starting at (row, col), truncating at the right edge. Each char takes one cell (single-width); callers that need double-width layout use Cell::wide with Screen::set or Screen::copy_cells.

pub fn copy_cells(&mut self, row: usize, col: usize, cells: &[Cell])

Copy a contiguous run of cells into row starting at column col, clipping the run at the right edge (and ignoring an out-of-range row or start column). Equivalent to calling Screen::set for each cell in turn, but with a single bounds check for the whole run — the fast path a compositor uses to blit a row slice.

pub fn write_ascii( &mut self, row: usize, col: usize, text: &[u8], style: Style, ) -> usize

Write ASCII text into row from column col in one pass, each byte a single-width cell in style, clipped at the right edge (an out-of-range row or column writes nothing). Returns the cells written. The same as Screen::copy_cells of Cell::new(b as char, style) for each byte, without building the cells first — the hot path of a terminal printing plain text. Bytes are not checked: callers pass printable ASCII.

pub fn scroll_rows_up( &mut self, top: usize, bottom: usize, n: usize, fill: Cell, )

Scroll rows top..=bottom up by n. Rows move up, the top n rows of the region are lost, and n rows of fill enter at the bottom. Rows outside the region are untouched. An empty or out-of-range region does nothing, and n is clamped to the region’s height.

Any region, the whole screen included, scrolls by rotating its entries in the row map and clearing the rows that come in: region index moves and O(1) per incoming row, never region x cols.

A terminal scrolls on every output line. Copying the region cell by cell fed a 16 MB log at 11 MB/s on a 40x160 grid; moving whole rows still held a 177x47 pane with a one-row status line (DECSTBM) to 21 MiB/s, against 182 MiB/s scrolling the full screen.

pub fn scroll_rows_down( &mut self, top: usize, bottom: usize, n: usize, fill: Cell, )

Scroll rows top..=bottom down by n: the mirror of Screen::scroll_rows_up. The bottom n rows of the region are lost, and n rows of fill enter at the top.

pub fn diff(&self, next: &Screen) -> Vec<u8>

The bytes that transform a terminal currently showing self into one showing next: cursor moves (CUP), minimal SGR transitions, and the changed characters, ending with a style reset and the cursor parked at next’s cursor. Equal screens produce no bytes at all.

Both screens must have the same dimensions; if they differ (a resize), the diff falls back to a full repaint of next.

pub fn render_full(&self) -> Vec<u8>

A from-scratch repaint: clear the screen, then paint every non-default cell, ending with a style reset and the cursor parked at this screen’s cursor.

Trait Implementations

impl Clone for Screen

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Screen

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for Screen

impl PartialEq for Screen

Two screens are equal when they show the same thing: same size, same cursor, same cell at every logical position. Where each row physically sits in the ring is an implementation detail, so a scrolled screen and a freshly built one with the same content compare equal.

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.