Struct Screen

pub struct Screen { /* private fields */ }

Represents the overall terminal state.

Implementations

impl Screen

pub fn size(&self) -> (u16, u16)

Returns the current size of the terminal.

The return value will be (rows, cols).

pub fn scrollback(&self) -> usize

Returns the current position in the scrollback.

This position indicates the offset from the top of the screen, and is 0 when the normal screen is in view.

pub fn contents(&self) -> String

Returns the text contents of the terminal.

This will not include any formatting information, and will be in plain text format.

pub fn rows(&self, start: u16, width: u16) -> impl Iterator<Item = String> + '_

Returns the text contents of the terminal by row, restricted to the given subset of columns.

This will not include any formatting information, and will be in plain text format.

Newlines will not be included.

pub fn contents_between( &self, start_row: u16, start_col: u16, end_row: u16, end_col: u16, ) -> String

Returns the text contents of the terminal logically between two cells. This will include the remainder of the starting row after start_col, followed by the entire contents of the rows between start_row and end_row, followed by the beginning of the end_row up until end_col. This is useful for things like determining the contents of a clipboard selection.

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

Return escape codes sufficient to reproduce the entire contents of the current terminal state. This is a convenience wrapper around contents_formatted, input_mode_formatted, and title_formatted.

pub fn state_diff(&self, prev: &Self) -> Vec<u8>

Return escape codes sufficient to turn the terminal state of the screen prev into the current terminal state. This is a convenience wrapper around contents_diff, input_mode_diff, title_diff, and bells_diff.

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

Returns the formatted visible contents of the terminal.

Formatting information will be included inline as terminal escape codes. The result will be suitable for feeding directly to a raw terminal parser, and will result in the same visual output.

pub fn rows_formatted( &self, start: u16, width: u16, ) -> impl Iterator<Item = Vec<u8>> + '_

Returns the formatted visible contents of the terminal by row, restricted to the given subset of columns.

Formatting information will be included inline as terminal escape codes. The result will be suitable for feeding directly to a raw terminal parser, and will result in the same visual output.

You are responsible for positioning the cursor before printing each row, and the final cursor position after displaying each row is unspecified.

pub fn contents_diff(&self, prev: &Self) -> Vec<u8>

Returns a terminal byte stream sufficient to turn the visible contents of the screen described by prev into the visible contents of the screen described by self.

The result of rendering prev.contents_formatted() followed by self.contents_diff(prev) should be equivalent to the result of rendering self.contents_formatted(). This is primarily useful when you already have a terminal parser whose state is described by prev, since the diff will likely require less memory and cause less flickering than redrawing the entire screen contents.

pub fn rows_diff<'a>( &'a self, prev: &'a Self, start: u16, width: u16, ) -> impl Iterator<Item = Vec<u8>> + 'a

Returns a sequence of terminal byte streams sufficient to turn the visible contents of the subset of each row from prev (as described by start and width) into the visible contents of the corresponding row subset in self.

You are responsible for positioning the cursor before printing each row, and the final cursor position after displaying each row is unspecified.

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

Returns terminal escape sequences sufficient to set the current terminal’s input modes.

Supported modes are:

• application keypad
• application cursor
• bracketed paste
• xterm mouse support

pub fn input_mode_diff(&self, prev: &Self) -> Vec<u8>

Returns terminal escape sequences sufficient to change the previous terminal’s input modes to the input modes enabled in the current terminal.

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

Returns terminal escape sequences sufficient to set the current terminal’s window title.

pub fn title_diff(&self, prev: &Self) -> Vec<u8>

Returns terminal escape sequences sufficient to change the previous terminal’s window title to the window title set in the current terminal.

pub fn bells_diff(&self, prev: &Self) -> Vec<u8>

Returns terminal escape sequences sufficient to cause audible and visual bells to occur if they have been received since the terminal described by prev.

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

Returns terminal escape sequences sufficient to set the current terminal’s drawing attributes.

Supported drawing attributes are:

• fgcolor
• bgcolor
• bold
• italic
• underline
• inverse

This is not typically necessary, since contents_formatted will leave the current active drawing attributes in the correct state, but this can be useful in the case of drawing additional things on top of a terminal output, since you will need to restore the terminal state without the terminal contents necessarily being the same.

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

Returns the current cursor position of the terminal.

The return value will be (row, col).

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

Returns terminal escape sequences sufficient to set the current cursor state of the terminal.

This is not typically necessary, since contents_formatted will leave the cursor in the correct state, but this can be useful in the case of drawing additional things on top of a terminal output, since you will need to restore the terminal state without the terminal contents necessarily being the same.

Note that the bytes returned by this function may alter the active drawing attributes, because it may require redrawing existing cells in order to position the cursor correctly (for instance, in the case where the cursor is past the end of a row). Therefore, you should ensure to reset the active drawing attributes if necessary after processing this data, for instance by using attributes_formatted.

pub fn cell(&self, row: u16, col: u16) -> Option<&Cell>

Returns the Cell object at the given location in the terminal, if it exists.

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

Returns whether the text in row row should wrap to the next line.

pub fn title(&self) -> &str

Returns the terminal’s window title.

pub fn icon_name(&self) -> &str

Returns the terminal’s icon name.

pub fn audible_bell_count(&self) -> usize

Returns a value which changes every time an audible bell is received.

Typically you would store this number after each call to process, and trigger an audible bell whenever it changes.

You shouldn’t rely on the exact value returned here, since the exact value will not be maintained by contents_formatted or contents_diff.

pub fn visual_bell_count(&self) -> usize

Returns a value which changes every time an visual bell is received.

Typically you would store this number after each call to process, and trigger an visual bell whenever it changes.

You shouldn’t rely on the exact value returned here, since the exact value will not be maintained by contents_formatted or contents_diff.

pub fn errors(&self) -> usize

Returns the number of parsing errors seen so far.

Currently this only tracks invalid UTF-8 and control characters other than 0x07-0x0f. This can give an idea of whether the input stream being fed to the parser is reasonable or not.

pub fn alternate_screen(&self) -> bool

Returns whether the alternate screen is currently in use.

pub fn application_keypad(&self) -> bool

Returns whether the terminal should be in application keypad mode.

pub fn application_cursor(&self) -> bool

Returns whether the terminal should be in application cursor mode.

pub fn hide_cursor(&self) -> bool

Returns whether the terminal should be in hide cursor mode.

pub fn bracketed_paste(&self) -> bool

Returns whether the terminal should be in bracketed paste mode.

pub fn mouse_protocol_mode(&self) -> MouseProtocolMode

Returns the currently active MouseProtocolMode

pub fn mouse_protocol_encoding(&self) -> MouseProtocolEncoding

Returns the currently active MouseProtocolEncoding

pub fn fgcolor(&self) -> Color

Returns the currently active foreground color.

pub fn bgcolor(&self) -> Color

Returns the currently active background color.

pub fn bold(&self) -> bool

Returns whether newly drawn text should be rendered with the bold text attribute.

pub fn italic(&self) -> bool

Returns whether newly drawn text should be rendered with the italic text attribute.

pub fn underline(&self) -> bool

Returns whether newly drawn text should be rendered with the underlined text attribute.

pub fn inverse(&self) -> bool

Returns whether newly drawn text should be rendered with the inverse text attribute.

Trait Implementations

impl Clone for Screen

fn clone(&self) -> Screen

Returns a copy 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 Perform for Screen

fn print(&mut self, c: char)

Draw a character to the screen and update states.

fn execute(&mut self, b: u8)

Execute a C0 or C1 control function.

fn esc_dispatch(&mut self, intermediates: &[u8], _ignore: bool, b: u8)

The final character of an escape sequence has arrived.

fn csi_dispatch( &mut self, params: &Params, intermediates: &[u8], _ignore: bool, c: char, )

A final character has arrived for a CSI sequence

fn osc_dispatch(&mut self, params: &[&[u8]], _bel_terminated: bool)

Dispatch an operating system command.

fn hook( &mut self, params: &Params, intermediates: &[u8], _ignore: bool, action: char, )

Invoked when a final character arrives in first part of device control string.

fn put(&mut self, _byte: u8)

Pass bytes as part of a device control string to the handle chosen in hook. C0 controls will also be passed to the handler.

fn unhook(&mut self)

Called when a device control string is terminated.