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×heightscreen, 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 hsets 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:
0for the terminal's default,1to6a 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
- link ↔ String?
-
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
xof rowyof 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
bytesas the terminal takes what an application writes: prints their text, runs their control sequences. A sequence cut off at the end ofbyteswaits for the rest in the next call. -
guardRows(
int count) → void -
Guards the top
countrows 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