nish/term
A terminal drawn as a grid of coloured cells, and the keys a terminal sends turned into events.
import {
ACTION_MOVE,
ACTION_PRESS,
ACTION_RELEASE,
ACTION_REPEAT,
ATTR_BOLD,
ATTR_INVERSE,
ATTR_NONE,
COLOR_DEFAULT,
Canvas,
EVENT_FOCUS,
EVENT_KEY,
EVENT_MOUSE,
EVENT_PASTE,
EVENT_QUIT,
EVENT_REPLY,
EVENT_RESIZE,
FixedStep,
KEY_BACKSPACE,
KEY_CHAR,
KEY_CONTROL,
KEY_CTRL_C,
KEY_DELETE,
KEY_DOWN,
KEY_END,
KEY_ENTER,
KEY_ESCAPE,
KEY_F1,
KEY_F10,
KEY_F11,
KEY_F12,
KEY_F2,
KEY_F3,
KEY_F4,
KEY_F5,
KEY_F6,
KEY_F7,
KEY_F8,
KEY_F9,
KEY_HOME,
KEY_INSERT,
KEY_LEFT,
KEY_PAGE_DOWN,
KEY_PAGE_UP,
KEY_RIGHT,
KEY_SPACE,
KEY_TAB,
KEY_UNKNOWN,
KEY_UP,
KeyDecoder,
KeyEvent,
KeyState,
MOD_ALT,
MOD_CTRL,
MOD_HYPER,
MOD_META,
MOD_SHIFT,
MOD_SUPER,
MOUSE_BUTTON_8,
MOUSE_LEFT,
MOUSE_MIDDLE,
MOUSE_NONE,
MOUSE_RIGHT,
MOUSE_WHEEL_DOWN,
MOUSE_WHEEL_LEFT,
MOUSE_WHEEL_RIGHT,
MOUSE_WHEEL_UP,
Screen,
TermEvent,
beginSync,
clearScreen,
endSync,
enterAltScreen,
hideCursor,
leaveAltScreen,
moveCursor,
paletteIndex,
resetStyle,
rgb,
showCursor,
} from "nish/term";
import { Screen, Canvas, rgb, COLOR_DEFAULT, enterAltScreen, hideCursor } from "nish/term";
const screen = new Screen(80, 24, false);
write(enterAltScreen() + hideCursor());
screen.clear(COLOR_DEFAULT);
screen.text(2, 1, "score 0", rgb(255, 255, 0), COLOR_DEFAULT, 0);
write(screen.flush()); // the whole frame the first time, then only what changed
beginSync
Begin a synchronized update (DEC mode 2026): a terminal that knows the mode holds what follows until endSync, then paints it in one go, so a frame is never seen half drawn.
clearScreen
Move the cursor home and erase the whole screen; a Screen that was drawn on wants invalidate after it.
endSync
End a synchronized update, so the terminal paints what beginSync held.
enterAltScreen
Switch to the alternate screen, which the terminal restores the old contents from on leaving.
hideCursor
Hide the cursor, so a redraw does not flicker it across the screen.
leaveAltScreen
Leave the alternate screen and show what was there before enterAltScreen.
moveCursor
Move the cursor to a cell.
paletteIndex
The 256-colour palette entry nearest a colour: one of the 6×6×6 cube (16–231) or of the 24 greys (232–255), whichever is closer in RGB.
resetStyle
Reset colour and attributes to the terminal's defaults: SGR 0.
rgb
A colour from its red, green and blue.
showCursor
Show the cursor again.
Canvas
Pixels on a Screen, two to a cell: width is the screen's columns and height twice its rows.
FixedStep
A fixed-step clock: it turns the time between frames into a whole number of steps of 1000 / stepsPerSecond milliseconds, so a game's logic runs at the same rate whatever the display does.
KeyDecoder
Bytes from a terminal in raw mode, turned into key events.
KeyEvent
One key: its KEY_ kind and a code, which is the code point for KEY_CHAR and otherwise the byte that named it.
KeyState
Which keys are down, from the events a KeyDecoder made — what a game asks each frame.
Screen
A grid of coloured cells, double-buffered, and the escapes that bring a terminal up to date with it.
TermEvent
One thing a terminal sent: a key, the mouse, a paste, a focus change or an answer to a query, told apart by type (an EVENT_ constant).
No I/O
Nothing here reads the terminal or writes to it: a Screen turns
the cells a program drew into the string that brings the terminal from the
last frame to this one, and a KeyDecoder turns the bytes a program read
into key events. The program writes the string with write and reads the
bytes however it reads its input; the size of the terminal, raw mode and the
clock are the caller's, passed in as numbers. So this module reaches no
capability, a test can compare its output byte for byte, and it runs the
same under Node.
A `Screen`
A Screen holds width × height cells, each a code point, a foreground,
a background and two attributes (bold, inverse), twice over: the frame being
drawn and the frame the terminal was last sent. flush walks both and emits
only the cells that differ — a cursor move where it is not already in place,
a style change only where the style differs from the cell before it, and the
glyph's UTF-8 bytes — then makes the drawn frame the sent one. Every glyph is
taken to be one column wide; a wide character (most CJK, most emoji) would
push the rest of its row along, and is the caller's to avoid.
A `Canvas`
A Canvas draws pixels on a Screen: each cell shows two, one above the
other, with the upper half block "▀" in the top pixel's colour on a background
of the bottom pixel's (and the lower half block "▄" when only the bottom
pixel is set). A terminal cell is about twice as tall as it is wide, so the
pixels come out roughly square.
Colour
Colour is 24-bit RGB, an i32 0xRRGGBB made by rgb, or
COLOR_DEFAULT for the terminal's own colour. A Screen made with
palette256 set sends each colour as the nearest of the 256-colour palette
instead, for a terminal without true colour; deciding which a terminal has
(COLORTERM is the usual sign) is the caller's.
Events
KeyDecoder.feed and poll answer KeyEvents, as they always
have. KeyDecoder.feedEvents(bytes, count, nowMs) and pollEvents(nowMs)
read the same bytes as one stream of TermEvents, whose type is an
EVENT_ constant:
-
EVENT_KEY, a key with itsKEY_kind andcode, itsMOD_bits (MOD_SHIFT,MOD_ALT,MOD_CTRL,MOD_SUPER,MOD_HYPER,MOD_META) and itsACTION_(ACTION_PRESS,ACTION_REPEAT,ACTION_RELEASE): legacy keys, xterm's modified keys and modifyOtherKeys (ESC [ 27 ; m ; c ~), and the kitty keyboard protocol'sESC [ code ; mods:event ; text u(sw.kovidgoyal.net/kitty/keyboard-protocol); -
EVENT_MOUSE, an SGR reportESC [ < b ; x ; y M|m(xterm ctlseqs, mode 1006, or 1016 in pixels withpixelMouseset) with itsMOUSE_button,ACTION_PRESS,ACTION_RELEASEorACTION_MOVE, and cellx,y; -
EVENT_PASTE, everything betweenESC [ 200 ~andESC [ 201 ~(xterm ctlseqs, "Bracketed Paste Mode") as onetext, never as keys; EVENT_FOCUS,ESC [ IorESC [ O(mode 1004),gainedor not;-
EVENT_REPLY, every answer a terminal sends to a query — DA, DSR, CPR, DECRPM, the kitty flags, XTVERSION and DECRQSS (DCS), OSC, APC — with itsintroducer,prefix,params,intermediate, final bytereplyandtext. A reply never reaches the program as a key.ESC [ row ; col Ris both a cursor position report and F3 with modifiers, so a caller that asks for one (ESC [ 6 n) adds 1 tocprOutstanding, and while it is above 0 the nextRis the reply, taking 1 off. Nothing expires it: a caller that gives up waiting for a report sets it back to 0; EVENT_RESIZEandEVENT_QUIT, which the caller andKeyStatemake.
An unfinished sequence is held for escapeTimeoutMs after the last byte arrived,
then given up by pollEvents as feed would; a control string cut off by
the timeout is dropped whole. A paste is never timed out. A CSI reply cut
off by the timeout (a terminal that stalls inside ESC [ ? 6 2 c) cannot
be told from keys, so its bytes come out as the keys they spell.
A `KeyState`
A KeyState turns those events into which keys are down. apply(events, nowMs) answers the events to act on and tick(nowMs) the releases due
meanwhile; isDown(key, code) asks. A terminal without the kitty protocol
sends no releases, so while releasesAreSynthetic is set (until the first
real release) a key counts as let go when its repeats stop: firstRepeatMs
(700 ms) after a press that has not repeated and releaseGapMs (100 ms)
after its last repeat.
Silence is measured in stream time when the caller has one: term-io sends an
in-order query after each frame and calls delivered with the send time of
each one answered, since by then everything the terminal generated before it
has arrived. Measured that way a stall, a burst or jittery reads delay the
watermark as much as the keys, so a held key never flickers and a tap comes
up 700 ms plus one round trip after its press.
With no watermark yet, silence is wall-clock time between applys, which a
link that reads in bursts more than releaseGapMs apart can mistake for a
key let go. While acks stop, nothing is released: there is no wall-clock
backstop, and a caller that stops getting answers clears watermarked to
fall back to the wall clock. term-io does so once 1000 ms pass with no query
answered, frames sent or not, which no working link reaches while it draws.
Within one read the caller applys its events before calling delivered for
the answer it carries: a tick between the two would judge keys against a
watermark that already covers repeats not yet applied, and report a release
and then a press. A non-finite time is ignored. Under X11 and Windows only
the last key pressed auto-repeats, so holding W and then pressing D lets W go
releaseGapMs after its last repeat.
A real release of a key not down is dropped, so one arriving after its key
was made up as released is not reported twice. Under kitty a real release
that is lost leaves its key down until focus is lost, and for good without
focus reporting. A key the batch apply takes names stays down. A made-up
release carries the code and modifiers the key last came with. Losing focus
lets every key go, and Ctrl-C becomes EVENT_QUIT while quitOnCtrlC is
set.
Under the kitty protocol a non-Latin layout sends Ctrl-C as its own letter
(ESC [ 1089 ; 5 u for Russian С), which is not read as a quit: the
base-layout key that flag 4 (report alternate keys) adds is not read yet.
The same bytes under Node
Natively a string is UTF-8 bytes, and flush
builds its answer as bytes and makes one string of them. Under Node a string
is UTF-16 units and write encodes it as UTF-8, so there flush decodes the
same bytes into code units first: the terminal receives the same bytes either
way, which tests/run.js checks ("nish/term prints the same bytes under
runtime/nish.mjs"). text reads a string's code points as UTF-8 natively and
as UTF-16 under Node, so a string literal draws the same cells both ways.
A TermEvent's text is made from bytes the terminal sent: natively it
holds them as they came, and under Node they are decoded as UTF-8 without
checking, so malformed UTF-8 in a paste or reply can differ between the two.
Integer division is spelled (a / b) | 0, which truncates in both.
Functions
beginSync
Begin a synchronized update (DEC mode 2026): a terminal that knows the mode
holds what follows until endSync, then paints it in one go, so a frame is
never seen half drawn. One that does not ignores it.
const beginSync: () => string
returnsstringThe escape sequence, to write.
clearScreen
Move the cursor home and erase the whole screen; a Screen that was drawn on
wants invalidate after it.
const clearScreen: () => string
returnsstringThe escape sequences, to write.
endSync
End a synchronized update, so the terminal paints what beginSync held.
const endSync: () => string
returnsstringThe escape sequence, to write.
enterAltScreen
Switch to the alternate screen, which the terminal restores the old contents from on leaving.
const enterAltScreen: () => string
returnsstringThe escape sequence, to write.
hideCursor
Hide the cursor, so a redraw does not flicker it across the screen.
const hideCursor: () => string
returnsstringThe escape sequence, to write.
leaveAltScreen
Leave the alternate screen and show what was there before enterAltScreen.
const leaveAltScreen: () => string
returnsstringThe escape sequence, to write.
moveCursor
Move the cursor to a cell.
const moveCursor: (x: i32, y: i32) => string
xi32requiredThe column, from 0 at the left.
yi32requiredThe row, from 0 at the top.
returnsstringThe escape sequence, to write.
paletteIndex
The 256-colour palette entry nearest a colour: one of the 6×6×6 cube (16–231) or of the 24 greys (232–255), whichever is closer in RGB.
const paletteIndex: (colour: i32) => i32
colouri32requiredAn 0xRRGGBB colour, or COLOR_DEFAULT.
returnsi32The palette index; COLOR_DEFAULT stays itself.
resetStyle
Reset colour and attributes to the terminal's defaults: SGR 0.
const resetStyle: () => string
returnsstringThe escape sequence, to write.
rgb
A colour from its red, green and blue.
const rgb: (r: i32, g: i32, b: i32) => i32
ri32requiredRed, 0–255; a value outside is clamped.
gi32requiredGreen, 0–255; a value outside is clamped.
bi32requiredBlue, 0–255; a value outside is clamped.
returnsi32The colour as 0xRRGGBB, for any fg, bg or pixel.
showCursor
Show the cursor again.
const showCursor: () => string
returnsstringThe escape sequence, to write.
Classes
Canvas
Pixels on a Screen, two to a cell: width is the screen's columns and
height twice its rows. Each pixel is a colour or COLOR_DEFAULT, which is
the terminal's background showing through. Drawing a pixel redraws its cell
at once, so text drawn after it lands on top, and pixels drawn after text
replace it.
class Canvas
| Member | |
|---|---|
new Canvas(screen: Screen) |
A canvas of screen's size, every pixel COLOR_DEFAULT. Make a new one after the screen is resized. |
height: i32 |
Pixels down: twice the screen's height. |
pixels: i32[] |
One colour per pixel, row by row. |
screen: Screen |
The screen the pixels are drawn on. |
width: i32 |
Pixels across: the screen's width. |
clear(colour: i32): void |
Set every pixel to one colour. |
fillRect(x: i32, y: i32, w: i32, h: i32, colour: i32): void |
Fill a rectangle, clipped to the canvas. |
line(x0: i32, y0: i32, x1: i32, y1: i32, colour: i32): void |
Draw a line, both ends included (Bresenham's). Any i32 ends will do: the walk stops once it leaves the canvas for good, though one that starts far outside steps all the way in. |
pixel(x: i32, y: i32): i32 |
What colour a pixel is. |
setPixel(x: i32, y: i32, colour: i32): void |
Set one pixel; a pixel off the canvas is not drawn. |
text(col: i32, row: i32, s: string, fg: i32): i32 |
Draw a string in screen cells over the pixels, each character on the colour of the pixels behind it (the top one, or the bottom one where the top is unset). |
FixedStep
A fixed-step clock: it turns the time between frames into a whole number of
steps of 1000 / stepsPerSecond milliseconds, so a game's logic runs at the
same rate whatever the display does. advance(nowMs) answers how many steps
to run since the last call and keeps the remainder for the next; alpha()
is that remainder as a fraction of a step, to draw between the last two
states. At most maxSteps run per call: a clock further behind drops the
backlog rather than spiral, keeping its phase. With maxSteps 1 the same
clock paces drawing, answering 1 when a frame is due. The clock is the
caller's, as KeyDecoder's is.
class FixedStep
| Member | |
|---|---|
new FixedStep(stepsPerSecond: i32, maxSteps: i32) |
A clock for a simulation that steps at a fixed rate whatever the frame rate. |
maxSteps: i32 |
The most steps one advance answers. |
stepMs: f64 |
The length of one step, in milliseconds. |
advance(nowMs: f64): i32 |
The steps to run for the time between the last call and now. The first call only starts the clock and answers 0, as does a time earlier than the last one. |
alpha(): f64 |
How far into the next step the clock is, for drawing between two steps. |
KeyDecoder
Bytes from a terminal in raw mode, turned into key events. A read can end in
the middle of an escape sequence or a UTF-8 character; the decoder keeps the
start and finishes it with the next feed. An ESC on its own is both the
escape key and the start of every arrow, so it is held until either more
bytes complete a sequence or escapeTimeoutMs passes with none, and then it
is KEY_ESCAPE.
Whatever is held past the timeout is given up the same way: the ESC as
KEY_ESCAPE, the bytes after it as keys of their own, and an unfinished
UTF-8 character as U+FFFD. The clock is the caller's: each call takes the
time now in milliseconds, from any origin, so long as it does not go
backwards.
feedEvents and pollEvents decode the same bytes into TermEvents
instead: keys with their modifiers and press, repeat or release, the mouse,
pastes, focus and the terminal's replies, none of which reaches the program
as a key. A decoder is fed one way or the other, not both. The module
header lists every sequence they read.
class KeyDecoder
| Member | |
|---|---|
new KeyDecoder(escapeTimeoutMs: f64) |
A decoder with nothing held. |
cellHeightPx: i32 |
A cell's height in pixels, to turn a 1016 report into a row; 0 while unknown. |
cellWidthPx: i32 |
A cell's width in pixels, to turn a 1016 report into a column; 0 while unknown. |
cprOutstanding: i32 |
How many cursor position reports (ESC [ 6 n) are awaited. ESC [ r ; c R is both the report and F3 with modifiers; while this is above 0 it is the report, and takes one off. Whoever writes the request adds one. |
escapeTimeoutMs: f64 |
How long a held ESC waits for the rest of a sequence, in milliseconds. |
pixelMouse: boolean |
Whether SGR mouse reports are in pixels (mode 1016), so px and py are set and x, y derived. |
feed(bytes: u8[], count: i32, nowMs: f64): KeyEvent[] |
Decode what was read, after whatever was held: held bytes older than the timeout are given up first, as keys of their own, and the rest continue into these. |
feedEvents(bytes: u8[], count: i32, nowMs: f64): TermEvent[] |
Decode what was read into events of every kind, after whatever was held, as feed takes them. The timeout counts from the last byte that arrived, so a reply split across reads is not given up halfway. |
poll(nowMs: f64): KeyEvent[] |
Give up held bytes once the timeout has passed since they arrived. |
pollEvents(nowMs: f64): TermEvent[] |
Give up held bytes once the timeout has passed: an ESC as KEY_ESCAPE, an unterminated DCS, APC or OSC as nothing. A paste waits for its end however long it takes. |
waiting(): boolean |
Whether bytes are held, so the caller should poll once the timeout has passed. |
KeyEvent
One key: its KEY_ kind and a code, which is the code point for KEY_CHAR and otherwise the byte that named it.
class KeyEvent
| Member | |
|---|---|
new KeyEvent(kind: i32, code: i32) |
A key event. |
code: i32 |
The character's code point, the control byte, or the escape sequence's final byte. |
kind: i32 |
One of the KEY_ constants. |
KeyState
Which keys are down, from the events a KeyDecoder made — what a game asks
each frame. Under the kitty protocol with event types (flag 2) a terminal
sends real releases. Without it a terminal sends nothing when a key comes up,
only the press again as it auto-repeats, so a key is let go once its repeats
stop: releaseGapMs after its last repeat, and firstRepeatMs after a press
that has not repeated.
The system waits before its first repeat — 660 ms under X11 by default, 500
under Windows, shorter under macOS — and repeats every 30–40 ms; a longer
delay needs firstRepeatMs raised, and a slower rate releaseGapMs. Input
arrives late and in bursts (over SSH, reads 150–250 ms apart are usual), so
when the reads alone are known the silence is not: a caller that sends
in-order queries calls delivered(sentAtMs) as each is answered, and silence
is then measured against that watermark rather than the clock.
A key last seen in a read at A is let go once the watermark reaches A + gap: had it still been down, the terminal would have generated a repeat
before then, and it would have arrived ahead of the answer. Until the first
delivered, and after the caller clears watermarked, the gap is measured
against nowMs. Pure, with the caller's clock, as KeyDecoder is.
class KeyState
| Member | |
|---|---|
new KeyState() |
No key down, releases synthesized, Ctrl-C a quit. |
firstRepeatMs: f64 |
How long the system waits before a held key's first repeat, at most, in milliseconds (700 by default, above X11's 660). |
quitOnCtrlC: boolean |
Whether Ctrl-C (byte 3, or kitty ESC [ 99 ; 5 u) becomes EVENT_QUIT (true by default). |
releaseGapMs: f64 |
How long after its last repeat a key is let go, in milliseconds (100 by default). |
releasesAreSynthetic: boolean |
Whether releases are made up from silence; false from the first real release, or when the caller knows kitty flag 2 is on. |
watermarked: boolean |
Whether silence is measured against watermarkMs rather than the clock; set by delivered, which the caller may clear when answers stop. |
watermarkMs: f64 |
The latest send time of an answered query that delivered was given: everything the terminal generated before it has arrived. |
apply(events: TermEvent[], nowMs: f64): TermEvent[] |
Take the events of one read and answer what the program should see: first the releases tick makes for the keys the events do not mention (a held key's repeats can wait in a read longer than the gap), then each event, with Ctrl-C as EVENT_QUIT (its repeats and release dropped) and a press of a key already down marked ACTION_REPEAT while releases are synthetic.A real release of a key not down is dropped: it was let go already, made up from silence or by losing focus. Losing focus lets every key go, since its release goes elsewhere. |
delivered(sentAtMs: f64): void |
Note that everything the terminal generated before a time has arrived: the answer to an in-order query sent then has come back. From now on silence is measured against the latest such time. |
deliveredAgoMs(nowMs: f64): f64 |
How long ago the latest answered query was sent; the caller clears watermarked once this passes its bound. |
isDown(key: i32, code: i32): boolean |
Whether a key is down. A letter is the same key in either case, since Shift changes the code a terminal sends. |
tick(nowMs: f64): TermEvent[] |
The releases due while releases are synthetic: each key whose gap has passed, let go. |
Screen
A grid of coloured cells, double-buffered, and the escapes that bring a terminal up to date with it.
class Screen
| Member | |
|---|---|
new Screen(width: i32, height: i32, palette256: boolean) |
A screen of blank cells in the terminal's colours, none of them sent yet, so the first flush draws them all. |
attrs: i32[] |
The frame's attributes, laid out as glyphs: ATTR_BOLD and ATTR_INVERSE, or'd. |
bgs: i32[] |
The frame's backgrounds, laid out as glyphs. |
fgs: i32[] |
The frame's foregrounds, laid out as glyphs: a colour or COLOR_DEFAULT. |
glyphs: i32[] |
The frame being drawn, one code point per cell, row by row. |
height: i32 |
Rows. |
palette256: boolean |
Whether colours go out as 256-colour palette indices rather than 24-bit RGB. |
sync: boolean |
Whether a flush that changes anything is wrapped in beginSync and endSync; off until set. |
width: i32 |
Columns. |
clear(background: i32): void |
Blank every cell of the frame being drawn. |
flush(): string |
Turn the frame last sent into the frame drawn, and make the drawn frame the sent one. Changed cells are visited row by row. The cursor is moved only when it is not already at the cell — ESC [ n C along the row, ESC [ row ; col H otherwise — and a gap of up to three unchanged ASCII cells in the current style is rewritten instead, which is shorter than the move. A style is sent only when it differs from the previous cell's, and only the parts that differ, from a reset when an attribute has to be turned off.A flush that leaves the terminal in a style other than the default ends with ESC [ 0 m, so what the caller writes next starts plain. With sync set, a flush that changes anything is wrapped in beginSync and endSync, in the same string, so the terminal paints the frame whole. |
glyphAt(x: i32, y: i32): i32 |
What the frame being drawn holds in a cell. |
invalidate(): void |
Forget what the terminal shows, so the next flush sends every cell: after a clearScreen, say. |
resize(width: i32, height: i32): void |
Make the screen a new size, blank and unsent: a terminal that changed size is redrawn in full. Each side is at most 4,096 cells and the screen at most 1,048,576, rows dropped to fit, so no size a terminal reports makes it overflow or run out of memory. |
set(x: i32, y: i32, glyph: i32, fg: i32, bg: i32, attrs: i32): void |
Draw one character in a cell; a cell off the screen is not drawn. |
text(x: i32, y: i32, s: string, fg: i32, bg: i32, attrs: i32): i32 |
Draw a string along a row, one cell per character, clipped at the edges. |
TermEvent
One thing a terminal sent: a key, the mouse, a paste, a focus change or an
answer to a query, told apart by type (an EVENT_ constant). Each type
fills its own fields and leaves the rest at their defaults: 0, -1 for the
pixel position, "" and no params.
class TermEvent
| Member | |
|---|---|
new TermEvent(type: i32) |
An event with every field but its type at its default. |
action: i32 |
An ACTION_ constant: whether a key or button went down, repeated, came up or (the mouse) moved. |
button: i32 |
The mouse's MOUSE_ button. |
code: i32 |
A key's code: the code point for KEY_CHAR, the byte for a control, the kitty key number or the final byte for KEY_UNKNOWN. |
gained: boolean |
For EVENT_FOCUS, whether the terminal gained focus. |
intermediate: i32 |
A reply's intermediate byte, such as the $ of DECRPM, or 0. |
introducer: i32 |
What opened a reply: [ for a CSI, P for a DCS, _ for an APC, ] for an OSC, ^ for a PM, X for an SOS. |
key: i32 |
A key's KEY_ kind. |
modifiers: i32 |
The MOD_ bits held with a key or a mouse event. |
params: i32[] |
A reply's numeric parameters, an omitted one as 0; for an OSC, its number; for KEY_UNKNOWN, the sequence's. |
prefix: i32 |
A reply's private marker, ?, >, = or <, or 0. |
px: i32 |
The mouse's pixel column, from 0, under mode 1016; -1 otherwise. |
py: i32 |
The mouse's pixel row, from 0, under mode 1016; -1 otherwise. |
reply: i32 |
A reply's final byte (c, R, y, …); for an APC, its first payload byte (G for kitty graphics); for an OSC, 0. |
text: string |
A paste's text, a kitty key's associated text, or the payload of a reply after its header. |
type: i32 |
One of the EVENT_ constants. |
x: i32 |
The mouse's column, from 0; -1 under mode 1016 while the cell size is unknown. |
y: i32 |
The mouse's row, from 0; -1 under mode 1016 while the cell size is unknown. |
Constants
4
ACTION_MOVE: i32
The mouse moved, with button held or MOUSE_NONE.
1
ACTION_PRESS: i32
A key or button went down.
3
ACTION_RELEASE: i32
A key or button came up.
2
ACTION_REPEAT: i32
A held key repeated.
1
ATTR_BOLD: i32
The bold attribute bit: SGR 1.
2
ATTR_INVERSE: i32
The inverse-video attribute bit, foreground and background swapped: SGR 7.
0
ATTR_NONE: i32
No attributes: plain text.
-1
COLOR_DEFAULT: i32
The terminal's own colour, foreground or background: SGR 39 and 49.
4
EVENT_FOCUS: i32
A TermEvent that is a focus change, ESC [ I or ESC [ O: gained says which.
1
EVENT_KEY: i32
A TermEvent that is a key: key, code, modifiers and action.
2
EVENT_MOUSE: i32
A TermEvent that is the mouse: button, action, modifiers, the cell x, y and, under mode 1016, the pixel px, py.
3
EVENT_PASTE: i32
A TermEvent that is a bracketed paste: text is everything between ESC [ 200 ~ and ESC [ 201 ~.
7
EVENT_QUIT: i32
A TermEvent that asks the program to quit: what KeyState makes of Ctrl-C.
6
EVENT_REPLY: i32
A TermEvent that is the terminal answering a query: introducer, prefix, params, intermediate, reply and text. Never a key.
5
EVENT_RESIZE: i32
A TermEvent that is a new terminal size. The decoder never makes one: it is for the code that watches the size.
11
KEY_BACKSPACE: i32
Backspace: DEL (127) or BS (8), which is the byte's code.
1
KEY_CHAR: i32
A printable character; the event's code is its code point.
12
KEY_CONTROL: i32
Any other control byte below 32; the event's code is the byte (Ctrl-A is 1).
9
KEY_CTRL_C: i32
Ctrl-C, byte 3, which a terminal in raw mode delivers instead of a signal.
31
KEY_DELETE: i32
Delete (the key, not DEL the byte): ESC [ 3 ~.
3
KEY_DOWN: i32
The down arrow, ESC [ B or ESC O B.
27
KEY_END: i32
End: ESC [ F, ESC O F, ESC [ 4 ~ or ESC [ 8 ~.
6
KEY_ENTER: i32
Enter: a carriage return (13) or a line feed (10), which is the byte's code.
8
KEY_ESCAPE: i32
The escape key: an ESC that no sequence followed within the timeout.
14
KEY_F1: i32
F1: ESC O P, ESC [ 1 ; m P, ESC [ 11 ~ or the Linux console's ESC [ [ A. F1–F12 are consecutive, so Fn is KEY_F1 + n - 1.
23
KEY_F10: i32
F10: ESC [ 21 ~.
24
KEY_F11: i32
F11: ESC [ 23 ~.
25
KEY_F12: i32
F12: ESC [ 24 ~.
15
KEY_F2: i32
F2: ESC O Q, ESC [ 1 ; m Q, ESC [ 12 ~ or ESC [ [ B.
16
KEY_F3: i32
F3: ESC O R, ESC [ 1 ; m R (when no cursor report is awaited), ESC [ 13 ~ or ESC [ [ C.
17
KEY_F4: i32
F4: ESC O S, ESC [ 1 ; m S, ESC [ 14 ~ or ESC [ [ D.
18
KEY_F5: i32
F5: ESC [ 15 ~ or ESC [ [ E.
19
KEY_F6: i32
F6: ESC [ 17 ~.
20
KEY_F7: i32
F7: ESC [ 18 ~.
21
KEY_F8: i32
F8: ESC [ 19 ~.
22
KEY_F9: i32
F9: ESC [ 20 ~.
26
KEY_HOME: i32
Home: ESC [ H, ESC O H, ESC [ 1 ~ or ESC [ 7 ~.
30
KEY_INSERT: i32
Insert: ESC [ 2 ~.
5
KEY_LEFT: i32
The left arrow, ESC [ D or ESC O D.
29
KEY_PAGE_DOWN: i32
Page Down: ESC [ 6 ~.
28
KEY_PAGE_UP: i32
Page Up: ESC [ 5 ~.
4
KEY_RIGHT: i32
The right arrow, ESC [ C or ESC O C.
7
KEY_SPACE: i32
The space bar (32).
10
KEY_TAB: i32
Tab (9).
13
KEY_UNKNOWN: i32
An escape sequence this decoder does not name; the event's code is its final byte.
2
KEY_UP: i32
The up arrow, ESC [ A or ESC O A.
2
MOD_ALT: i32
The Alt bit of modifiers; also set for an ESC followed by an ASCII key.
4
MOD_CTRL: i32
The Ctrl bit of modifiers.
16
MOD_HYPER: i32
The Hyper bit of modifiers (kitty only).
32
MOD_META: i32
The Meta bit of modifiers (kitty only).
1
MOD_SHIFT: i32
The Shift bit of modifiers. The bits are the kitty keyboard protocol's modifier value minus one, which the xterm ; m forms share.
8
MOD_SUPER: i32
The Super bit of modifiers (the Windows or Command key).
8
MOUSE_BUTTON_8: i32
Button 8 (back on most mice); 9, 10 and 11 follow it.
1
MOUSE_LEFT: i32
The left button.
2
MOUSE_MIDDLE: i32
The middle button.
0
MOUSE_NONE: i32
No button: a move with nothing held, or a release a terminal does not name.
3
MOUSE_RIGHT: i32
The right button.
5
MOUSE_WHEEL_DOWN: i32
The wheel turned down.
6
MOUSE_WHEEL_LEFT: i32
The wheel tilted left.
7
MOUSE_WHEEL_RIGHT: i32
The wheel tilted right.
4
MOUSE_WHEEL_UP: i32
The wheel turned up; MOUSE_WHEEL_DOWN, _LEFT and _RIGHT follow it. A wheel only ever presses.

