Overview of curses

Compiling programs using curses

For you to use the curses library, certain types and variables must be defined. For example, you must have the following line at the top of the program source:

#include <curses.h>

Because the screen package uses the standard input/output (I/O) library, <curses.h> includes <stdio.h>. Additionally, <curses.h> includes <termios.h>. It is redundant but does no harm if you do these includes as well. In linking with curses, you must have -lcurses in your LDFLAGS or on the command line. You need not have any other libraries.

Updating the screen

For you to update the screen optimally, the routines must know how the screen currently looks and what you want it to look like next. A structure data type called window is defined for this purpose. It describes a window image to the routines. This description includes the window size and the starting position, which is indicated by the (y, x) coordinates of the upper-left corner of the screen. One of these, curscr (current screen), is a screen image of the current state of the terminal. You can make changes on another screen, stdscr (standard screen), which is provided by default.

A window is purely an internal representation. It is used to build and store a potential image of a portion of the terminal. It does not necessarily bear any relation to what is really on the terminal screen. It is more like a scratch pad or write buffer.

When you make a section of physical screen correspond to a window that reflects the contents of the window structure, the routine refresh() is called. If the window is not stdscr, wrefresh() is called.

A given physical screen section can be within the scope of any number of overlapping windows. You can make changes to windows in any order, without regard to motion efficiency. You can effectively say "...make it look like this...," and let the package determine the most efficient way to repaint the screen.

Standard windows and function naming conventions

The routines can use several windows, but two are automatically given: curscr, which knows how the terminal looks; and stdscr, which is how you want the terminal to look next.

You should never access curscr directly. Instead, you should first make changes to stdscr through the application programming interface (API), and then call the routines refresh() or wrefresh(). Then, curses copies the information from stdscr to curscr; the changes are then displayed.

Many functions are defined to use stdscr as a default screen. For example, to add a character to stdscr, you can call addch(), with a character as the argument. To write to a different window, use the routine waddch(), which stands for window-specific addch(). The convention of prefixing function names with a w when they are applied to specific windows is consistent. The only routines that do not follow this convention are those for which a window must always be specified.

You can move the current (y, x) coordinates from one point to another with the routines move() and wmove(). It is often desirable to perform the move first, and then perform some I/O operation, however. To make this work more smoothly, most I/O routines can be preceded by the prefix mv and the desired (y, x) coordinates prefixed to the arguments of the function. For example, you can replace the following calls:

move(y, x);
addch(ch);

by using:

mvaddch(y, x, ch);

You can also replace the following calls:

wmove(win, y, x);
waddch(win, ch);

by using:

mvwaddch(win, y, x, ch);

Variables

The curses library sets several variables describing terminal capabilities:

The <curses.h> library also introduces some #define constants and types: