vtterm.screen
Keep a terminal’s grid of character cells and its cursor.
Screen is what the escape codes act on. It holds each row as four
bytearrays (characters, foreground, background and style flags), so a scroll
moves rows in a list instead of copying bytes. Rows that change are marked in
Screen.dirty for a renderer to redraw, and whole-screen scrolls are counted
in Screen.scrolled so a display that can scroll in hardware only draws the
new rows.
A cell holds one byte. Printable ASCII is itself, and the line-drawing
characters are the codes below 32 in GLYPHS, which a renderer draws as lines.
-
vtterm.screen.BOLD = 1
bold, drawn as the bright version of colors 0 to 7.
- Type:
Style flag
-
vtterm.screen.UNDERLINE = 2
underline.
- Type:
Style flag
-
vtterm.screen.REVERSE = 4
foreground and background swapped.
- Type:
Style flag
-
vtterm.screen.GLYPHS = ' ◆▒ ┘┐┌└┼⎺⎻─⎼⎽├┤┴┬│ ·'
the DEC line-drawing
set’s diamond, checkerboard, corners, tees, cross, lines and dot.
- Type:
The character each cell code below 32 stands for
-
class vtterm.screen.Screen(cols, rows, fg=7, bg=0, scrollback=0)[source]
Bases: object
A grid of character cells with a cursor, a pen and a scroll region.
Coordinates are zero-based: x is the column, y the row.
- Parameters:
cols (int) – Columns.
rows (int) – Rows.
fg (int) – Default foreground, an ANSI palette index.
bg (int) – Default background, an ANSI palette index.
scrollback (int) – Bytes to spend on rows that scroll off the top, four
per cell; 0 keeps none.
-
lines
One [chars, fg, bg, flags] list of bytearrays per row.
- Type:
list
-
dirty
Non-zero for each row changed since the last render.
- Type:
bytearray
-
scrolled
Whole-screen scrolls up since the last render.
- Type:
int
-
x
Cursor column.
- Type:
int
-
y
Cursor row.
- Type:
int
-
fg
Pen foreground.
- Type:
int
-
bg
Pen background.
- Type:
int
-
flags
Pen style flags (BOLD, UNDERLINE, REVERSE).
- Type:
int
-
cursor_visible
Whether the cursor is shown.
- Type:
bool
-
app_cursor
Cursor keys send application sequences (ESC O A).
- Type:
bool
-
g0
Character set G0 is the line-drawing set (ESC ( 0).
- Type:
bool
-
g1
Character set G1 is the line-drawing set (ESC ) 0).
- Type:
bool
-
shift
Which set is in use: 0 for G0, 1 for G1 (SO, SI).
- Type:
int
-
mouse
The mouse reports the program asked for: 0 for none,
or 9, 1000, 1002 or 1003.
- Type:
int
-
mouse_sgr
Reports use the SGR form (ESC [ ? 1006 h).
- Type:
bool
-
history
Rows that scrolled off the top, oldest first.
- Type:
list
-
view
How many rows the view is scrolled back; 0 is live.
- Type:
int
-
alt
Whether the alternate screen is showing.
- Type:
bool
-
reset()[source]
Return to the power-on state: clear, home, default pen and modes.
-
touch_all()[source]
Mark every row for redraw.
-
visible(y)[source]
Return the row drawn at screen row y, which may come from the history.
-
scroll_view(n)[source]
Scroll the view back n rows into the history; negative comes forward.
- Returns:
int – How many rows back the view is now (0 is live).
-
snap()[source]
Return the view to the live screen.
-
enter_alt(clear=True)[source]
Show a separate blank screen, keeping the main one to come back to.
-
leave_alt()[source]
Go back to the main screen as it was, and free the alternate one.
-
text(y)[source]
Return row y as a string, for tests and dumps.
Line-drawing cells come back as their box-drawing characters.
-
dump()[source]
Return the whole grid as a list of strings.
-
set_pen(fg=None, bg=None, flags=None)[source]
Change the colors and style that new characters and erases use.
-
put(data, start, end)[source]
Write the printable bytes data[start:end] at the cursor.
Wraps at the right edge when autowrap is on; otherwise the last
column takes each character that doesn’t fit.
-
linefeed()[source]
Move down a row, scrolling the region when at its bottom.
-
reverse_index()[source]
Move up a row, scrolling the region down when at its top.
-
carriage_return()[source]
Move to the first column.
-
backspace()[source]
Move one column left, stopping at the edge.
-
tab()[source]
Move to the next tab stop (every 8 columns) or the last column.
-
move_to(y, x)[source]
Put the cursor at row y, column x, inside the region in origin mode.
-
move_column(x)[source]
Put the cursor in column x of its row.
-
move_row(y)[source]
Put the cursor in row y, keeping its column.
-
up(n)[source]
Move up n rows, stopping at the region’s top when inside it.
-
down(n)[source]
Move down n rows, stopping at the region’s bottom when inside it.
-
right(n)[source]
Move right n columns, stopping at the edge.
-
left(n)[source]
Move left n columns, stopping at the edge.
-
set_region(top, bottom)[source]
Set the scroll region to rows top to bottom and home the cursor.
-
save_cursor()[source]
Remember the cursor, the pen, origin mode and the character sets (ESC 7).
-
restore_cursor()[source]
Go back to what save_cursor remembered, or home with a default pen.
-
scroll_up(n, top=None)[source]
Scroll rows top (default the region’s top) to the region’s bottom up n.
-
scroll_down(n, top=None)[source]
Scroll rows top (default the region’s top) to the region’s bottom down n.
-
erase_line(mode)[source]
Erase to the end (0), from the start (1) or all (2) of the cursor’s row.
-
erase_display(mode)[source]
Erase below (0), above (1) or all (2, 3) of the screen, the cursor included.
-
erase_chars(n)[source]
Blank n cells from the cursor without moving the rest of the row.
-
insert_chars(n)[source]
Open n blank cells at the cursor, pushing the rest of the row right.
-
delete_chars(n)[source]
Remove n cells at the cursor, pulling the rest of the row left.
-
insert_lines(n)[source]
Insert n blank rows at the cursor’s row, inside the scroll region.
-
delete_lines(n)[source]
Delete n rows at the cursor’s row, inside the scroll region.
-
fill_e()[source]
Fill the screen with E for alignment (ESC # 8).