termbox

  1. termbox
    1. Description
    2. Author
    3. Requirements
    4. Example
    5. Documentation
      1. Procedures
      2. Constants
        1. Keys
        2. Key modifiers
        3. Colours
        4. Attributes

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

[procedure] (style colour attributes ...)

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

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

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))
[procedure] (create-cells string fg-style bg-style)

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

Procedures

[procedure] (init)
[procedure] (shutdown)

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.

[procedure] (width)
[procedure] (height)

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

[procedure] (clear [fg bg])

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

[procedure] (present)

Syncronizes the internal back buffer with the terminal.

[procedure] (cursor-set! x y)

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

[procedure] (hide-cursor!)

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

[procedure] (put-cell!)

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

[procedure] (blit x y w h cells)

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.

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

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

[procedure] (input-mode [mode])

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

Returns the current mode if node mode is given.

[procedure] (output-mode [mode])

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

Example usage:

      (change_cell! x y #\@ (style black bold) red)

Example usage:

      (change_cell! x y #\@ (style 184) (style 240))
      (change_cell! x y #\@ (style #xb8) (style #xf0))

Returns the current mode if node mode is given.

[procedure] (poll on-keypress on-resize)

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
[constant] 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
Key modifiers
[constant] mod-alt
Colours
[constant] black
[constant] red
[constant] green
[constant] yellow
[constant] blue
[constant] magenta
[constant] cyan
[constant] white
Attributes
[constant] bold
[constant] underline
[constant] reversed