PDCurses User's Guide

Curses Overview

The X/Open Curses Interface Definition describes a set of C-Language functions that provide screen-handling and updating, which are collectively known as the curses library.

The curses library permits manipulation of data structures called windows which may be thought of as two-dimensional arrays of characters representing all or part of a terminal's screen. The windows are manipulated using a procedural interface described elsewhere. The curses package maintains a record of what characters are on the screen. At the most basic level, manipulation is done with the routines move() and addch() which are used to "move" the curses around and add characters to the default window, stdscr, which represents the whole screen.

An application may use these routines to add data to the window in any convenient order. Once all data have been added, the routine refresh() is called. The package then determines what changes have been made which affect the screen. The screen contents are then changed to reflect those characters now in the window, using a sequence of operations optimized for the type of terminal in use.

At a higher level routines combining the actions of move() and addch() are defined, as are routines to add whole strings and to perform format conversions in the manner of printf().

Interfaces are also defined to erase the entire window and to specify the attributes of individual characters in the window. Attributes such as inverse video, underline and blink can be used on a per-character basis.

New windows can be created by allowing the application to build several images of the screen and display the appropriate one very quickly. New windows are created using the routine newwin(). For each routine that manipulates the default window, stdscr, there is a corresponding routine prefixed with w to manipulate the contents of a specified window; for example, move() and wmove(). In fact, move(...) is functionally equivalent to wmove( stdscr, ...). This is similar to the interface offered by printf(...) and fprintf(stdout, ...).

Windows do not have to correspond to the entire screen. It is possible to create smaller windows, and also to indicate that the window is only partially visible on the screen. Furthermore, large windows or pads, which are bigger than the actual screen size, may be created.

Interfaces are also defined to allow input character manipulation and to disable and enable many input attributes: character echo, single character input with or without signal processing (cbreak or raw modes), carriage returns mapping to newlines, screen scrolling, etc.

Data Types and the <curses.h> Header

The data types supported by curses are described in this section.

As the library supports a procedural interface to the data types, actual structure contents are not described. All curses data are manipulated using the routines provided.

The <curses.h> Header

The <curses.h> header defines various constants and declares the data types that are available to the application.

Data Types

The following data types are declared:

Type	Description
WINDOW *	pointer to screen representation
SCREEN *	pointer to terminal descriptor
bool	boolean data type
chtype	representation of a character in a window
cchar_t	the wide-character equivalent of chtype
attr_t	for WA_-style attributes

The actual WINDOW and SCREEN objects used to store information are created by the corresponding routines and a pointer to them is provided. All manipulation is through that pointer.

Variables

The following variables are defined:

Variable	Description
LINES	number of lines on terminal screen
COLS	number of columns on terminal screen
stdscr	pointer to the default screen window
curscr	pointer to the current screen image
SP	pointer to the current SCREEN struct
Mouse_status	status of the mouse
COLORS	number of colors available
COLOR_PAIRS	number of color pairs available
TABSIZE	size of one TAB block
acs_map[]	alternate character set map
ttytype[]	terminal name/description

Constants

The following constants are defined:

General

Constant	Description
FALSE	boolean false value
TRUE	boolean true value
NULL	zero pointer value
ERR	value returned on error condition
OK	value returned on successful completion

Video Attributes

Normally, attributes are a property of the character.

For chtype:

Attribute	Description
A_ALTCHARSET	use the alternate character set
A_BLINK	bright background or blinking
A_BOLD	bright foreground or bold
A_DIM	half bright -- no effect in PDCurses
A_INVIS	invisible -- no effect in PDCurses
A_ITALIC	italic
A_LEFT	line along the left edge
A_PROTECT	protected -- no effect in PDCurses
A_REVERSE	reverse video
A_RIGHT	line along the right edge
A_STANDOUT	terminal's best highlighting mode
A_UNDERLINE	underline
A_ATTRIBUTES	bit-mask to extract attributes
A_CHARTEXT	bit-mask to extract a character
A_COLOR	bit-mask to extract a color-pair

Not all attributes will work on all terminals. A_ITALIC is not standard, but is shared with ncurses.

For attr_t:

Attribute	Description
WA_ALTCHARSET	same as A_ALTCHARSET
WA_BLINK	same as A_BLINK
WA_BOLD	same as A_BOLD
WA_DIM	same as A_DIM
WA_INVIS	same as A_INVIS
WA_ITALIC	same as A_ITALIC
WA_LEFT	same as A_LEFT
WA_PROTECT	same as A_PROTECT
WA_REVERSE	same as A_REVERSE
WA_RIGHT	same as A_RIGHT
WA_STANDOUT	same as A_STANDOUT
WA_UNDERLINE	same as A_UNDERLINE

The following are also defined, for compatibility, but currently have no effect in PDCurses: A_HORIZONTAL, A_LOW, A_TOP, A_VERTICAL and their WA_* equivalents.

The Alternate Character Set

For use in chtypes and with related functions. These are a portable way to represent graphics characters on different terminals.

VT100-compatible symbols -- box characters:

Name	Description
ACS_ULCORNER	upper left box corner
ACS_LLCORNER	lower left box corner
ACS_URCORNER	upper right box corner
ACS_LRCORNER	lower right box corner
ACS_RTEE	right "T"
ACS_LTEE	left "T"
ACS_BTEE	bottom "T"
ACS_TTEE	top "T"
ACS_HLINE	horizontal line
ACS_VLINE	vertical line
ACS_PLUS	plus sign, cross, or four-corner piece

VT100-compatible symbols -- other:

Name	Description
ACS_S1	scan line 1
ACS_S9	scan line 9
ACS_DIAMOND	diamond
ACS_CKBOARD	checkerboard -- 50% grey
ACS_DEGREE	degree symbol
ACS_PLMINUS	plus/minus sign
ACS_BULLET	bullet

Teletype 5410v1 symbols -- these are defined in SysV curses, but are not well-supported by most terminals. Stick to VT100 characters for optimum portability:

Name	Description
ACS_LARROW	left arrow
ACS_RARROW	right arrow
ACS_DARROW	down arrow
ACS_UARROW	up arrow
ACS_BOARD	checkerboard -- less dense than ACS_CKBOARD
ACS_LANTERN	lantern symbol
ACS_BLOCK	solid block

That goes double for these -- undocumented SysV symbols. Don't use them:

Name	Description
ACS_S3	scan line 3
ACS_S7	scan line 7
ACS_LEQUAL	less than or equal
ACS_GEQUAL	greater than or equal
ACS_PI	pi
ACS_NEQUAL	not equal
ACS_STERLING	pounds sterling symbol

Box character aliases:

Name	Description
ACS_BSSB	same as ACS_ULCORNER
ACS_SSBB	same as ACS_LLCORNER
ACS_BBSS	same as ACS_URCORNER
ACS_SBBS	same as ACS_LRCORNER
ACS_SBSS	same as ACS_RTEE
ACS_SSSB	same as ACS_LTEE
ACS_SSBS	same as ACS_BTEE
ACS_BSSS	same as ACS_TTEE
ACS_BSBS	same as ACS_HLINE
ACS_SBSB	same as ACS_VLINE
ACS_SSSS	same as ACS_PLUS

For cchar_t and wide-character functions, WACS_ equivalents are also defined.

Colors

For use with init_pair(), color_set(), etc.:

Name	BGR value	RGB value
COLOR_BLACK	0	0
COLOR_BLUE	1	4
COLOR_GREEN	2	2
COLOR_CYAN	3	6
COLOR_RED	4	1
COLOR_MAGENTA	5	5
COLOR_YELLOW	6	3
COLOR_WHITE	7	7

Use the symbolic names instead of numeric values. The definition of the colors depends on the implementation of curses.

Input Values

The following constants might be returned by getch() if keypad() has been enabled. Note that not all of these may be supported on a particular terminal:

Name	Description
KEY_BREAK	break key
KEY_DOWN	the four arrow keys
KEY_UP
KEY_LEFT
KEY_RIGHT
KEY_HOME	home key (upward+left arrow)
KEY_BACKSPACE	backspace
KEY_F0	function keys; space for 64 keys is reserved
KEY_F(n)	(KEY_F0+(n))
KEY_DL	delete line
KEY_IL	insert line
KEY_DC	delete character
KEY_IC	insert character
KEY_EIC	exit insert character mode
KEY_CLEAR	clear screen
KEY_EOS	clear to end of screen
KEY_EOL	clear to end of line
KEY_SF	scroll 1 line forwards
KEY_SR	scroll 1 line backwards (reverse)
KEY_NPAGE	next page
KEY_PPAGE	previous page
KEY_STAB	set tab
KEY_CTAB	clear tab
KEY_CATAB	clear all tabs
KEY_ENTER	enter or send
KEY_SRESET	soft (partial) reset
KEY_RESET	reset or hard reset
KEY_PRINT	print or copy
KEY_LL	home down or bottom (lower left)
KEY_A1	upper left of virtual keypad
KEY_A3	upper right of virtual keypad
KEY_B2	center of virtual keypad
KEY_C1	lower left of virtual keypad
KEY_C3	lower right of virtual keypad
KEY_BTAB	Back tab key
KEY_BEG	Beginning key
KEY_CANCEL	Cancel key
KEY_CLOSE	Close key
KEY_COMMAND	Cmd (command) key
KEY_COPY	Copy key
KEY_CREATE	Create key
KEY_END	End key
KEY_EXIT	Exit key
KEY_FIND	Find key
KEY_HELP	Help key
KEY_MARK	Mark key
KEY_MESSAGE	Message key
KEY_MOVE	Move key
KEY_NEXT	Next object key
KEY_OPEN	Open key
KEY_OPTIONS	Options key
KEY_PREVIOUS	Previous object key
KEY_REDO	Redo key
KEY_REFERENCE	Reference key
KEY_REFRESH	Refresh key
KEY_REPLACE	Replace key
KEY_RESTART	Restart key
KEY_RESUME	Resume key
KEY_SAVE	Save key
KEY_SBEG	Shifted beginning key
KEY_SCANCEL	Shifted cancel key
KEY_SCOMMAND	Shifted command key
KEY_SCOPY	Shifted copy key
KEY_SCREATE	Shifted create key
KEY_SDC	Shifted delete char key
KEY_SDL	Shifted delete line key
KEY_SELECT	Select key
KEY_SEND	Shifted end key
KEY_SEOL	Shifted clear line key
KEY_SEXIT	Shifted exit key
KEY_SFIND	Shifted find key
KEY_SHELP	Shifted help key
KEY_SHOME	Shifted home key
KEY_SIC	Shifted input key
KEY_SLEFT	Shifted left arrow key
KEY_SMESSAGE	Shifted message key
KEY_SMOVE	Shifted move key
KEY_SNEXT	Shifted next key
KEY_SOPTIONS	Shifted options key
KEY_SPREVIOUS	Shifted prev key
KEY_SPRINT	Shifted print key
KEY_SREDO	Shifted redo key
KEY_SREPLACE	Shifted replace key
KEY_SRIGHT	Shifted right arrow
KEY_SRSUME	Shifted resume key
KEY_SSAVE	Shifted save key
KEY_SSUSPEND	Shifted suspend key
KEY_SUNDO	Shifted undo key
KEY_SUSPEND	Suspend key
KEY_UNDO	Undo key

The virtual keypad is arranged like this:

A1     up     A3
left   B2  right
C1    down    C3

This list is incomplete -- see curses.h for the full list, and use the testcurs demo to see what values are actually returned. The above are just the keys required by X/Open. In particular, PDCurses defines many CTL_ and ALT_ combinations; these are not portable.