Curses library
The curses library provides a set of functions that enable you to manipulate a terminal's display regardless of the terminal type. The curses library supports color. However, multibyte characters are not supported. All references to characters in the curses documentation refer to single-byte characters.
Throughout this documentation, the curses library is referred to as curses.
The basis of curses programming is the window data structure. Using this structure, you can manipulate data on a terminal's display. You can instruct curses to treat the entire terminal display as one large window, or you can create multiple windows on the display. The windows can be different sizes and can overlap one another. A typical curses application has a single large window and one subwindow within it.
Each window on a terminal's display has its own window data structure. This structure keeps state information about the window, such as its size and where it is located on the display. Curses uses the window data structure to obtain the relevant information it needs to carry out your instructions.
Terminology
When programming with curses, you should be familiar with the following terms:
| Term | Definition |
|---|---|
| current character | The character that the logical cursor is currently on. |
| current line | The line that the logical cursor is currently on. |
| curscr | A virtual default window provided by curses. The curscr (current screen) is an internal representation of what currently appears on the terminal's external display. Do not modify the curscr. |
| display | A physical display connected to a workstation. |
| logical cursor | The cursor location within each window. The window data structure keeps track of the location of its logical cursor. |
| pad | A pad is a window that is not restricted by the size of the screen |
| physical cursor | The cursor that appears on a display. The workstation uses this cursor to write to the display. There is only one physical cursor per display. |
| screen | The window that fills the entire display. The screen is synonymous with the stdscr. |
| stdscr | A virtual default window (standard screen) provided by curses that represents the entire display. |
| window | A pointer to a C data structure and the graphic representation of that data structure on the display. A window can be thought of as a two-dimensional array representing how all or part of the display looks at any point in time. |
Naming conventions
A single curses subroutine can have more than one version. Curses subroutines with multiple versions follow distinct naming conventions that identify the separate versions. These conventions add a prefix to a standard curses subroutine and identify what arguments the subroutine requires or what actions take place when the subroutine is called. The different versions of curses subroutine names use the following prefixes:
| Prefix | Description |
|---|---|
| w | Identifies a subroutine that requires a window argument |
| p | Identifies a subroutine that requires a pad argument |
| mv | Identifies a subroutine that first performs a move to the program-supplied coordinates |
If a curses subroutine has multiple versions and does not include one of the preceding prefixes, the curses default window stdscr (standard screen) is used. The majority of subroutines that use the stdscr are macros created in the /usr/include/curses.h file using #define statements. The preprocessor replaces these statements at compilation time. As a result, these macros do not appear in the compiled assembler code, a trace, a debug program, or the curses source code.
If a curses subroutine has only a single version, it does not necessarily use stdscr. For example, the printw subroutine prints a string to the stdscr. The wprintw subroutine prints a string to a specific window by supplying the window argument. The mvprintw subroutine moves the specified coordinates to the stdscr and then performs the same function as the printw subroutine. Likewise, the mvwprintw subroutine moves the specified coordinates to the specified window and then performs the same function as the wprintw subroutine.
Structure of a curses Pprogram
In general, a curses program has the following progression:
- Start curses.
- Check for color support (optional).
- Start color (optional).
- Create one or more windows.
- Manipulate windows.
- Destroy one or more windows.
- Stop curses.
Some steps are optional, so your program does not have to follow this progression exactly.
Return values
With a few exceptions, all curses subroutines return either the integer value ERR or the integer value OK. Subroutines that do not follow this convention are noted appropriately. Subroutines that return pointers always return a null pointer or an error.