termbox

Outdated egg!

This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for the CHICKEN 5 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

TOC »

Outdated egg!
termbox
- Description
- Author
- Requirements
- Example
- Documentation
  - Procedures
  - Constants
    - Keys
    - Key modifiers
    - Colours
    - 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

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