Struct stakker_tui::TermOut

pub struct TermOut { /* fields omitted */ }

Output buffer for the terminal

This just buffers byte data on the way to the terminal. It allows batching up a whole screen update into a single write, to try to avoid tearing. This is shared between the Terminal actor and the actor(s) that will be writing data to the terminal.

Note that coordinates and sizes are passed as i32 here, because that is more convenient when relative offsets might be negative. It also allows positions modulo the screen dimensions, i.e. negative positions measuring from the right or bottom edge.

Calls that add to the buffer return the same self value, allowing the calls to be chained.

Not all ANSI sequences are covered here, just the basic ones require to implement a full-screen application and that are commonly supported everywhere. If you need another ANSI sequence, it is easy to create, for example termout.csi().num(5).asc('C') to do "cursor forward 5 cells".

Implementations

impl TermOut

pub fn features(&self) -> &Features

Get the features supported by the terminal

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

Get current terminal size: (rows, columns)

pub fn sy(&self) -> i32

Get current terminal size-Y, i.e. rows

pub fn sx(&self) -> i32

Get current terminal size-X, i.e. columns

pub fn flush(&mut self)

Mark all the data from the start of the buffer to the current end of the buffer as ready for flushing. However the data won't be flushed until the Terminal actor receives a Terminal::flush call. Any data added after this call won't be flushed unless another call to this method is made.

pub fn out(&mut self, data: &str) -> &mut Self

Add a chunk of UTF-8 string data to the output buffer.

See also the Write implementation, which allows use of write! and writeln! to add data to the buffer.

pub fn bytes(&mut self, data: &[u8]) -> &mut Self

Add a chunk of byte data to the output buffer.

See also the Write implementation, which allows use of write! and writeln! to add data to the buffer.

pub fn byt(&mut self, v1: u8) -> &mut Self

Add a single byte to the output buffer.

pub fn asc(&mut self, c: char) -> &mut Self

Add a single ASCII byte to the output buffer.

pub fn esc(&mut self, c: char) -> &mut Self

Add an ESC byte (27) + ASCII byte to the output buffer.

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

Add ESC [, which is the CSI sequence

pub fn num(&mut self, v: i32) -> &mut Self

Add a 1-3 digit decimal number (0..=999) to the output buffer, as used in control sequences. If number is out of range, then nearest valid number is used.

pub fn at(&mut self, y: i32, x: i32) -> &mut Self

Add ANSI sequence to move cursor to the given coordinates. Note that coordinates are row-first, with (0,0) as top-left. Coordinates are taken modulo the screen dimensions, so for example -1,-1 is bottom-right, and (0, -10) is 10 from the right on the top line.

pub fn attr(&mut self, codes: &str) -> &mut Self

Add an attribute string. The codes passed should be the semicolon-separated list of numeric codes, for example "1;31;46".

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

Add an attribute string to provide the given HFB colour expressed as 3 decimal digits HFB, or 2 decimal digits FB. This is intended for compact representation of the basic colours. H is highlight, used to control bold: 0 normal, 1 bold. F and B are foreground and background in colour-intensity order, 0-9: 0 black, 1 blue, 2 red, 3 magenta, 4 green, 5 cyan, 6 yellow, 7 white, 8/9 default.

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

Add ANSI sequence to switch to underline cursor

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

Add ANSI sequence to switch to block cursor

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

Add ANSI sequences to show cursor

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

Add ANSI sequences to hide cursor

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

Add ANSI sequence to move to origin (top-left)

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

Add ANSI sequence to erase to end-of-line

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

Add ANSI sequence to erase whole display

pub fn spaces(&mut self, n: i32) -> &mut Self

Add N spaces

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

Add ANSI sequence to reset attributes to the default

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

Add ANSI sequence to do a full reset of the terminal

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

Switch to UTF-8 mode. Useful for those terminals that don't default to UTF-8.

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

Move cursor to bottom line and do a linefeed. This results in the screen scrolling one line, and the cursor being left at the bottom-left corner.

pub fn save_cleanup(&mut self)

Save the current contents of the output buffer as the cleanup string, then clear the output buffer. The cleanup string will be output to the terminal on error or when the terminal is paused. This string should reset any settings that have been modified, and put the cursor somewhere sensible. Default is Esc c which completely resets the terminal, but usually it's better to do something less drastic, for example reset just the state that was changed, put the cursor at the bottom of the screen and do a LF. This will take effect on the next flush.

Trait Implementations

impl Write for TermOut

fn write(&mut self, buf: &[u8]) -> Result<usize>

Write a buffer into this writer, returning how many bytes were written.

fn flush(&mut self) -> Result<()>

Logically we consider the final destination of the Write trait to be the buffer. So this flush call does nothing. In general we'll want to gather all the updates into one big flush to avoid tearing on the terminal.

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

🔬 This is a nightly-only experimental API. (can_vector)

Determines if this Writeer has an efficient write_vectored implementation.

fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this writer.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

🔬 This is a nightly-only experimental API. (write_all_vectored)

Attempts to write multiple buffers into this writer.

fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

Creates a "by reference" adaptor for this instance of Write.