5.2.1 Overview

The GNU Guile-Ncurses library routines give the user a terminal-independent method of updating character screens with reasonable optimization.

The package supports overall screen, window and pad manipulation; output to windows and pads; reading terminal input; control over terminal and curses input and output options; environment query routines; color manipulation; use of soft label keys; terminfo capabilities; and access to low-level terminal-manipulation routines.

To initialize the routines, the routine initscr or newterm must be called before any of the other routines that deal with windows and screens are used. The routine endwin must be called before exiting. To get character-at-a-time input without echoing (most interactive, screen oriented programs want this), the following sequence should be used:

(cbreak!)
(noecho!)

Most programs would additionally use the sequence:

(nonl!)
(intrflush! #f)
(keypad! stdscr #t))

Before a curses program is run, the tab stops of the terminal should be set and its initialization strings, if defined, must be output. This can be done by executing the tput init command after the shell environment variable TERM has been exported. tset is usually responsible for doing this. [See terminfo for further details.]

The Guile-Ncurses library permits manipulation of data structures, the #<window> type, which can be thought of as two-dimensional arrays of characters representing all or part of a CRT screen. A default window, conventionally called stdscr, which is the size of the terminal screen, is supplied. The #<window> information for stdscr is returned by calling the procedure initscr. Other windows may be created with newwin.

Note that (ncurses curses) does not easily handle overlapping windows. Overlapping windows usually require the use of the (ncurses panel) library. Without the panel library, you can either position everything on screen by hand or divide the screen into tiled windows. Chose one of the two strategies and stick with it. Mixing the two will result in unpredictable, and undesired, effects.

Windows are referred to by variables declared as #<window>. These data structures are manipulated with routines described here. Among those, the most basic routines are move and addch. move places the cursor at a location in a buffer, and addch puts a character at that location.

After using routines to manipulate a window, refresh is called, telling curses to make the user’s CRT screen look like array of characters in a #<window> buffer. Other information about the character may also be stored with each character.

Special windows called pads may also be manipulated. These are windows which are not constrained to the size of the screen and whose contents need not be completely displayed.

In addition to drawing characters on the screen, video attributes and colors may be supported, causing the characters to show up in such modes as underlined, in reverse video, or in color on terminals that support such display enhancements. Line drawing characters may be specified to be output. On input, curses is also able to translate arrow and function keys that transmit escape sequences into single values. The video attributes, line drawing characters, and input values use names, such as A_REVERSE, (acs-hline), and KEY_LEFT.

If the environment variables LINES and COLUMNS are set, or if the program is executing in a window environment, line and column information in the environment will override information read by terminfo.

If the environment variable TERMINFO is defined, any program using curses checks for a local terminal definition before checking in the standard places. For example, if TERM is set to xterm, then the compiled terminal definition is found in /usr/share/terminfo/x/xterm

(The “x” is copied from the first letter of “xterm” to avoid creation of huge directories.) However, if TERMINFO is set to $HOME/myterms, curses first checks $HOME/myterms/x/xterm, and if that fails, it then checks the standard location.

This is useful for developing experimental definitions or when write permission in /usr/share/terminfo is not available.

The getter procedures (lines) and (cols) are defined in (ncurses curses) and will be return the size of the screen at the time initscr was called.

5.2.1.1 The Coordinate System

The move routine and routines that take #:y and #:x arguments use a screen based coordinate system. The coordinate y always refers to the row (of the window), and x always refers to the column. The upper left-hand corner is always (0,0). y increases as one moves down the window, and x increases as one moves left.