ncurses 5.0
[ncurses.git] / misc / ncurses-intro.doc
1
2                          Writing Programs with NCURSES
3                                        
4      by Eric S. Raymond and Zeyd M. Ben-Halim
5      updates since release 1.9.9e by Thomas Dickey
6      
7                                    Contents
8                                        
9      * Introduction
10           + A Brief History of Curses
11           + Scope of This Document
12           + Terminology
13      * The Curses Library
14           + An Overview of Curses
15                o Compiling Programs using Curses
16                o Updating the Screen
17                o Standard Windows and Function Naming Conventions
18                o Variables
19           + Using the Library
20                o Starting up
21                o Output
22                o Input
23                o Using Forms Characters
24                o Character Attributes and Color
25                o Mouse Interfacing
26                o Finishing Up
27           + Function Descriptions
28                o Initialization and Wrapup
29                o Causing Output to the Terminal
30                o Low-Level Capability Access
31                o Debugging
32           + Hints, Tips, and Tricks
33                o Some Notes of Caution
34                o Temporarily Leaving ncurses Mode
35                o Using ncurses under xterm
36                o Handling Multiple Terminal Screens
37                o Testing for Terminal Capabilities
38                o Tuning for Speed
39                o Special Features of ncurses
40           + Compatibility with Older Versions
41                o Refresh of Overlapping Windows
42                o Background Erase
43           + XSI Curses Conformance
44      * The Panels Library
45           + Compiling With the Panels Library
46           + Overview of Panels
47           + Panels, Input, and the Standard Screen
48           + Hiding Panels
49           + Miscellaneous Other Facilities
50      * The Menu Library
51           + Compiling with the menu Library
52           + Overview of Menus
53           + Selecting items
54           + Menu Display
55           + Menu Windows
56           + Processing Menu Input
57           + Miscellaneous Other Features
58      * The Forms Library
59           + Compiling with the forms Library
60           + Overview of Forms
61           + Creating and Freeing Fields and Forms
62           + Fetching and Changing Field Attributes
63                o Fetching Size and Location Data
64                o Changing the Field Location
65                o The Justification Attribute
66                o Field Display Attributes
67                o Field Option Bits
68                o Field Status
69                o Field User Pointer
70           + Variable-Sized Fields
71           + Field Validation
72                o TYPE_ALPHA
73                o TYPE_ALNUM
74                o TYPE_ENUM
75                o TYPE_INTEGER
76                o TYPE_NUMERIC
77                o TYPE_REGEXP
78           + Direct Field Buffer Manipulation
79           + Attributes of Forms
80           + Control of Form Display
81           + Input Processing in the Forms Driver
82                o Page Navigation Requests
83                o Inter-Field Navigation Requests
84                o Intra-Field Navigation Requests
85                o Scrolling Requests
86                o Field Editing Requests
87                o Order Requests
88                o Application Commands
89           + Field Change Hooks
90           + Field Change Commands
91           + Form Options
92           + Custom Validation Types
93                o Union Types
94                o New Field Types
95                o Validation Function Arguments
96                o Order Functions For Custom Types
97                o Avoiding Problems
98      _________________________________________________________________
99    
100                                  Introduction
101                                        
102    This document is an introduction to programming with curses. It is not
103    an exhaustive reference for the curses Application Programming
104    Interface (API); that role is filled by the curses manual pages.
105    Rather, it is intended to help C programmers ease into using the
106    package.
107    
108    This document is aimed at C applications programmers not yet
109    specifically familiar with ncurses. If you are already an experienced
110    curses programmer, you should nevertheless read the sections on Mouse
111    Interfacing, Debugging, Compatibility with Older Versions, and Hints,
112    Tips, and Tricks. These will bring you up to speed on the special
113    features and quirks of the ncurses implementation. If you are not so
114    experienced, keep reading.
115    
116    The curses package is a subroutine library for terminal-independent
117    screen-painting and input-event handling which presents a high level
118    screen model to the programmer, hiding differences between terminal
119    types and doing automatic optimization of output to change one screen
120    full of text into another. Curses uses terminfo, which is a database
121    format that can describe the capabilities of thousands of different
122    terminals.
123    
124    The curses API may seem something of an archaism on UNIX desktops
125    increasingly dominated by X, Motif, and Tcl/Tk. Nevertheless, UNIX
126    still supports tty lines and X supports xterm(1); the curses API has
127    the advantage of (a) back-portability to character-cell terminals, and
128    (b) simplicity. For an application that does not require bit-mapped
129    graphics and multiple fonts, an interface implementation using curses
130    will typically be a great deal simpler and less expensive than one
131    using an X toolkit.
132    
133 A Brief History of Curses
134
135    Historically, the first ancestor of curses was the routines written to
136    provide screen-handling for the game rogue; these used the
137    already-existing termcap database facility for describing terminal
138    capabilities. These routines were abstracted into a documented library
139    and first released with the early BSD UNIX versions.
140    
141    System III UNIX from Bell Labs featured a rewritten and much-improved
142    curses library. It introduced the terminfo format. Terminfo is based
143    on Berkeley's termcap database, but contains a number of improvements
144    and extensions. Parameterized capabilities strings were introduced,
145    making it possible to describe multiple video attributes, and colors
146    and to handle far more unusual terminals than possible with termcap.
147    In the later AT&T System V releases, curses evolved to use more
148    facilities and offer more capabilities, going far beyond BSD curses in
149    power and flexibility.
150    
151 Scope of This Document
152
153    This document describes ncurses, a free implementation of the System V
154    curses API with some clearly marked extensions. It includes the
155    following System V curses features:
156    
157      * Support for multiple screen highlights (BSD curses could only
158        handle one `standout' highlight, usually reverse-video).
159      * Support for line- and box-drawing using forms characters.
160      * Recognition of function keys on input.
161      * Color support.
162      * Support for pads (windows of larger than screen size on which the
163        screen or a subwindow defines a viewport).
164        
165    Also, this package makes use of the insert and delete line and
166    character features of terminals so equipped, and determines how to
167    optimally use these features with no help from the programmer. It
168    allows arbitrary combinations of video attributes to be displayed,
169    even on terminals that leave ``magic cookies'' on the screen to mark
170    changes in attributes.
171    
172    The ncurses package can also capture and use event reports from a
173    mouse in some environments (notably, xterm under the X window system).
174    This document includes tips for using the mouse.
175    
176    The ncurses package was originated by Pavel Curtis. The original
177    maintainer of this package is Zeyd Ben-Halim <zmbenhal@netcom.com>.
178    Eric S. Raymond <esr@snark.thyrsus.com> wrote many of the new features
179    in versions after 1.8.1 and wrote most of this introduction. Jürgen
180    Pfeifer wrote all of the menu and forms code as well as the Ada95
181    binding. Ongoing work is being done by Thomas Dickey and Jürgen
182    Pfeifer. Florian La Roche acts as the maintainer for the Free Software
183    Foundation, which holds the copyright on ncurses. Contact the current
184    maintainers at bug-ncurses@gnu.org.
185    
186    This document also describes the panels extension library, similarly
187    modeled on the SVr4 panels facility. This library allows you to
188    associate backing store with each of a stack or deck of overlapping
189    windows, and provides operations for moving windows around in the
190    stack that change their visibility in the natural way (handling window
191    overlaps).
192    
193    Finally, this document describes in detail the menus and forms
194    extension libraries, also cloned from System V, which support easy
195    construction and sequences of menus and fill-in forms.
196    
197 Terminology
198
199    In this document, the following terminology is used with reasonable
200    consistency:
201    
202    window
203           A data structure describing a sub-rectangle of the screen
204           (possibly the entire screen). You can write to a window as
205           though it were a miniature screen, scrolling independently of
206           other windows on the physical screen.
207           
208    screens
209           A subset of windows which are as large as the terminal screen,
210           i.e., they start at the upper left hand corner and encompass
211           the lower right hand corner. One of these, stdscr, is
212           automatically provided for the programmer.
213           
214    terminal screen
215           The package's idea of what the terminal display currently looks
216           like, i.e., what the user sees now. This is a special screen.
217           
218                               The Curses Library
219                                        
220 An Overview of Curses
221
222   Compiling Programs using Curses
223   
224    In order to use the library, it is necessary to have certain types and
225    variables defined. Therefore, the programmer must have a line:
226           #include <curses.h>
227
228    at the top of the program source. The screen package uses the Standard
229    I/O library, so <curses.h> includes <stdio.h>. <curses.h> also
230    includes <termios.h>, <termio.h>, or <sgtty.h> depending on your
231    system. It is redundant (but harmless) for the programmer to do these
232    includes, too. In linking with curses you need to have -lncurses in
233    your LDFLAGS or on the command line. There is no need for any other
234    libraries.
235    
236   Updating the Screen
237   
238    In order to update the screen optimally, it is necessary for the
239    routines to know what the screen currently looks like and what the
240    programmer wants it to look like next. For this purpose, a data type
241    (structure) named WINDOW is defined which describes a window image to
242    the routines, including its starting position on the screen (the (y,
243    x) coordinates of the upper left hand corner) and its size. One of
244    these (called curscr, for current screen) is a screen image of what
245    the terminal currently looks like. Another screen (called stdscr, for
246    standard screen) is provided by default to make changes on.
247    
248    A window is a purely internal representation. It is used to build and
249    store a potential image of a portion of the terminal. It doesn't bear
250    any necessary relation to what is really on the terminal screen; it's
251    more like a scratchpad or write buffer.
252    
253    To make the section of physical screen corresponding to a window
254    reflect the contents of the window structure, the routine refresh()
255    (or wrefresh() if the window is not stdscr) is called.
256    
257    A given physical screen section may be within the scope of any number
258    of overlapping windows. Also, changes can be made to windows in any
259    order, without regard to motion efficiency. Then, at will, the
260    programmer can effectively say ``make it look like this,'' and let the
261    package implementation determine the most efficient way to repaint the
262    screen.
263    
264   Standard Windows and Function Naming Conventions
265   
266    As hinted above, the routines can use several windows, but two are
267    automatically given: curscr, which knows what the terminal looks like,
268    and stdscr, which is what the programmer wants the terminal to look
269    like next. The user should never actually access curscr directly.
270    Changes should be made to through the API, and then the routine
271    refresh() (or wrefresh()) called.
272    
273    Many functions are defined to use stdscr as a default screen. For
274    example, to add a character to stdscr, one calls addch() with the
275    desired character as argument. To write to a different window. use the
276    routine waddch() (for `w'indow-specific addch()) is provided. This
277    convention of prepending function names with a `w' when they are to be
278    applied to specific windows is consistent. The only routines which do
279    not follow it are those for which a window must always be specified.
280    
281    In order to move the current (y, x) coordinates from one point to
282    another, the routines move() and wmove() are provided. However, it is
283    often desirable to first move and then perform some I/O operation. In
284    order to avoid clumsiness, most I/O routines can be preceded by the
285    prefix 'mv' and the desired (y, x) coordinates prepended to the
286    arguments to the function. For example, the calls
287           move(y, x);
288           addch(ch);
289
290    can be replaced by
291           mvaddch(y, x, ch);
292
293    and
294           wmove(win, y, x);
295           waddch(win, ch);
296
297    can be replaced by
298           mvwaddch(win, y, x, ch);
299
300    Note that the window description pointer (win) comes before the added
301    (y, x) coordinates. If a function requires a window pointer, it is
302    always the first parameter passed.
303    
304   Variables
305   
306    The curses library sets some variables describing the terminal
307    capabilities.
308       type   name      description
309       ------------------------------------------------------------------
310       int    LINES     number of lines on the terminal
311       int    COLS      number of columns on the terminal
312
313    The curses.h also introduces some #define constants and types of
314    general usefulness:
315    
316    bool
317           boolean type, actually a `char' (e.g., bool doneit;)
318           
319    TRUE
320           boolean `true' flag (1).
321           
322    FALSE
323           boolean `false' flag (0).
324           
325    ERR
326           error flag returned by routines on a failure (-1).
327           
328    OK
329           error flag returned by routines when things go right.
330           
331 Using the Library
332
333    Now we describe how to actually use the screen package. In it, we
334    assume all updating, reading, etc. is applied to stdscr. These
335    instructions will work on any window, providing you change the
336    function names and parameters as mentioned above.
337    
338    Here is a sample program to motivate the discussion:
339    
340 #include <curses.h>
341 #include <signal.h>
342
343 static void finish(int sig);
344
345 main(int argc, char *argv[])
346 {
347     /* initialize your non-curses data structures here */
348
349     (void) signal(SIGINT, finish);      /* arrange interrupts to terminate */
350
351     (void) initscr();      /* initialize the curses library */
352     keypad(stdscr, TRUE);  /* enable keyboard mapping */
353     (void) nonl();         /* tell curses not to do NL->CR/NL on output */
354     (void) cbreak();       /* take input chars one at a time, no wait for \n */
355     (void) noecho();       /* don't echo input */
356
357     if (has_colors())
358     {
359         start_color();
360
361         /*
362          * Simple color assignment, often all we need.
363          */
364         init_pair(COLOR_BLACK, COLOR_BLACK, COLOR_BLACK);
365         init_pair(COLOR_GREEN, COLOR_GREEN, COLOR_BLACK);
366         init_pair(COLOR_RED, COLOR_RED, COLOR_BLACK);
367         init_pair(COLOR_CYAN, COLOR_CYAN, COLOR_BLACK);
368         init_pair(COLOR_WHITE, COLOR_WHITE, COLOR_BLACK);
369         init_pair(COLOR_MAGENTA, COLOR_MAGENTA, COLOR_BLACK);
370         init_pair(COLOR_BLUE, COLOR_BLUE, COLOR_BLACK);
371         init_pair(COLOR_YELLOW, COLOR_YELLOW, COLOR_BLACK);
372     }
373
374     for (;;)
375     {
376         int c = getch();     /* refresh, accept single keystroke of input */
377
378         /* process the command keystroke */
379     }
380
381     finish(0);               /* we're done */
382 }
383
384 static void finish(int sig)
385 {
386     endwin();
387
388     /* do your non-curses wrapup here */
389
390     exit(0);
391 }
392
393   Starting up
394   
395    In order to use the screen package, the routines must know about
396    terminal characteristics, and the space for curscr and stdscr must be
397    allocated. These function initscr() does both these things. Since it
398    must allocate space for the windows, it can overflow memory when
399    attempting to do so. On the rare occasions this happens, initscr()
400    will terminate the program with an error message. initscr() must
401    always be called before any of the routines which affect windows are
402    used. If it is not, the program will core dump as soon as either
403    curscr or stdscr are referenced. However, it is usually best to wait
404    to call it until after you are sure you will need it, like after
405    checking for startup errors. Terminal status changing routines like
406    nl() and cbreak() should be called after initscr().
407    
408    Once the screen windows have been allocated, you can set them up for
409    your program. If you want to, say, allow a screen to scroll, use
410    scrollok(). If you want the cursor to be left in place after the last
411    change, use leaveok(). If this isn't done, refresh() will move the
412    cursor to the window's current (y, x) coordinates after updating it.
413    
414    You can create new windows of your own using the functions newwin(),
415    derwin(), and subwin(). The routine delwin() will allow you to get rid
416    of old windows. All the options described above can be applied to any
417    window.
418    
419   Output
420   
421    Now that we have set things up, we will want to actually update the
422    terminal. The basic functions used to change what will go on a window
423    are addch() and move(). addch() adds a character at the current (y, x)
424    coordinates. move() changes the current (y, x) coordinates to whatever
425    you want them to be. It returns ERR if you try to move off the window.
426    As mentioned above, you can combine the two into mvaddch() to do both
427    things at once.
428    
429    The other output functions, such as addstr() and printw(), all call
430    addch() to add characters to the window.
431    
432    After you have put on the window what you want there, when you want
433    the portion of the terminal covered by the window to be made to look
434    like it, you must call refresh(). In order to optimize finding
435    changes, refresh() assumes that any part of the window not changed
436    since the last refresh() of that window has not been changed on the
437    terminal, i.e., that you have not refreshed a portion of the terminal
438    with an overlapping window. If this is not the case, the routine
439    touchwin() is provided to make it look like the entire window has been
440    changed, thus making refresh() check the whole subsection of the
441    terminal for changes.
442    
443    If you call wrefresh() with curscr as its argument, it will make the
444    screen look like curscr thinks it looks like. This is useful for
445    implementing a command which would redraw the screen in case it get
446    messed up.
447    
448   Input
449   
450    The complementary function to addch() is getch() which, if echo is
451    set, will call addch() to echo the character. Since the screen package
452    needs to know what is on the terminal at all times, if characters are
453    to be echoed, the tty must be in raw or cbreak mode. Since initially
454    the terminal has echoing enabled and is in ordinary ``cooked'' mode,
455    one or the other has to changed before calling getch(); otherwise, the
456    program's output will be unpredictable.
457    
458    When you need to accept line-oriented input in a window, the functions
459    wgetstr() and friends are available. There is even a wscanw() function
460    that can do scanf()(3)-style multi-field parsing on window input.
461    These pseudo-line-oriented functions turn on echoing while they
462    execute.
463    
464    The example code above uses the call keypad(stdscr, TRUE) to enable
465    support for function-key mapping. With this feature, the getch() code
466    watches the input stream for character sequences that correspond to
467    arrow and function keys. These sequences are returned as
468    pseudo-character values. The #define values returned are listed in the
469    curses.h The mapping from sequences to #define values is determined by
470    key_ capabilities in the terminal's terminfo entry.
471    
472   Using Forms Characters
473   
474    The addch() function (and some others, including box() and border())
475    can accept some pseudo-character arguments which are specially defined
476    by ncurses. These are #define values set up in the curses.h header;
477    see there for a complete list (look for the prefix ACS_).
478    
479    The most useful of the ACS defines are the forms-drawing characters.
480    You can use these to draw boxes and simple graphs on the screen. If
481    the terminal does not have such characters, curses.h will map them to
482    a recognizable (though ugly) set of ASCII defaults.
483    
484   Character Attributes and Color
485   
486    The ncurses package supports screen highlights including standout,
487    reverse-video, underline, and blink. It also supports color, which is
488    treated as another kind of highlight.
489    
490    Highlights are encoded, internally, as high bits of the
491    pseudo-character type (chtype) that curses.h uses to represent the
492    contents of a screen cell. See the curses.h header file for a complete
493    list of highlight mask values (look for the prefix A_).
494    
495    There are two ways to make highlights. One is to logical-or the value
496    of the highlights you want into the character argument of an addch()
497    call, or any other output call that takes a chtype argument.
498    
499    The other is to set the current-highlight value. This is logical-or'ed
500    with any highlight you specify the first way. You do this with the
501    functions attron(), attroff(), and attrset(); see the manual pages for
502    details. Color is a special kind of highlight. The package actually
503    thinks in terms of color pairs, combinations of foreground and
504    background colors. The sample code above sets up eight color pairs,
505    all of the guaranteed-available colors on black. Note that each color
506    pair is, in effect, given the name of its foreground color. Any other
507    range of eight non-conflicting values could have been used as the
508    first arguments of the init_pair() values.
509    
510    Once you've done an init_pair() that creates color-pair N, you can use
511    COLOR_PAIR(N) as a highlight that invokes that particular color
512    combination. Note that COLOR_PAIR(N), for constant N, is itself a
513    compile-time constant and can be used in initializers.
514    
515   Mouse Interfacing
516   
517    The ncurses library also provides a mouse interface.
518    
519      NOTE: this facility is specific to ncurses, it is not part of
520      either the XSI Curses standard, nor of System V Release 4, nor BSD
521      curses. System V Release 4 curses contains code with similar
522      interface definitions, however it is not documented. Other than by
523      disassembling the library, we have no way to determine exactly how
524      that mouse code works. Thus, we recommend that you wrap
525      mouse-related code in an #ifdef using the feature macro
526      NCURSES_MOUSE_VERSION so it will not be compiled and linked on
527      non-ncurses systems.
528      
529    Presently, mouse event reporting works in the following environments:
530      * xterm and similar programs such as rxvt.
531      * Linux console, when configured with gpm(1), Alessandro Rubini's
532        mouse server.
533      * OS/2 EMX
534        
535    The mouse interface is very simple. To activate it, you use the
536    function mousemask(), passing it as first argument a bit-mask that
537    specifies what kinds of events you want your program to be able to
538    see. It will return the bit-mask of events that actually become
539    visible, which may differ from the argument if the mouse device is not
540    capable of reporting some of the event types you specify.
541    
542    Once the mouse is active, your application's command loop should watch
543    for a return value of KEY_MOUSE from wgetch(). When you see this, a
544    mouse event report has been queued. To pick it off the queue, use the
545    function getmouse() (you must do this before the next wgetch(),
546    otherwise another mouse event might come in and make the first one
547    inaccessible).
548    
549    Each call to getmouse() fills a structure (the address of which you'll
550    pass it) with mouse event data. The event data includes zero-origin,
551    screen-relative character-cell coordinates of the mouse pointer. It
552    also includes an event mask. Bits in this mask will be set,
553    corresponding to the event type being reported.
554    
555    The mouse structure contains two additional fields which may be
556    significant in the future as ncurses interfaces to new kinds of
557    pointing device. In addition to x and y coordinates, there is a slot
558    for a z coordinate; this might be useful with touch-screens that can
559    return a pressure or duration parameter. There is also a device ID
560    field, which could be used to distinguish between multiple pointing
561    devices.
562    
563    The class of visible events may be changed at any time via
564    mousemask(). Events that can be reported include presses, releases,
565    single-, double- and triple-clicks (you can set the maximum
566    button-down time for clicks). If you don't make clicks visible, they
567    will be reported as press-release pairs. In some environments, the
568    event mask may include bits reporting the state of shift, alt, and
569    ctrl keys on the keyboard during the event.
570    
571    A function to check whether a mouse event fell within a given window
572    is also supplied. You can use this to see whether a given window
573    should consider a mouse event relevant to it.
574    
575    Because mouse event reporting will not be available in all
576    environments, it would be unwise to build ncurses applications that
577    require the use of a mouse. Rather, you should use the mouse as a
578    shortcut for point-and-shoot commands your application would normally
579    accept from the keyboard. Two of the test games in the ncurses
580    distribution (bs and knight) contain code that illustrates how this
581    can be done.
582    
583    See the manual page curs_mouse(3X) for full details of the
584    mouse-interface functions.
585    
586   Finishing Up
587   
588    In order to clean up after the ncurses routines, the routine endwin()
589    is provided. It restores tty modes to what they were when initscr()
590    was first called, and moves the cursor down to the lower-left corner.
591    Thus, anytime after the call to initscr, endwin() should be called
592    before exiting.
593    
594 Function Descriptions
595
596    We describe the detailed behavior of some important curses functions
597    here, as a supplement to the manual page descriptions.
598    
599   Initialization and Wrapup
600   
601    initscr()
602           The first function called should almost always be initscr().
603           This will determine the terminal type and initialize curses
604           data structures. initscr() also arranges that the first call to
605           refresh() will clear the screen. If an error occurs a message
606           is written to standard error and the program exits. Otherwise
607           it returns a pointer to stdscr. A few functions may be called
608           before initscr (slk_init(), filter(), ripofflines(), use_env(),
609           and, if you are using multiple terminals, newterm().)
610           
611    endwin()
612           Your program should always call endwin() before exiting or
613           shelling out of the program. This function will restore tty
614           modes, move the cursor to the lower left corner of the screen,
615           reset the terminal into the proper non-visual mode. Calling
616           refresh() or doupdate() after a temporary escape from the
617           program will restore the ncurses screen from before the escape.
618           
619    newterm(type, ofp, ifp)
620           A program which outputs to more than one terminal should use
621           newterm() instead of initscr(). newterm() should be called once
622           for each terminal. It returns a variable of type SCREEN * which
623           should be saved as a reference to that terminal. The arguments
624           are the type of the terminal (a string) and FILE pointers for
625           the output and input of the terminal. If type is NULL then the
626           environment variable $TERM is used. endwin() should called once
627           at wrapup time for each terminal opened using this function.
628           
629    set_term(new)
630           This function is used to switch to a different terminal
631           previously opened by newterm(). The screen reference for the
632           new terminal is passed as the parameter. The previous terminal
633           is returned by the function. All other calls affect only the
634           current terminal.
635           
636    delscreen(sp)
637           The inverse of newterm(); deallocates the data structures
638           associated with a given SCREEN reference.
639           
640   Causing Output to the Terminal
641   
642    refresh() and wrefresh(win)
643           These functions must be called to actually get any output on
644           the terminal, as other routines merely manipulate data
645           structures. wrefresh() copies the named window to the physical
646           terminal screen, taking into account what is already there in
647           order to do optimizations. refresh() does a refresh of
648           stdscr(). Unless leaveok() has been enabled, the physical
649           cursor of the terminal is left at the location of the window's
650           cursor.
651           
652    doupdate() and wnoutrefresh(win)
653           These two functions allow multiple updates with more efficiency
654           than wrefresh. To use them, it is important to understand how
655           curses works. In addition to all the window structures, curses
656           keeps two data structures representing the terminal screen: a
657           physical screen, describing what is actually on the screen, and
658           a virtual screen, describing what the programmer wants to have
659           on the screen. wrefresh works by first copying the named window
660           to the virtual screen (wnoutrefresh()), and then calling the
661           routine to update the screen (doupdate()). If the programmer
662           wishes to output several windows at once, a series of calls to
663           wrefresh will result in alternating calls to wnoutrefresh() and
664           doupdate(), causing several bursts of output to the screen. By
665           calling wnoutrefresh() for each window, it is then possible to
666           call doupdate() once, resulting in only one burst of output,
667           with fewer total characters transmitted (this also avoids a
668           visually annoying flicker at each update).
669           
670   Low-Level Capability Access
671   
672    setupterm(term, filenum, errret)
673           This routine is called to initialize a terminal's description,
674           without setting up the curses screen structures or changing the
675           tty-driver mode bits. term is the character string representing
676           the name of the terminal being used. filenum is the UNIX file
677           descriptor of the terminal to be used for output. errret is a
678           pointer to an integer, in which a success or failure indication
679           is returned. The values returned can be 1 (all is well), 0 (no
680           such terminal), or -1 (some problem locating the terminfo
681           database).
682           
683           The value of term can be given as NULL, which will cause the
684           value of TERM in the environment to be used. The errret pointer
685           can also be given as NULL, meaning no error code is wanted. If
686           errret is defaulted, and something goes wrong, setupterm() will
687           print an appropriate error message and exit, rather than
688           returning. Thus, a simple program can call setupterm(0, 1, 0)
689           and not worry about initialization errors.
690           
691           After the call to setupterm(), the global variable cur_term is
692           set to point to the current structure of terminal capabilities.
693           By calling setupterm() for each terminal, and saving and
694           restoring cur_term, it is possible for a program to use two or
695           more terminals at once. Setupterm() also stores the names
696           section of the terminal description in the global character
697           array ttytype[]. Subsequent calls to setupterm() will overwrite
698           this array, so you'll have to save it yourself if need be.
699           
700   Debugging
701   
702      NOTE: These functions are not part of the standard curses API!
703      
704    trace()
705           This function can be used to explicitly set a trace level. If
706           the trace level is nonzero, execution of your program will
707           generate a file called `trace' in the current working directory
708           containing a report on the library's actions. Higher trace
709           levels enable more detailed (and verbose) reporting -- see
710           comments attached to TRACE_ defines in the curses.h file for
711           details. (It is also possible to set a trace level by assigning
712           a trace level value to the environment variable NCURSES_TRACE).
713           
714    _tracef()
715           This function can be used to output your own debugging
716           information. It is only available only if you link with
717           -lncurses_g. It can be used the same way as printf(), only it
718           outputs a newline after the end of arguments. The output goes
719           to a file called trace in the current directory.
720           
721    Trace logs can be difficult to interpret due to the sheer volume of
722    data dumped in them. There is a script called tracemunch included with
723    the ncurses distribution that can alleviate this problem somewhat; it
724    compacts long sequences of similar operations into more succinct
725    single-line pseudo-operations. These pseudo-ops can be distinguished
726    by the fact that they are named in capital letters.
727    
728 Hints, Tips, and Tricks
729
730    The ncurses manual pages are a complete reference for this library. In
731    the remainder of this document, we discuss various useful methods that
732    may not be obvious from the manual page descriptions.
733    
734   Some Notes of Caution
735   
736    If you find yourself thinking you need to use noraw() or nocbreak(),
737    think again and move carefully. It's probably better design to use
738    getstr() or one of its relatives to simulate cooked mode. The noraw()
739    and nocbreak() functions try to restore cooked mode, but they may end
740    up clobbering some control bits set before you started your
741    application. Also, they have always been poorly documented, and are
742    likely to hurt your application's usability with other curses
743    libraries.
744    
745    Bear in mind that refresh() is a synonym for wrefresh(stdscr). Don't
746    try to mix use of stdscr with use of windows declared by newwin(); a
747    refresh() call will blow them off the screen. The right way to handle
748    this is to use subwin(), or not touch stdscr at all and tile your
749    screen with declared windows which you then wnoutrefresh() somewhere
750    in your program event loop, with a single doupdate() call to trigger
751    actual repainting.
752    
753    You are much less likely to run into problems if you design your
754    screen layouts to use tiled rather than overlapping windows.
755    Historically, curses support for overlapping windows has been weak,
756    fragile, and poorly documented. The ncurses library is not yet an
757    exception to this rule.
758    
759    There is a panels library included in the ncurses distribution that
760    does a pretty good job of strengthening the overlapping-windows
761    facilities.
762    
763    Try to avoid using the global variables LINES and COLS. Use getmaxyx()
764    on the stdscr context instead. Reason: your code may be ported to run
765    in an environment with window resizes, in which case several screens
766    could be open with different sizes.
767    
768   Temporarily Leaving NCURSES Mode
769   
770    Sometimes you will want to write a program that spends most of its
771    time in screen mode, but occasionally returns to ordinary `cooked'
772    mode. A common reason for this is to support shell-out. This behavior
773    is simple to arrange in ncurses.
774    
775    To leave ncurses mode, call endwin() as you would if you were
776    intending to terminate the program. This will take the screen back to
777    cooked mode; you can do your shell-out. When you want to return to
778    ncurses mode, simply call refresh() or doupdate(). This will repaint
779    the screen.
780    
781    There is a boolean function, isendwin(), which code can use to test
782    whether ncurses screen mode is active. It returns TRUE in the interval
783    between an endwin() call and the following refresh(), FALSE otherwise.
784    
785    Here is some sample code for shellout:
786     addstr("Shelling out...");
787     def_prog_mode();           /* save current tty modes */
788     endwin();                  /* restore original tty modes */
789     system("sh");              /* run shell */
790     addstr("returned.\n");     /* prepare return message */
791     refresh();                 /* restore save modes, repaint screen */
792
793   Using NCURSES under XTERM
794   
795    A resize operation in X sends SIGWINCH to the application running
796    under xterm. The ncurses library provides an experimental signal
797    handler, but in general does not catch this signal, because it cannot
798    know how you want the screen re-painted. You will usually have to
799    write the SIGWINCH handler yourself. Ncurses can give you some help.
800    
801    The easiest way to code your SIGWINCH handler is to have it do an
802    endwin, followed by an refresh and a screen repaint you code yourself.
803    The refresh will pick up the new screen size from the xterm's
804    environment.
805    
806    That is the standard way, of course (it even works with some vendor's
807    curses implementations). Its drawback is that it clears the screen to
808    reinitialize the display, and does not resize subwindows which must be
809    shrunk. Ncurses provides an extension which works better, the
810    resizeterm function. That function ensures that all windows are
811    limited to the new screen dimensions, and pads stdscr with blanks if
812    the screen is larger.
813    
814    Finally, ncurses can be configured to provide its own SIGWINCH
815    handler, based on resizeterm.
816    
817   Handling Multiple Terminal Screens
818   
819    The initscr() function actually calls a function named newterm() to do
820    most of its work. If you are writing a program that opens multiple
821    terminals, use newterm() directly.
822    
823    For each call, you will have to specify a terminal type and a pair of
824    file pointers; each call will return a screen reference, and stdscr
825    will be set to the last one allocated. You will switch between screens
826    with the set_term call. Note that you will also have to call
827    def_shell_mode and def_prog_mode on each tty yourself.
828    
829   Testing for Terminal Capabilities
830   
831    Sometimes you may want to write programs that test for the presence of
832    various capabilities before deciding whether to go into ncurses mode.
833    An easy way to do this is to call setupterm(), then use the functions
834    tigetflag(), tigetnum(), and tigetstr() to do your testing.
835    
836    A particularly useful case of this often comes up when you want to
837    test whether a given terminal type should be treated as `smart'
838    (cursor-addressable) or `stupid'. The right way to test this is to see
839    if the return value of tigetstr("cup") is non-NULL. Alternatively, you
840    can include the term.h file and test the value of the macro
841    cursor_address.
842    
843   Tuning for Speed
844   
845    Use the addchstr() family of functions for fast screen-painting of
846    text when you know the text doesn't contain any control characters.
847    Try to make attribute changes infrequent on your screens. Don't use
848    the immedok() option!
849    
850   Special Features of NCURSES
851   
852    The wresize() function allows you to resize a window in place. The
853    associated resizeterm() function simplifies the construction of
854    SIGWINCH handlers, for resizing all windows.
855    
856    The define_key() function allows you to define at runtime function-key
857    control sequences which are not in the terminal description. The
858    keyok() function allows you to temporarily enable or disable
859    interpretation of any function-key control sequence.
860    
861    The use_default_colors() function allows you to construct applications
862    which can use the terminal's default foreground and background colors
863    as an additional "default" color. Several terminal emulators support
864    this feature, which is based on ISO 6429.
865    
866    Ncurses supports up 16 colors, unlike SVr4 curses which defines only
867    8. While most terminals which provide color allow only 8 colors, about
868    a quarter (including XFree86 xterm) support 16 colors.
869    
870 Compatibility with Older Versions
871
872    Despite our best efforts, there are some differences between ncurses
873    and the (undocumented!) behavior of older curses implementations.
874    These arise from ambiguities or omissions in the documentation of the
875    API.
876    
877   Refresh of Overlapping Windows
878   
879    If you define two windows A and B that overlap, and then alternately
880    scribble on and refresh them, the changes made to the overlapping
881    region under historic curses versions were often not documented
882    precisely.
883    
884    To understand why this is a problem, remember that screen updates are
885    calculated between two representations of the entire display. The
886    documentation says that when you refresh a window, it is first copied
887    to to the virtual screen, and then changes are calculated to update
888    the physical screen (and applied to the terminal). But "copied to" is
889    not very specific, and subtle differences in how copying works can
890    produce different behaviors in the case where two overlapping windows
891    are each being refreshed at unpredictable intervals.
892    
893    What happens to the overlapping region depends on what wnoutrefresh()
894    does with its argument -- what portions of the argument window it
895    copies to the virtual screen. Some implementations do "change copy",
896    copying down only locations in the window that have changed (or been
897    marked changed with wtouchln() and friends). Some implementations do
898    "entire copy", copying all window locations to the virtual screen
899    whether or not they have changed.
900    
901    The ncurses library itself has not always been consistent on this
902    score. Due to a bug, versions 1.8.7 to 1.9.8a did entire copy.
903    Versions 1.8.6 and older, and versions 1.9.9 and newer, do change
904    copy.
905    
906    For most commercial curses implementations, it is not documented and
907    not known for sure (at least not to the ncurses maintainers) whether
908    they do change copy or entire copy. We know that System V release 3
909    curses has logic in it that looks like an attempt to do change copy,
910    but the surrounding logic and data representations are sufficiently
911    complex, and our knowledge sufficiently indirect, that it's hard to
912    know whether this is reliable. It is not clear what the SVr4
913    documentation and XSI standard intend. The XSI Curses standard barely
914    mentions wnoutrefresh(); the SVr4 documents seem to be describing
915    entire-copy, but it is possible with some effort and straining to read
916    them the other way.
917    
918    It might therefore be unwise to rely on either behavior in programs
919    that might have to be linked with other curses implementations.
920    Instead, you can do an explicit touchwin() before the wnoutrefresh()
921    call to guarantee an entire-contents copy anywhere.
922    
923    The really clean way to handle this is to use the panels library. If,
924    when you want a screen update, you do update_panels(), it will do all
925    the necessary wnoutrfresh() calls for whatever panel stacking order
926    you have defined. Then you can do one doupdate() and there will be a
927    single burst of physical I/O that will do all your updates.
928    
929   Background Erase
930   
931    If you have been using a very old versions of ncurses (1.8.7 or older)
932    you may be surprised by the behavior of the erase functions. In older
933    versions, erased areas of a window were filled with a blank modified
934    by the window's current attribute (as set by wattrset(), wattron(),
935    wattroff() and friends).
936    
937    In newer versions, this is not so. Instead, the attribute of erased
938    blanks is normal unless and until it is modified by the functions
939    bkgdset() or wbkgdset().
940    
941    This change in behavior conforms ncurses to System V Release 4 and the
942    XSI Curses standard.
943    
944 XSI Curses Conformance
945
946    The ncurses library is intended to be base-level conformant with the
947    XSI Curses standard from X/Open. Many extended-level features (in
948    fact, almost all features not directly concerned with wide characters
949    and internationalization) are also supported.
950    
951    One effect of XSI conformance is the change in behavior described
952    under "Background Erase -- Compatibility with Old Versions".
953    
954    Also, ncurses meets the XSI requirement that every macro entry point
955    have a corresponding function which may be linked (and will be
956    prototype-checked) if the macro definition is disabled with #undef.
957    
958                               The Panels Library
959                                        
960    The ncurses library by itself provides good support for screen
961    displays in which the windows are tiled (non-overlapping). In the more
962    general case that windows may overlap, you have to use a series of
963    wnoutrefresh() calls followed by a doupdate(), and be careful about
964    the order you do the window refreshes in. It has to be bottom-upwards,
965    otherwise parts of windows that should be obscured will show through.
966    
967    When your interface design is such that windows may dive deeper into
968    the visibility stack or pop to the top at runtime, the resulting
969    book-keeping can be tedious and difficult to get right. Hence the
970    panels library.
971    
972    The panel library first appeared in AT&T System V. The version
973    documented here is the panel code distributed with ncurses.
974    
975 Compiling With the Panels Library
976
977    Your panels-using modules must import the panels library declarations
978    with
979           #include <panel.h>
980
981    and must be linked explicitly with the panels library using an -lpanel
982    argument. Note that they must also link the ncurses library with
983    -lncurses. Many linkers are two-pass and will accept either order, but
984    it is still good practice to put -lpanel first and -lncurses second.
985    
986 Overview of Panels
987
988    A panel object is a window that is implicitly treated as part of a
989    deck including all other panel objects. The deck has an implicit
990    bottom-to-top visibility order. The panels library includes an update
991    function (analogous to refresh()) that displays all panels in the deck
992    in the proper order to resolve overlaps. The standard window, stdscr,
993    is considered below all panels.
994    
995    Details on the panels functions are available in the man pages. We'll
996    just hit the highlights here.
997    
998    You create a panel from a window by calling new_panel() on a window
999    pointer. It then becomes the top of the deck. The panel's window is
1000    available as the value of panel_window() called with the panel pointer
1001    as argument.
1002    
1003    You can delete a panel (removing it from the deck) with del_panel.
1004    This will not deallocate the associated window; you have to do that
1005    yourself. You can replace a panel's window with a different window by
1006    calling replace_window. The new window may be of different size; the
1007    panel code will re-compute all overlaps. This operation doesn't change
1008    the panel's position in the deck.
1009    
1010    To move a panel's window, use move_panel(). The mvwin() function on
1011    the panel's window isn't sufficient because it doesn't update the
1012    panels library's representation of where the windows are. This
1013    operation leaves the panel's depth, contents, and size unchanged.
1014    
1015    Two functions (top_panel(), bottom_panel()) are provided for
1016    rearranging the deck. The first pops its argument window to the top of
1017    the deck; the second sends it to the bottom. Either operation leaves
1018    the panel's screen location, contents, and size unchanged.
1019    
1020    The function update_panels() does all the wnoutrefresh() calls needed
1021    to prepare for doupdate() (which you must call yourself, afterwards).
1022    
1023    Typically, you will want to call update_panels() and doupdate() just
1024    before accepting command input, once in each cycle of interaction with
1025    the user. If you call update_panels() after each and every panel
1026    write, you'll generate a lot of unnecessary refresh activity and
1027    screen flicker.
1028    
1029 Panels, Input, and the Standard Screen
1030
1031    You shouldn't mix wnoutrefresh() or wrefresh() operations with panels
1032    code; this will work only if the argument window is either in the top
1033    panel or unobscured by any other panels.
1034    
1035    The stsdcr window is a special case. It is considered below all
1036    panels. Because changes to panels may obscure parts of stdscr, though,
1037    you should call update_panels() before doupdate() even when you only
1038    change stdscr.
1039    
1040    Note that wgetch automatically calls wrefresh. Therefore, before
1041    requesting input from a panel window, you need to be sure that the
1042    panel is totally unobscured.
1043    
1044    There is presently no way to display changes to one obscured panel
1045    without repainting all panels.
1046    
1047 Hiding Panels
1048
1049    It's possible to remove a panel from the deck temporarily; use
1050    hide_panel for this. Use show_panel() to render it visible again. The
1051    predicate function panel_hidden tests whether or not a panel is
1052    hidden.
1053    
1054    The panel_update code ignores hidden panels. You cannot do top_panel()
1055    or bottom_panel on a hidden panel(). Other panels operations are
1056    applicable.
1057    
1058 Miscellaneous Other Facilities
1059
1060    It's possible to navigate the deck using the functions panel_above()
1061    and panel_below. Handed a panel pointer, they return the panel above
1062    or below that panel. Handed NULL, they return the bottom-most or
1063    top-most panel.
1064    
1065    Every panel has an associated user pointer, not used by the panel
1066    code, to which you can attach application data. See the man page
1067    documentation of set_panel_userptr() and panel_userptr for details.
1068    
1069                                The Menu Library
1070                                        
1071    A menu is a screen display that assists the user to choose some subset
1072    of a given set of items. The menu library is a curses extension that
1073    supports easy programming of menu hierarchies with a uniform but
1074    flexible interface.
1075    
1076    The menu library first appeared in AT&T System V. The version
1077    documented here is the menu code distributed with ncurses.
1078    
1079 Compiling With the menu Library
1080
1081    Your menu-using modules must import the menu library declarations with
1082           #include <menu.h>
1083
1084    and must be linked explicitly with the menus library using an -lmenu
1085    argument. Note that they must also link the ncurses library with
1086    -lncurses. Many linkers are two-pass and will accept either order, but
1087    it is still good practice to put -lmenu first and -lncurses second.
1088    
1089 Overview of Menus
1090
1091    The menus created by this library consist of collections of items
1092    including a name string part and a description string part. To make
1093    menus, you create groups of these items and connect them with menu
1094    frame objects.
1095    
1096    The menu can then by posted, that is written to an associated window.
1097    Actually, each menu has two associated windows; a containing window in
1098    which the programmer can scribble titles or borders, and a subwindow
1099    in which the menu items proper are displayed. If this subwindow is too
1100    small to display all the items, it will be a scrollable viewport on
1101    the collection of items.
1102    
1103    A menu may also be unposted (that is, undisplayed), and finally freed
1104    to make the storage associated with it and its items available for
1105    re-use.
1106    
1107    The general flow of control of a menu program looks like this:
1108     1. Initialize curses.
1109     2. Create the menu items, using new_item().
1110     3. Create the menu using new_menu().
1111     4. Post the menu using menu_post().
1112     5. Refresh the screen.
1113     6. Process user requests via an input loop.
1114     7. Unpost the menu using menu_unpost().
1115     8. Free the menu, using free_menu().
1116     9. Free the items using free_item().
1117    10. Terminate curses.
1118        
1119 Selecting items
1120
1121    Menus may be multi-valued or (the default) single-valued (see the
1122    manual page menu_opts(3x) to see how to change the default). Both
1123    types always have a current item.
1124    
1125    From a single-valued menu you can read the selected value simply by
1126    looking at the current item. From a multi-valued menu, you get the
1127    selected set by looping through the items applying the item_value()
1128    predicate function. Your menu-processing code can use the function
1129    set_item_value() to flag the items in the select set.
1130    
1131    Menu items can be made unselectable using set_item_opts() or
1132    item_opts_off() with the O_SELECTABLE argument. This is the only
1133    option so far defined for menus, but it is good practice to code as
1134    though other option bits might be on.
1135    
1136 Menu Display
1137
1138    The menu library calculates a minimum display size for your window,
1139    based on the following variables:
1140    
1141      * The number and maximum length of the menu items
1142      * Whether the O_ROWMAJOR option is enabled
1143      * Whether display of descriptions is enabled
1144      * Whatever menu format may have been set by the programmer
1145      * The length of the menu mark string used for highlighting selected
1146        items
1147        
1148    The function set_menu_format() allows you to set the maximum size of
1149    the viewport or menu page that will be used to display menu items. You
1150    can retrieve any format associated with a menu with menu_format(). The
1151    default format is rows=16, columns=1.
1152    
1153    The actual menu page may be smaller than the format size. This depends
1154    on the item number and size and whether O_ROWMAJOR is on. This option
1155    (on by default) causes menu items to be displayed in a `raster-scan'
1156    pattern, so that if more than one item will fit horizontally the first
1157    couple of items are side-by-side in the top row. The alternative is
1158    column-major display, which tries to put the first several items in
1159    the first column.
1160    
1161    As mentioned above, a menu format not large enough to allow all items
1162    to fit on-screen will result in a menu display that is vertically
1163    scrollable.
1164    
1165    You can scroll it with requests to the menu driver, which will be
1166    described in the section on menu input handling.
1167    
1168    Each menu has a mark string used to visually tag selected items; see
1169    the menu_mark(3x) manual page for details. The mark string length also
1170    influences the menu page size.
1171    
1172    The function scale_menu() returns the minimum display size that the
1173    menu code computes from all these factors. There are other menu
1174    display attributes including a select attribute, an attribute for
1175    selectable items, an attribute for unselectable items, and a pad
1176    character used to separate item name text from description text. These
1177    have reasonable defaults which the library allows you to change (see
1178    the menu_attribs(3x) manual page.
1179    
1180 Menu Windows
1181
1182    Each menu has, as mentioned previously, a pair of associated windows.
1183    Both these windows are painted when the menu is posted and erased when
1184    the menu is unposted.
1185    
1186    The outer or frame window is not otherwise touched by the menu
1187    routines. It exists so the programmer can associate a title, a border,
1188    or perhaps help text with the menu and have it properly refreshed or
1189    erased at post/unpost time. The inner window or subwindow is where the
1190    current menu page is displayed.
1191    
1192    By default, both windows are stdscr. You can set them with the
1193    functions in menu_win(3x).
1194    
1195    When you call menu_post(), you write the menu to its subwindow. When
1196    you call menu_unpost(), you erase the subwindow, However, neither of
1197    these actually modifies the screen. To do that, call wrefresh() or
1198    some equivalent.
1199    
1200 Processing Menu Input
1201
1202    The main loop of your menu-processing code should call menu_driver()
1203    repeatedly. The first argument of this routine is a menu pointer; the
1204    second is a menu command code. You should write an input-fetching
1205    routine that maps input characters to menu command codes, and pass its
1206    output to menu_driver(). The menu command codes are fully documented
1207    in menu_driver(3x).
1208    
1209    The simplest group of command codes is REQ_NEXT_ITEM, REQ_PREV_ITEM,
1210    REQ_FIRST_ITEM, REQ_LAST_ITEM, REQ_UP_ITEM, REQ_DOWN_ITEM,
1211    REQ_LEFT_ITEM, REQ_RIGHT_ITEM. These change the currently selected
1212    item. These requests may cause scrolling of the menu page if it only
1213    partially displayed.
1214    
1215    There are explicit requests for scrolling which also change the
1216    current item (because the select location does not change, but the
1217    item there does). These are REQ_SCR_DLINE, REQ_SCR_ULINE,
1218    REQ_SCR_DPAGE, and REQ_SCR_UPAGE.
1219    
1220    The REQ_TOGGLE_ITEM selects or deselects the current item. It is for
1221    use in multi-valued menus; if you use it with O_ONEVALUE on, you'll
1222    get an error return (E_REQUEST_DENIED).
1223    
1224    Each menu has an associated pattern buffer. The menu_driver() logic
1225    tries to accumulate printable ASCII characters passed in in that
1226    buffer; when it matches a prefix of an item name, that item (or the
1227    next matching item) is selected. If appending a character yields no
1228    new match, that character is deleted from the pattern buffer, and
1229    menu_driver() returns E_NO_MATCH.
1230    
1231    Some requests change the pattern buffer directly: REQ_CLEAR_PATTERN,
1232    REQ_BACK_PATTERN, REQ_NEXT_MATCH, REQ_PREV_MATCH. The latter two are
1233    useful when pattern buffer input matches more than one item in a
1234    multi-valued menu.
1235    
1236    Each successful scroll or item navigation request clears the pattern
1237    buffer. It is also possible to set the pattern buffer explicitly with
1238    set_menu_pattern().
1239    
1240    Finally, menu driver requests above the constant MAX_COMMAND are
1241    considered application-specific commands. The menu_driver() code
1242    ignores them and returns E_UNKNOWN_COMMAND.
1243    
1244 Miscellaneous Other Features
1245
1246    Various menu options can affect the processing and visual appearance
1247    and input processing of menus. See menu_opts(3x) for details.
1248    
1249    It is possible to change the current item from application code; this
1250    is useful if you want to write your own navigation requests. It is
1251    also possible to explicitly set the top row of the menu display. See
1252    mitem_current(3x). If your application needs to change the menu
1253    subwindow cursor for any reason, pos_menu_cursor() will restore it to
1254    the correct location for continuing menu driver processing.
1255    
1256    It is possible to set hooks to be called at menu initialization and
1257    wrapup time, and whenever the selected item changes. See
1258    menu_hook(3x).
1259    
1260    Each item, and each menu, has an associated user pointer on which you
1261    can hang application data. See mitem_userptr(3x) and menu_userptr(3x).
1262    
1263                                The Forms Library
1264                                        
1265    The form library is a curses extension that supports easy programming
1266    of on-screen forms for data entry and program control.
1267    
1268    The form library first appeared in AT&T System V. The version
1269    documented here is the form code distributed with ncurses.
1270    
1271 Compiling With the form Library
1272
1273    Your form-using modules must import the form library declarations with
1274           #include <form.h>
1275
1276    and must be linked explicitly with the forms library using an -lform
1277    argument. Note that they must also link the ncurses library with
1278    -lncurses. Many linkers are two-pass and will accept either order, but
1279    it is still good practice to put -lform first and -lncurses second.
1280    
1281 Overview of Forms
1282
1283    A form is a collection of fields; each field may be either a label
1284    (explanatory text) or a data-entry location. Long forms may be
1285    segmented into pages; each entry to a new page clears the screen.
1286    
1287    To make forms, you create groups of fields and connect them with form
1288    frame objects; the form library makes this relatively simple.
1289    
1290    Once defined, a form can be posted, that is written to an associated
1291    window. Actually, each form has two associated windows; a containing
1292    window in which the programmer can scribble titles or borders, and a
1293    subwindow in which the form fields proper are displayed.
1294    
1295    As the form user fills out the posted form, navigation and editing
1296    keys support movement between fields, editing keys support modifying
1297    field, and plain text adds to or changes data in a current field. The
1298    form library allows you (the forms designer) to bind each navigation
1299    and editing key to any keystroke accepted by curses Fields may have
1300    validation conditions on them, so that they check input data for type
1301    and value. The form library supplies a rich set of pre-defined field
1302    types, and makes it relatively easy to define new ones.
1303    
1304    Once its transaction is completed (or aborted), a form may be unposted
1305    (that is, undisplayed), and finally freed to make the storage
1306    associated with it and its items available for re-use.
1307    
1308    The general flow of control of a form program looks like this:
1309     1. Initialize curses.
1310     2. Create the form fields, using new_field().
1311     3. Create the form using new_form().
1312     4. Post the form using form_post().
1313     5. Refresh the screen.
1314     6. Process user requests via an input loop.
1315     7. Unpost the form using form_unpost().
1316     8. Free the form, using free_form().
1317     9. Free the fields using free_field().
1318    10. Terminate curses.
1319        
1320    Note that this looks much like a menu program; the form library
1321    handles tasks which are in many ways similar, and its interface was
1322    obviously designed to resemble that of the menu library wherever
1323    possible.
1324    
1325    In forms programs, however, the `process user requests' is somewhat
1326    more complicated than for menus. Besides menu-like navigation
1327    operations, the menu driver loop has to support field editing and data
1328    validation.
1329    
1330 Creating and Freeing Fields and Forms
1331
1332    The basic function for creating fields is new_field():
1333    
1334 FIELD *new_field(int height, int width,   /* new field size */
1335                  int top, int left,       /* upper left corner */
1336                  int offscreen,           /* number of offscreen rows */
1337                  int nbuf);               /* number of working buffers */
1338
1339    Menu items always occupy a single row, but forms fields may have
1340    multiple rows. So new_field() requires you to specify a width and
1341    height (the first two arguments, which mist both be greater than
1342    zero).
1343    
1344    You must also specify the location of the field's upper left corner on
1345    the screen (the third and fourth arguments, which must be zero or
1346    greater). Note that these coordinates are relative to the form
1347    subwindow, which will coincide with stdscr by default but need not be
1348    stdscr if you've done an explicit set_form_window() call.
1349    
1350    The fifth argument allows you to specify a number of off-screen rows.
1351    If this is zero, the entire field will always be displayed. If it is
1352    nonzero, the form will be scrollable, with only one screen-full
1353    (initially the top part) displayed at any given time. If you make a
1354    field dynamic and grow it so it will no longer fit on the screen, the
1355    form will become scrollable even if the offscreen argument was
1356    initially zero.
1357    
1358    The forms library allocates one working buffer per field; the size of
1359    each buffer is ((height + offscreen)*width + 1, one character for each
1360    position in the field plus a NUL terminator. The sixth argument is the
1361    number of additional data buffers to allocate for the field; your
1362    application can use them for its own purposes.
1363    
1364 FIELD *dup_field(FIELD *field,            /* field to copy */
1365                  int top, int left);      /* location of new copy */
1366
1367    The function dup_field() duplicates an existing field at a new
1368    location. Size and buffering information are copied; some attribute
1369    flags and status bits are not (see the form_field_new(3X) for
1370    details).
1371    
1372 FIELD *link_field(FIELD *field,           /* field to copy */
1373                   int top, int left);     /* location of new copy */
1374
1375    The function link_field() also duplicates an existing field at a new
1376    location. The difference from dup_field() is that it arranges for the
1377    new field's buffer to be shared with the old one.
1378    
1379    Besides the obvious use in making a field editable from two different
1380    form pages, linked fields give you a way to hack in dynamic labels. If
1381    you declare several fields linked to an original, and then make them
1382    inactive, changes from the original will still be propagated to the
1383    linked fields.
1384    
1385    As with duplicated fields, linked fields have attribute bits separate
1386    from the original.
1387    
1388    As you might guess, all these field-allocations return NULL if the
1389    field allocation is not possible due to an out-of-memory error or
1390    out-of-bounds arguments.
1391    
1392    To connect fields to a form, use
1393    
1394 FORM *new_form(FIELD **fields);
1395
1396    This function expects to see a NULL-terminated array of field
1397    pointers. Said fields are connected to a newly-allocated form object;
1398    its address is returned (or else NULL if the allocation fails).
1399    
1400    Note that new_field() does not copy the pointer array into private
1401    storage; if you modify the contents of the pointer array during forms
1402    processing, all manner of bizarre things might happen. Also note that
1403    any given field may only be connected to one form.
1404    
1405    The functions free_field() and free_form are available to free field
1406    and form objects. It is an error to attempt to free a field connected
1407    to a form, but not vice-versa; thus, you will generally free your form
1408    objects first.
1409    
1410 Fetching and Changing Field Attributes
1411
1412    Each form field has a number of location and size attributes
1413    associated with it. There are other field attributes used to control
1414    display and editing of the field. Some (for example, the O_STATIC bit)
1415    involve sufficient complications to be covered in sections of their
1416    own later on. We cover the functions used to get and set several basic
1417    attributes here.
1418    
1419    When a field is created, the attributes not specified by the new_field
1420    function are copied from an invisible system default field. In
1421    attribute-setting and -fetching functions, the argument NULL is taken
1422    to mean this field. Changes to it persist as defaults until your forms
1423    application terminates.
1424    
1425   Fetching Size and Location Data
1426   
1427    You can retrieve field sizes and locations through:
1428    
1429 int field_info(FIELD *field,              /* field from which to fetch */
1430                int *height, *int width,   /* field size */
1431                int *top, int *left,       /* upper left corner */
1432                int *offscreen,            /* number of offscreen rows */
1433                int *nbuf);                /* number of working buffers */
1434
1435    This function is a sort of inverse of new_field(); instead of setting
1436    size and location attributes of a new field, it fetches them from an
1437    existing one.
1438    
1439   Changing the Field Location
1440   
1441    It is possible to move a field's location on the screen:
1442    
1443 int move_field(FIELD *field,              /* field to alter */
1444                int top, int left);        /* new upper-left corner */
1445
1446    You can, of course. query the current location through field_info().
1447    
1448   The Justification Attribute
1449   
1450    One-line fields may be unjustified, justified right, justified left,
1451    or centered. Here is how you manipulate this attribute:
1452    
1453 int set_field_just(FIELD *field,          /* field to alter */
1454                    int justmode);         /* mode to set */
1455
1456 int field_just(FIELD *field);             /* fetch mode of field */
1457
1458    The mode values accepted and returned by this functions are
1459    preprocessor macros NO_JUSTIFICATION, JUSTIFY_RIGHT, JUSTIFY_LEFT, or
1460    JUSTIFY_CENTER.
1461    
1462   Field Display Attributes
1463   
1464    For each field, you can set a foreground attribute for entered
1465    characters, a background attribute for the entire field, and a pad
1466    character for the unfilled portion of the field. You can also control
1467    pagination of the form.
1468    
1469    This group of four field attributes controls the visual appearance of
1470    the field on the screen, without affecting in any way the data in the
1471    field buffer.
1472    
1473 int set_field_fore(FIELD *field,          /* field to alter */
1474                    chtype attr);          /* attribute to set */
1475
1476 chtype field_fore(FIELD *field);          /* field to query */
1477
1478 int set_field_back(FIELD *field,          /* field to alter */
1479                    chtype attr);          /* attribute to set */
1480
1481 chtype field_back(FIELD *field);          /* field to query */
1482
1483 int set_field_pad(FIELD *field,           /* field to alter */
1484                  int pad);                /* pad character to set */
1485
1486 chtype field_pad(FIELD *field);
1487
1488 int set_new_page(FIELD *field,            /* field to alter */
1489                  int flag);               /* TRUE to force new page */
1490
1491 chtype new_page(FIELD *field);            /* field to query */
1492
1493    The attributes set and returned by the first four functions are normal
1494    curses(3x) display attribute values (A_STANDOUT, A_BOLD, A_REVERSE
1495    etc). The page bit of a field controls whether it is displayed at the
1496    start of a new form screen.
1497    
1498   Field Option Bits
1499   
1500    There is also a large collection of field option bits you can set to
1501    control various aspects of forms processing. You can manipulate them
1502    with these functions:
1503 int set_field_opts(FIELD *field,          /* field to alter */
1504                    int attr);             /* attribute to set */
1505
1506 int field_opts_on(FIELD *field,           /* field to alter */
1507                   int attr);              /* attributes to turn on */
1508
1509 int field_opts_off(FIELD *field,          /* field to alter */
1510                    int attr);             /* attributes to turn off */
1511
1512 int field_opts(FIELD *field);             /* field to query */
1513
1514    By default, all options are on. Here are the available option bits:
1515    
1516    O_VISIBLE
1517           Controls whether the field is visible on the screen. Can be
1518           used during form processing to hide or pop up fields depending
1519           on the value of parent fields.
1520           
1521    O_ACTIVE
1522           Controls whether the field is active during forms processing
1523           (i.e. visited by form navigation keys). Can be used to make
1524           labels or derived fields with buffer values alterable by the
1525           forms application, not the user.
1526           
1527    O_PUBLIC
1528           Controls whether data is displayed during field entry. If this
1529           option is turned off on a field, the library will accept and
1530           edit data in that field, but it will not be displayed and the
1531           visible field cursor will not move. You can turn off the
1532           O_PUBLIC bit to define password fields.
1533           
1534    O_EDIT
1535           Controls whether the field's data can be modified. When this
1536           option is off, all editing requests except REQ_PREV_CHOICE and
1537           REQ_NEXT_CHOICE will fail. Such read-only fields may be useful
1538           for help messages.
1539           
1540    O_WRAP
1541           Controls word-wrapping in multi-line fields. Normally, when any
1542           character of a (blank-separated) word reaches the end of the
1543           current line, the entire word is wrapped to the next line
1544           (assuming there is one). When this option is off, the word will
1545           be split across the line break.
1546           
1547    O_BLANK
1548           Controls field blanking. When this option is on, entering a
1549           character at the first field position erases the entire field
1550           (except for the just-entered character).
1551           
1552    O_AUTOSKIP
1553           Controls automatic skip to next field when this one fills.
1554           Normally, when the forms user tries to type more data into a
1555           field than will fit, the editing location jumps to next field.
1556           When this option is off, the user's cursor will hang at the end
1557           of the field. This option is ignored in dynamic fields that
1558           have not reached their size limit.
1559           
1560    O_NULLOK
1561           Controls whether validation is applied to blank fields.
1562           Normally, it is not; the user can leave a field blank without
1563           invoking the usual validation check on exit. If this option is
1564           off on a field, exit from it will invoke a validation check.
1565           
1566    O_PASSOK
1567           Controls whether validation occurs on every exit, or only after
1568           the field is modified. Normally the latter is true. Setting
1569           O_PASSOK may be useful if your field's validation function may
1570           change during forms processing.
1571           
1572    O_STATIC
1573           Controls whether the field is fixed to its initial dimensions.
1574           If you turn this off, the field becomes dynamic and will
1575           stretch to fit entered data.
1576           
1577    A field's options cannot be changed while the field is currently
1578    selected. However, options may be changed on posted fields that are
1579    not current.
1580    
1581    The option values are bit-masks and can be composed with logical-or in
1582    the obvious way.
1583    
1584 Field Status
1585
1586    Every field has a status flag, which is set to FALSE when the field is
1587    created and TRUE when the value in field buffer 0 changes. This flag
1588    can be queried and set directly:
1589    
1590 int set_field_status(FIELD *field,      /* field to alter */
1591                    int status);         /* mode to set */
1592
1593 int field_status(FIELD *field);         /* fetch mode of field */
1594
1595    Setting this flag under program control can be useful if you use the
1596    same form repeatedly, looking for modified fields each time.
1597    
1598    Calling field_status() on a field not currently selected for input
1599    will return a correct value. Calling field_status() on a field that is
1600    currently selected for input may not necessarily give a correct field
1601    status value, because entered data isn't necessarily copied to buffer
1602    zero before the exit validation check. To guarantee that the returned
1603    status value reflects reality, call field_status() either (1) in the
1604    field's exit validation check routine, (2) from the field's or form's
1605    initialization or termination hooks, or (3) just after a
1606    REQ_VALIDATION request has been processed by the forms driver.
1607    
1608 Field User Pointer
1609
1610    Each field structure contains one character pointer slot that is not
1611    used by the forms library. It is intended to be used by applications
1612    to store private per-field data. You can manipulate it with:
1613 int set_field_userptr(FIELD *field,       /* field to alter */
1614                    char *userptr);        /* mode to set */
1615
1616 char *field_userptr(FIELD *field);        /* fetch mode of field */
1617
1618    (Properly, this user pointer field ought to have (void *) type. The
1619    (char *) type is retained for System V compatibility.)
1620    
1621    It is valid to set the user pointer of the default field (with a
1622    set_field_userptr() call passed a NULL field pointer.) When a new
1623    field is created, the default-field user pointer is copied to
1624    initialize the new field's user pointer.
1625    
1626 Variable-Sized Fields
1627
1628    Normally, a field is fixed at the size specified for it at creation
1629    time. If, however, you turn off its O_STATIC bit, it becomes dynamic
1630    and will automatically resize itself to accommodate data as it is
1631    entered. If the field has extra buffers associated with it, they will
1632    grow right along with the main input buffer.
1633    
1634    A one-line dynamic field will have a fixed height (1) but variable
1635    width, scrolling horizontally to display data within the field area as
1636    originally dimensioned and located. A multi-line dynamic field will
1637    have a fixed width, but variable height (number of rows), scrolling
1638    vertically to display data within the field area as originally
1639    dimensioned and located.
1640    
1641    Normally, a dynamic field is allowed to grow without limit. But it is
1642    possible to set an upper limit on the size of a dynamic field. You do
1643    it with this function:
1644    
1645 int set_max_field(FIELD *field,     /* field to alter (may not be NULL) */
1646                    int max_size);   /* upper limit on field size */
1647
1648    If the field is one-line, max_size is taken to be a column size limit;
1649    if it is multi-line, it is taken to be a line size limit. To disable
1650    any limit, use an argument of zero. The growth limit can be changed
1651    whether or not the O_STATIC bit is on, but has no effect until it is.
1652    
1653    The following properties of a field change when it becomes dynamic:
1654      * If there is no growth limit, there is no final position of the
1655        field; therefore O_AUTOSKIP and O_NL_OVERLOAD are ignored.
1656      * Field justification will be ignored (though whatever justification
1657        is set up will be retained internally and can be queried).
1658      * The dup_field() and link_field() calls copy dynamic-buffer sizes.
1659        If the O_STATIC option is set on one of a collection of links,
1660        buffer resizing will occur only when the field is edited through
1661        that link.
1662      * The call field_info() will retrieve the original static size of
1663        the field; use dynamic_field_info() to get the actual dynamic
1664        size.
1665        
1666 Field Validation
1667
1668    By default, a field will accept any data that will fit in its input
1669    buffer. However, it is possible to attach a validation type to a
1670    field. If you do this, any attempt to leave the field while it
1671    contains data that doesn't match the validation type will fail. Some
1672    validation types also have a character-validity check for each time a
1673    character is entered in the field.
1674    
1675    A field's validation check (if any) is not called when
1676    set_field_buffer() modifies the input buffer, nor when that buffer is
1677    changed through a linked field.
1678    
1679    The form library provides a rich set of pre-defined validation types,
1680    and gives you the capability to define custom ones of your own. You
1681    can examine and change field validation attributes with the following
1682    functions:
1683    
1684 int set_field_type(FIELD *field,          /* field to alter */
1685                    FIELDTYPE *ftype,      /* type to associate */
1686                    ...);                  /* additional arguments*/
1687
1688 FIELDTYPE *field_type(FIELD *field);      /* field to query */
1689
1690    The validation type of a field is considered an attribute of the
1691    field. As with other field attributes, Also, doing set_field_type()
1692    with a NULL field default will change the system default for
1693    validation of newly-created fields.
1694    
1695    Here are the pre-defined validation types:
1696    
1697   TYPE_ALPHA
1698   
1699    This field type accepts alphabetic data; no blanks, no digits, no
1700    special characters (this is checked at character-entry time). It is
1701    set up with:
1702    
1703 int set_field_type(FIELD *field,          /* field to alter */
1704                    TYPE_ALPHA,            /* type to associate */
1705                    int width);            /* maximum width of field */
1706
1707    The width argument sets a minimum width of data. Typically you'll want
1708    to set this to the field width; if it's greater than the field width,
1709    the validation check will always fail. A minimum width of zero makes
1710    field completion optional.
1711    
1712   TYPE_ALNUM
1713   
1714    This field type accepts alphabetic data and digits; no blanks, no
1715    special characters (this is checked at character-entry time). It is
1716    set up with:
1717    
1718 int set_field_type(FIELD *field,          /* field to alter */
1719                    TYPE_ALNUM,            /* type to associate */
1720                    int width);            /* maximum width of field */
1721
1722    The width argument sets a minimum width of data. As with TYPE_ALPHA,
1723    typically you'll want to set this to the field width; if it's greater
1724    than the field width, the validation check will always fail. A minimum
1725    width of zero makes field completion optional.
1726    
1727   TYPE_ENUM
1728   
1729    This type allows you to restrict a field's values to be among a
1730    specified set of string values (for example, the two-letter postal
1731    codes for U.S. states). It is set up with:
1732    
1733 int set_field_type(FIELD *field,          /* field to alter */
1734                    TYPE_ENUM,             /* type to associate */
1735                    char **valuelist;      /* list of possible values */
1736                    int checkcase;         /* case-sensitive? */
1737                    int checkunique);      /* must specify uniquely? */
1738
1739    The valuelist parameter must point at a NULL-terminated list of valid
1740    strings. The checkcase argument, if true, makes comparison with the
1741    string case-sensitive.
1742    
1743    When the user exits a TYPE_ENUM field, the validation procedure tries
1744    to complete the data in the buffer to a valid entry. If a complete
1745    choice string has been entered, it is of course valid. But it is also
1746    possible to enter a prefix of a valid string and have it completed for
1747    you.
1748    
1749    By default, if you enter such a prefix and it matches more than one
1750    value in the string list, the prefix will be completed to the first
1751    matching value. But the checkunique argument, if true, requires prefix
1752    matches to be unique in order to be valid.
1753    
1754    The REQ_NEXT_CHOICE and REQ_PREV_CHOICE input requests can be
1755    particularly useful with these fields.
1756    
1757   TYPE_INTEGER
1758   
1759    This field type accepts an integer. It is set up as follows:
1760    
1761 int set_field_type(FIELD *field,          /* field to alter */
1762                    TYPE_INTEGER,          /* type to associate */
1763                    int padding,           /* # places to zero-pad to */
1764                    int vmin, int vmax);   /* valid range */
1765
1766    Valid characters consist of an optional leading minus and digits. The
1767    range check is performed on exit. If the range maximum is less than or
1768    equal to the minimum, the range is ignored.
1769    
1770    If the value passes its range check, it is padded with as many leading
1771    zero digits as necessary to meet the padding argument.
1772    
1773    A TYPE_INTEGER value buffer can conveniently be interpreted with the C
1774    library function atoi(3).
1775    
1776   TYPE_NUMERIC
1777   
1778    This field type accepts a decimal number. It is set up as follows:
1779    
1780 int set_field_type(FIELD *field,              /* field to alter */
1781                    TYPE_NUMERIC,              /* type to associate */
1782                    int padding,               /* # places of precision */
1783                    double vmin, double vmax); /* valid range */
1784
1785    Valid characters consist of an optional leading minus and digits.
1786    possibly including a decimal point. If your system supports locale's,
1787    the decimal point character used must be the one defined by your
1788    locale. The range check is performed on exit. If the range maximum is
1789    less than or equal to the minimum, the range is ignored.
1790    
1791    If the value passes its range check, it is padded with as many
1792    trailing zero digits as necessary to meet the padding argument.
1793    
1794    A TYPE_NUMERIC value buffer can conveniently be interpreted with the C
1795    library function atof(3).
1796    
1797   TYPE_REGEXP
1798   
1799    This field type accepts data matching a regular expression. It is set
1800    up as follows:
1801    
1802 int set_field_type(FIELD *field,          /* field to alter */
1803                    TYPE_REGEXP,           /* type to associate */
1804                    char *regexp);         /* expression to match */
1805
1806    The syntax for regular expressions is that of regcomp(3). The check
1807    for regular-expression match is performed on exit.
1808    
1809 Direct Field Buffer Manipulation
1810
1811    The chief attribute of a field is its buffer contents. When a form has
1812    been completed, your application usually needs to know the state of
1813    each field buffer. You can find this out with:
1814    
1815 char *field_buffer(FIELD *field,          /* field to query */
1816                    int bufindex);         /* number of buffer to query */
1817
1818    Normally, the state of the zero-numbered buffer for each field is set
1819    by the user's editing actions on that field. It's sometimes useful to
1820    be able to set the value of the zero-numbered (or some other) buffer
1821    from your application:
1822 int set_field_buffer(FIELD *field,        /* field to alter */
1823                    int bufindex,          /* number of buffer to alter */
1824                    char *value);          /* string value to set */
1825
1826    If the field is not large enough and cannot be resized to a
1827    sufficiently large size to contain the specified value, the value will
1828    be truncated to fit.
1829    
1830    Calling field_buffer() with a null field pointer will raise an error.
1831    Calling field_buffer() on a field not currently selected for input
1832    will return a correct value. Calling field_buffer() on a field that is
1833    currently selected for input may not necessarily give a correct field
1834    buffer value, because entered data isn't necessarily copied to buffer
1835    zero before the exit validation check. To guarantee that the returned
1836    buffer value reflects on-screen reality, call field_buffer() either
1837    (1) in the field's exit validation check routine, (2) from the field's
1838    or form's initialization or termination hooks, or (3) just after a
1839    REQ_VALIDATION request has been processed by the forms driver.
1840    
1841 Attributes of Forms
1842
1843    As with field attributes, form attributes inherit a default from a
1844    system default form structure. These defaults can be queried or set by
1845    of these functions using a form-pointer argument of NULL.
1846    
1847    The principal attribute of a form is its field list. You can query and
1848    change this list with:
1849    
1850 int set_form_fields(FORM *form,           /* form to alter */
1851                     FIELD **fields);      /* fields to connect */
1852
1853 char *form_fields(FORM *form);            /* fetch fields of form */
1854
1855 int field_count(FORM *form);              /* count connect fields */
1856
1857    The second argument of set_form_fields() may be a NULL-terminated
1858    field pointer array like the one required by new_form(). In that case,
1859    the old fields of the form are disconnected but not freed (and
1860    eligible to be connected to other forms), then the new fields are
1861    connected.
1862    
1863    It may also be null, in which case the old fields are disconnected
1864    (and not freed) but no new ones are connected.
1865    
1866    The field_count() function simply counts the number of fields
1867    connected to a given from. It returns -1 if the form-pointer argument
1868    is NULL.
1869    
1870 Control of Form Display
1871
1872    In the overview section, you saw that to display a form you normally
1873    start by defining its size (and fields), posting it, and refreshing
1874    the screen. There is an hidden step before posting, which is the
1875    association of the form with a frame window (actually, a pair of
1876    windows) within which it will be displayed. By default, the forms
1877    library associates every form with the full-screen window stdscr.
1878    
1879    By making this step explicit, you can associate a form with a declared
1880    frame window on your screen display. This can be useful if you want to
1881    adapt the form display to different screen sizes, dynamically tile
1882    forms on the screen, or use a form as part of an interface layout
1883    managed by panels.
1884    
1885    The two windows associated with each form have the same functions as
1886    their analogues in the menu library. Both these windows are painted
1887    when the form is posted and erased when the form is unposted.
1888    
1889    The outer or frame window is not otherwise touched by the form
1890    routines. It exists so the programmer can associate a title, a border,
1891    or perhaps help text with the form and have it properly refreshed or
1892    erased at post/unpost time. The inner window or subwindow is where the
1893    current form page is actually displayed.
1894    
1895    In order to declare your own frame window for a form, you'll need to
1896    know the size of the form's bounding rectangle. You can get this
1897    information with:
1898    
1899 int scale_form(FORM *form,                /* form to query */
1900                int *rows,                 /* form rows */
1901                int *cols);                /* form cols */
1902
1903    The form dimensions are passed back in the locations pointed to by the
1904    arguments. Once you have this information, you can use it to declare
1905    of windows, then use one of these functions:
1906 int set_form_win(FORM *form,              /* form to alter */
1907                  WINDOW *win);            /* frame window to connect */
1908
1909 WINDOW *form_win(FORM *form);             /* fetch frame window of form */
1910
1911 int set_form_sub(FORM *form,              /* form to alter */
1912                  WINDOW *win);            /* form subwindow to connect */
1913
1914 WINDOW *form_sub(FORM *form);             /* fetch form subwindow of form */
1915
1916    Note that curses operations, including refresh(), on the form, should
1917    be done on the frame window, not the form subwindow.
1918    
1919    It is possible to check from your application whether all of a
1920    scrollable field is actually displayed within the menu subwindow. Use
1921    these functions:
1922    
1923 int data_ahead(FORM *form);               /* form to be queried */
1924
1925 int data_behind(FORM *form);              /* form to be queried */
1926
1927    The function data_ahead() returns TRUE if (a) the current field is
1928    one-line and has undisplayed data off to the right, (b) the current
1929    field is multi-line and there is data off-screen below it.
1930    
1931    The function data_behind() returns TRUE if the first (upper left hand)
1932    character position is off-screen (not being displayed).
1933    
1934    Finally, there is a function to restore the form window's cursor to
1935    the value expected by the forms driver:
1936    
1937 int pos_form_cursor(FORM *)               /* form to be queried */
1938
1939    If your application changes the form window cursor, call this function
1940    before handing control back to the forms driver in order to
1941    re-synchronize it.
1942    
1943 Input Processing in the Forms Driver
1944
1945    The function form_driver() handles virtualized input requests for form
1946    navigation, editing, and validation requests, just as menu_driver does
1947    for menus (see the section on menu input handling).
1948    
1949 int form_driver(FORM *form,               /* form to pass input to */
1950                 int request);             /* form request code */
1951
1952    Your input virtualization function needs to take input and then
1953    convert it to either an alphanumeric character (which is treated as
1954    data to be entered in the currently-selected field), or a forms
1955    processing request.
1956    
1957    The forms driver provides hooks (through input-validation and
1958    field-termination functions) with which your application code can
1959    check that the input taken by the driver matched what was expected.
1960    
1961   Page Navigation Requests
1962   
1963    These requests cause page-level moves through the form, triggering
1964    display of a new form screen.
1965    
1966    REQ_NEXT_PAGE
1967           Move to the next form page.
1968           
1969    REQ_PREV_PAGE
1970           Move to the previous form page.
1971           
1972    REQ_FIRST_PAGE
1973           Move to the first form page.
1974           
1975    REQ_LAST_PAGE
1976           Move to the last form page.
1977           
1978    These requests treat the list as cyclic; that is, REQ_NEXT_PAGE from
1979    the last page goes to the first, and REQ_PREV_PAGE from the first page
1980    goes to the last.
1981    
1982   Inter-Field Navigation Requests
1983   
1984    These requests handle navigation between fields on the same page.
1985    
1986    REQ_NEXT_FIELD
1987           Move to next field.
1988           
1989    REQ_PREV_FIELD
1990           Move to previous field.
1991           
1992    REQ_FIRST_FIELD
1993           Move to the first field.
1994           
1995    REQ_LAST_FIELD
1996           Move to the last field.
1997           
1998    REQ_SNEXT_FIELD
1999           Move to sorted next field.
2000           
2001    REQ_SPREV_FIELD
2002           Move to sorted previous field.
2003           
2004    REQ_SFIRST_FIELD
2005           Move to the sorted first field.
2006           
2007    REQ_SLAST_FIELD
2008           Move to the sorted last field.
2009           
2010    REQ_LEFT_FIELD
2011           Move left to field.
2012           
2013    REQ_RIGHT_FIELD
2014           Move right to field.
2015           
2016    REQ_UP_FIELD
2017           Move up to field.
2018           
2019    REQ_DOWN_FIELD
2020           Move down to field.
2021           
2022    These requests treat the list of fields on a page as cyclic; that is,
2023    REQ_NEXT_FIELD from the last field goes to the first, and
2024    REQ_PREV_FIELD from the first field goes to the last. The order of the
2025    fields for these (and the REQ_FIRST_FIELD and REQ_LAST_FIELD requests)
2026    is simply the order of the field pointers in the form array (as set up
2027    by new_form() or set_form_fields()
2028    
2029    It is also possible to traverse the fields as if they had been sorted
2030    in screen-position order, so the sequence goes left-to-right and
2031    top-to-bottom. To do this, use the second group of four
2032    sorted-movement requests.
2033    
2034    Finally, it is possible to move between fields using visual directions
2035    up, down, right, and left. To accomplish this, use the third group of
2036    four requests. Note, however, that the position of a form for purposes
2037    of these requests is its upper-left corner.
2038    
2039    For example, suppose you have a multi-line field B, and two
2040    single-line fields A and C on the same line with B, with A to the left
2041    of B and C to the right of B. A REQ_MOVE_RIGHT from A will go to B
2042    only if A, B, and C all share the same first line; otherwise it will
2043    skip over B to C.
2044    
2045   Intra-Field Navigation Requests
2046   
2047    These requests drive movement of the edit cursor within the currently
2048    selected field.
2049    
2050    REQ_NEXT_CHAR
2051           Move to next character.
2052           
2053    REQ_PREV_CHAR
2054           Move to previous character.
2055           
2056    REQ_NEXT_LINE
2057           Move to next line.
2058           
2059    REQ_PREV_LINE
2060           Move to previous line.
2061           
2062    REQ_NEXT_WORD
2063           Move to next word.
2064           
2065    REQ_PREV_WORD
2066           Move to previous word.
2067           
2068    REQ_BEG_FIELD
2069           Move to beginning of field.
2070           
2071    REQ_END_FIELD
2072           Move to end of field.
2073           
2074    REQ_BEG_LINE
2075           Move to beginning of line.
2076           
2077    REQ_END_LINE
2078           Move to end of line.
2079           
2080    REQ_LEFT_CHAR
2081           Move left in field.
2082           
2083    REQ_RIGHT_CHAR
2084           Move right in field.
2085           
2086    REQ_UP_CHAR
2087           Move up in field.
2088           
2089    REQ_DOWN_CHAR
2090           Move down in field.
2091           
2092    Each word is separated from the previous and next characters by
2093    whitespace. The commands to move to beginning and end of line or field
2094    look for the first or last non-pad character in their ranges.
2095    
2096   Scrolling Requests
2097   
2098    Fields that are dynamic and have grown and fields explicitly created
2099    with offscreen rows are scrollable. One-line fields scroll
2100    horizontally; multi-line fields scroll vertically. Most scrolling is
2101    triggered by editing and intra-field movement (the library scrolls the
2102    field to keep the cursor visible). It is possible to explicitly
2103    request scrolling with the following requests:
2104    
2105    REQ_SCR_FLINE
2106           Scroll vertically forward a line.
2107           
2108    REQ_SCR_BLINE
2109           Scroll vertically backward a line.
2110           
2111    REQ_SCR_FPAGE
2112           Scroll vertically forward a page.
2113           
2114    REQ_SCR_BPAGE
2115           Scroll vertically backward a page.
2116           
2117    REQ_SCR_FHPAGE
2118           Scroll vertically forward half a page.
2119           
2120    REQ_SCR_BHPAGE
2121           Scroll vertically backward half a page.
2122           
2123    REQ_SCR_FCHAR
2124           Scroll horizontally forward a character.
2125           
2126    REQ_SCR_BCHAR
2127           Scroll horizontally backward a character.
2128           
2129    REQ_SCR_HFLINE
2130           Scroll horizontally one field width forward.
2131           
2132    REQ_SCR_HBLINE
2133           Scroll horizontally one field width backward.
2134           
2135    REQ_SCR_HFHALF
2136           Scroll horizontally one half field width forward.
2137           
2138    REQ_SCR_HBHALF
2139           Scroll horizontally one half field width backward.
2140           
2141    For scrolling purposes, a page of a field is the height of its visible
2142    part.
2143    
2144   Editing Requests
2145   
2146    When you pass the forms driver an ASCII character, it is treated as a
2147    request to add the character to the field's data buffer. Whether this
2148    is an insertion or a replacement depends on the field's edit mode
2149    (insertion is the default.
2150    
2151    The following requests support editing the field and changing the edit
2152    mode:
2153    
2154    REQ_INS_MODE
2155           Set insertion mode.
2156           
2157    REQ_OVL_MODE
2158           Set overlay mode.
2159           
2160    REQ_NEW_LINE
2161           New line request (see below for explanation).
2162           
2163    REQ_INS_CHAR
2164           Insert space at character location.
2165           
2166    REQ_INS_LINE
2167           Insert blank line at character location.
2168           
2169    REQ_DEL_CHAR
2170           Delete character at cursor.
2171           
2172    REQ_DEL_PREV
2173           Delete previous word at cursor.
2174           
2175    REQ_DEL_LINE
2176           Delete line at cursor.
2177           
2178    REQ_DEL_WORD
2179           Delete word at cursor.
2180           
2181    REQ_CLR_EOL
2182           Clear to end of line.
2183           
2184    REQ_CLR_EOF
2185           Clear to end of field.
2186           
2187    REQ_CLEAR_FIELD
2188           Clear entire field.
2189           
2190    The behavior of the REQ_NEW_LINE and REQ_DEL_PREV requests is
2191    complicated and partly controlled by a pair of forms options. The
2192    special cases are triggered when the cursor is at the beginning of a
2193    field, or on the last line of the field.
2194    
2195    First, we consider REQ_NEW_LINE:
2196    
2197    The normal behavior of REQ_NEW_LINE in insert mode is to break the
2198    current line at the position of the edit cursor, inserting the portion
2199    of the current line after the cursor as a new line following the
2200    current and moving the cursor to the beginning of that new line (you
2201    may think of this as inserting a newline in the field buffer).
2202    
2203    The normal behavior of REQ_NEW_LINE in overlay mode is to clear the
2204    current line from the position of the edit cursor to end of line. The
2205    cursor is then moved to the beginning of the next line.
2206    
2207    However, REQ_NEW_LINE at the beginning of a field, or on the last line
2208    of a field, instead does a REQ_NEXT_FIELD. O_NL_OVERLOAD option is
2209    off, this special action is disabled.
2210    
2211    Now, let us consider REQ_DEL_PREV:
2212    
2213    The normal behavior of REQ_DEL_PREV is to delete the previous
2214    character. If insert mode is on, and the cursor is at the start of a
2215    line, and the text on that line will fit on the previous one, it
2216    instead appends the contents of the current line to the previous one
2217    and deletes the current line (you may think of this as deleting a
2218    newline from the field buffer).
2219    
2220    However, REQ_DEL_PREV at the beginning of a field is instead treated
2221    as a REQ_PREV_FIELD.
2222    
2223    If the O_BS_OVERLOAD option is off, this special action is disabled
2224    and the forms driver just returns E_REQUEST_DENIED.
2225    
2226    See Form Options for discussion of how to set and clear the overload
2227    options.
2228    
2229   Order Requests
2230   
2231    If the type of your field is ordered, and has associated functions for
2232    getting the next and previous values of the type from a given value,
2233    there are requests that can fetch that value into the field buffer:
2234    
2235    REQ_NEXT_CHOICE
2236           Place the successor value of the current value in the buffer.
2237           
2238    REQ_PREV_CHOICE
2239           Place the predecessor value of the current value in the buffer.
2240           
2241    Of the built-in field types, only TYPE_ENUM has built-in successor and
2242    predecessor functions. When you define a field type of your own (see
2243    Custom Validation Types), you can associate our own ordering
2244    functions.
2245    
2246   Application Commands
2247   
2248    Form requests are represented as integers above the curses value
2249    greater than KEY_MAX and less than or equal to the constant
2250    MAX_COMMAND. If your input-virtualization routine returns a value
2251    above MAX_COMMAND, the forms driver will ignore it.
2252    
2253 Field Change Hooks
2254
2255    It is possible to set function hooks to be executed whenever the
2256    current field or form changes. Here are the functions that support
2257    this:
2258    
2259 typedef void    (*HOOK)();       /* pointer to function returning void */
2260
2261 int set_form_init(FORM *form,    /* form to alter */
2262                   HOOK hook);    /* initialization hook */
2263
2264 HOOK form_init(FORM *form);      /* form to query */
2265
2266 int set_form_term(FORM *form,    /* form to alter */
2267                   HOOK hook);    /* termination hook */
2268
2269 HOOK form_term(FORM *form);      /* form to query */
2270
2271 int set_field_init(FORM *form,   /* form to alter */
2272                   HOOK hook);    /* initialization hook */
2273
2274 HOOK field_init(FORM *form);     /* form to query */
2275
2276 int set_field_term(FORM *form,   /* form to alter */
2277                   HOOK hook);    /* termination hook */
2278
2279 HOOK field_term(FORM *form);     /* form to query */
2280
2281    These functions allow you to either set or query four different hooks.
2282    In each of the set functions, the second argument should be the
2283    address of a hook function. These functions differ only in the timing
2284    of the hook call.
2285    
2286    form_init
2287           This hook is called when the form is posted; also, just after
2288           each page change operation.
2289           
2290    field_init
2291           This hook is called when the form is posted; also, just after
2292           each field change
2293           
2294    field_term
2295           This hook is called just after field validation; that is, just
2296           before the field is altered. It is also called when the form is
2297           unposted.
2298           
2299    form_term
2300           This hook is called when the form is unposted; also, just
2301           before each page change operation.
2302           
2303    Calls to these hooks may be triggered
2304     1. When user editing requests are processed by the forms driver
2305     2. When the current page is changed by set_current_field() call
2306     3. When the current field is changed by a set_form_page() call
2307        
2308    See Field Change Commands for discussion of the latter two cases.
2309    
2310    You can set a default hook for all fields by passing one of the set
2311    functions a NULL first argument.
2312    
2313    You can disable any of these hooks by (re)setting them to NULL, the
2314    default value.
2315    
2316 Field Change Commands
2317
2318    Normally, navigation through the form will be driven by the user's
2319    input requests. But sometimes it is useful to be able to move the
2320    focus for editing and viewing under control of your application, or
2321    ask which field it currently is in. The following functions help you
2322    accomplish this:
2323    
2324 int set_current_field(FORM *form,         /* form to alter */
2325                       FIELD *field);      /* field to shift to */
2326
2327 FIELD *current_field(FORM *form);         /* form to query */
2328
2329 int field_index(FORM *form,               /* form to query */
2330                 FIELD *field);            /* field to get index of */
2331
2332    The function field_index() returns the index of the given field in the
2333    given form's field array (the array passed to new_form() or
2334    set_form_fields()).
2335    
2336    The initial current field of a form is the first active field on the
2337    first page. The function set_form_fields() resets this.
2338    
2339    It is also possible to move around by pages.
2340    
2341 int set_form_page(FORM *form,             /* form to alter */
2342                   int page);              /* page to go to (0-origin) */
2343
2344 int form_page(FORM *form);                /* return form's current page */
2345
2346    The initial page of a newly-created form is 0. The function
2347    set_form_fields() resets this.
2348    
2349 Form Options
2350
2351    Like fields, forms may have control option bits. They can be changed
2352    or queried with these functions:
2353    
2354 int set_form_opts(FORM *form,             /* form to alter */
2355                   int attr);              /* attribute to set */
2356
2357 int form_opts_on(FORM *form,              /* form to alter */
2358                  int attr);               /* attributes to turn on */
2359
2360 int form_opts_off(FORM *form,             /* form to alter */
2361                   int attr);              /* attributes to turn off */
2362
2363 int form_opts(FORM *form);                /* form to query */
2364
2365    By default, all options are on. Here are the available option bits:
2366    
2367    O_NL_OVERLOAD
2368           Enable overloading of REQ_NEW_LINE as described in Editing
2369           Requests. The value of this option is ignored on dynamic fields
2370           that have not reached their size limit; these have no last
2371           line, so the circumstances for triggering a REQ_NEXT_FIELD
2372           never arise.
2373           
2374    O_BS_OVERLOAD
2375           Enable overloading of REQ_DEL_PREV as described in Editing
2376           Requests.
2377           
2378    The option values are bit-masks and can be composed with logical-or in
2379    the obvious way.
2380    
2381 Custom Validation Types
2382
2383    The form library gives you the capability to define custom validation
2384    types of your own. Further, the optional additional arguments of
2385    set_field_type effectively allow you to parameterize validation types.
2386    Most of the complications in the validation-type interface have to do
2387    with the handling of the additional arguments within custom validation
2388    functions.
2389    
2390   Union Types
2391   
2392    The simplest way to create a custom data type is to compose it from
2393    two preexisting ones:
2394    
2395 FIELD *link_fieldtype(FIELDTYPE *type1,
2396                       FIELDTYPE *type2);
2397
2398    This function creates a field type that will accept any of the values
2399    legal for either of its argument field types (which may be either
2400    predefined or programmer-defined). If a set_field_type() call later
2401    requires arguments, the new composite type expects all arguments for
2402    the first type, than all arguments for the second. Order functions
2403    (see Order Requests) associated with the component types will work on
2404    the composite; what it does is check the validation function for the
2405    first type, then for the second, to figure what type the buffer
2406    contents should be treated as.
2407    
2408   New Field Types
2409   
2410    To create a field type from scratch, you need to specify one or both
2411    of the following things:
2412    
2413      * A character-validation function, to check each character as it is
2414        entered.
2415      * A field-validation function to be applied on exit from the field.
2416        
2417    Here's how you do that:
2418    
2419 typedef int     (*HOOK)();       /* pointer to function returning int */
2420
2421 FIELDTYPE *new_fieldtype(HOOK f_validate, /* field validator */
2422                          HOOK c_validate) /* character validator */
2423
2424
2425 int free_fieldtype(FIELDTYPE *ftype);     /* type to free */
2426
2427    At least one of the arguments of new_fieldtype() must be non-NULL. The
2428    forms driver will automatically call the new type's validation
2429    functions at appropriate points in processing a field of the new type.
2430    
2431    The function free_fieldtype() deallocates the argument fieldtype,
2432    freeing all storage associated with it.
2433    
2434    Normally, a field validator is called when the user attempts to leave
2435    the field. Its first argument is a field pointer, from which it can
2436    get to field buffer 0 and test it. If the function returns TRUE, the
2437    operation succeeds; if it returns FALSE, the edit cursor stays in the
2438    field.
2439    
2440    A character validator gets the character passed in as a first
2441    argument. It too should return TRUE if the character is valid, FALSE
2442    otherwise.
2443    
2444   Validation Function Arguments
2445   
2446    Your field- and character- validation functions will be passed a
2447    second argument as well. This second argument is the address of a
2448    structure (which we'll call a pile) built from any of the
2449    field-type-specific arguments passed to set_field_type(). If no such
2450    arguments are defined for the field type, this pile pointer argument
2451    will be NULL.
2452    
2453    In order to arrange for such arguments to be passed to your validation
2454    functions, you must associate a small set of storage-management
2455    functions with the type. The forms driver will use these to synthesize
2456    a pile from the trailing arguments of each set_field_type() argument,
2457    and a pointer to the pile will be passed to the validation functions.
2458    
2459    Here is how you make the association:
2460    
2461 typedef char    *(*PTRHOOK)();    /* pointer to function returning (char *) */
2462 typedef void    (*VOIDHOOK)();    /* pointer to function returning void */
2463
2464 int set_fieldtype_arg(FIELDTYPE *type,    /* type to alter */
2465                       PTRHOOK make_str,   /* make structure from args */
2466                       PTRHOOK copy_str,   /* make copy of structure */
2467                       VOIDHOOK free_str); /* free structure storage */
2468
2469    Here is how the storage-management hooks are used:
2470    
2471    make_str
2472           This function is called by set_field_type(). It gets one
2473           argument, a va_list of the type-specific arguments passed to
2474           set_field_type(). It is expected to return a pile pointer to a
2475           data structure that encapsulates those arguments.
2476           
2477    copy_str
2478           This function is called by form library functions that allocate
2479           new field instances. It is expected to take a pile pointer,
2480           copy the pile to allocated storage, and return the address of
2481           the pile copy.
2482           
2483    free_str
2484           This function is called by field- and type-deallocation
2485           routines in the library. It takes a pile pointer argument, and
2486           is expected to free the storage of that pile.
2487           
2488    The make_str and copy_str functions may return NULL to signal
2489    allocation failure. The library routines will that call them will
2490    return error indication when this happens. Thus, your validation
2491    functions should never see a NULL file pointer and need not check
2492    specially for it.
2493    
2494   Order Functions For Custom Types
2495   
2496    Some custom field types are simply ordered in the same well-defined
2497    way that TYPE_ENUM is. For such types, it is possible to define
2498    successor and predecessor functions to support the REQ_NEXT_CHOICE and
2499    REQ_PREV_CHOICE requests. Here's how:
2500    
2501 typedef int     (*INTHOOK)();     /* pointer to function returning int */
2502
2503 int set_fieldtype_arg(FIELDTYPE *type,    /* type to alter */
2504                       INTHOOK succ,       /* get successor value */
2505                       INTHOOK pred);      /* get predecessor value */
2506
2507    The successor and predecessor arguments will each be passed two
2508    arguments; a field pointer, and a pile pointer (as for the validation
2509    functions). They are expected to use the function field_buffer() to
2510    read the current value, and set_field_buffer() on buffer 0 to set the
2511    next or previous value. Either hook may return TRUE to indicate
2512    success (a legal next or previous value was set) or FALSE to indicate
2513    failure.
2514    
2515   Avoiding Problems
2516   
2517    The interface for defining custom types is complicated and tricky.
2518    Rather than attempting to create a custom type entirely from scratch,
2519    you should start by studying the library source code for whichever of
2520    the pre-defined types seems to be closest to what you want.
2521    
2522    Use that code as a model, and evolve it towards what you really want.
2523    You will avoid many problems and annoyances that way. The code in the
2524    ncurses library has been specifically exempted from the package
2525    copyright to support this.
2526    
2527    If your custom type defines order functions, have do something
2528    intuitive with a blank field. A useful convention is to make the
2529    successor of a blank field the types minimum value, and its
2530    predecessor the maximum.