Tribblix: manual page: curses.3xcurses

CURSES(3XCURSES) X/Open Curses Library Functions CURSES(3XCURSES)

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

To set environment variables using other command line interfaces or
shells, see the environ(7) manual page.

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

1. 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.

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

3. 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:

o The cursor can be placed anywhere in the window. Window
and screen origins are (0,0).

o 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.

o 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.

o 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(4I) 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:

o {, [, and ( represent the left halves of multi-column
characters. }, ], and ) represent the corresponding right
halves of the same multi-column characters.

o Alphanumeric characters and periods (.) represent single-
column characters.

o 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()..

There are no special problems with this situation.

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 */

You can use code similar to this to implement generic popup() and
popdown() routines in a variety of CURSES implementations (including
BSD UNIX, and UNIX System V). In the simple case where the base
window contains single-column characters only, it would correctly
restore the image that appeared on the screen before the dialog box
was displayed.

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

The background character (#) replaces the ] character that would have
been copied from the source, because it is not possible to expand the
multi-column character to its complete form.

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

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

This second example is the same as the first, but with the right
margin.

ATTRIBUTES