Screen Updating and Cursor Movement Optimization: A Library Package Kenneth C. R. C. Arnold Elan Amir Computer Science Division Department of Electrical Engineering and Computer Science University of California, Berkeley Berkeley, California 94720
This document describes a package of C library functions which allow the user to:
These routines all use the termcap(5) database to describe the capabilities of the terminal. Acknowledgements
This package would not exist without the work of Bill Joy, who, in writing his editor, created the capability to generally describe terminals, wrote the routines which read this database, and, most importantly, those which implement optimal cursor movement, which routines I have simply lifted nearly intact. Doug Merritt and Kurt Shoens also were extremely important, as were both willing to waste time listening to me rant and rave. The help and/or support of Ken Abrams, Alan Char, Mark Horton, and Joe Kalash, was, and is, also greatly appreciated. Ken Arnold 16 April 1986
The help and/or support of Kirk McKusick and Keith Bostic (public vi!) was invaluable in bringing the package ``into the 90's'', which now includes completely new data structures and screen refresh optimization routines. Elan Amir 29 December 1992
In making available the generalized terminal descriptions in termcap(5), much information was made available to the programmer, but little work was taken out of one's hands. The purpose of this package is to allow the C programmer to do the most common type of terminal dependent functions, those of movement optimization and optimal screen updating, without doing any of the dirty work, and with nearly as much ease as is necessary to simply print or read things.
In this document, the following terminology is used:
window:
An internal representation
containing an image of what a section of the terminal screen may look like
at some point in time.
This subsection can either encompass the entire terminal screen,
or any smaller portion down to a single character within that screen.
terminal:
Sometimes called
terminal
screen.
The package's idea of what the terminal's screen currently looks like,
i.e.,
what the user sees now.
This is a special
screen:
screen:
This is a subset of windows which are as large as the terminal screen,
i.e.,
they start at the upper left hand corner
and encompass the lower right hand corner.
One of these,
stdscr,
is automatically provided for the programmer.
In order to use the library, it is necessary to have certain types and variables defined. Therefore, the programmer must have a line:
#include <curses.h>
cc [ flags ] file ... -lcurses -ltermcap
In order to update the screen optimally, it is necessary for the routines to know what the screen currently looks like and what the programmer wants it to look like next. For this purpose, a data type (structure) named WINDOW is defined which describes a window image to the routines, including its starting position on the screen (the (y, x) co-ordinates of the upper left hand corner) and its size. One of these (called curscr for current screen) is a screen image of what the terminal currently looks like. Another screen (called stdscr, for standard screen) is provided by default to make changes on.
A window is a purely internal representation. It is used to build and store a potential image of a portion of the terminal. It doesn't bear any necessary relation to what is really on the terminal screen. It is more like an array of characters on which to make changes.
When one has a window which describes what some part the terminal should look like, the routine refresh() (or wrefresh() if the window is not stdscr) is called. Refresh() makes the terminal, in the area covered by the window, look like that window. Note, therefore, that changing something on a window does change the terminal. Actual updates to the terminal screen are made only by calling refresh() or wrefresh(). This allows the programmer to maintain several different ideas of what a portion of the terminal screen should look like. Also, changes can be made to windows in any order, without regard to motion efficiency. Then, at will, the programmer can effectively say ``make it look like this'', and the package will execute the changes in an optimal way.
As hinted above, the routines can use several windows, but two are always available: curscr, which is the image of what the terminal looks like at present, and stdscr, which is the image of what the programmer wants the terminal to look like next. The user should not access curscr directly. Changes should be made to the appropriate screen, and then the routine refresh() (or wrefresh()) should be called.
Many functions are set up to deal with stdscr as a default screen. For example, to add a character to stdscr, one calls addch() with the desired character. If a different window is to be used, the routine waddch() (for window-specific addch()) is provided[1]. This convention of prepending function names with a ``w'' when they are to be applied to specific windows is consistent. The only routines which do not do this are those to which a window must always be specified.
In order to move the current (y, x) co-ordinates from one point to another, the routines move() and wmove() are provided. However, it is often desirable to first move and then perform some I/O operation. In order to avoid clumsiness, most I/O routines can be preceded by the prefix ``mv'' and the desired (y, x) co-ordinates can then be added to the arguments to the function. For example, the calls
move(y, x); addch(ch);
mvaddch(y, x, ch);
wmove(win, y, x); waddch(win, ch);
mvwaddch(win, y, x, ch);