termbox.q

Draw on the terminal as a grid of cells: .termbox.init[] takes the screen, .termbox.show rows paints a list of strings from the top-left corner, .termbox.present[] flushes the changes, .termbox.peek_event 100 waits up to 100 ms for a key or mouse event, .termbox.shutdown[] hands the terminal back. The names and meanings follow termbox2 (snake_case), so its documentation and examples carry over. examples/q/life.q is the worked example. One session at a time. The terminal is restored on shutdown, on any error, on Ctrl-C and on exit, so restore is never the program's job; Ctrl-C is the interrupt, never a key. Text written by show or -1 inside a loop reaches the screen only after the statement ends: draw through .termbox instead.

Examples

.termbox.init[]
.termbox.show ("hello";"press any key")
.termbox.present[]
e:.termbox.poll_event[]
.termbox.shutdown[]
e`name

Entity Summary

Entities	Short Description
.termbox.beep[hz;ms]	Start a tone of hz for ms milliseconds and return at once (one plays at a time): 1b when a tone was started, 0b when one is still playing (the call is dropped) or there was no audio device and the terminal bell rang instead.
.termbox.cells[]	The back buffer as a table with one row per cell, ch a long codepoint: what present would send, before it is sent.
.termbox.clear[]	Blank every cell of the back buffer (space, default colours).
.termbox.clock[]	Milliseconds since init on a monotonic clock (never wall time); 0 before init, so a game can call it anywhere.
.termbox.events[ms]	Every pending event as a table with peek_event's columns, one row per event in arrival order: waits at most ms milliseconds for the first, then takes what is already queued.
.termbox.has_truecolor[]	Whether the terminal reported 24-bit colour at init.
.termbox.height[]	The screen height in cells, as of the last present.
.termbox.hide_cursor[]	Hide the cursor (the state init starts in).
.termbox.init[]	Take the terminal: raw input, the alternate screen, cursor hidden.
.termbox.invalidate[]	Forget what the terminal shows, so the next present repaints every cell.
.termbox.peek_event[ms]	Wait up to ms milliseconds for an event and answer it as a dict; a field that does not apply is null.
.termbox.poll_event[]	Wait for the next event, with no timeout.
.termbox.present[]	Write the back buffer to the terminal: only the cells that changed since the last present are sent.
.termbox.print	Write a string into the back buffer from column x, row y, one cell per character (a multibyte UTF-8 character is one cell); text past the right edge is dropped.
.termbox.rgb[r;g;b]	A 24-bit colour as a style long.
.termbox.set_cell[x;y;ch;fg;bg]	Write one cell of the back buffer at column x, row y (0-based).
.termbox.set_cells[x;y;ch;fg;bg]	Write many cells at once: cell i lands at x[i], y[i].
.termbox.set_cursor[x;y]	Place the cursor at column x, row y (0-based; shown at the next present).
.termbox.set_input_mode[mode]	Choose how input is read: a sum of .termbox.input. values.
.termbox.set_output_mode[mode]	Choose how colours are sent: a .termbox.output. value.
.termbox.show	Paint whole rows from the top-left corner, row y from the string at y.
.termbox.shutdown[]	Hand the terminal back exactly as init found it.
.termbox.width[]	The screen width in cells, as of the last present.
.termbox.wrap[width;text]	Word-wrap text to width cells (a multibyte character is one cell): breaks at spaces, a newline starts a new line, a word wider than the width is split where it must be.

Entity Details

.termbox.beep[hz;ms]

Start a tone of hz for ms milliseconds and return at once (one plays at a time): 1b when a tone was started, 0b when one is still playing (the call is dropped) or there was no audio device and the terminal bell rang instead.

Parameters:	hz - 0-32767; 0 is silence ms - 0-60000

Examples

.termbox.beep[440;200]

.termbox.cells[]

The back buffer as a table with one row per cell, ch a long codepoint: what present would send, before it is sent.

col:	ch the codepoint; "c"$ it for ASCII text

Examples

select from .termbox.cells[] where ch<>32

.termbox.clear[]

Blank every cell of the back buffer (space, default colours). Nothing shows until present.

.termbox.events[ms]

Every pending event as a table with peek_event's columns, one row per event in arrival order: waits at most ms milliseconds for the first, then takes what is already queued. Empty when nothing arrived.

Parameters:	ms - the timeout for the first event; negative waits forever

Examples

select name, ch from .termbox.events 100

.termbox.init[]

Take the terminal: raw input, the alternate screen, cursor hidden.

throws:	os - stdin/stdout is not a terminal domain - a session is already open

.termbox.peek_event[ms]

Wait up to ms milliseconds for an event and answer it as a dict; a field that does not apply is null. Mouse events arrive only after set_input_mode with .termbox.input.mouse. There are no key-release events.

Columns:	button - `left`right`middle`wheel_up`wheel_down`release, `none for a plain movement mod - the sum of 1 shift, 2 alt, 4 ctrl ch - the char for a printable key, or a long codepoint when it is not one byte kind - `key, `mouse, `resize, or `none when nothing arrived in time w - width after a resize name - the key's name (`a, `enter, `space, `left, `f1, `ctrl_c, `esc ...); for any other event its kind again (`mouse, `resize, `none) so one switch on name dispatches everything, except a pointer movement, which is `move x - column of a mouse event h - height after a resize y - row of a mouse event
Return:	a dict `kind`name`ch`mod`x`y`button`w`h
Parameters:	ms - the timeout; negative waits forever

Examples

.termbox.peek_event 100

.termbox.poll_event[]

Wait for the next event, with no timeout. peek_event's answer.

.termbox.present[]

Write the back buffer to the terminal: only the cells that changed since the last present are sent. A resized window is noticed here; the next peek_event answers a `resize event.

.termbox.print

Write a string into the back buffer from column x, row y, one cell per character (a multibyte UTF-8 character is one cell); text past the right edge is dropped. .termbox.print[x;y;fg;bg;text;w;align] places the text inside a w-cell field starting at x, aligned `left, `centre (`center) or `right, clipped to the field.

Parameters:	fg - a style, or a long vector with one style per character bg - a style, or a long vector with one style per character

Examples

.termbox.print[0;0;.termbox.color.yellow;.termbox.color.default;"score 42"]

.termbox.print[0;1;.termbox.color.default;.termbox.color.default;"centred";.termbox.width[];`centre]

.termbox.rgb[r;g;b]

A 24-bit colour as a style long. Styles are disjoint bit fields, so add colours and attributes.

Parameters:	r - 0-255 b - 0-255 g - 0-255

Examples

.termbox.rgb[255;128;0]+.termbox.attribute.bold

.termbox.set_cell[x;y;ch;fg;bg]

Write one cell of the back buffer at column x, row y (0-based). A position off the screen is ignored.

Parameters:	fg - a style: .termbox.color. or .termbox.rgb[r;g;b], plus any .termbox.attribute. ch - a char, or a Unicode codepoint as a long

Examples

.termbox.set_cell[0;0;"@";.termbox.color.red+.termbox.attribute.bold;.termbox.color.default]

.termbox.set_cells[x;y;ch;fg;bg]

Write many cells at once: cell i lands at x[i], y[i]. Cells off the screen are dropped.

Parameters:

fg - a style for every cell, or a long vector with one per cell
ch - one char or codepoint for every cell, a string with one byte per cell, a long vector of codepoints, or a list of strings each decoding from UTF-8 to one codepoint
bg - a style for every cell, or a long vector with one per cell
x - column vector, or an atom that extends to the length of y
y - row vector, or an atom that extends to the length of x

throws:

length x, y, ch and a vector style do not agree

Examples

.termbox.set_cells[til 5;0;"#####";.termbox.color.green;.termbox.color.default]

.termbox.set_cursor[x;y]

Place the cursor at column x, row y (0-based; shown at the next present). A negative coordinate hides it.

.termbox.set_input_mode[mode]

Choose how input is read: a sum of .termbox.input. values. .termbox.input.mouse turns mouse reporting on (clicks, wheel, releases and every pointer movement); esc and alt both read Esc-prefixed keys as alt-modified.

Return:	the previous mode

Examples

.termbox.set_input_mode .termbox.input.esc+.termbox.input.mouse

.termbox.set_output_mode[mode]

Choose how colours are sent: a .termbox.output. value. init picks the richest the terminal reports (COLORTERM, TERM); NO_COLOR or PEACHQ_COLORS=0 picks mono. A style richer than the mode degrades to the nearest colour the mode has.

Return:	the previous mode

Examples

.termbox.set_output_mode .termbox.output.color256

.termbox.show

Paint whole rows from the top-left corner, row y from the string at y. .termbox.show[rows;fg;bg] also styles them: a style atom for everything, a long vector with one style per row, or a list of long vectors with one style per cell. Rows below the screen and cells past the right edge are dropped.

Examples

.termbox.show ("row 0";"row 1")

.termbox.show[("row 0";"row 1");.termbox.color.red .termbox.color.green;.termbox.color.default]

.termbox.shutdown[]

Hand the terminal back exactly as init found it. Safe to call when no session is open.

.termbox.wrap[width;text]

Word-wrap text to width cells (a multibyte character is one cell): breaks at spaces, a newline starts a new line, a word wider than the width is split where it must be. Needs no session.

Return:	a list of strings

Examples

.termbox.wrap[10;"the quick brown fox jumps"]