chickadee » termbox



Library for writing text-based user interfaces.


Richard van Roy (pluizer)




(use termbox)

;; Little function that gives a random colour.
(define (random-colour)
  (let ((colours
	 (list black red green yellow blue magenta cyan white)))
    (list-ref colours (random (length colours)))))

;; Initialise termbox

;; Needed to stop the script when a key is pressed.
(define running (make-parameter #t))

;; Create a list of cells of every character in the string "Hello world !!!!!!"
;; all with a black underlined foreground and a yellow background.
(define cells (create-cells "Hello world !!!!!!"
			    (style black underline) (style yellow)))

(let loop ()
  ;; Blit all the cells of the string "Hello world !!!!!!" 
  ;; at position (5 5) inside a box with a size of (6 3).
  (blit 5 5 6 3 cells)

  ;; Present all changes to the screen

  ;; Poll for events
  (poll (lambda (mod key ch)

	   ;; When enter is pressed, clear the screen to a random colour.
	   ((eq? key key-enter) (clear (style black) 
				       (style (random-colour))))

	   ;; When escape is pressed stop the script.
	   ((eq? key key-esc) (running #f))))

	(lambda (w h)
	  ;; When screen is resized, print the screensize at the top-left corner
	  (bprintf 0 0
		   (style black underline) (style white)
		   "screen size ~a, ~a" w h)))

  ;; Continue running the loop as long as enter is not pressed.
  (when (running) (loop)))

;; Close termbox


(style colour attributes ...) procedure

Creates a style, combining a colour with zero or more attributes: underline, bold, and reversed.

(create-cell char fg-style bg-style) procedure

Creates a cell containing a character with specific foreground and background colours/attributes. These can then be put on screen with the functions (put-cell!) or (blit).


	; Create a letter ''H'' with black text and a white background.
	(create-cell #\H (style black) (style white))
	; Create a letter ''H'' with black underlines text and a white background.
	(create-cell #\H (style black underline) (style white))
(create-cells string fg-style bg-style) procedure

Create a list of cells of all characters in string all sharing the same foreground and background style.


(init) procedure
(shutdown) procedure

Initializes the termbox library. This function should be called before any other functions. After successful initialization, the library must be finalized using the (shutdown) function.

(width) procedure
(height) procedure

Returns the size of the internal back buffer (which is the same as terminal's window size in characters). The internal buffer can be resized after (clear) or (present) function calls. Both dimensions have an unspecified negative value when called before (init) or after (shutdown).

(clear [fg bg]) procedure

Clears the interbal back buffer to specific foreground and background colour which default to colour-default

(present) procedure

Syncronizes the internal back buffer with the terminal.

(cursor-set! x y) procedure

Sets the position of the cursor. Upper-left character is (0, 0).

(hide-cursor!) procedure

Hides the cursor. If (cursor-set!) is called after this the cursor will be visible again. Cursor is hidden by default.

(put-cell!) procedure

Changes cell's parameters in the internal back buffer at the specified position.

(blit x y w h cells) procedure

Copies the buffer from 'cells' at the specified position, assuming the buffer is a two-dimensional list of size ('w' x 'h'), represented as a one-dimensional list containing lines of cells starting from the top.

(bprintf x y fg-style bg-style formatstring ... args) procedure

Prints a formated string (like printf) at position (x y). Using a specific foreground and background style.

(input-mode [mode]) procedure

Sets the termbox input mode. Termbox has two input modes:<br/>

  • esc input mode: When ESC sequence is in the buffer and it doesn't match any known ESC sequence.
  • alt input mode: When ESC sequence is in the buffer and it doesn't match any known sequence => ESC enables mod-alt modifier for the next keyboard event.

Returns the current mode if node mode is given.

(output-mode [mode]) procedure

Sets the termbox output mode. Termbox has three output options:

  • normal [1..8]: This mode provides 8 different colours: black, red, green, yellow, blue, magenta, cyan, white. Attributes: bold, underline, reversed

Example usage:

      (change_cell! x y #\@ (style black bold) red)
  • 256 [0..256]: In this mode you can leverage the 256 terminal mode:
    • 0x00 - 0x07: the 8 colours as in normal
    • 0x08 - 0x0f: (style red bold)
    • 0x10 - 0xe7: 216 different colours
    • 0xe8 - 0xff: 24 different shades of grey

Example usage:

      (change_cell! x y #\@ (style 184) (style 240))
      (change_cell! x y #\@ (style #xb8) (style #xf0))
  • 216 [0..216]: This mode supports the 3rd range of the 256 mode only. But you dont need to provide an offset.
  • grayscale [0..23]: This mode supports the 4th range of the 256 mode only. But you dont need to provide an offset.

Returns the current mode if node mode is given.

(poll on-keypress on-resize) procedure

Waits until there is an event availiable. If there is it will call, if it is a key event, on-keypress which must be of form (lambda (mod key ch) ...). If the event is a resize event it will kall on-resize which must be of form (lambda (w h) ...).


key-f1 constant
key-f2 constant
key-f3 constant
key-f4 constant
key-f5 constant
key-f6 constant
key-f7 constant
key-f8 constant
key-f9 constant
key-f10 constant
key-f11 constant
key-f12 constant
key-insert constant
key-delete constant
key-home constant
key-end constant
key-pgup constant
key-pgdn constant
key-arrow-up constant
key-arrow-down constant
key-arrow-left constant
key-arrow-right constant
key-ctrl-tilde constant
key-ctrl-2 constant
key-ctrl-a constant
key-ctrl-b constant
key-ctrl-c constant
key-ctrl-d constant
key-ctrl-e constant
key-ctrl-f constant
key-ctrl-g constant
key-backspace constant
key-ctrl-h constant
key-tab constant
key-ctrl-i constant
key-ctrl-j constant
key-ctrl-k constant
key-ctrl-l constant
key-enter constant
key-ctrl-m constant
key-ctrl-n constant
key-ctrl-o constant
key-ctrl-p constant
key-ctrl-q constant
key-ctrl-r constant
key-ctrl-s constant
key-ctrl-t constant
key-ctrl-u constant
key-ctrl-v constant
key-ctrl-w constant
key-ctrl-x constant
key-ctrl-y constant
key-ctrl-z constant
key-esc constant
key-ctrl-lsq-bracket constant
key-ctrl-3 constant
key-ctrl-4 constant
key-ctrl-backslash constant
key-ctrl-5 constant
key-ctrl-rsq-bracket constant
key-ctrl-6 constant
key-ctrl-7 constant
key-ctrl-slash constant
key-ctrl-underscore constant
key-space constant
key-backspace2 constant
key-ctrl-8 constant
Key modifiers
mod-alt constant
black constant
red constant
green constant
yellow constant
blue constant
magenta constant
cyan constant
white constant
bold constant
underline constant
reversed constant

Contents »