[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]

General Programming Concepts: Writing and Debugging Programs


Chapter 2. The 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.

The Curses library provides a set of functions that enable you to manipulate a terminal's display regardless of the terminal type. 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 inside.

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 relevant information it needs to carry out your instructions.

For more information on curses programming, see the following:


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 type of window that is larger than the dimensions of the terminal's display.

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 two or more versions. 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 three 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.

Some curses subroutines with multiple versions do not include one of the preceding prefixes. These subroutines use the curses default window stdscr (standard screen). 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 debugger, 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 Program

In general, a curses program has the following progression:

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 on an error.

Related Information

Initializing Curses

Windows in the Curses Environment


[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]