curses
will typically be a great deal simpler and less expensive than one using an
-X toolkit. +X toolkit.
curses evolved to use more facilities and offer
-more capabilities, going far beyond BSD curses in power and flexibility.+more capabilities, going far beyond BSD curses in power and flexibility.
ncurses, a free implementation of
the System V curses API with some clearly marked extensions.
-It includes the following System V curses features: +It includes the following System V curses features:
-
-
-
+handle one `standout' highlight, usually reverse-video). +
Finally, this document describes in detail the menus and forms extension libraries, also cloned from System V, which support easy construction and sequences of menus and fill-in -forms.
+forms.
+screen, scrolling independently of other windows on the physical screen.
stdscr, is automatically provided for the programmer.
+of these, stdscr, is automatically provided for the programmer.
+determine the most efficient way to repaint the screen.
+parameter passed.
stdscr. These instructions w
work on any window, providing you change the function names and parameters as
mentioned above. -Here is a sample program to motivate the discussion:
+Here is a sample program to motivate the discussion:
#include <curses.h> @@ -413,8 +413,11 @@ Here is a sample program to motivate the discussion:static void finish(int sig); +int main(int argc, char *argv[]) { + int num = 0; + /* initialize your non-curses data structures here */ (void) signal(SIGINT, finish); /* arrange interrupts to terminate */ @@ -423,28 +426,32 @@ main(int argc, char *argv[]) keypad(stdscr, TRUE); /* enable keyboard mapping */ (void) nonl(); /* tell curses not to do NL->CR/NL on output */ (void) cbreak(); /* take input chars one at a time, no wait for \n */ - (void) noecho(); /* don't echo input */ + (void) echo(); /* echo input - in color */ if (has_colors()) { start_color(); /* - * Simple color assignment, often all we need. + * Simple color assignment, often all we need. Color pair 0 cannot + * be redefined. This example uses the same value for the color + * pair as for the foreground color, though of course that is not + * necessary: */ - init_pair(COLOR_BLACK, COLOR_BLACK, COLOR_BLACK); - init_pair(COLOR_GREEN, COLOR_GREEN, COLOR_BLACK); - init_pair(COLOR_RED, COLOR_RED, COLOR_BLACK); - init_pair(COLOR_CYAN, COLOR_CYAN, COLOR_BLACK); - init_pair(COLOR_WHITE, COLOR_WHITE, COLOR_BLACK); - init_pair(COLOR_MAGENTA, COLOR_MAGENTA, COLOR_BLACK); - init_pair(COLOR_BLUE, COLOR_BLUE, COLOR_BLACK); - init_pair(COLOR_YELLOW, COLOR_YELLOW, COLOR_BLACK); + init_pair(1, COLOR_RED, COLOR_BLACK); + init_pair(2, COLOR_GREEN, COLOR_BLACK); + init_pair(3, COLOR_YELLOW, COLOR_BLACK); + init_pair(4, COLOR_BLUE, COLOR_BLACK); + init_pair(5, COLOR_CYAN, COLOR_BLACK); + init_pair(6, COLOR_MAGENTA, COLOR_BLACK); + init_pair(7, COLOR_WHITE, COLOR_BLACK); } for (;;) { int c = getch(); /* refresh, accept single keystroke of input */ + attrset(COLOR_PAIR(num % 8)); + num++; /* process the command keystroke */ } @@ -487,7 +494,7 @@ coordinates after updating it.
You can create new windows of your own using the functions
newwin(),derwin(), andsubwin(). The routinedelwin()will allow you to get rid of old windows. All the options described above can be -applied to any window.+applied to any window.
Output
@@ -515,7 +522,7 @@ to make it look like the entire window has been changed, thus making If you callwrefresh()withcurscras its argument, it will make the screen look likecurscrthinks it looks like. This is useful for implementing a command which would redraw the screen in case it get messed -up.+up.
Input
@@ -539,7 +546,7 @@ watches the input stream for character sequences that correspond to arrow and function keys. These sequences are returned as pseudo-character values. The#definevalues returned are listed in thecurses.hThe mapping from sequences to#definevalues is determined by -key_capabilities in the terminal's terminfo entry.+
key_capabilities in the terminal's terminfo entry.Using Forms Characters
@@ -552,7 +559,7 @@ the prefixACS_).The most useful of the ACS defines are the forms-drawing characters. You can use these to draw boxes and simple graphs on the screen. If the terminal does not have such characters,
curses.hwill map them to a -recognizable (though ugly) set of ASCII defaults.+recognizable (though ugly) set of ASCII defaults.
Character Attributes and Color
@@ -584,7 +591,7 @@ have been used as the first arguments of theinit_pair()values.init_pair() that creates color-pair N, you can use
COLOR_PAIR(N)as a highlight that invokes that particular color combination. Note thatCOLOR_PAIR(N), for constant N, -is itself a compile-time constant and can be used in initializers.+is itself a compile-time constant and can be used in initializers.
Mouse Interfacing
@@ -657,7 +664,7 @@ would normally accept from the keyboard. Two of the test games in the code that illustrates how this can be done.See the manual page
curs_mouse(3X)for full details of the -mouse-interface functions.+mouse-interface functions.
Finishing Up
@@ -665,7 +672,7 @@ In order to clean up after thencursesroutines, the routineendwin()is provided. It restores tty modes to what they were wheninitscr()was first called, and moves the cursor down to the lower-left corner. Thus, anytime after the call to initscr,endwin()-should be called before exiting.+should be called before exiting.
Function Descriptions
@@ -684,14 +691,14 @@ occurs a message is written to standard error and the program exits. Otherwise it returns a pointer to stdscr. A few functions may be called before initscr (slk_init(),filter(),ripofflines(),use_env(), and, if you are using multiple -terminals,newterm().)+terminals,
newterm().)
endwin()
endwin() before exiting or
shelling out of the program. This function will restore tty modes,
move the cursor to the lower left corner of the screen, reset the
terminal into the proper non-visual mode. Calling refresh()
or doupdate() after a temporary escape from the program will
-restore the ncurses screen from before the escape. +restore the ncurses screen from before the escape.
newterm(type, ofp, ifp)
newterm() instead of initscr(). newterm() should
@@ -701,12 +708,12 @@ terminal. The arguments are the type of the terminal (a string) and
FILE pointers for the output and input of the terminal. If
type is NULL then the environment variable $TERM is used.
endwin() should called once at wrapup time for each terminal
-opened using this function. +opened using this function.
set_term(new)
newterm(). The screen reference for the new terminal
is passed as the parameter. The previous terminal is returned by the
-function. All other calls affect only the current terminal. +function. All other calls affect only the current terminal.
delscreen(sp)
newterm(); deallocates the data structures
associated with a given SCREEN reference.
@@ -723,7 +730,7 @@ terminal screen, taking into account what is already
there in order to do optimizations. refresh() does a
refresh of stdscr(). Unless leaveok() has been
enabled, the physical cursor of the terminal is left at the
-location of the window's cursor. +location of the window's cursor.
doupdate() and wnoutrefresh(win)
ncurses distribution that can alleviate
this problem somewhat; it compacts long sequences of similar operations into
more succinct single-line pseudo-operations. These pseudo-ops can be
-distinguished by the fact that they are named in capital letters.+distinguished by the fact that they are named in capital letters.
ncurses manual 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. +may not be obvious from the manual page descriptions.
Try to avoid using the global variables LINES and COLS. Use
getmaxyx() on the stdscr context instead. Reason:
your code may be ported to run in an environment with window resizes,
-in which case several screens could be open with different sizes.
+in which case several screens could be open with different sizes.
stdscr will be
set to the last one allocated. You will switch between screens with the
set_term call. Note that you will also have to call
-def_shell_mode and def_prog_mode on each tty yourself.
+def_shell_mode and def_prog_mode on each tty yourself.
tigetstr("cup") is non-NULL. Alternatively,
you can include the term.h file and test the value of the
-macro cursor_address.
+macro cursor_address.
addchstr() family of functions for fast
screen-painting of text when you know the text doesn't contain any
control characters. Try to make attribute changes infrequent on your
-screens. Don't use the immedok() option!
+screens. Don't use the immedok() option!
update_panels(), it will
do all the necessary wnoutrfresh() calls for whatever panel
stacking order you have defined. Then you can do one doupdate()
and there will be a single burst of physical I/O that will do
-all your updates. +all your updates.
bkgdset()wbkgdset().
This change in behavior conforms ncurses to System V Release 4 and
-the XSI Curses standard.
+the XSI Curses standard.
ncurses meets the XSI requirement that every macro
entry point have a corresponding function which may be linked (and
will be prototype-checked) if the macro definition is disabled with
-#undef.
+#undef.
update_panels() and
doupdate() just before accepting command input, once in each cycle
of interaction with the user. If you call update_panels() after
each and every panel write, you'll generate a lot of unnecessary refresh
-activity and screen flicker. +activity and screen flicker.
There is presently no way to display changes to one obscured panel without -repainting all panels.
+repainting all panels.
The panel_update code ignores hidden panels. You cannot do
top_panel() or bottom_panel on a hidden panel().
-Other panels operations are applicable.
+Other panels operations are applicable.
set_panel_userptr() and panel_userptr for
-details. +details.
The menu library first appeared in AT&T System V. The
version documented here is the menu code distributed
-with ncurses.
+with ncurses.
set_item_opts()
or item_opts_off() with the O_SELECTABLE
argument. This is the only option so far defined for menus, but it
-is good practice to code as though other option bits might be on. +is good practice to code as though other option bits might be on.
+on the following variables:
menu_attribs(3x) manual page.
+change (see the menu_attribs(3x) manual page.
menu_win(3x).
When you call menu_post(), you write the menu to its
subwindow. When you call menu_unpost(), you erase the
subwindow, However, neither of these actually modifies the screen. To
-do that, call wrefresh() or some equivalent.
+do that, call wrefresh() or some equivalent.
mitem_userptr(3x) and
-menu_userptr(3x).
+menu_userptr(3x).
The form library first appeared in AT&T System V. The
version documented here is the form code distributed
-with ncurses.
+with ncurses.
-lform argument. Note that they must also link the
ncurses library with -lncurses. Many linkers
are two-pass and will accept either order, but it is still good practice
-to put -lform first and -lncurses second.
+to put -lform first and -lncurses second.
In forms programs, however, the `process user requests' is somewhat more complicated than for menus. Besides menu-like navigation operations, -the menu driver loop has to support field editing and data validation.
+the menu driver loop has to support field editing and data validation.
new_field():
+The basic function for creating fields is new_field():
FIELD *new_field(int height, int width, /* new field size */ @@ -1482,7 +1489,7 @@ The forms library allocates one working buffer per field; the size of each buffer is((height + offscreen)*width + 1, one character for each position in the field plus a NUL terminator. The sixth argument is the number of additional data buffers to allocate for the -field; your application can use them for its own purposes.+field; your application can use them for its own purposes.
FIELD *dup_field(FIELD *field, /* field to copy */ @@ -1492,7 +1499,7 @@ FIELD *dup_field(FIELD *field, /* field to copy */ The functiondup_field()duplicates an existing field at a new location. Size and buffering information are copied; some attribute flags and status bits are not (see the -form_field_new(3X)for details).+
form_field_new(3X)for details).FIELD *link_field(FIELD *field, /* field to copy */ @@ -1516,7 +1523,7 @@ As you might guess, all these field-allocations returnNULLif the field allocation is not possible due to an out-of-memory error or out-of-bounds arguments.-To connect fields to a form, use
+To connect fields to a form, use
FORM *new_form(FIELD **fields); @@ -1534,7 +1541,7 @@ note that any given field may only be connected to one form.The functions
free_field()andfree_formare available to free field and form objects. It is an error to attempt to free a field connected to a form, but not vice-versa; thus, you will generally free -your form objects first.+your form objects first.
Fetching and Changing Field Attributes
@@ -1549,11 +1556,11 @@ When a field is created, the attributes not specified by thenew_fieldfunction are copied from an invisible system default field. In attribute-setting and -fetching functions, the argument NULL is taken to mean this field. Changes to it persist -as defaults until your forms application terminates.+as defaults until your forms application terminates.
Fetching Size and Location Data
-You can retrieve field sizes and locations through:+You can retrieve field sizes and locations through:
int field_info(FIELD *field, /* field from which to fetch */ @@ -1565,11 +1572,11 @@ int field_info(FIELD *field, /* field from which to fetch */ This function is a sort of inverse ofnew_field(); instead of setting size and location attributes of a new field, it fetches them -from an existing one.+from an existing one.
Changing the Field Location
-It 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 */ @@ -1581,7 +1588,7 @@ You can, of course. query the current location throughfield_info()The Justification Attribute
One-line fields may be unjustified, justified right, justified left, -or centered. Here is how you manipulate this attribute:+or centered. Here is how you manipulate this attribute:
int set_field_just(FIELD *field, /* field to alter */ @@ -1592,7 +1599,7 @@ int field_just(FIELD *field); /* fetch mode of field */ The mode values accepted and returned by this functions are preprocessor macrosNO_JUSTIFICATION,JUSTIFY_RIGHT, -JUSTIFY_LEFT, orJUSTIFY_CENTER.+
JUSTIFY_LEFT, orJUSTIFY_CENTER.Field Display Attributes
@@ -1603,7 +1610,7 @@ control pagination of the form.This group of four field attributes controls the visual appearance of the field on the screen, without affecting in any way the data -in the field buffer.
+in the field buffer.
int set_field_fore(FIELD *field, /* field to alter */ @@ -1632,7 +1639,7 @@ The attributes set and returned by the first four functions are normalA_BOLD,A_REVERSEetc). The page bit of a field controls whether it is displayed at the start of -a new form screen.+a new form screen.
Field Option Bits
@@ -1708,13 +1715,13 @@ A field's options cannot be changed while the field is currently selected. However, options may be changed on posted fields that are not current.The option values are bit-masks and can be composed with logical-or in -the obvious way.
+the obvious way.
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:+be queried and set directly:
int set_field_status(FIELD *field, /* field to alter */ @@ -1736,7 +1743,7 @@ To guarantee that the returned status value reflects reality, callfield_status()either (1) in the field's exit validation check routine, (2) from the field's or form's initialization or termination hooks, or (3) just after aREQ_VALIDATIONrequest has been -processed by the forms driver.+processed by the forms driver.
Field User Pointer
@@ -1757,7 +1764,7 @@ 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.+to initialize the new field's user pointer.
Variable-Sized Fields
@@ -1776,7 +1783,7 @@ dimensioned and located.Normally, a dynamic field is allowed to grow without limit. But it is possible to set an upper limit on the size of a dynamic field. You do -it with this function:
+it with this function:
int set_max_field(FIELD *field, /* field to alter (may not be NULL) */ @@ -1818,7 +1825,7 @@ is changed through a linked field.The
formlibrary provides a rich set of pre-defined validation types, and gives you the capability to define custom ones of your own. You can examine and change field validation attributes with the following -functions:+functions:
int set_field_type(FIELD *field, /* field to alter */ @@ -1833,12 +1840,12 @@ with other field attributes, Also, doingset_field_type()with aNULLfield default will change the system default for validation of newly-created fields.-Here are the pre-defined validation types:
+Here are the pre-defined validation types:
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:+characters (this is checked at character-entry time). It is set up with:
int set_field_type(FIELD *field, /* field to alter */ @@ -1849,12 +1856,12 @@ int set_field_type(FIELD *field, /* field to alter */ Thewidthargument sets a minimum width of data. Typically you'll want to set this to the field width; if it's greater than the field width, the validation check will always fail. A minimum width -of zero makes field completion optional.+of zero makes field completion optional.
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:+characters (this is checked at character-entry time). It is set up with:
int set_field_type(FIELD *field, /* field to alter */ @@ -1865,13 +1872,13 @@ int set_field_type(FIELD *field, /* field to alter */ Thewidthargument sets a minimum width of data. As with TYPE_ALPHA, typically you'll want to set this to the field width; if it's greater than the field width, the validation check will always fail. A -minimum width of zero makes field completion optional.+minimum width of zero makes field completion optional.
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:+states). It is set up with:
int set_field_type(FIELD *field, /* field to alter */ @@ -1896,11 +1903,11 @@ value. But thecheckuniqueargument, if true, requires prefix matches to be unique in order to be valid.The
REQ_NEXT_CHOICEandREQ_PREV_CHOICEinput requests -can be particularly useful with these fields.+can be particularly useful with these fields.
TYPE_INTEGER
-This field type accepts an integer. It is set up as follows:+This field type accepts an integer. It is set up as follows:
int set_field_type(FIELD *field, /* field to alter */ @@ -1921,7 +1928,7 @@ with the C library functionatoi(3).TYPE_NUMERIC
-This field type accepts a decimal number. It is set up as follows:+This field type accepts a decimal number. It is set up as follows:
int set_field_type(FIELD *field, /* field to alter */ @@ -1945,7 +1952,7 @@ with the C library functionatof(3).TYPE_REGEXP
This field type accepts data matching a regular expression. It is set up -as follows:+as follows:
int set_field_type(FIELD *field, /* field to alter */ @@ -1960,7 +1967,7 @@ The check for regular-expression match is performed on exit. 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:+field buffer. You can find this out with:
char *field_buffer(FIELD *field, /* field to query */ @@ -1993,7 +2000,7 @@ To guarantee that the returned buffer value reflects on-screen reality, callfield_buffer()either (1) in the field's exit validation check routine, (2) from the field's or form's initialization or termination hooks, or (3) just after aREQ_VALIDATIONrequest has been processed -by the forms driver.+by the forms driver.
Attributes of Forms
@@ -2002,7 +2009,7 @@ system default form structure. These defaults can be queried or set by of these functions using a form-pointer argument ofNULL.The principal attribute of a form is its field list. You can query -and change this list with:
+and change this list with:
int set_form_fields(FORM *form, /* form to alter */ @@ -2024,7 +2031,7 @@ It may also be null, in which case the old fields are disconnected Thefield_count()function simply counts the number of fields connected to a given from. It returns -1 if the form-pointer argument -is NULL.+is NULL.
Control of Form Display
@@ -2055,7 +2062,7 @@ is where the current form page is actually displayed.In order to declare your own frame window for a form, you'll need to know the size of the form's bounding rectangle. You can get this -information with:
+information with:
int scale_form(FORM *form, /* form to query */ @@ -2084,7 +2091,7 @@ should be done on the frame window, not the form subwindow.It is possible to check from your application whether all of a scrollable field is actually displayed within the menu subwindow. Use -these functions:
+these functions:
int data_ahead(FORM *form); /* form to be queried */ @@ -2100,21 +2107,21 @@ The functiondata_behind()returns TRUE if the first (upper left hand) character position is off-screen (not being displayed).Finally, there is a function to restore the form window's cursor to the -value expected by the forms driver:
+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.+handing control back to the forms driver in order to re-synchronize it.
Input Processing in the Forms Driver
The functionform_driver()handles virtualized input requests for form navigation, editing, and validation requests, just asmenu_driverdoes for menus (see the section on menu input handling).+HREF="#minput">menu input handling).
int form_driver(FORM *form, /* form to pass input to */ @@ -2127,12 +2134,12 @@ entered in the currently-selected field), or a forms processing request.The forms driver provides hooks (through input-validation and field-termination functions) with which your application code can check -that the input taken by the driver matched what was expected.
+that the input taken by the driver matched what was expected.
Page Navigation Requests
These requests cause page-level moves through the form, -triggering display of a new form screen.+triggering display of a new form screen.
REQ_NEXT_PAGE
@@ -2147,11 +2154,11 @@ triggering display of a new form screen.
These requests treat the list as cyclic; that is, REQ_NEXT_PAGE
from the last page goes to the first, and REQ_PREV_PAGE from
-the first page goes to the last.
+the first page goes to the last.
+These requests handle navigation between fields on the same page.
REQ_NEXT_FIELD
@@ -2162,7 +2169,6 @@ These requests handle navigation between fields on the same page.
REQ_LAST_FIELD
REQ_SNEXT_FIELD
REQ_SPREV_FIELD
@@ -2171,7 +2177,6 @@ These requests handle navigation between fields on the same page.
REQ_SLAST_FIELD
REQ_LEFT_FIELD
REQ_RIGHT_FIELD
@@ -2203,12 +2208,12 @@ For example, suppose you have a multi-line field B, and two
single-line fields A and C on the same line with B, with A to the left
of B and C to the right of B. A REQ_MOVE_RIGHT 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. +otherwise it will skip over B to C.
+selected field.
REQ_NEXT_CHAR
@@ -2243,7 +2248,7 @@ selected field. Each word is separated from the previous and next characters by whitespace. The commands to move to beginning and end of line or field -look for the first or last non-pad character in their ranges.
+look for the first or last non-pad character in their ranges.
REQ_SCR_FLINE
@@ -2283,7 +2287,7 @@ following requests:
+of its visible part.
The following requests support editing the field and changing the edit -mode:
+mode:
REQ_INS_MODE
@@ -2359,13 +2363,13 @@ treated as a REQ_PREV_FIELD. If the
disabled and the forms driver just returns E_REQUEST_DENIED.
See Form Options for discussion of how to set -and clear the overload options.
+and clear the overload options.
+there are requests that can fetch that value into the field buffer:
REQ_NEXT_CHOICE
@@ -2377,19 +2381,19 @@ there are requests that can fetch that value into the field buffer:
Of the built-in field types, only TYPE_ENUM has built-in successor
and predecessor functions. When you define a field type of your own
(see Custom Validation Types), you can associate
-our own ordering functions.
+our own ordering functions.
curses value
greater than KEY_MAX and less than or equal to the constant
MAX_COMMAND. If your input-virtualization routine returns a
-value above MAX_COMMAND, the forms driver will ignore it.
+value above MAX_COMMAND, the forms driver will ignore it.
+current field or form changes. Here are the functions that support this:
typedef void (*HOOK)(); /* pointer to function returning void */ @@ -2418,7 +2422,7 @@ 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 functions differ only in the timing -of the hook call.+of the hook call.
+the field is altered. It is also called when the form is unposted.
You can disable any of these hooks by (re)setting them to NULL, the default -value.
+value.
+accomplish this:
int set_current_field(FORM *form, /* form to alter */ @@ -2476,7 +2480,7 @@ in the given form's field array (the array passed tonew_form()or The initial current field of a form is the first active field on the first page. The functionset_form_fields()resets this.-It is also possible to move around by pages.
+It is also possible to move around by pages.
int set_form_page(FORM *form, /* form to alter */ @@ -2486,12 +2490,12 @@ 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.+
set_form_fields()resets this.Form Options
Like fields, forms may have control option bits. They can be changed -or queried with these functions:+or queried with these functions:
int set_form_opts(FORM *form, /* form to alter */ @@ -2521,7 +2525,7 @@ these have no last line, so the circumstances for triggering a
+the obvious way.
set_field_type effectively allow you to parameterize validation
types. Most of the complications in the validation-type interface have to
do with the handling of the additional arguments within custom validation
-functions. +functions.
+preexisting ones:
FIELD *link_fieldtype(FIELDTYPE *type1, @@ -2551,19 +2555,19 @@ composite type expects all arguments for the first type, than all arguments for the second. Order functions (see Order Requests) associated with the component types will work on the composite; what it does is check the validation function for the first type, then for the second, to -figure what type the buffer contents should be treated as.+figure what type the buffer contents should be treated as.
New Field Types
To create a field type from scratch, you need to specify one or both of the -following things:+following things:
+Here's how you do that:
typedef int (*HOOK)(); /* pointer to function returning int */ @@ -2589,7 +2593,7 @@ the operation succeeds; if it returns FALSE, the edit cursor stays in the field.A character validator gets the character passed in as a first argument. -It too should return TRUE if the character is valid, FALSE otherwise.
+It too should return TRUE if the character is valid, FALSE otherwise.
Validation Function Arguments
@@ -2606,7 +2610,7 @@ with the type. The forms driver will use these to synthesize a pile from the trailing arguments of eachset_field_type()argument, and a pointer to the pile will be passed to the validation functions.-Here is how you make the association:
+Here is how you make the association:
typedef char *(*PTRHOOK)(); /* pointer to function returning (char *) */ @@ -2618,7 +2622,7 @@ int set_fieldtype_arg(FIELDTYPE *type, /* type to alter */ VOIDHOOK free_str); /* free structure storage */-Here is how the storage-management hooks are used:+Here is how the storage-management hooks are used:
make_str
@@ -2639,14 +2643,14 @@ storage of that pile.
The make_str and copy_str functions may return NULL to
signal allocation failure. The library routines will that call them will
return error indication when this happens. Thus, your validation functions
-should never see a NULL file pointer and need not check specially for it. +should never see a NULL file pointer and need not check specially for it.
TYPE_ENUM is. For such types, it is possible to define
successor and predecessor functions to support the REQ_NEXT_CHOICE
-and REQ_PREV_CHOICE requests. Here's how:
+and REQ_PREV_CHOICE requests. Here's how:
typedef int (*INTHOOK)(); /* pointer to function returning int */ @@ -2661,7 +2665,7 @@ a field pointer, and a pile pointer (as for the validation functions). They are expected to use the functionfield_buffer()to read the current value, andset_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.+legal next or previous value was set) or FALSE to indicate failure.
Avoiding Problems