by Eric S. Raymond and Zeyd M. Ben-Halim-
updates since release 1.9.9e by Thomas Dickey
This document is an introduction to programming with
curses. It is not an exhaustive reference for the
@@ -349,7 +340,7 @@
curses will typically be a great deal simpler and
less expensive than one using an X toolkit.
Historically, the first ancestor of curses was
the routines written to provide screen-handling for the
@@ -387,7 +378,7 @@
to use more facilities and offer more capabilities, going far
beyond BSD curses in power and flexibility.
This document describes ncurses, a free
implementation of the System V curses API with some
@@ -448,7 +439,7 @@
libraries, also cloned from System V, which support easy
construction and sequences of menus and fill-in forms.
In this document, the following terminology is used with reasonable consistency:
@@ -476,21 +467,20 @@ screen. -In order to use the library, it is necessary to have certain types and variables defined. Therefore, the programmer must have a line:
-+#include <curses.h>-at the top of the program source. The screen package uses the Standard I/O library, so
-<curses.h>includes<stdio.h>.<curses.h>also @@ -502,7 +492,7 @@ your LDFLAGS or on the command line. There is no need for any other libraries.Updating the Screen
+Updating the Screen
In order to update the screen optimally, it is necessary for the routines to know what the screen currently looks like and @@ -533,8 +523,8 @@ like this,” and let the package implementation determine the most efficient way to repaint the screen.
-Standard Windows and Function - Naming Conventions
+Standard Windows and Function + Naming Conventions
As hinted above, the routines can use several windows, but two are automatically given:
-curscr, which knows what @@ -563,46 +553,41 @@ “mv” and the desired (y, x) coordinates prepended to the arguments to the function. For example, the calls+move(y, x); addch(ch);-can be replaced by
-+mvaddch(y, x, ch);-and
-+wmove(win, y, x); waddch(win, ch);-can be replaced by
-+mvwaddch(win, y, x, ch);-Note that the window description pointer (win) comes before the added (y, x) coordinates. If a function requires a window pointer, it is always the first parameter passed.
-Variables
+Variables
The
-curseslibrary sets some variables describing the terminal capabilities.+type name description ------------------------------------------------------------------ int LINES number of lines on the terminal int COLS number of columns on the terminal-The
@@ -635,7 +620,7 @@curses.halso introduces some#defineconstants and types of general usefulness:
Now we describe how to actually use the screen package. In it, we assume all updating, reading, etc. is applied to @@ -645,7 +630,7 @@
Here is a sample program to motivate the discussion:
-+#include <stdlib.h> #include <curses.h> #include <signal.h> @@ -707,8 +692,7 @@ static void finish(int sig) exit(0); }- -Starting up
+Starting up
In order to use the screen package, the routines must know about terminal characteristics, and the space for @@ -740,7 +724,7 @@ static void finish(int sig) allow you to get rid of old windows. All the options described above can be applied to any window.
-Output
+Output
Now that we have set things up, we will want to actually update the terminal. The basic functions used to change what will @@ -775,7 +759,7 @@ static void finish(int sig) implementing a command which would redraw the screen in case it get messed up.
-Input
+Input
The complementary function to
-addch()isgetch()which, if echo is set, will call @@ -804,8 +788,8 @@ static void finish(int sig)#definevalues is determined bykey_capabilities in the terminal's terminfo entry.Using Forms - Characters
+Using Forms + Characters
The
-addch()function (and some others, includingbox()andborder()) can accept some @@ -820,8 +804,8 @@ static void finish(int sig)curses.hwill map them to a recognizable (though ugly) set of ASCII defaults.Character Attributes and - Color
+Character Attributes and + Color
The
-ncursespackage supports screen highlights including standout, reverse-video, underline, and blink. It also @@ -859,7 +843,7 @@ static void finish(int sig) thatCOLOR_PAIR(N), for constant N, is itself a compile-time constant and can be used in initializers.Mouse Interfacing
+Mouse Interfacing
The
@@ -947,7 +931,7 @@ static void finish(int sig)ncurseslibrary also provides a mouse interface.See the manual page
-curs_mouse(3X)for full details of the mouse-interface functions.Finishing Up
+Finishing Up
In order to clean up after the
-ncursesroutines, the routineendwin()is provided. It restores tty @@ -956,13 +940,13 @@ static void finish(int sig) anytime after the call to initscr,endwin()should be called before exiting.Function Descriptions
+Function Descriptions
We describe the detailed behavior of some important curses functions here, as a supplement to the manual page descriptions.
-Initialization and Wrapup
+Initialization and Wrapup
initscr()
@@ -1025,7 +1009,7 @@ static void finish(int sig)
reference.
refresh() and wrefresh(win)setupterm(term, filenum, errret)
@@ -1082,7 +1066,6 @@ static void finish(int sig)
indication is returned. The values returned can be 1 (all is
well), 0 (no such terminal), or -1 (some problem locating the
terminfo database).
-
The value of term can be given as NULL, which
will cause the value of TERM in the environment
to be used. The errret pointer can also be given
@@ -1107,7 +1090,7 @@ static void finish(int sig)
NOTE: These functions are not part of the @@ -1149,14 +1132,14 @@ static void finish(int sig) be distinguished by the fact that they are named in capital letters. -Hints, Tips, and Tricks
+Hints, Tips, and Tricks
The
-ncursesmanual pages are a complete reference for this library. In the remainder of this document, we discuss various useful methods that may not be obvious from the manual page descriptions.Some Notes of Caution
+Some Notes of Caution
If you find yourself thinking you need to use
-noraw()ornocbreak(), think again and @@ -1196,8 +1179,8 @@ static void finish(int sig) with window resizes, in which case several screens could be open with different sizes.Temporarily Leaving NCURSES - Mode
+Temporarily Leaving NCURSES + Mode
Sometimes you will want to write a program that spends most of its time in screen mode, but occasionally returns to ordinary @@ -1220,7 +1203,7 @@ static void finish(int sig)
Here is some sample code for shellout:
-+addstr("Shelling out..."); def_prog_mode(); /* save current tty modes */ endwin(); /* restore original tty modes */ @@ -1228,8 +1211,7 @@ static void finish(int sig) addstr("returned.\n"); /* prepare return message */ refresh(); /* restore save modes, repaint screen */- -Using NCURSES under XTERM
+Using NCURSES under XTERM
A resize operation in X sends
-SIGWINCHto the application running under xterm. The easiest way to handle @@ -1258,8 +1240,8 @@ static void finish(int sig) special-purpose code to handleKEY_RESIZEyourself.Handling Multiple Terminal - Screens
+Handling Multiple Terminal + Screens
The
-initscr()function actually calls a function namednewterm()to do most of its work. If you are @@ -1274,8 +1256,8 @@ static void finish(int sig)def_shell_modeanddef_prog_modeon each tty yourself.Testing for Terminal - Capabilities
+Testing for Terminal + Capabilities
Sometimes you may want to write programs that test for the presence of various capabilities before deciding whether to go @@ -1292,7 +1274,7 @@ static void finish(int sig) include the
-term.hfile and test the value of the macrocursor_address.Tuning for Speed
+Tuning for Speed
Use the
-addchstr()family of functions for fast screen-painting of text when you know the text does not contain @@ -1300,8 +1282,8 @@ static void finish(int sig) on your screens. Do not use theimmedok()option!Special Features of - NCURSES
+Special Features of + NCURSES
The
-wresize()function allows you to resize a window in place. The associatedresizeterm()@@ -1325,16 +1307,16 @@ static void finish(int sig) only 8 colors, about a quarter (including XFree86 xterm) support 16 colors.Compatibility with Older - Versions
+Compatibility with Older + Versions
Despite our best efforts, there are some differences between
-ncursesand the (undocumented!) behavior of older curses implementations. These arise from ambiguities or omissions in the documentation of the API.Refresh of Overlapping - Windows
+Refresh of Overlapping + Windows
If you define two windows A and B that overlap, and then alternately scribble on and refresh them, the changes made to the @@ -1392,7 +1374,7 @@ static void finish(int sig)
-doupdate()and there will be a single burst of physical I/O that will do all your updates.Background Erase
+Background Erase
If you have been using a very old versions of
ncurses(1.8.7 or older) you may be surprised by the @@ -1409,7 +1391,7 @@ static void finish(int sig)This change in behavior conforms
-ncursesto System V Release 4 and the XSI Curses standard.XSI Curses Conformance
+XSI Curses Conformance
The
-ncurseslibrary is intended to be base-level conformant with the XSI Curses standard from X/Open. Many @@ -1426,7 +1408,7 @@ static void finish(int sig) be linked (and will be prototype-checked) if the macro definition is disabled with#undef.The Panels Library
+The Panels Library
The
-ncurseslibrary by itself provides good support for screen displays in which the windows are tiled @@ -1446,16 +1428,15 @@ static void finish(int sig) System V. The version documented here is thepanelcode distributed withncurses.Compiling With the Panels - Library
+Compiling With the Panels + Library
Your panels-using modules must import the panels library declarations with
-+#include <panel.h>-and must be linked explicitly with the panels library using an
--lpanelargument. Note that they must also link thencurseslibrary with-lncurses. Many @@ -1463,7 +1444,7 @@ static void finish(int sig) still good practice to put-lpanelfirst and-lncursessecond.Overview of Panels
+Overview of Panels
A panel object is a window that is implicitly treated as part of a deck including all other panel objects. The deck @@ -1514,8 +1495,8 @@ static void finish(int sig) you will generate a lot of unnecessary refresh activity and screen flicker.
-Panels, Input, and the - Standard Screen
+Panels, Input, and the + Standard Screen
You should not mix
wnoutrefresh()orwrefresh()operations with panels code; this will @@ -1536,7 +1517,7 @@ static void finish(int sig)There is presently no way to display changes to one obscured panel without repainting all panels.
-Hiding Panels
+Hiding Panels
It is possible to remove a panel from the deck temporarily; use
-hide_panelfor this. Use @@ -1548,7 +1529,7 @@ static void finish(int sig) cannot dotop_panel()orbottom_panelon a hidden panel(). Other panels operations are applicable.Miscellaneous Other Facilities
+Miscellaneous Other Facilities
It is possible to navigate the deck using the functions
-panel_above()andpanel_below. Handed a @@ -1561,7 +1542,7 @@ static void finish(int sig) page documentation ofset_panel_userptr()andpanel_userptrfor details.The Menu Library
+The Menu Library
A menu is a screen display that assists the user to choose some subset of a given set of items. The
-menu@@ -1572,16 +1553,15 @@ static void finish(int sig) System V. The version documented here is themenucode distributed withncurses.Compiling With the menu - Library
+Compiling With the menu + Library
Your menu-using modules must import the menu library declarations with
-+#include <menu.h>-and must be linked explicitly with the menus library using an
--lmenuargument. Note that they must also link thencurseslibrary with-lncurses. Many @@ -1589,7 +1569,7 @@ static void finish(int sig) still good practice to put-lmenufirst and-lncursessecond.Overview of Menus
+Overview of Menus
The menus created by this library consist of collections of items including a name string part and a description @@ -1633,7 +1613,7 @@ static void finish(int sig)
- Terminate
-curses.Selecting items
+Selecting items
Menus may be multi-valued or (the default) single-valued (see the manual page
-menu_opts(3x)to see how to change @@ -1654,7 +1634,7 @@ static void finish(int sig) so far defined for menus, but it is good practice to code as though other option bits might be on.Menu Display
+Menu Display
The menu library calculates a minimum display size for your window, based on the following variables:
@@ -1710,7 +1690,7 @@ static void finish(int sig) which the library allows you to change (see themenu_attribs(3x)manual page. -Menu Windows
+Menu Windows
Each menu has, as mentioned previously, a pair of associated windows. Both these windows are painted when the menu is posted @@ -1732,7 +1712,7 @@ static void finish(int sig) the screen. To do that, call
-wrefresh()or some equivalent.Processing Menu Input
+Processing Menu Input
The main loop of your menu-processing code should call
-menu_driver()repeatedly. The first argument of this @@ -1784,7 +1764,7 @@ static void finish(int sig) commands. Themenu_driver()code ignores them and returnsE_UNKNOWN_COMMAND.Miscellaneous Other Features
+Miscellaneous Other Features
Various menu options can affect the processing and visual appearance and input processing of menus. See
-menu_opts(3x) @@ -1807,7 +1787,7 @@ static void finish(int sig)mitem_userptr(3x)andmenu_userptr(3x).The Forms Library
+The Forms Library
The
-formlibrary is a curses extension that supports easy programming of on-screen forms for data entry and @@ -1817,16 +1797,15 @@ static void finish(int sig) System V. The version documented here is theformcode distributed withncurses.Compiling With the form - Library
+Compiling With the form + Library
Your form-using modules must import the form library declarations with
-+#include <form.h>-and must be linked explicitly with the forms library using an
--lformargument. Note that they must also link thencurseslibrary with-lncurses. Many @@ -1834,7 +1813,7 @@ static void finish(int sig) still good practice to put-lformfirst and-lncursessecond.Overview of Forms
+Overview of Forms
A form is a collection of fields; each field may be either a label (explanatory text) or a data-entry location. Long forms may @@ -1903,19 +1882,18 @@ static void finish(int sig) Besides menu-like navigation operations, the menu driver loop has to support field editing and data validation.
-Creating and Freeing Fields - and Forms
+Creating and Freeing Fields + and Forms
The basic function for creating fields is
-new_field():+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 */-Menu items always occupy a single row, but forms fields may have multiple rows. So
-new_field()requires you to specify a width and height (the first two arguments, which mist @@ -1943,21 +1921,19 @@ FIELD *new_field(int height, int width, /* new field size */ buffers to allocate for the field; your application can use them for its own purposes.+FIELD *dup_field(FIELD *field, /* field to copy */ int top, int left); /* location of new copy */-The function
-dup_field()duplicates an existing field at a new location. Size and buffering information are copied; some attribute flags and status bits are not (see theform_field_new(3X)for details).+FIELD *link_field(FIELD *field, /* field to copy */ int top, int left); /* location of new copy */-The function
link_field()also duplicates an existing field at a new location. The difference fromdup_field()is that it arranges for the new field's @@ -1978,10 +1954,9 @@ FIELD *link_field(FIELD *field, /* field to copy */To connect fields to a form, use
-+FORM *new_form(FIELD **fields);-This function expects to see a NULL-terminated array of field pointers. Said fields are connected to a newly-allocated form object; its address is returned (or else NULL if the allocation @@ -1999,8 +1974,8 @@ FORM *new_form(FIELD **fields); form, but not vice-versa; thus, you will generally free your form objects first.
-Fetching and Changing - Field Attributes
+Fetching and Changing + Field Attributes
Each form field has a number of location and size attributes associated with it. There are other field attributes used to @@ -2016,56 +1991,53 @@ FORM *new_form(FIELD **fields); to it persist as defaults until your forms application terminates.
-Fetching Size and Location - Data
+Fetching Size and Location + Data
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 *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 setting size and location attributes of a new field, it fetches them from an existing one.Changing the Field - Location
+Changing the Field + Location
It is possible to move a field's location on the screen:
-+int move_field(FIELD *field, /* field to alter */ int top, int left); /* new upper-left corner */-You can, of course. query the current location through
-field_info().The Justification Attribute
+The Justification Attribute
One-line fields may be unjustified, justified right, justified left, or centered. Here is how you manipulate this attribute:
-+int set_field_just(FIELD *field, /* field to alter */ int justmode); /* mode to set */ int field_just(FIELD *field); /* fetch mode of field */-The mode values accepted and returned by this functions are preprocessor macros
-NO_JUSTIFICATION,JUSTIFY_RIGHT,JUSTIFY_LEFT, orJUSTIFY_CENTER.Field Display - Attributes
+Field Display + Attributes
For each field, you can set a foreground attribute for entered characters, a background attribute for the entire field, and a @@ -2076,7 +2048,7 @@ int field_just(FIELD *field); /* fetch mode of field */ appearance of the field on the screen, without affecting in any way the data in the field buffer.
-+int set_field_fore(FIELD *field, /* field to alter */ chtype attr); /* attribute to set */ @@ -2097,20 +2069,19 @@ int set_new_page(FIELD *field, /* field to alter */ chtype new_page(FIELD *field); /* field to query */-The attributes set and returned by the first four functions are normal
-curses(3x)display attribute values (A_STANDOUT,A_BOLD,A_REVERSEetc). The page bit of a field controls whether it is displayed at the start of a new form screen.Field Option Bits
+Field Option Bits
There is also a large collection of field option bits you can set to control various aspects of forms processing. You can manipulate them with these functions:
-+int set_field_opts(FIELD *field, /* field to alter */ int attr); /* attribute to set */ @@ -2122,7 +2093,6 @@ int field_opts_off(FIELD *field, /* field to alter */ int field_opts(FIELD *field); /* field to query */-By default, all options are on. Here are the available option bits:
@@ -2209,19 +2179,18 @@ int field_opts(FIELD *field); /* field to query */The option values are bit-masks and can be composed with logical-or in the obvious way.
-Field Status
+Field Status
Every field has a status flag, which is set to FALSE when the field is created and TRUE when the value in field buffer 0 changes. This flag can be queried and set directly:
-+int set_field_status(FIELD *field, /* field to alter */ int status); /* mode to set */ int field_status(FIELD *field); /* fetch mode of field */-Setting this flag under program control can be useful if you use the same form repeatedly, looking for modified fields each time.
@@ -2238,14 +2207,14 @@ int field_status(FIELD *field); /* fetch mode of field */ just after aREQ_VALIDATIONrequest has been processed by the forms driver. -Field User Pointer
+Field User Pointer
Each field structure contains one character pointer slot that is not used by the forms library. It is intended to be used by applications to store private per-field data. You can manipulate it with:
-+int set_field_userptr(FIELD *field, /* field to alter */ char *userptr); /* mode to set */ @@ -2253,13 +2222,12 @@ 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
-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.Variable-Sized Fields
+Variable-Sized Fields
Normally, a field is fixed at the size specified for it at creation time. If, however, you turn off its O_STATIC bit, it @@ -2279,11 +2247,10 @@ System V compatibility.) But it is possible to set an upper limit on the size of a dynamic field. You do 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 */-If the field is one-line,
max_sizeis taken to be a column size limit; if it is multi-line, it is taken to be a line size limit. To disable any limit, use an argument of zero. @@ -2314,7 +2281,7 @@ int set_max_field(FIELD *field, /* field to alter (may not be NULL) */ 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 @@ -2332,14 +2299,13 @@ int set_max_field(FIELD *field, /* field to alter (may not be NULL) */ define custom ones of your own. You can examine and change field validation attributes with the following functions:
-+int set_field_type(FIELD *field, /* field to alter */ FIELDTYPE *ftype, /* type to associate */ ...); /* additional arguments*/ FIELDTYPE *field_type(FIELD *field); /* field to query */-The validation type of a field is considered an attribute of the field. As with other field attributes, Also, doing
set_field_type()with aNULLfield @@ -2348,56 +2314,53 @@ FIELDTYPE *field_type(FIELD *field); /* field to query */Here are the pre-defined validation types:
-TYPE_ALPHA
+TYPE_ALPHA
This field type accepts alphabetic data; no blanks, no digits, no special characters (this is checked at character-entry time). It is set up with:
-+int set_field_type(FIELD *field, /* field to alter */ TYPE_ALPHA, /* type to associate */ int width); /* maximum width of field */-The
-widthargument sets a minimum width of data. Typically you will want to set this to the field width; if it is greater than the field width, the validation check will always fail. A minimum width of zero makes field completion optional.TYPE_ALNUM
+TYPE_ALNUM
This field type accepts alphabetic data and digits; no blanks, no special characters (this is checked at character-entry time). It is set up with:
-+int set_field_type(FIELD *field, /* field to alter */ TYPE_ALNUM, /* type to associate */ int width); /* maximum width of field */-The
-widthargument sets a minimum width of data. As with TYPE_ALPHA, typically you will want to set this to the field width; if it is greater than the field width, the validation check will always fail. A minimum width of zero makes field completion optional.TYPE_ENUM
+TYPE_ENUM
This type allows you to restrict a field's values to be among a specified set of string values (for example, the two-letter postal codes for U.S. states). It is set up with:
-+int set_field_type(FIELD *field, /* field to alter */ TYPE_ENUM, /* type to associate */ char **valuelist; /* list of possible values */ int checkcase; /* case-sensitive? */ int checkunique); /* must specify uniquely? */-The
-valuelistparameter must point at a NULL-terminated list of valid strings. Thecheckcaseargument, if true, makes comparison with the string @@ -2419,18 +2382,17 @@ int set_field_type(FIELD *field, /* field to alter */REQ_PREV_CHOICEinput requests can be particularly useful with these fields.TYPE_INTEGER
+TYPE_INTEGER
This field type accepts an integer. It is set up as follows:
-+int set_field_type(FIELD *field, /* field to alter */ TYPE_INTEGER, /* type to associate */ int padding, /* # places to zero-pad to */ int vmin, int vmax); /* valid range */-Valid characters consist of an optional leading minus and digits. The range check is performed on exit. If the range maximum is less than or equal to the minimum, the range is @@ -2443,18 +2405,17 @@ int set_field_type(FIELD *field, /* field to alter */
A
-TYPE_INTEGERvalue buffer can conveniently be interpreted with the C library functionatoi(3).TYPE_NUMERIC
+TYPE_NUMERIC
This field type accepts a decimal number. It is set up as follows:
-+int set_field_type(FIELD *field, /* field to alter */ TYPE_NUMERIC, /* type to associate */ int padding, /* # places of precision */ double vmin, double vmax); /* valid range */-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 @@ -2469,44 +2430,41 @@ int set_field_type(FIELD *field, /* field to alter */
A
-TYPE_NUMERICvalue buffer can conveniently be interpreted with the C library functionatof(3).TYPE_REGEXP
+TYPE_REGEXP
This field type accepts data matching a regular expression. It is set up as follows:
-+int set_field_type(FIELD *field, /* field to alter */ TYPE_REGEXP, /* type to associate */ char *regexp); /* expression to match */-The syntax for regular expressions is that of
-regcomp(3). The check for regular-expression match is performed on exit.Direct Field Buffer - Manipulation
+Direct Field Buffer + Manipulation
The chief attribute of a field is its buffer contents. When a form has been completed, your application usually needs to know the state of each field buffer. You can find this out with:
-+char *field_buffer(FIELD *field, /* field to query */ int bufindex); /* number of buffer to query */-Normally, the state of the zero-numbered buffer for each field is set by the user's editing actions on that field. It is sometimes useful to be able to set the value of the zero-numbered (or some other) buffer from your application:
-+int set_field_buffer(FIELD *field, /* field to alter */ int bufindex, /* number of buffer to alter */ char *value); /* string value to set */-If the field is not large enough and cannot be resized to a sufficiently large size to contain the specified value, the value will be truncated to fit.
@@ -2525,7 +2483,7 @@ int set_field_buffer(FIELD *field, /* field to alter */REQ_VALIDATIONrequest has been processed by the forms driver. -Attributes of Forms
+Attributes of Forms
As with field attributes, form attributes inherit a default from a system default form structure. These defaults can be @@ -2535,7 +2493,7 @@ int set_field_buffer(FIELD *field, /* field to alter */
The principal attribute of a form is its field list. You can query and change this list with:
-+int set_form_fields(FORM *form, /* form to alter */ FIELD **fields); /* fields to connect */ @@ -2543,7 +2501,6 @@ char *form_fields(FORM *form); /* fetch fields of form */ int field_count(FORM *form); /* count connect fields */-The second argument of
-set_form_fields()may be a NULL-terminated field pointer array like the one required bynew_form(). In that case, the old fields of the form @@ -2557,7 +2514,7 @@ int field_count(FORM *form); /* count connect fields */ number of fields connected to a given from. It returns -1 if the form-pointer argument is NULL.Control of Form Display
+Control of Form Display
In the overview section, you saw that to display a form you normally start by defining its size (and fields), posting it, and @@ -2589,17 +2546,16 @@ int field_count(FORM *form); /* count connect fields */ need to know the size of the form's bounding rectangle. You can get this information with:
-+int scale_form(FORM *form, /* form to query */ int *rows, /* form rows */ int *cols); /* form cols */-The form dimensions are passed back in the locations pointed to by the arguments. Once you have this information, you can use it to declare of windows, then use one of these functions:
-+int set_form_win(FORM *form, /* form to alter */ WINDOW *win); /* frame window to connect */ @@ -2610,7 +2566,6 @@ int set_form_sub(FORM *form, /* form to alter */ WINDOW *form_sub(FORM *form); /* fetch form subwindow of form */-Note that curses operations, including
@@ -2619,12 +2574,11 @@ WINDOW *form_sub(FORM *form); /* fetch form subwindow of form */ scrollable field is actually displayed within the menu subwindow. Use these functions: -refresh(), on the form, should be done on the frame window, not the form subwindow.+int data_ahead(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 field is one-line and has undisplayed data off to the right, (b) the current field is multi-line and there is data @@ -2637,27 +2591,25 @@ int data_behind(FORM *form); /* form to be queried */Finally, there is a function to restore the form window's cursor to the value expected by the forms driver:
-+int pos_form_cursor(FORM *) /* form to be queried */-If your application changes the form window cursor, call this function before handing control back to the forms driver in order to re-synchronize it.
-Input Processing in the Forms - Driver
+Input Processing in the Forms + Driver
The function
-form_driver()handles virtualized input requests for form navigation, editing, and validation requests, just asmenu_driverdoes for menus (see the section on menu input handling).+int form_driver(FORM *form, /* form to pass input to */ int request); /* form request code */-Your input virtualization function needs to take input and then convert it to either an alphanumeric character (which is treated as data to be entered in the currently-selected field), @@ -2668,7 +2620,7 @@ int form_driver(FORM *form, /* form to pass input to */ check that the input taken by the driver matched what was expected.
-Page Navigation Requests
+Page Navigation Requests
These requests cause page-level moves through the form, triggering display of a new form screen.
@@ -2700,8 +2652,8 @@ int form_driver(FORM *form, /* form to pass input to */ andREQ_PREV_PAGEfrom the first page goes to the last. -Inter-Field Navigation - Requests
+Inter-Field Navigation + Requests
These requests handle navigation between fields on the same page.
@@ -2794,8 +2746,8 @@ int form_driver(FORM *form, /* form to pass input to */ from A will go to B only if A, B, and C all share the same first line; otherwise it will skip over B to C. -Intra-Field Navigation - Requests
+Intra-Field Navigation + Requests
These requests drive movement of the edit cursor within the currently selected field.
@@ -2877,7 +2829,7 @@ int form_driver(FORM *form, /* form to pass input to */ end of line or field look for the first or last non-pad character in their ranges. -Scrolling Requests
+Scrolling Requests
Fields that are dynamic and have grown and fields explicitly created with offscreen rows are scrollable. One-line fields @@ -2952,7 +2904,7 @@ int form_driver(FORM *form, /* form to pass input to */
For scrolling purposes, a page of a field is the height of its visible part.
-Editing Requests
+Editing Requests
When you pass the forms driver an ASCII character, it is treated as a request to add the character to the field's data @@ -3068,7 +3020,7 @@ int form_driver(FORM *form, /* form to pass input to */
See Form Options for discussion of how to set and clear the overload options.
-Order Requests
+Order Requests
If the type of your field is ordered, and has associated functions for getting the next and previous values of the type @@ -3094,7 +3046,7 @@ int form_driver(FORM *form, /* form to pass input to */ field type of your own (see Custom Validation Types), you can associate our own ordering functions.
-Application Commands
+Application Commands
Form requests are represented as integers above the
-cursesvalue greater thanKEY_MAXand @@ -3102,13 +3054,13 @@ int form_driver(FORM *form, /* form to pass input to */ your input-virtualization routine returns a value aboveMAX_COMMAND, the forms driver will ignore it.Field Change Hooks
+Field Change Hooks
It is possible to set function hooks to be executed whenever the current field or form changes. Here are the functions that support this:
-+typedef void (*HOOK)(); /* pointer to function returning void */ int set_form_init(FORM *form, /* form to alter */ @@ -3131,7 +3083,6 @@ int set_field_term(FORM *form, /* form to alter */ HOOK field_term(FORM *form); /* form to query */-These functions allow you to either set or query four different hooks. In each of the set functions, the second argument should be the address of a hook function. These @@ -3182,7 +3133,7 @@ HOOK field_term(FORM *form); /* form to query */
You can disable any of these hooks by (re)setting them to NULL, the default value.
-Field Change Commands
+Field Change Commands
Normally, navigation through the form will be driven by the user's input requests. But sometimes it is useful to be able to @@ -3190,7 +3141,7 @@ HOOK field_term(FORM *form); /* form to query */ application, or ask which field it currently is in. The following functions help you accomplish this:
-+int set_current_field(FORM *form, /* form to alter */ FIELD *field); /* field to shift to */ @@ -3199,7 +3150,6 @@ FIELD *current_field(FORM *form); /* form to query */ int field_index(FORM *form, /* form to query */ FIELD *field); /* field to get index of */-The function
field_index()returns the index of the given field in the given form's field array (the array passed tonew_form()or @@ -3211,22 +3161,21 @@ int field_index(FORM *form, /* form to query */It is also possible to move around by pages.
-+int set_form_page(FORM *form, /* form to alter */ int page); /* page to go to (0-origin) */ int form_page(FORM *form); /* return form's current page */-The initial page of a newly-created form is 0. The function
-set_form_fields()resets this.Form Options
+Form Options
Like fields, forms may have control option bits. They can be changed or queried with these functions:
-+int set_form_opts(FORM *form, /* form to alter */ int attr); /* attribute to set */ @@ -3238,7 +3187,6 @@ int form_opts_off(FORM *form, /* form to alter */ int form_opts(FORM *form); /* form to query */-By default, all options are on. Here are the available option bits:
@@ -3261,7 +3209,7 @@ int form_opts(FORM *form); /* form to query */The option values are bit-masks and can be composed with logical-or in the obvious way.
-Custom Validation Types
+Custom Validation Types
The
-formlibrary gives you the capability to define custom validation types of your own. Further, the optional @@ -3271,16 +3219,15 @@ int form_opts(FORM *form); /* form to query */ the handling of the additional arguments within custom validation functions.Union Types
+Union Types
The simplest way to create a custom data type is to compose it from two preexisting ones:
-+FIELD *link_fieldtype(FIELDTYPE *type1, FIELDTYPE *type2);-This function creates a field type that will accept any of the values legal for either of its argument field types (which may be either predefined or programmer-defined). If a @@ -3292,7 +3239,7 @@ FIELD *link_fieldtype(FIELDTYPE *type1, function for the first type, then for the second, to figure what type the buffer contents should be treated as.
-New Field Types
+New Field Types
To create a field type from scratch, you need to specify one or both of the following things:
@@ -3307,7 +3254,7 @@ FIELD *link_fieldtype(FIELDTYPE *type1,Here is how you do that:
-+typedef int (*HOOK)(); /* pointer to function returning int */ FIELDTYPE *new_fieldtype(HOOK f_validate, /* field validator */ @@ -3315,7 +3262,6 @@ FIELDTYPE *new_fieldtype(HOOK f_validate, /* field validator */ int free_fieldtype(FIELDTYPE *ftype); /* type to free */-At least one of the arguments of
-new_fieldtype()must be non-NULL. The forms driver will automatically call the new type's validation functions at appropriate points in @@ -3334,8 +3280,8 @@ int free_fieldtype(FIELDTYPE *ftype); /* type to free */ argument. It too should return TRUE if the character is valid, FALSE otherwise.Validation Function - Arguments
+Validation Function + Arguments
Your field- and character- validation functions will be passed a second argument as well. This second argument is the address of @@ -3353,7 +3299,7 @@ int free_fieldtype(FIELDTYPE *ftype); /* type to free */
Here is how you make the association:
-+typedef char *(*PTRHOOK)(); /* pointer to function returning (char *) */ typedef void (*VOIDHOOK)(); /* pointer to function returning void */ @@ -3362,7 +3308,6 @@ int set_fieldtype_arg(FIELDTYPE *type, /* type to alter */ PTRHOOK copy_str, /* make copy of structure */ VOIDHOOK free_str); /* free structure storage */-Here is how the storage-management hooks are used:
Some custom field types are simply ordered in the same
well-defined way that TYPE_ENUM is. For such types,
@@ -3407,14 +3352,13 @@ int set_fieldtype_arg(FIELDTYPE *type, /* type to alter */
support the REQ_NEXT_CHOICE and
REQ_PREV_CHOICE requests. Here is how:
+typedef int (*INTHOOK)(); /* pointer to function returning int */ int set_fieldtype_arg(FIELDTYPE *type, /* type to alter */ INTHOOK succ, /* get successor value */ INTHOOK pred); /* get predecessor value */-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 @@ -3424,7 +3368,7 @@ int set_fieldtype_arg(FIELDTYPE *type, /* type to alter */ (a legal next or previous value was set) or FALSE to indicate failure.
-Avoiding Problems
+Avoiding Problems
The interface for defining custom types is complicated and tricky. Rather than attempting to create a custom type entirely