chickadee » termbox

termbox

Description

Library for writing text-based user interfaces.

Author

Richard van Roy (pluizer)

Requirements

none

Example

(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
(init)

;; 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
  (present)

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

	   ;; 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
(shutdown)

Documentation

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-styleprocedure

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

Example:

	; 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-styleprocedure

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

Procedures

initprocedure
shutdownprocedure

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.

widthprocedure
heightprocedure

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

presentprocedure

Syncronizes the internal back buffer with the terminal.

cursor-set! x yprocedure

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 cellsprocedure

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

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

input-mode #!optional modeprocedure

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 #!optional modeprocedure

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-resizeprocedure

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

Constants

Keys
key-f1constant
key-f2constant
key-f3constant
key-f4constant
key-f5constant
key-f6constant
key-f7constant
key-f8constant
key-f9constant
key-f10constant
key-f11constant
key-f12constant
key-insertconstant
key-deleteconstant
key-homeconstant
key-endconstant
key-pgupconstant
key-pgdnconstant
key-arrow-upconstant
key-arrow-downconstant
key-arrow-leftconstant
key-arrow-rightconstant
key-ctrl-tildeconstant
key-ctrl-2constant
key-ctrl-aconstant
key-ctrl-bconstant
key-ctrl-cconstant
key-ctrl-dconstant
key-ctrl-econstant
key-ctrl-fconstant
key-ctrl-gconstant
key-backspaceconstant
key-ctrl-hconstant
key-tabconstant
key-ctrl-iconstant
key-ctrl-jconstant
key-ctrl-kconstant
key-ctrl-lconstant
key-enterconstant
key-ctrl-mconstant
key-ctrl-nconstant
key-ctrl-oconstant
key-ctrl-pconstant
key-ctrl-qconstant
key-ctrl-rconstant
key-ctrl-sconstant
key-ctrl-tconstant
key-ctrl-uconstant
key-ctrl-vconstant
key-ctrl-wconstant
key-ctrl-xconstant
key-ctrl-yconstant
key-ctrl-zconstant
key-escconstant
key-ctrl-lsq-bracketconstant
key-ctrl-3constant
key-ctrl-4constant
key-ctrl-backslashconstant
key-ctrl-5constant
key-ctrl-rsq-bracketconstant
key-ctrl-6constant
key-ctrl-7constant
key-ctrl-slashconstant
key-ctrl-underscoreconstant
key-spaceconstant
key-backspace2constant
key-ctrl-8constant
Key modifiers
mod-altconstant
Colours
blackconstant
redconstant
greenconstant
yellowconstant
blueconstant
magentaconstant
cyanconstant
whiteconstant
Attributes
boldconstant
underlineconstant
reversedconstant

Contents »