Lines Matching full:to
30 o Causing Output to the Terminal
103 This document is an introduction to programming with curses. It is not
106 Rather, it is intended to help C programmers ease into using the
113 Tips, and Tricks. These will bring you up to speed on the special
119 screen model to the programmer, hiding differences between terminal
120 types and doing automatic optimization of output to change one screen
128 the advantage of (a) back-portability to character-cell terminals, and
136 Historically, the first ancestor of curses was the routines written to
145 After graduation, one of those students went to work at AT&T Bell
147 "libterm"), and adapted the curses library to use this. That was
149 other developers added to the curses and terminfo libraries. For
151 library as well as a tool (tic) to compile the terminal descriptions.
160 To recap, terminfo is based on Berkeley's termcap database, but
162 capabilities strings were introduced, making it possible to describe
163 multiple video attributes, and colors and to handle far more unusual
165 releases, curses evolved to use more facilities and offer more
182 character features of terminals so equipped, and determines how to
184 allows arbitrary combinations of video attributes to be displayed,
185 even on terminals that leave "magic cookies" on the screen to mark
201 modeled on the SVr4 panels facility. This library allows you to
218 (possibly the entire screen). You can write to a window as
238 In order to use the library, it is necessary to have certain types and
245 system. It is redundant (but harmless) for the programmer to do these
246 includes, too. In linking with curses you need to have -lncurses in
252 In order to update the screen optimally, it is necessary for the
253 routines to know what the screen currently looks like and what the
254 programmer wants it to look like next. For this purpose, a data type
255 (structure) named WINDOW is defined which describes a window image to
260 standard screen) is provided by default to make changes on.
262 A window is a purely internal representation. It is used to build and
264 any necessary relation to what is really on the terminal screen; it is
267 To make the section of physical screen corresponding to a window
272 of overlapping windows. Also, changes can be made to windows in any
273 order, without regard to motion efficiency. Then, at will, the
275 package implementation determine the most efficient way to repaint the
282 and stdscr, which is what the programmer wants the terminal to look
284 Changes should be made to through the API, and then the routine
287 Many functions are defined to use stdscr as a default screen. For
288 example, to add a character to stdscr, one calls addch() with the
289 desired character as argument. To write to a different window. use the
291 convention of prepending function names with a "w" when they are to be
292 applied to specific windows is consistent. The only routines which do
295 In order to move the current (y, x) coordinates from one point to
297 often desirable to first move and then perform some I/O operation. In
298 order to avoid clumsiness, most I/O routines can be preceded by the
299 prefix "mv" and the desired (y, x) coordinates prepended to the
300 arguments to the function. For example, the calls
347 Now we describe how to actually use the screen package. In it, we
348 assume all updating, reading, etc. is applied to stdscr. These
352 Here is a sample program to motivate the discussion:
366 (void) signal(SIGINT, finish); /* arrange interrupts to terminate */
370 (void) nonl(); /* tell curses not to do NL->CR/NL on output */
416 In order to use the screen package, the routines must know about
420 attempting to do so. On the rare occasions this happens, initscr()
424 curscr or stdscr are referenced. However, it is usually best to wait
425 to call it until after you are sure you will need it, like after
430 your program. If you want to, say, allow a screen to scroll, use
431 scrollok(). If you want the cursor to be left in place after the last
433 cursor to the window's current (y, x) coordinates after updating it.
436 derwin(), and subwin(). The routine delwin() will allow you to get rid
437 of old windows. All the options described above can be applied to any
442 Now that we have set things up, we will want to actually update the
443 terminal. The basic functions used to change what will go on a window
445 coordinates. move() changes the current (y, x) coordinates to whatever
446 you want them to be. It returns ERR if you try to move off the window.
447 As mentioned above, you can combine the two into mvaddch() to do both
451 addch() to add characters to the window.
454 the portion of the terminal covered by the window to be made to look
455 like it, you must call refresh(). In order to optimize finding
460 touchwin() is provided to make it look like the entire window has been
471 The complementary function to addch() is getch() which, if echo is
472 set, will call addch() to echo the character. Since the screen package
473 needs to know what is on the terminal at all times, if characters are
474 to be echoed, the tty must be in raw or cbreak mode. Since initially
476 or the other has to changed before calling getch(); otherwise, the
479 When you need to accept line-oriented input in a window, the functions
485 The example code above uses the call keypad(stdscr, TRUE) to enable
487 watches the input stream for character sequences that correspond to
490 curses.h The mapping from sequences to #define values is determined by
501 You can use these to draw boxes and simple graphs on the screen. If
502 the terminal does not have such characters, curses.h will map them to
512 pseudo-character type (chtype) that curses.h uses to represent the
516 There are two ways to make highlights. One is to logical-or the value
520 The other is to set the current-highlight value. This is logical-ORed
540 NOTE: this facility is specific to ncurses, it is not part of
544 disassembling the library, we have no way to determine exactly how
557 The mouse interface is very simple. To activate it, you use the
559 specifies what kinds of events you want your program to be able to
566 mouse event report has been queued. To pick it off the queue, use the
571 Each call to getmouse() fills a structure (the address of which you
575 set, corresponding to the event type being reported.
578 significant in the future as ncurses interfaces to new kinds of
579 pointing device. In addition to x and y coordinates, there is a slot
582 field, which could be used to distinguish between multiple pointing
593 A function to check whether a mouse event fell within a given window
594 is also supplied. You can use this to see whether a given window
595 should consider a mouse event relevant to it.
598 environments, it would be unwise to build ncurses applications that
610 In order to clean up after the ncurses routines, the routine endwin()
611 is provided. It restores tty modes to what they were when initscr()
612 was first called, and moves the cursor down to the lower-left corner.
613 Thus, anytime after the call to initscr, endwin() should be called
619 here, as a supplement to the manual page descriptions.
626 data structures. initscr() also arranges that the first call to
628 is written to standard error and the program exits. Otherwise
629 it returns a pointer to stdscr. A few functions may be called
636 modes, move the cursor to the lower left corner of the screen,
642 A program which outputs to more than one terminal should use
645 should be saved as a reference to that terminal. (NOTE: a
647 in this introduction, but a collection of parameters used to
655 This function is used to switch to a different terminal
665 Causing Output to the Terminal
668 These functions must be called to actually get any output on
670 structures. wrefresh() copies the named window to the physical
672 order to do optimizations. refresh() does a refresh of stdscr.
678 than wrefresh. To use them, it is important to understand how
679 curses works. In addition to all the window structures, curses
682 a virtual screen, describing what the programmer wants to have
684 to the virtual screen (wnoutrefresh()), and then calling the
685 routine to update the screen (doupdate()). If the programmer
686 wishes to output several windows at once, a series of calls to
687 wrefresh will result in alternating calls to wnoutrefresh() and
688 doupdate(), causing several bursts of output to the screen. By
689 calling wnoutrefresh() for each window, it is then possible to
697 This routine is called to initialize a terminal's description,
701 descriptor of the terminal to be used for output. errret is a
702 pointer to an integer, in which a success or failure indication
708 value of TERM in the environment to be used. The errret pointer
715 After the call to setupterm(), the global variable cur_term is
716 set to point to the current structure of terminal capabilities.
718 restoring cur_term, it is possible for a program to use two or
721 array ttytype[]. Subsequent calls to setupterm() will overwrite
722 this array, so you will have to save it yourself if need be.
729 This function can be used to explicitly set a trace level. If
734 comments attached to TRACE_ defines in the curses.h file for
735 details. (It is also possible to set a trace level by assigning
736 a trace level value to the environment variable NCURSES_TRACE).
739 This function can be used to output your own debugging
743 to a file called trace in the current directory.
745 Trace logs can be difficult to interpret due to the sheer volume of
760 If you find yourself thinking you need to use noraw() or nocbreak(),
761 think again and move carefully. It is probably better design to use
762 getstr() or one of its relatives to simulate cooked mode. The noraw()
763 and nocbreak() functions try to restore cooked mode, but they may end
766 likely to hurt your application's usability with other curses
770 try to mix use of stdscr with use of windows declared by newwin(); a
771 refresh() call will blow them off the screen. The right way to handle
772 this is to use subwin(), or not touch stdscr at all and tile your
774 in your program event loop, with a single doupdate() call to trigger
777 You are much less likely to run into problems if you design your
778 screen layouts to use tiled rather than overlapping windows.
781 exception to this rule.
787 Try to avoid using the global variables LINES and COLS. Use getmaxyx()
788 on the stdscr context instead. Reason: your code may be ported to run
794 Sometimes you will want to write a program that spends most of its
795 time in screen mode, but occasionally returns to ordinary "cooked"
796 mode. A common reason for this is to support shell-out. This behavior
797 is simple to arrange in ncurses.
799 To leave ncurses mode, call endwin() as you would if you were
800 intending to terminate the program. This will take the screen back to
801 cooked mode; you can do your shell-out. When you want to return to
805 There is a boolean function, isendwin(), which code can use to test
819 A resize operation in X sends SIGWINCH to the application running
820 under xterm. The easiest way to handle SIGWINCH is to do an endwin,
825 curses implementations). Its drawback is that it clears the screen to
829 limited to the new screen dimensions, and pads stdscr with blanks if
834 calls resizeterm to update the size of the standard screen's window,
838 have to write special-purpose code to handle KEY_RESIZE yourself.
842 The initscr() function actually calls a function named newterm() to do
846 For each call, you will have to specify a terminal type and a pair of
848 will be set to the last one allocated. You will switch between screens
849 with the set_term call. Note that you will also have to call
854 Sometimes you may want to write programs that test for the presence of
855 various capabilities before deciding whether to go into ncurses mode.
856 An easy way to do this is to call setupterm(), then use the functions
857 tigetflag(), tigetnum(), and tigetstr() to do your testing.
859 A particularly useful case of this often comes up when you want to
861 (cursor-addressable) or "stupid". The right way to test this is to see
870 Try to make attribute changes infrequent on your screens. Do not use
875 The wresize() function allows you to resize a window in place. The
879 The define_key() function allows you to define at runtime function-key
881 keyok() function allows you to temporarily enable or disable
884 The use_default_colors() function allows you to construct applications
903 scribble on and refresh them, the changes made to the overlapping
907 To understand why this is a problem, remember that screen updates are
910 to the virtual screen, and then changes are calculated to update the
911 physical screen (and applied to the terminal). But "copied to" is not
916 What happens to the overlapping region depends on what wnoutrefresh()
918 copies to the virtual screen. Some implementations do "change copy",
921 "entire copy", copying all window locations to the virtual screen
925 score. Due to a bug, versions 1.8.7 to 1.9.8a did entire copy.
930 not known for sure (at least not to the ncurses maintainers) whether
932 curses has logic in it that looks like an attempt to do change copy,
934 complex, and our knowledge sufficiently indirect, that it is hard to
937 mentions wnoutrefresh(); the SVr4 documents seem to be describing
938 entire-copy, but it is possible with some effort and straining to read
941 It might therefore be unwise to rely on either behavior in programs
942 that might have to be linked with other curses implementations.
944 call to guarantee an entire-contents copy anywhere.
946 The really clean way to handle this is to use the panels library. If,
964 This change in behavior conforms ncurses to System V Release 4 and the
969 The ncurses library is intended to be base-level conformant with the
985 general case that windows may overlap, you have to use a series of
987 the order you do the window refreshes in. It has to be bottom-upwards,
991 the visibility stack or pop to the top at runtime, the resulting
992 book-keeping can be tedious and difficult to get right. Hence the
1007 it is still good practice to put -lpanel first and -lncurses second.
1013 bottom-to-top visibility order. The panels library includes an update
1014 function (analogous to refresh()) that displays all panels in the deck
1015 in the proper order to resolve overlaps. The standard window, stdscr,
1027 This will not deallocate the associated window; you have to do that
1033 To move a panel's window, use move_panel(). The mvwin() function on
1039 rearranging the deck. The first pops its argument window to the top of
1040 the deck; the second sends it to the bottom. Either operation leaves
1044 to prepare for doupdate() (which you must call yourself, afterwards).
1046 Typically, you will want to call update_panels() and doupdate() just
1059 panels. Because changes to panels may obscure parts of stdscr, though,
1064 requesting input from a panel window, you need to be sure that the
1067 There is presently no way to display changes to one obscured panel
1072 It is possible to remove a panel from the deck temporarily; use
1073 hide_panel for this. Use show_panel() to render it visible again. The
1083 It is possible to navigate the deck using the functions panel_above()
1089 code, to which you can attach application data. See the man page
1094 A menu is a screen display that assists the user to choose some subset
1110 it is still good practice to put -lmenu first and -lncurses second.
1115 including a name string part and a description string part. To make
1119 The menu can then by posted, that is written to an associated window.
1123 small to display all the items, it will be a scrollable viewport on
1127 to make the storage associated with it and its items available for
1145 manual page menu_opts(3x) to see how to change the default). Both
1152 set_item_value() to flag the items in the select set.
1156 option so far defined for menus, but it is good practice to code as
1170 The function set_menu_format() allows you to set the maximum size of
1171 the viewport or menu page that will be used to display menu items. You
1177 (on by default) causes menu items to be displayed in a "raster-scan"
1180 column-major display, which tries to put the first several items in
1183 As mentioned above, a menu format not large enough to allow all items
1184 to fit on-screen will result in a menu display that is vertically
1187 You can scroll it with requests to the menu driver, which will be
1190 Each menu has a mark string used to visually tag selected items; see
1198 character used to separate item name text from description text. These
1199 have reasonable defaults which the library allows you to change (see
1217 When you call post_menu(), you write the menu to its subwindow. When
1219 these actually modifies the screen. To do that, call wrefresh() or
1227 routine that maps input characters to menu command codes, and pass its
1228 output to menu_driver(). The menu command codes are fully documented
1247 tries to accumulate printable ASCII characters passed in in that
1259 buffer. It is also possible to set the pattern buffer explicitly with
1271 It is possible to change the current item from application code; this
1272 is useful if you want to write your own navigation requests. It is
1273 also possible to explicitly set the top row of the menu display. See
1274 mitem_current(3x). If your application needs to change the menu
1275 subwindow cursor for any reason, pos_menu_cursor() will restore it to
1278 It is possible to set hooks to be called at menu initialization and
1301 it is still good practice to put -lform first and -lncurses second.
1307 segmented into pages; each entry to a new page clears the screen.
1309 To make forms, you create groups of fields and connect them with form
1312 Once defined, a form can be posted, that is written to an associated
1319 field, and plain text adds to or changes data in a current field. The
1320 form library allows you (the forms designer) to bind each navigation
1321 and editing key to any keystroke accepted by curses Fields may have
1324 types, and makes it relatively easy to define new ones.
1327 (that is, undisplayed), and finally freed to make the storage
1344 obviously designed to resemble that of the menu library wherever
1349 operations, the menu driver loop has to support field editing and data
1361 multiple rows. So new_field() requires you to specify a width and
1367 greater). Note that these coordinates are relative to the form
1371 The fifth argument allows you to specify a number of off-screen rows.
1382 number of additional data buffers to allocate for the field; your
1384 FIELD *dup_field(FIELD *field, /* field to copy */
1391 FIELD *link_field(FIELD *field, /* field to copy */
1396 new field's buffer to be shared with the old one.
1399 form pages, linked fields give you a way to hack in dynamic labels. If
1400 you declare several fields linked to an original, and then make them
1401 inactive, changes from the original will still be propagated to the
1408 field allocation is not possible due to an out-of-memory error or
1411 To connect fields to a form, use
1414 This function expects to see a NULL-terminated array of field
1415 pointers. Said fields are connected to a newly-allocated form object;
1421 any given field may only be connected to one form.
1423 The functions free_field() and free_form are available to free field
1424 and form objects. It is an error to attempt to free a field connected
1425 to a form, but not vice-versa; thus, you will generally free your form
1431 associated with it. There are other field attributes used to control
1433 involve sufficient complications to be covered in sections of their
1434 own later on. We cover the functions used to get and set several basic
1440 to mean this field. Changes to it persist as defaults until your forms
1446 int field_info(FIELD *field, /* field from which to fetch */
1458 It is possible to move a field's location on the screen:
1459 int move_field(FIELD *field, /* field to alter */
1468 int set_field_just(FIELD *field, /* field to alter */
1469 int justmode); /* mode to set */
1487 int set_field_fore(FIELD *field, /* field to alter */
1488 chtype attr); /* attribute to set */
1490 chtype field_fore(FIELD *field); /* field to query */
1492 int set_field_back(FIELD *field, /* field to alter */
1493 chtype attr); /* attribute to set */
1495 chtype field_back(FIELD *field); /* field to query */
1497 int set_field_pad(FIELD *field, /* field to alter */
1498 int pad); /* pad character to set */
1502 int set_new_page(FIELD *field, /* field to alter */
1503 int flag); /* TRUE to force new page */
1505 chtype new_page(FIELD *field); /* field to query */
1514 There is also a large collection of field option bits you can set to
1517 int set_field_opts(FIELD *field, /* field to alter */
1518 int attr); /* attribute to set */
1520 int field_opts_on(FIELD *field, /* field to alter */
1521 int attr); /* attributes to turn on */
1523 int field_opts_off(FIELD *field, /* field to alter */
1524 int attr); /* attributes to turn off */
1526 int field_opts(FIELD *field); /* field to query */
1532 used during form processing to hide or pop up fields depending
1537 (i.e. visited by form navigation keys). Can be used to make
1546 O_PUBLIC bit to define password fields.
1557 current line, the entire word is wrapped to the next line
1567 Controls automatic skip to next field when this one fills.
1568 Normally, when the forms user tries to type more data into a
1569 field than will fit, the editing location jumps to next field.
1575 Controls whether validation is applied to blank fields.
1587 Controls whether the field is fixed to its initial dimensions.
1589 stretch to fit entered data.
1600 Every field has a status flag, which is set to FALSE when the field is
1603 int set_field_status(FIELD *field, /* field to alter */
1604 int status); /* mode to set */
1614 status value, because entered data is not necessarily copied to buffer
1615 zero before the exit validation check. To guarantee that the returned
1624 used by the forms library. It is intended to be used by applications
1625 to store private per-field data. You can manipulate it with:
1626 int set_field_userptr(FIELD *field, /* field to alter */
1627 char *userptr); /* mode to set */
1631 (Properly, this user pointer field ought to have (void *) type. The
1634 It is valid to set the user pointer of the default field (with a
1636 field is created, the default-field user pointer is copied to
1643 and will automatically resize itself to accommodate data as it is
1648 width, scrolling horizontally to display data within the field area as
1651 vertically to display data within the field area as originally
1654 Normally, a dynamic field is allowed to grow without limit. But it is
1655 possible to set an upper limit on the size of a dynamic field. You do
1657 int set_max_field(FIELD *field, /* field to alter (may not be NULL) */
1660 If the field is one-line, max_size is taken to be a column size limit;
1661 if it is multi-line, it is taken to be a line size limit. To disable
1675 the field; use dynamic_field_info() to get the actual dynamic
1681 buffer. However, it is possible to attach a validation type to a
1682 field. If you do this, any attempt to leave the field while it
1692 and gives you the capability to define custom ones of your own. You
1695 int set_field_type(FIELD *field, /* field to alter */
1696 FIELDTYPE *ftype, /* type to associate */
1699 FIELDTYPE *field_type(FIELD *field); /* field to query */
1713 int set_field_type(FIELD *field, /* field to alter */
1714 TYPE_ALPHA, /* type to associate */
1718 want to set this to the field width; if it is greater than the field
1727 int set_field_type(FIELD *field, /* field to alter */
1728 TYPE_ALNUM, /* type to associate */
1732 typically you will want to set this to the field width; if it is
1738 This type allows you to restrict a field's values to be among a
1741 int set_field_type(FIELD *field, /* field to alter */
1742 TYPE_ENUM, /* type to associate */
1752 to complete the data in the buffer to a valid entry. If a complete
1754 possible to enter a prefix of a valid string and have it completed for
1758 value in the string list, the prefix will be completed to the first
1760 matches to be unique in order to be valid.
1768 int set_field_type(FIELD *field, /* field to alter */
1769 TYPE_INTEGER, /* type to associate */
1770 int padding, /* # places to zero-pad to */
1775 equal to the minimum, the range is ignored.
1778 zero digits as necessary to meet the padding argument.
1786 int set_field_type(FIELD *field, /* field to alter */
1787 TYPE_NUMERIC, /* type to associate */
1795 less than or equal to the minimum, the range is ignored.
1798 trailing zero digits as necessary to meet the padding argument.
1807 int set_field_type(FIELD *field, /* field to alter */
1808 TYPE_REGEXP, /* type to associate */
1809 char *regexp); /* expression to match */
1817 been completed, your application usually needs to know the state of
1819 char *field_buffer(FIELD *field, /* field to query */
1820 int bufindex); /* number of buffer to query */
1823 by the user's editing actions on that field. It is sometimes useful to
1824 be able to set the value of the zero-numbered (or some other) buffer
1826 int set_field_buffer(FIELD *field, /* field to alter */
1827 int bufindex, /* number of buffer to alter */
1828 char *value); /* string value to set */
1830 If the field is not large enough and cannot be resized to a
1831 sufficiently large size to contain the specified value, the value will
1832 be truncated to fit.
1838 buffer value, because entered data is not necessarily copied to buffer
1839 zero before the exit validation check. To guarantee that the returned
1853 int set_form_fields(FORM *form, /* form to alter */
1854 FIELD **fields); /* fields to connect */
1863 eligible to be connected to other forms), then the new fields are
1870 connected to a given from. It returns -1 if the form-pointer argument
1875 In the overview section, you saw that to display a form you normally
1883 frame window on your screen display. This can be useful if you want to
1884 adapt the form display to different screen sizes, dynamically tile
1898 In order to declare your own frame window for a form, you will need to
1901 int scale_form(FORM *form, /* form to query */
1905 The form dimensions are passed back in the locations pointed to by the
1906 arguments. Once you have this information, you can use it to declare
1908 int set_form_win(FORM *form, /* form to alter */
1909 WINDOW *win); /* frame window to connect */
1913 int set_form_sub(FORM *form, /* form to alter */
1914 WINDOW *win); /* form subwindow to connect */
1921 It is possible to check from your application whether all of a
1924 int data_ahead(FORM *form); /* form to be queried */
1926 int data_behind(FORM *form); /* form to be queried */
1929 one-line and has undisplayed data off to the right, (b) the current
1935 Finally, there is a function to restore the form window's cursor to
1937 int pos_form_cursor(FORM *) /* form to be queried */
1940 before handing control back to the forms driver in order to
1948 int form_driver(FORM *form, /* form to pass input to */
1951 Your input virtualization function needs to take input and then
1952 convert it to either an alphanumeric character (which is treated as
1953 data to be entered in the currently-selected field), or a forms
1966 Move to the next form page.
1969 Move to the previous form page.
1972 Move to the first form page.
1975 Move to the last form page.
1978 the last page goes to the first, and REQ_PREV_PAGE from the first page
1979 goes to the last.
1986 Move to next field.
1989 Move to previous field.
1992 Move to the first field.
1995 Move to the last field.
1998 Move to sorted next field.
2001 Move to sorted previous field.
2004 Move to the sorted first field.
2007 Move to the sorted last field.
2010 Move left to field.
2013 Move right to field.
2016 Move up to field.
2019 Move down to field.
2022 REQ_NEXT_FIELD from the last field goes to the first, and
2023 REQ_PREV_FIELD from the first field goes to the last. The order of the
2028 It is also possible to traverse the fields as if they had been sorted
2029 in screen-position order, so the sequence goes left-to-right and
2030 top-to-bottom. To do this, use the second group of four
2033 Finally, it is possible to move between fields using visual directions
2034 up, down, right, and left. To accomplish this, use the third group of
2039 single-line fields A and C on the same line with B, with A to the left
2040 of B and C to the right of B. A REQ_MOVE_RIGHT from A will go to B
2042 skip over B to C.
2050 Move to next character.
2053 Move to previous character.
2056 Move to next line.
2059 Move to previous line.
2062 Move to next word.
2065 Move to previous word.
2068 Move to beginning of field.
2071 Move to end of field.
2074 Move to beginning of line.
2077 Move to end of line.
2092 whitespace. The commands to move to beginning and end of line or field
2101 field to keep the cursor visible). It is possible to explicitly
2146 request to add the character to the field's data buffer. Whether this
2181 Clear to end of line.
2184 Clear to end of field.
2196 The normal behavior of REQ_NEW_LINE in insert mode is to break the
2199 current and moving the cursor to the beginning of that new line (you
2202 The normal behavior of REQ_NEW_LINE in overlay mode is to clear the
2203 current line from the position of the edit cursor to end of line. The
2204 cursor is then moved to the beginning of the next line.
2212 The normal behavior of REQ_DEL_PREV is to delete the previous
2215 instead appends the contents of the current line to the previous one
2225 See Form Options for discussion of how to set and clear the overload
2248 greater than KEY_MAX and less than or equal to the constant
2254 It is possible to set function hooks to be executed whenever the
2257 typedef void (*HOOK)(); /* pointer to function returning void */
2259 int set_form_init(FORM *form, /* form to alter */
2262 HOOK form_init(FORM *form); /* form to query */
2264 int set_form_term(FORM *form, /* form to alter */
2267 HOOK form_term(FORM *form); /* form to query */
2269 int set_field_init(FORM *form, /* form to alter */
2272 HOOK field_init(FORM *form); /* form to query */
2274 int set_field_term(FORM *form, /* form to alter */
2277 HOOK field_term(FORM *form); /* form to query */
2279 These functions allow you to either set or query four different hooks.
2301 Calls to these hooks may be triggered
2311 You can disable any of these hooks by (re)setting them to NULL, the
2317 input requests. But sometimes it is useful to be able to move the
2321 int set_current_field(FORM *form, /* form to alter */
2322 FIELD *field); /* field to shift to */
2324 FIELD *current_field(FORM *form); /* form to query */
2326 int field_index(FORM *form, /* form to query */
2327 FIELD *field); /* field to get index of */
2330 given form's field array (the array passed to new_form() or
2336 It is also possible to move around by pages.
2337 int set_form_page(FORM *form, /* form to alter */
2338 int page); /* page to go to (0-origin) */
2349 int set_form_opts(FORM *form, /* form to alter */
2350 int attr); /* attribute to set */
2352 int form_opts_on(FORM *form, /* form to alter */
2353 int attr); /* attributes to turn on */
2355 int form_opts_off(FORM *form, /* form to alter */
2356 int attr); /* attributes to turn off */
2358 int form_opts(FORM *form); /* form to query */
2378 The form library gives you the capability to define custom validation
2380 set_field_type effectively allow you to parameterize validation types.
2381 Most of the complications in the validation-type interface have to do
2387 The simplest way to create a custom data type is to compose it from
2399 first type, then for the second, to figure what type the buffer
2404 To create a field type from scratch, you need to specify one or both
2406 * A character-validation function, to check each character as it is
2408 * A field-validation function to be applied on exit from the field.
2411 typedef int (*HOOK)(); /* pointer to function returning int */
2416 int free_fieldtype(FIELDTYPE *ftype); /* type to free */
2425 Normally, a field validator is called when the user attempts to leave
2427 get to field buffer 0 and test it. If the function returns TRUE, the
2440 field-type-specific arguments passed to set_field_type(). If no such
2444 In order to arrange for such arguments to be passed to your validation
2446 functions with the type. The forms driver will use these to synthesize
2448 and a pointer to the pile will be passed to the validation functions.
2451 typedef char *(*PTRHOOK)(); /* pointer to function returning (char *) */
2452 typedef void (*VOIDHOOK)(); /* pointer to function returning void */
2454 int set_fieldtype_arg(FIELDTYPE *type, /* type to alter */
2463 argument, a va_list of the type-specific arguments passed to
2464 set_field_type(). It is expected to return a pile pointer to a
2469 new field instances. It is expected to take a pile pointer,
2470 copy the pile to allocated storage, and return the address of
2476 is expected to free the storage of that pile.
2478 The make_str and copy_str functions may return NULL to signal
2487 way that TYPE_ENUM is. For such types, it is possible to define
2488 successor and predecessor functions to support the REQ_NEXT_CHOICE and
2490 typedef int (*INTHOOK)(); /* pointer to function returning int */
2492 int set_fieldtype_arg(FIELDTYPE *type, /* type to alter */
2498 functions). They are expected to use the function field_buffer() to
2499 read the current value, and set_field_buffer() on buffer 0 to set the
2500 next or previous value. Either hook may return TRUE to indicate
2501 success (a legal next or previous value was set) or FALSE to indicate
2507 Rather than attempting to create a custom type entirely from scratch,
2509 the pre-defined types seems to be closest to what you want.
2514 copyright to support this.
2517 intuitive with a blank field. A useful convention is to make the