curses(3XCURSES) (man pages section 3: Curses Library Functions)

man pages section 3: Curses Library Functions

curses(3XCURSES)

NAME | DESCRIPTION | EXAMPLES | ATTRIBUTES | SEE ALSO

NAME

curses– introduction and overview of X/Open Curses

DESCRIPTION

The Curses screen management package conforms fully with Issue 4, Version 2 of the X/Open Curses specification. It provides a set of internationalized functions and macros for creating and modifying input and output to a terminal screen. This includes functions for creating windows, highlighting text, writing to the screen, reading from user input, and moving the cursor.

X/Open Curses is a terminal-independent package, providing a common user interface to a variety of terminal types. Its portability is facilitated by the Terminfo database which contains a compiled definition of each terminal type. By referring to the database information X/Open Curses gains access to low-level details about individual terminals.

X/Open Curses tailors its activities to the terminal type specified by the TERM environment variable. The TERM environment variable may be set in the Korn Shell (see ksh(1)) by typing:

export TERM=terminal_name

environ(5)

Three additional environment variables are useful, and can be set in the Korn Shell:

If you have an alternate Terminfo database containing terminal types that are not available in the system default database /usr/share/lib/terminfo, you can specify the TERMINFO environment variable to point to this alternate database:
export TERMINFO=path
This path specifies the location of the alternate compiled Terminfo database whose structure consists of directory names 0 to 9 and a to z (which represent the first letter of the compiled terminal definition file name).

The alternate database specified by TERMINFO is examined before the system default database. If the terminal type specified by TERM cannot be found in either database, the default terminal type dumb is assumed.
To specify a window width smaller than your screen width (for example, in situations where your communications line is slow), set the COLUMNS environment variable to the number of vertical columns you want between the left and right margins:
export COLUMNS=number
The number of columns may be set to a number smaller than the screen size; however, if set larger than the screen or window width, the results are undefined.

The value set using this environment variable takes precedence over the value normally used for the terminal.
To specify a window height smaller than your current screen height (for example, in situations where your communications line is slow), override the LINES environment variable by setting it to a smaller number of horizontal lines:
export LINES=number
The number of lines may be set to a number smaller than the screen height; however, if set larger than the screen or window height, the results are undefined.

The value set using this environment variable takes precedence over the value normally used for the terminal.

Data Types

X/Open Curses defines the following data types:

attr_t: An integral type that holds an OR-ed set of attributes. The attributes acceptable are those which begin with the WA_ prefix .
bool: Boolean data type.
cchar_t: A type that refers to a string consisting of a spacing wide character, up to 5 non-spacing wide characters, and zero or more attributes of any type. See Attributes, Color Pairs, and Renditions. A null cchar_t object terminates arrays of cchar_t objects.
chtype: An integral type whose values are formed by OR-ing an "unsigned char" with a color pair. and with zero or more attributes. The attributes acceptable are those which begin with the A_ prefix and COLOR_PAIR(3XCURSES)
SCREEN: An opaque data type associated with a terminal's display screen.
TERMINAL: An opaque data type associated with a terminal. It contains information about the terminal's capabilities (as defined by terminfo), the terminal modes, and current state of input/output operations.
wchar_t: An integral data type whose values represent wide characters.
WINDOW: An opaque data type associated with a window.

Screens, Windows, and Terminals

The X/Open Curses manual pages refer at various points to screens, windows (also subwindows, derived windows, and pads), and terminals. The following list defines each of these terms.

Screen: A screen is a terminal's physical output device. The SCREEN data type is associated with a terminal.
Window: Window objects are two-dimensional arrays of characters and their renditions. X/Open Curses provides stdscr, a default window which is the size of of the terminal screen. You can use the newwin(3XCURSES) function to create others.

To refer to a window, use a variable declared as WINDOW *. X/Open Curses includes both functions that modify stdscr, and more general versions that let you specify a window.

There are three sub-types of windows:

Subwindow: A window which has been created within another window (the parent window) and whose position has been specified with absolute screen coordinates. The derwin(3XCURSES) and subwin(3XCURSES) functions can be used to create subwindows.
Derived Window: A subwindow whose position is defined relative to the parent window's coordinates rather than in absolute terms.
Pad: A special type of window that can be larger than the screen. For more information, see the newpad(3XCURSES) man page.
Terminal: A terminal is the input and output device which character-based applications use to interact with the user. The TERMINAL data type is associated with such a device.

Attributes, Color Pairs, and Renditions

A character's rendition consists of its attributes (such as underlining or reverse video) and its color pair (the foreground and background colors). When using waddstr(3XCURSES), waddchstr(3XCURSES), wprintw(3XCURSES), winsch(3XCURSES), and so on, the window's rendition is combined with that character's renditions. The window rendition is the attributes and color set using the attroff(3XCURSES) and attr_off(3XCURSES) sets of functions. The window's background character and rendition are set with the bkgdset(3XCURSES) and bkgrndset(3XCURSES) sets of functions.

When spaces are written to the screen, the background character and window rendition replace the space. For example, if the background rendition and character is A_UNDERLINE|'*', text written to the window appears underlined and the spaces appear as underlined asterisks.

Each character written retains the rendition that it has obtained. This allows the character to be copied "as is" to or from a window with the addchstr(3XCURSES) or inch(3XCURSES) functions.

A_ Constant Values for Attributes

You can specify Attributes, Color Pairs, and Renditions attributes using the constants listed in the tables below. The following constants modify objects of type chtype:

`Constant`	`Description`
`A_ALTCHARSET`	Alternate character set
`A_ATTRIBUTES`	Bit-mask to extract attributes
`A_BLINK`	Blinking
`A_BOLD`	Bold
`A_CHARTEXT`	Bit-mask to extract a character
`A_COLOR`	Bit-mask to extract color-pair information
`A_DIM`	Half-bright
`A_INVIS`	Invisible
`A_PROTECT`	Protected
`A_REVERSE`	Reverse video
`A_STANDOUT`	Highlights specific to terminal
`A_UNDERLINE`	Underline

WA_ Constant Values for Attributes

The following constants modify objects of type attr_t:

`Constant`	`Description`
`WA_ALTCHARSET`	Alternate character set
`WA_ATTRIBUTES`	Attribute mask
`WA_BLINK`	Blinking
`WA_BOLD`	Bold
`WA_DIM`	Half-bright
`WA_HORIZONTAL`	Horizontal highlight
`WA_INVIS`	Invisible
`WA_LEFT`	Left highlist
`WA_LOW`	Low highlist
`WA_PROTECT`	Protected
`WA_REVERSE`	Reverse video
`WA_RIGHT`	Right highlight
`WA_STANDOUT`	Highlights specific to terminal
`WA_TOP`	Top highlight
`WA_UNDERLINE`	Underline
`WA_VERTICAL`	Vertical highlight

Color Macros

Colors always appear in pairs; the foreground color of the character itself and the background color of the field on which it is displayed. The following color macros are defined:

`Macro`	`Description`
`COLOR_BLACK`	Black
`COLOR_BLUE`	Blue
`COLOR_GREEN`	Green
`COLOR_CYAN`	Cyan
`COLOR_RED`	Red
`COLOR_MAGENTA`	Magenta
`COLOR_YELLOW`	Yellow
`COLOR_WHITE`	White

Together, a character's attributes and its color pair form the character's rendition. A character's rendition moves with the character during any scrolling or insert/delete operations. If your terminal lacks support for the specified rendition, X/Open Curses may substitute a different rendition.

The COLOR_PAIR(3XCURSES) function modifies a chtype object. The PAIR_NUMBER(3XCURSES) function extracts the color pair from a chtype object.

Functions for Modifying a Window's Color

The following functions modify a window's color:

`Function`	`Description`
`attr_set()`, wattr_set( )	Change the window's rendition.
`color_set()`, wcolor_set( )	Set the window's color

Non-Spacing Characters

When the wcwidth(3C) function returns a width of zero for a character, that character is called a non-spacing character. Non-spacing characters can be written to a window. Each non-spacing character is associated with a spacing character (that is, one which does not have a width of zero) and modifies that character. You cannot address a non-spacing character directly. Whenever you perform an X/Open Curses operation on the associated character, you are implicitly addressing the non-spacing character.

Non-spacing characters do not have a rendition. For functions that use wide characters and a rendition, X/Open Curses ignores any rendition specified for non-spacing characters. Multi-column characters have one rendition that applies to all columns spanned.

Complex Characters

The cchar_t date type represents a complex character. A complex character may contain a spacing character, its associated non-spacing characters, and its rendition. This implementation of complex characters supports up to 5 non-spacing characters for each spacing character.

When a cchar_t object representing a non-spacing complex character is written to the screen, its rendition is not used, but rather it becomes associated with the rendition of the existing character at that location. The setcchar(3XCURSES) function initializes an object of type cchar_t. The getcchar(3XCURSES) function extracts the contents of a cchar_t object.

Display Operations

In adding internationalization support to X/Open Curses, every attempt was made to minimize the number of changes to the historical CURSES package. This enables programs written to use the historical implementation of CURSES to use the internationalized version with little or no modification. The following rules apply to the internationalized X/Open Curses package:

The cursor can be placed anywhere in the window. Window and screen origins are (0,0).
A multi-column character cannot be displayed in the last column, because the character would appear truncated. Instead, the background character is displayed in the last column and the multi-column character appears at the beginning of the next line. This is called wrapping.

If the original line is the last line in the scroll region and scrolling is enabled, X/Open Curses moves the contents of each line in the region to the previous line. The first line of the region is lost. The last line of the scrolling region contains any wrapped characters. The remainder of that line is filled with the background character. If scrolling is disabled, X/Open Curses truncates any character that would extend past the last column of the screen.
Overwrites operate on screen columns. If displaying a single-column or multi-column character results in overwriting only a portion of a multi-column character or characters, background characters are displayed in place of the non-overwritten portions.
Insertions and deletions operate on whole characters. The cursor is moved to the first column of the character prior to performing the operation.

Overlapping Windows

When windows overlap, it may be necessary to overwrite only part of a multi-column character. As mentioned earlier, the non-overwritten portions are replaced with the background character. This results in issues concerning the overwrite(3XCURSES), overlay(3XCURSES), copywin(3XCURSES), wnoutrefresh(3XCURSES), and wrefresh(3XCURSES) functions.

Special Characters

Some functions assign special meanings to certain special characters:

Backspace

Moves the cursor one column towards the beginning of the line. If the cursor was already at the beginning of the line, it remains there. All subsequent characters are added or inserted at this point.

Carriage Return

Moves the cursor to the beginning of the current line. If the cursor was already at the beginning of the line, it remains there. All subsequent characters are added or inserted at this point.

Newline

When adding characters, X/Open Curses fills the remainder of the line with the background character (effectively truncating the newline) and scrolls the window as described earlier. All subsequent characters are inserted at the start of the new line.

When inserting characters, X/Open Curses fills the remainder of the line with the background character (effectively truncating the line), moves the cursor to the beginning of a new line, and scrolls the window as described earlier. All subsequent characters are placed at the start of the new line.

Tab

moves subsequent characters to next horizontal tab strop. Default tab stops are set at 0, 8, 16, and so on.

When adding or inserting characters, X/Open Curses inserts or adds the background character into each column until the next tab stop is reached. If there are no remaining tab stops on the current line, wrapping and scrolling occur as described earlier.

Control Characters

When X/Open Curses functions perform special character processing, they convert control characters to the ‸X notation, where X is a single-column character (uppercase, if it is a letter) and writes that notation to the window. Functions that retrieve text from the window will retrieve the converted notation not the original.

X/Open Curses displays non-printable bytes, that have their high bit set, using the M-X meta notation where X is the non-printable byte with its high bit turned off.

Input Processing

There are four input modes possible with X/Open Curses that affect the behavior of input functions like getch(3XCURSES) and getnstr(3XCURSES).

Line Canonical (Cooked)

In line input mode, the terminal driver handles the input of line units as well as SIGERASE and SIGKILL character processing. See termio(7I) for more information.

In this mode, the getch() and getnstr() functions will not return until a complete line has been read by the terminal driver, at which point only the requested number of bytes/characters are returned. The rest of the line unit remains unread until subsequent call to the getch() or getnstr() functions.

The functions nocbreak(3XCURSES) and noraw(3XCURSES) are used to enter this mode. These functions are described on the cbreak(3XCURSES) man page which also details which termios flags are enabled.

Of the modes available, this one gives applications the least amount of control over input. However, it is the only input mode possible on a block mode terminal.

cbreak Mode

Byte/character input provides a finer degree of control. The terminal driver passes each byte read to the application without interpreting erase and kill characters. It is the application's responsibility to handle line editing. It is unknown whether the signal characters (SIGINTR, SIGQUIT, SIGSUSP) and flow control characters (SIGSTART, SIGSTOP) are enabled. To ensure that they are, call the noraw() function first, then call the cbreak() function.

halfdelay Mode

This is the same as the cbreak() mode with a timeout. The terminal driver waits for a byte to be received or for a timer to expire, in which case the getch() function either returns a byte or ERR respectively. This mode overrides timeouts set for an individual window with the wtimeout() function.

raw Mode

This mode provides byte/character input with the most control for an application. It is similar to cbreak() mode, but also disables signal character processing (SIGINTR, SIGSUSP, SIGQUIT) and flow control processing (SIGSTART, SIGSTOP) so that the application can process them as it wants.

These modes affect all X/Open Curses input. The default input mode is inherited from the parent process when the application starts up.

A timeout similar to halfdelay(3XCURSES) can be applied to individual windows (see timeout(3XCURSES)). The nodelay(3XCURSES) function is equivalent to setting wtimeout(3XCURSES) for a window with a zero timeout (non-blocking) or infinite delay (blocking).

To handle function keys, keypad(3XCURSES) must be enabled. When it is enabled, the getch() function returns a KEY_ constant for a uniquely encoded key defined for that terminal. When keypad() is disabled, the getch() function returns the individual bytes composing the function key (see getch(3XCURSES) and wget_wch(3XCURSES)). By default, keypad() is disabled.

When processing function keys, once the first byte is recognized, a timer is set for each subsequent byte in the sequence. If any byte in the function key sequence is not received before the timer expires, the bytes already received are pushed into a buffer and the original first byte is returned. Subsequent X/Open Curses input would take bytes from the buffer until exhausted, after which new input from the terminal will be requested. Enabling and disabling of the function key interbyte timer is handled by the notimeout(3XCURSES) function. By default, notimeout() is disabled (that is, the timer is used).

X/Open Curses always disables the terminal driver's echo processing. The echo(3XCURSES) and noecho(3XCURSES) functions control X/Open Curses software echoing. When software echoing is enabled, X/Open Curses input functions echo printable characters, control keys, and meta keys in the input window at the last cursor position. Functions keys are never echoed. When software echoing is disabled, it is the application's responsibility to handle echoing.

EXAMPLES

Example 1 Copying Single-Column Characters Over Single-Column Characters

In the upcoming examples, some characters have special meanings:

{, [, and ( represent the left halves of multi-column characters. }, ], and ) represent the corresponding right halves of the same multi-column characters.
Alphanumeric characters and periods (.) represent single-column characters.
The number sign (#) represents the background character.

copywin(s, t, 0, 1, 0, 1, 1, 3, 0)

            s               t         ->     t
        abcdef        ......          .bcd..
        ghijkl        ......          .hij..

There are no special problems with this situation.

Example 2 Copying Multi-column Characters Over Single-Column Characters

copywin(s, t, 0, 1, 0, 1, 1, 3, 0)

            s               t         ->     t
        a[]def        ......          .[]d..
        gh()kl        ......          .h()..

Example 3 Copying Single-Column Characters From Source Overlaps Multi-column Characters In Target

copywin(s, t, 0, 1, 0, 1, 1, 3, 0)

            s               t         ->     t
        abcdef        []....          #bcd..
        ghijk tol        ...().          .hij#.

Overwriting multi-column characters in t has resulted in the # background characters being required to erase the remaining halves of the target's multi-column characters.

Example 4 Copy Incomplete Multi-column Characters From Source To Target.

copywin(s, t, 0, 1, 0, 1, 1, 3, 0)

            s               t         ->     t
        []cdef        123456          []cd56
        ghi()l        789012          7hi()2

The ] and ( halves of the multi-column characters have been copied from the source and expanded in the target outside of the specified target region.

Consider a pop-up dialog box that contains single-column characters and a base window that contains multi-column characters and you do the following:

save=dupwin(dialog);     /* create backing store */ 
overwrite(cursor, save); /* save region to be overlayed */ 
wrefresh(dialog);        /* display dialog */ 
wrefresh(save);          /* restore screen image */ 
delwin(save);            /* release backing store */

popup()

popdown()

However, with multi-column characters, the overwrite() function might save a region with incomplete multi-column characters. The wrefresh(dialog) statement results in the behavior described in example 3 above. The behavior described in this example (that is, example 4) allows the wrefresh(save) statement to restore the window correctly.

Example 5 Copying An Incomplete Multi-column Character To Region Next To Screen Margin (Not A Window Edge)

Two cases of copying an incomplete multi-column character to a region next to a screen margin follow:

copywin(s, t, 0, 1, 0, 0, 1, 2, 0)

            s               t         ->     t
        []cdef        123456          #cd456
        ghijkl        789012          hij012

#

]

copywin(s, t, 0, 1, 0, 3, 1, 5, 0)

            s               t         ->     t
        abcdef        123456          123bcd
        ghi()l        789012          789hi#

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Standard
MT-Level	Unsafe