Vt class final

A terminal emulator of width × height cells that fails on what a terminal would show wrong: feed gives it the bytes an application writes, and cell, lines and the cursor (cx, cy) read back what the screen shows.

A sequence it does not take, and a print that wraps or scrolls, is an error: kept in errors, and thrown as a StateError when strict.

A screen of 20 × 2 cells, fed a bold word and a move to the next row:

final vt = Vt(20, 2)..feed('\x1b[1mhi\x1b[0m\x1b[2;1Hthere'.codeUnits);
assert(vt.lines.first == 'hi');
assert(vt.cell(0, 0).attrs & Attr.bold != 0);
assert(vt.cy == 1);

See also:

  • TwkTester.vt, the emulator of a test's app, fed its frames.
  • VtTerminal, a terminal backend that writes into one.

Constructors

Vt(int width, int height, {bool bce = true, bool konsoleLines = false, bool konsoleImages = false, TextSegmenter? segmenter, bool strict = true, bool allowLineFeed = false, bool scrollback = false, bool relativeOnly = false, int cellPixelWidth = 10, int cellPixelHeight = 20})
A width × height screen, blank, the cursor at its top left.

Properties

allowLineFeed → bool
Accept LF (cursor down, scrolling at the bottom margin). Off by default: twk_core never emits LF (with the tty's ONLCR an LF would also return the cursor to column 0).
final
altScreenSwitches ↔ int
How many times the alternate screen (DEC mode 1049) was entered or left.
getter/setter pair
attrs ↔ int
The attributes text is printed with, as SGR set them last; as VtCell.attrs.
getter/setter pair
autowrap ↔ bool
DEC mode 7: a character printed past the last column goes to the start of the next row; off, it overwrites the last column.
getter/setter pair
bce → bool
Background color erase: an erasure (EL, ECH, ED, scrolling, IL, DL) leaves blanks in the current background; off, in the default one.
final
bg ↔ int
The background text is printed on, as SGR set it last; as VtCell.bg.
getter/setter pair
bidiExplicit ↔ bool
BDSM (ECMA-48 mode 8) reset by CSI 8 l: explicit mode, each character shown in the cell it is written to, which is all this emulator does either way; CSI 8 h sets it again (implicit mode).
getter/setter pair
bottomMargin ↔ int
The bottom row of the scroll region (DECSTBM), from 0.
getter/setter pair
cellPixelHeight → int
A cell's height in pixels, as cellPixelWidth is its width.
final
cellPixelWidth → int
A cell's width in pixels: a sixel image covers the cells its pixels reach into.
final
cursorShape ↔ int
The cursor's shape as DECSCUSR set it last: 0 for the terminal's default, 1 to 6 a blinking or steady block, underline or bar.
getter/setter pair
cursorVisible ↔ bool
DEC mode 25: whether the terminal shows the cursor.
getter/setter pair
cx ↔ int
The cursor's column, from 0.
getter/setter pair
cy ↔ int
The cursor's row, from 0.
getter/setter pair
drawnOnAlternate ↔ bool
Whether a row was written while on the alternate screen, which this emulator keeps no screen of its own for: an app drawn there. A probe that asks its queries there, which write no cell, isn't.
getter/setter pair
errors → List<String>
What went wrong, in order: a sequence not taken, a print that wrapped, a guarded row changed. Empty while the application writes only what a terminal shows right.
final
fg ↔ int
The color text is printed in, as SGR set it last; as VtCell.fg.
getter/setter pair
hashCode → int
The hash code for this object.
no setterinherited
height ↔ int
The screen's rows.
getter/setter pair
history → List<List<VtCell>>
The scrollback, oldest line first (see scrollback).
final
images → List<VtImage>
The images on the screen, top to bottom, each where it is: the rectangle around the cells it still has.
no setter
kittyImages → Map<int, int>
kitty: the images the terminal holds, by id, and their bytes.
final
konsoleImages → bool
Konsole's images (its Screen::scrollPlacements): they are not carried by the rows they are on but kept apart, and moved by the whole screen's scroll up of every SU, DL and line feed at the bottom margin, those outside the scrolled rows too, and by no scroll down (SD, IL, a reverse index). A deletion (a=d, ED 2) takes the placements away and keeps the image data, which only an image sent under the same id replaces.
final
konsoleLines → bool
Konsole's line model: a row holds the cells up to its stored length (the end of what was printed on it, or erased on it short of the right margin in any colours, as Konsole's clearImage pads the line it erases; the cells past it show as default blanks), which an erasure to the right margin in the default colours cuts back to its start and one in other colours stretches to the margin. DCH works within that length: at or past it nothing happens, before it the deleted cells are taken out and as many blanks in the current colours and attributes are appended at its end, not at the right margin. ICH inserts blanks in the default colours, not the current background, and extends it, up to the margin.
final
leftMargin ↔ int
The left column of the scroll region (DECSLRM), from 0.
getter/setter pair
leftRightMode ↔ bool
DECLRMM (DEC mode 69): whether DECSLRM sets leftMargin and rightMargin.
getter/setter pair
lines → List<String>
The text of every line, the scrollback first, without the blanks that end them.
no setter
Current hyperlink (OSC 8), applied to printed cells.
getter/setter pair
pendingWrap ↔ bool
Whether a character was printed in the last column and the cursor waits there: the next one printed wraps, with autowrap.
getter/setter pair
printWraps ↔ int
Count of wraps/scrolls caused by printing (should stay 0).
getter/setter pair
relativeOnly → bool
Absolute rows are an error (CUP, DECSTBM, ED 2, the alternate screen): an inline region doesn't know which screen row it starts on.
final
rightMargin ↔ int
The right column of the scroll region (DECSLRM), from 0.
getter/setter pair
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
scrollback → bool
A normal screen: lines scrolled off its top (by LF or SU over the whole screen) are kept in history instead of being dropped.
final
segmenter → TextSegmenter
How this terminal splits printed text into cells and how wide they are.
final
sixelCursorRight ↔ bool
DEC mode 8452: a sixel image leaves the cursor to its right, on its last row, instead of below it.
getter/setter pair
strict → bool
Whether an error is thrown as a StateError when it happens, besides being kept in errors.
final
syncDepth ↔ int
How deep the synchronized updates (DEC mode 2026) are open: 1 between a begin and its end, 0 outside; anything else is an error.
getter/setter pair
topMargin ↔ int
The top row of the scroll region (DECSTBM), from 0.
getter/setter pair
ul ↔ int
The underline's color, as SGR 58 set it last; as VtCell.ul.
getter/setter pair
width ↔ int
The screen's columns.
getter/setter pair

Methods

cell(int x, int y) → VtCell
The cell at column x of row y of the screen, both from 0.
dump() → String
The rows of the screen, every cell's text with the blanks that end them, a line each.
feed(List<int> bytes) → void
Takes bytes as the terminal takes what an application writes: prints their text, runs their control sequences. A sequence cut off at the end of bytes waits for the rest in the next call.
guardRows(int count) → void
Guards the top count rows of the screen and every line in history: writing to, erasing or moving one of them is an error, wherever scrolling or a resize takes it.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
resize(int w, int h) → void
Simulates a resize. Real terminals reflow or keep old content in arbitrary ways, so the new grid is filled with junk: the application must repaint every cell.
resizeKeeping(int w, int h, {bool pull = false}) → void
Simulates a resize of a terminal that keeps what the screen shows: rows are cut or padded with blanks at the right (no reflow) and the cursor stays on its row. A screen shorter than the cursor's row scrolls the rows above it into history (rows below the cursor are cut); a taller one gains blank rows at the bottom (xterm) or, with pull, takes lines back from history at the top (VTE).
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited