Struct termwiz::surface::Surface

pub struct Surface { /* fields omitted */ }

The Surface type represents the contents of a terminal screen. It is not directly connected to a terminal device. It consists of a buffer and a log of changes. You can accumulate updates to the screen by adding instances of the Change enum that describe the updates.

When ready to render the Surface to a Terminal, you can use the get_changes method to return an optimized stream of Changes since the last render and then pass it to an instance of Renderer.

Surfaces can also be composited together; this is useful when building up a UI with layers or widgets: each widget can be its own Surface instance and have its content maintained independently from the other widgets on the screen and can then be copied into the target Surface buffer for rendering.

To support more efficient updates in the composite use case, a draw_from_screen method is available; the intent is to have one Surface be hold the data that was last rendered, and a second Surface of the same size that is repeatedly redrawn from the composite of the widgets. draw_from_screen is used to extract the smallest difference between the updated screen and apply those changes to the render target, and then use get_changes to render those without repainting the world on each update.

Methods

impl Surface

pub fn new(width: usize, height: usize) -> Self

Create a new Surface with the specified width and height.

pub fn dimensions(&self) -> (usize, usize)

Returns the (width, height) of the surface

pub fn cursor_position(&self) -> (usize, usize)

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

Resize the Surface to the specified width and height. If the width and/or height are smaller than previously, the rows and/or columns are truncated. If the width and/or height are larger than previously then an appropriate number of cells are added to the buffer and filled with default attributes. The resize event invalidates the change stream, discarding it and causing a subsequent get_changes call to yield a full repaint. If the cursor position would be outside the bounds of the newly resized screen, it will be moved to be within the new bounds.

pub fn add_changes(&mut self, changes: Vec<Change>) -> SequenceNo

Efficiently apply a series of changes Returns the sequence number at the end of the change.

pub fn add_change<C: Into<Change>>(&mut self, change: C) -> SequenceNo

Apply a change and return the sequence number at the end of the change.

pub fn screen_chars_to_string(&self) -> String

Returns the entire contents of the screen as a string. Only the character data is returned. The end of each line is returned as a \n character. This function exists primarily for testing purposes.

pub fn screen_cells(&self) -> Vec<&[Cell]>

Returns the cell data for the screen. This is intended to be used for testing purposes.

pub fn get_changes(&self, seq: SequenceNo) -> (SequenceNo, Cow<[Change]>)

Returns a stream of changes suitable to update the screen to match the model. The input seq argument should be 0 on the first call, or in any situation where the screen contents may have been invalidated, otherwise it should be set to the SequenceNo returned by the most recent call to get_changes. get_changes will use a heuristic to decide on the lower cost approach to updating the screen and return some sequence of Change entries that will update the display accordingly. The worst case is that this function will fabricate a sequence of Change entries to paint the screen from scratch.

pub fn flush_changes_older_than(&mut self, seq: SequenceNo)

After having called get_changes and processed the resultant change stream, the caller can then pass the returned SequenceNo value to this call to prune the list of changes and free up resources from the change log.

pub fn diff_region(
    &self,
    x: usize,
    y: usize,
    width: usize,
    height: usize,
    other: &Surface,
    other_x: usize,
    other_y: usize
) -> Vec<Change>

Computes the change stream required to make the region within self at coordinates x, y and size width, height look like the same sized region within other at coordinates other_x, other_y.

other and self may be the same, causing regions within the same Surface to be differenced; this is used by the copy_region method.

The returned list of Changes can be passed to the add_changes method to make the region within self match the region within other.

Panics

Will panic if the regions of interest are not within the bounds of their respective Surface.

pub fn diff_lines(&self, other_lines: Vec<&Line>) -> Vec<Change>

pub fn diff_screens(&self, other: &Surface) -> Vec<Change>

Computes the change stream required to make self have the same screen contents as other.

pub fn draw_from_screen(
    &mut self,
    other: &Surface,
    x: usize,
    y: usize
) -> SequenceNo

Draw the contents of other into self at the specified coordinates. The required updates are recorded as Change entries as well as stored in the screen line/cell data. Saves the cursor position and attributes that were in effect prior to calling draw_from_screen and restores them after applying the changes from the other surface.

pub fn copy_region(
    &mut self,
    src_x: usize,
    src_y: usize,
    width: usize,
    height: usize,
    dest_x: usize,
    dest_y: usize
) -> SequenceNo

Copy the contents of the specified region to the same sized region elsewhere in the screen display. The regions may overlap.

Panics

The destination region must be the same size as the source (which is implied by the function parameters) and must fit within the width and height of the Surface or this operation will panic.

Trait Implementations

impl Default for Surface

fn default() -> Surface

Returns the "default value" for a type.