by Eric S. Raymond and Zeyd M. Ben-Halim
+updates since release 1.9.9e by Thomas Dickey
ncurses under xterm
curses. It is
+This document is an introduction to programming with curses. It is
not an exhaustive reference for the curses Application Programming Interface
(API); that role is filled by the curses manual pages. Rather, it
is intended to help C programmers ease into using the package.
@@ -148,7 +149,7 @@ This document is aimed at C applications programmers not yet specifically
familiar with ncurses. If you are already an experienced curses
programmer, you should nevertheless read the sections on
Mouse Interfacing, Debugging,
-Compatibility with Older Versions,
+Compatibility with Older Versions,
and Hints, Tips, and Tricks. These will bring you up
to speed on the special features and quirks of the ncurses
implementation. If you are not so experienced, keep reading.
@@ -189,7 +190,7 @@ more capabilities, going far beyond BSD curses in power and flexibility.
ncurses, a freeware implementation of
+This document describes ncurses, a free implementation of
the System V curses API with some clearly marked extensions.
It includes the following System V curses features:
The ncurses package was originated by Pavel Curtis. The original
-maintainer of the package is
+maintainer of this package is
Zeyd Ben-Halim
<zmbenhal@netcom.com>.
-Eric S. Raymond
+Eric S. Raymond
<esr@snark.thyrsus.com>
-wrote many of the new features in versions after 1.8.1
+wrote many of the new features in versions after 1.8.1
and wrote most of this introduction.
-Jürgen Pfeifer
-wrote all of the menu and forms code as well as the
+Jürgen Pfeifer
+wrote all of the menu and forms code as well as the
Ada95 binding.
Ongoing work is being done by
Thomas Dickey
and
-Jürgen Pfeifer.
+Jürgen Pfeifer.
Florian La Roche
acts as the maintainer for the Free Software Foundation, which holds the
copyright on ncurses.
@@ -234,7 +235,7 @@ Contact the current maintainers at
bug-ncurses@gnu.org.
-This document also describes the panels extension library, +This document also describes the panels extension library, similarly modeled on the SVr4 panels facility. This library allows you to associate backing store with each of a stack or deck of overlapping windows, and provides operations for moving windows around in the stack that change @@ -253,17 +254,17 @@ consistency:
stdscr, is automatically provided for the programmer.
curses.h also introduces some #define constants and types
of general usefulness:
-bool
bool doneit;)
TRUE
@@ -587,21 +588,30 @@ is itself a compile-time constant and can be used in initializers.
ncurses library also provides a mouse interface. Note:
-his facility is original to ncurses, it is not part of either
+The ncurses library also provides a mouse interface.
+
++NOTE: this facility is specific to+ +Presently, mouse event reporting works in the following environments: +ncurses, it is not part of either the XSI Curses standard, nor of System V Release 4, nor BSD curses. +System V Release 4 curses contains code with similar interface definitions, +however it is not documented. Other than by disassembling the library, we +have no way to determine exactly how that mouse code works. Thus, we recommend that you wrap mouse-related code in an #ifdef using the feature macro NCURSES_MOUSE_VERSION so it will not be compiled and linked -on non-ncurses systems.- -Presently, mouse event reporting works only under xterm. In the -future, ncurses will detect the presence of
gpm(1), Alessandro -Rubini's freeware mouse server for Linux systems, and accept mouse -reports through it.- +on non-ncurses systems. +
gpm(1), Alessandro
+Rubini's mouse server.
+
The mouse interface is very simple. To activate it, you use the function
mousemask(), passing it as first argument a bit-mask that specifies
-what kinds of events you want your program to be able to see. It will
+what kinds of events you want your program to be able to see. It will
return the bit-mask of events that actually become visible, which may differ
from the argument if the mouse device is not capable of reporting some of
the event types you specify.
@@ -616,13 +626,13 @@ in and make the first one inaccessible).
Each call to getmouse() fills a structure (the address of which you'll
pass it) with mouse event data. The event data includes zero-origin,
screen-relative character-cell coordinates of the mouse pointer. It also
-includes an event mask. Bits in this mask will be set, corresponding
+includes an event mask. Bits in this mask will be set, corresponding
to the event type being reported.
The mouse structure contains two additional fields which may be significant in the future as ncurses interfaces to new kinds of pointing device. In addition to x and y coordinates, there is a slot -for a z coordinate; this might be useful with touch-screens that can +for a z coordinate; this might be useful with touch-screens that can return a pressure or duration parameter. There is also a device ID field, which could be used to distinguish between multiple pointing devices.
@@ -766,7 +776,10 @@ yourself if need be.
+ +
+NOTE: These functions are not part of the standard curses API! +
trace()
@@ -780,7 +793,7 @@ in the curses.h file for details. (It is also possible to set
a trace level by assigning a trace level value to the environment variable
NCURSES_TRACE).
_tracef()
-printf(), only it outputs a newline after the end of arguments.
@@ -811,8 +824,8 @@ some control bits set before you started your application. Also, they
have always been poorly documented, and are likely to hurt your
application's usability with other curses libraries.
-Bear in mind that refresh() is a synonym for wrefresh(stdscr),
-and don't try to mix use of stdscr with use of windows declared
+Bear in mind that refresh() is a synonym for wrefresh(stdscr).
+Don't try to mix use of stdscr with use of windows declared
by newwin(); a refresh() call will blow them off the
screen. The right way to handle this is to use subwin(), or
not touch stdscr at all and tile your screen with declared
@@ -826,7 +839,7 @@ curses support for overlapping windows has been weak, fragile, and poorly
documented. The ncurses library is not yet an exception to this
rule.
-There is a freeware panels library included in the ncurses
+There is a panels library included in the ncurses
distribution that does a pretty good job of strengthening the
overlapping-windows facilities.
@@ -835,7 +848,7 @@ Try to avoid using the global variables LINES and COLS. Use your code may be ported to run in an environment with window resizes, in which case several screens could be open with different sizes.
-
ncurses Modencurses Under xtermncurses library does not catch this signal, because it cannot in
-general know how you want the screen re-painted. You will have to write the
-SIGWINCH handler yourself.
+The ncurses library provides an experimental signal
+handler, but in general does not catch this signal, because it cannot
+know how you want the screen re-painted. You will usually have to write the
+SIGWINCH handler yourself. Ncurses can give you some help.
The easiest way to code your SIGWINCH handler is to have it do an
endwin, followed by an refresh and a screen repaint you code
yourself. The refresh will pick up the new screen size from the
-xterm's environment.
+xterm's environment.
+
+That is the standard way, of course (it even works with some vendor's curses
+implementations).
+Its drawback is that it clears the screen to reinitialize the display, and does
+not resize subwindows which must be shrunk.
+Ncurses provides an extension which works better, the
+resizeterm function. That function ensures that all windows
+are limited to the new screen dimensions, and pads stdscr
+with blanks if the screen is larger.
+
+Finally, ncurses can be configured to provide its own SIGWINCH handler,
+based on resizeterm.
immedok() option! -
ncurseswresize() function allows you to resize a window in place.
+The associated resizeterm() function simplifies the construction
+of SIGWINCH handlers, for resizing all windows.
+
+The define_key() function allows you
+to define at runtime function-key control sequences which are not in the
+terminal description.
+The keyok() function allows you to temporarily
+enable or disable interpretation of any function-key control sequence.
-When running on PC-clones, ncurses has enhanced support for
-the IBM high-half and ROM characters. The A_ALTCHARSET highlight,
-enables display of both high-half ACS graphics and the PC ROM graphics
-0-31 that are normally interpreted as control characters.
+The use_default_colors() function allows you to construct
+applications which can use the terminal's default foreground and
+background colors as an additional "default" color.
+Several terminal emulators support this feature, which is based on ISO 6429.
-The wresize() function allows you to resize a window in place.
+Ncurses supports up 16 colors, unlike SVr4 curses which defines only 8. +While most terminals which provide color allow only 8 colors, about +a quarter (including XFree86 xterm) support 16 colors.
What happens to the overlapping region depends on what wnoutrefresh()
does with its argument -- what portions of the argument window it copies to the
virtual screen. Some implementations do "change copy", copying down only
-locations in the window that have changed (or been marked changed with
+locations in the window that have changed (or been marked changed with
wtouchln() and friends). Some implementations do "entire copy",
copying all window locations to the virtual screen whether or not
they have changed.
@@ -978,7 +1016,7 @@ all your updates.
ncurses (1.8.7 or
+If you have been using a very old versions of ncurses (1.8.7 or
older) you may be surprised by the behavior of the erase functions. In older
versions, erased areas of a window were filled with a blank modified by the
window's current attribute (as set by wattrset(), wattron(),
@@ -994,7 +1032,7 @@ the XSI Curses standard.
ncurses library is intended to be base-level conformant with the
-XSI Curses standard from X/Open. Many extended-level features (in fact, almost
+XSI Curses standard from X/Open. Many extended-level features (in fact, almost
all features not directly concerned with wide characters and
internationalization) are also supported. @@ -1021,7 +1059,7 @@ visibility stack or pop to the top at runtime, the resulting book-keeping can be tedious and difficult to get right. Hence the panels library.
The panel library first appeared in AT&T System V. The
-version documented here is the freeware panel code distributed
+version documented here is the panel code distributed
with ncurses.
The menu library first appeared in AT&T System V. The
-version documented here is the freeware menu code distributed
+version documented here is the menu code distributed
with ncurses.
From a single-valued menu you can read the selected value simply by looking
at the current item. From a multi-valued menu, you get the selected set
-by looping through the items applying the item_value()
+by looping through the items applying the item_value()
predicate function. Your menu-processing code can use the function
set_item_value() to flag the items in the select set.
@@ -1218,9 +1256,9 @@ to display menu items. You can retrieve any format associated with a
menu with menu_format(). The default format is rows=16,
columns=1.
-The actual menu page may be smaller than the format size. This depends
+The actual menu page may be smaller than the format size. This depends
on the item number and size and whether O_ROWMAJOR is on. This option
-(on by default) causes menu items to be displayed in a `raster-scan'
+(on by default) causes menu items to be displayed in a `raster-scan'
pattern, so that if more than one item will fit horizontally the first
couple of items are side-by-side in the top row. The alternative is
column-major display, which tries to put the first several items in
@@ -1235,7 +1273,7 @@ Each menu has a mark string used to visually tag selected items;
see the menu_mark(3x) manual page for details. The mark
string length also influences the menu page size.
-The function scale_menu() returns the minimum display size
+The function scale_menu() returns the minimum display size
that the menu code computes from all these factors.
There are other menu display attributes including a select attribute,
@@ -1283,7 +1321,7 @@ partially displayed.
There are explicit requests for scrolling which also change the
current item (because the select location does not change, but the
-item there does). These are REQ_SCR_DLINE,
+item there does). These are REQ_SCR_DLINE,
REQ_SCR_ULINE, REQ_SCR_DPAGE, and
REQ_SCR_UPAGE.
@@ -1303,7 +1341,7 @@ Some requests change the pattern buffer directly:
REQ_CLEAR_PATTERN, REQ_BACK_PATTERN,
REQ_NEXT_MATCH, REQ_PREV_MATCH. The latter
two are useful when pattern buffer input matches more than one item
-in a multi-valued menu.
+in a multi-valued menu.
Each successful scroll or item navigation request clears the pattern
buffer. It is also possible to set the pattern buffer explicitly
@@ -1342,7 +1380,7 @@ The form library is a curses extension that supports easy
programming of on-screen forms for data entry and program control.
The form library first appeared in AT&T System V. The
-version documented here is the freeware form code distributed
+version documented here is the form code distributed
with ncurses.
curses
Fields may have validation conditions on them, so that they check input
-data for type and value. The form library supplies a rich set of
+data for type and value. The form library supplies a rich set of
pre-defined field types, and makes it relatively easy to define new ones. Once its transaction is completed (or aborted), a form may be @@ -1407,7 +1445,7 @@ designed to resemble that of the menu library wherever possible.
In forms programs, however, the `process user requests' is somewhat more -complicated than for menus. Besides menu-like navigation operations, +complicated than for menus. Besides menu-like navigation operations, the menu driver loop has to support field editing and data validation.
The basic function for creating fields is new_field():
-FIELD *new_field(int height, int width, /* new field size */
+FIELD *new_field(int height, int width, /* new field size */
int top, int left, /* upper left corner */
int offscreen, /* number of offscreen rows */
int nbuf); /* number of working buffers */
@@ -1434,8 +1472,8 @@ need not be stdscr if you've done an explicit
set_form_window() call.
The fifth argument allows you to specify a number of off-screen rows. If
-this is zero, the entire field will always be displayed. If it is
-nonzero, the form will be scrollable, with only one screen-full (initially
+this is zero, the entire field will always be displayed. If it is
+nonzero, the form will be scrollable, with only one screen-full (initially
the top part) displayed at any given time. If you make a field dynamic
and grow it so it will no longer fit on the screen, the form will become
scrollable even if the offscreen argument was initially zero.
@@ -1519,19 +1557,19 @@ You can retrieve field sizes and locations through:
int field_info(FIELD *field, /* field from which to fetch */
- int *height, *int width, /* field size */
+ int *height, *int width, /* field size */
int *top, int *left, /* upper left corner */
int *offscreen, /* number of offscreen rows */
int *nbuf); /* number of working buffers */
-This function is a sort of inverse of new_field(); instead of
+This function is a sort of inverse of new_field(); instead of
setting size and location attributes of a new field, it fetches them
from an existing one.
Changing the Field Location
-If is possible to move a field's location on the screen:
+It is possible to move a field's location on the screen:
int move_field(FIELD *field, /* field to alter */
@@ -1569,22 +1607,22 @@ in the field buffer.
int set_field_fore(FIELD *field, /* field to alter */
- chtype attr); /* attribute to set */
+ chtype attr); /* attribute to set */
chtype field_fore(FIELD *field); /* field to query */
int set_field_back(FIELD *field, /* field to alter */
- chtype attr); /* attribute to set */
+ chtype attr); /* attribute to set */
chtype field_back(FIELD *field); /* field to query */
int set_field_pad(FIELD *field, /* field to alter */
- int pad); /* pad character to set */
+ int pad); /* pad character to set */
chtype field_pad(FIELD *field);
int set_new_page(FIELD *field, /* field to alter */
- int flag); /* TRUE to force new page */
+ int flag); /* TRUE to force new page */
chtype new_page(FIELD *field); /* field to query */
@@ -1604,13 +1642,13 @@ functions:
int set_field_opts(FIELD *field, /* field to alter */
- int attr); /* attribute to set */
+ int attr); /* attribute to set */
int field_opts_on(FIELD *field, /* field to alter */
- int attr); /* attributes to turn on */
+ int attr); /* attributes to turn on */
int field_opts_off(FIELD *field, /* field to alter */
- int attr); /* attributes to turn off */
+ int attr); /* attributes to turn off */
int field_opts(FIELD *field); /* field to query */
@@ -1627,19 +1665,19 @@ visited by form navigation keys). Can be used to make labels or derived
fields with buffer values alterable by the forms application, not the user.
REQ_PREV_CHOICE and
+off, all editing requests except REQ_PREV_CHOICE and
REQ_NEXT_CHOICE will fail. Such read-only fields may be useful for
help messages.
Calling field_status() on a field not currently selected
for input will return a correct value. Calling field_status() on a
-field that is currently selected for input may not necessarily give a
+field that is currently selected for input may not necessarily give a
correct field status value, because entered data isn't necessarily copied to
buffer zero before the exit validation check.
@@ -1716,7 +1754,7 @@ char *field_userptr(FIELD *field); /* fetch mode of field */
(Properly, this user pointer field ought to have (void *) type.
The (char *) type is retained for System V compatibility.)
-It is valid to set the user pointer of the default field (with a
+It is valid to set the user pointer of the default field (with a
set_field_userptr() call passed a NULL field pointer.)
When a new field is created, the default-field user pointer is copied
to initialize the new field's user pointer.
@@ -1742,7 +1780,7 @@ it with this function:
int set_max_field(FIELD *field, /* field to alter (may not be NULL) */ - int max_size); /* upper limit on field size */ + int max_size); /* upper limit on field size */If the field is one-line,
max_size is taken to be a column size
@@ -1755,9 +1793,9 @@ The following properties of a field change when it becomes dynamic:
O_AUTOSKIP and O_NL_OVERLOAD are ignored.
-dup_field() and link_field() calls copy
+dup_field() and link_field() calls copy
dynamic-buffer sizes. If the O_STATIC option is set on one of a
collection of links, buffer resizing will occur only when the field is
edited through that link.
@@ -1770,7 +1808,7 @@ the field; use dynamic_field_info() to get the actual dynamic size.
By default, a field will accept any data that will fit in its input buffer.
However, it is possible to attach a validation type to a field. If you do
this, any attempt to leave the field while it contains data that doesn't
-match the validation type will fail. Some validation types also have a
+match the validation type will fail. Some validation types also have a
character-validity check for each time a character is entered in the field. A field's validation check (if any) is not called when @@ -1853,7 +1891,7 @@ has been entered, it is of course valid. But it is also possible to enter a prefix of a valid string and have it completed for you.
By default, if you enter such a prefix and it matches more than one value
-in the string list, the prefix will be completed to the first matching
+in the string list, the prefix will be completed to the first matching
value. But the checkunique argument, if true, requires prefix
matches to be unique in order to be valid.
@@ -1894,7 +1932,7 @@ int set_field_type(FIELD *field, /* field to alter */ Valid characters consist of an optional leading minus and digits. possibly including a decimal point. If your system supports locale's, the decimal point -character used must be the one defined by your locale. The range check is +character used must be the one defined by your locale. The range check is performed on exit. If the range maximum is less than or equal to the minimum, the range is ignored.
@@ -1947,7 +1985,7 @@ to fit.
Calling field_buffer() with a null field pointer will raise an
error. Calling field_buffer() on a field not currently selected
for input will return a correct value. Calling field_buffer() on a
-field that is currently selected for input may not necessarily give a
+field that is currently selected for input may not necessarily give a
correct field buffer value, because entered data isn't necessarily copied to
buffer zero before the exit validation check.
@@ -2049,9 +2087,9 @@ scrollable field is actually displayed within the menu subwindow. Use
these functions:
-int data_ahead(FORM *form); /* form to be queried */ +int data_ahead(FORM *form); /* form to be queried */ -int data_behind(FORM *form); /* form to be queried */ +int data_behind(FORM *form); /* form to be queried */The function
data_ahead() returns TRUE if (a) the current
@@ -2084,7 +2122,7 @@ int form_driver(FORM *form, /* form to pass input to */
Your input virtualization function needs to take input and then convert it
-to either an alphanumeric character (which is treated as data to be
+to either an alphanumeric character (which is treated as data to be
entered in the currently-selected field), or a forms processing request. The forms driver provides hooks (through input-validation and @@ -2337,7 +2375,7 @@ there are requests that can fetch that value into the field buffer:
TYPE_ENUM has built-in successor
-and predecessor functions. When you define a field type of your own
+and predecessor functions. When you define a field type of your own
(see Custom Validation Types), you can associate
our own ordering functions. @@ -2457,13 +2495,13 @@ or queried with these functions:
int set_form_opts(FORM *form, /* form to alter */ - int attr); /* attribute to set */ + int attr); /* attribute to set */ int form_opts_on(FORM *form, /* form to alter */ - int attr); /* attributes to turn on */ + int attr); /* attributes to turn on */ int form_opts_off(FORM *form, /* form to alter */ - int attr); /* attributes to turn off */ + int attr); /* attributes to turn off */ int form_opts(FORM *form); /* form to query */@@ -2500,7 +2538,7 @@ The simplest way to create a custom data type is to compose it from two preexisting ones:
-FIELD *link_fieldtype(FIELDTYPE *type1,
+FIELD *link_fieldtype(FIELDTYPE *type1,
FIELDTYPE *type2);
@@ -2620,7 +2658,7 @@ int set_fieldtype_arg(FIELDTYPE *type, /* type to alter */
The successor and predecessor arguments will each be passed two arguments;
a field pointer, and a pile pointer (as for the validation functions). They
-are expected to use the function field_buffer() to read the
+are expected to use the function field_buffer() to read the
current value, and set_field_buffer() on buffer 0 to set the next
or previous value. Either hook may return TRUE to indicate success (a
legal next or previous value was set) or FALSE to indicate failure.