INTRODUCTION TO NCURSES
DESCRIPTION
The
curses routines give the user a terminal-independent method of updating screens
with reasonable optimization. In order 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. (Three exceptions are
noted where they apply). The routine endwin()
must be called before exiting. To get character-at-a-time input without
echoing, (most interactive, screen oriented programs want this) after calling initscr()
you should call { cbreak(); noecho();
}.
Most programs additionally call { nonl();
intrflush (stdscr, FALSE); keypad (stdscr,
TRUE); }. Before curses program is run, a terminal's tab stops 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. The curses library contains routines that manipulate data
structures called WINDOWS that can be
thought of as two-dimensional arrays of characters representing all or part of
terminal screen. A default window called stdscr
is supplied, which uses the size of the terminal screen. Others may be created
with newwin(). Windows are referred
to by variables declared as WINDOW *;
the type WINDOW is defined in <curses.h>
to be a C structure.
These data structures are manipulated with routines
described below, among which the most basic are move() and addch(). (More
general versions of routines are included with the names beginning with ‘w’,
allowing you to specify the window. The routines not beginning with ‘w’
usually affect stdscr(). Then refresh()
is called, telling the routines to make the user's terminal screen look like stdscr. The characters in a window are actually of type chtype,
so that 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 displayed completely. In addition
to drawing characters on the screen, video attributes may be included which
cause the characters to show up in modes such as underlined or in reverse video
on terminals that support such display enhancements.
On
input, curses is also able to
translate arrow and function keys that transmit escape sequence into single
values. The video attributes, and input values use names, defined in <curses.h>,
such as A_REVERSE, ACS_HLINE,
and KEY_LEFT. If the window argument to clearok() is cursor,
the next call to wrefresh() with any window will cause the screen to be cleared and
repainted from scratch. If the window argument to wrefresh() is cursor, the screen is immediately cleared and
repainted from scratch. This is how most program implement a "repaint-screen" function. The environment variables LINES
and COLUMNS may be set to override terminfo's idea of how a large screen
is.
These
may be used in an AT&T Teletype 5620 layer, for example, where the size of a
screen is changeable. The integer variables LINES and COLS are defined in <curses.h>,
and will be filled in by initscr()
with the size of the screen. The constants TRUE
and FALSE have the values 1
and 0 respectively. The constants ERR
and OK are returned by routines to
indicate whether the routine successfully completed. These constants are also
defined in <curses.h>.
ROUTINES
Many of the
following routines have two or more versions. The outlines prefixed with ‘w’
require a window argument. The routines prefixed with ‘p’ require a pad
argument. Those without a prefix generally use stdscr. The outlines prefixed
with ‘mv’ require ‘y’ and ‘x’ coordinates to move to before
performing the appropriate action. The mv() routines imply a call to move() before the call
to the other routine. The window argument is always specified before the
coordinates. ‘y’ always refers to the ROW
(of the window), and ‘x’ always refers to the COLUMN. The upper left corner is always (0, 0) , not (1,1) . The
routines prefixed with ‘mvw’ take
both a window argument and y and x coordinates. In each case, win
is the window affected and pad is the
pad affected, (win and pad
always of type WINDOW *). Option-setting routines
require a boolean flag bf with
the value TRUE or FALSE, (bf is always of type bool) .The types WINDOW,
bool, and chtype are
defined in <curses.h>. Routines that return pointers always return NULL on
error.
ZAP works