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).