diff options
Diffstat (limited to 'contrib/ncurses/misc/ncurses-intro.doc')
| -rw-r--r-- | contrib/ncurses/misc/ncurses-intro.doc | 2530 |
1 files changed, 0 insertions, 2530 deletions
diff --git a/contrib/ncurses/misc/ncurses-intro.doc b/contrib/ncurses/misc/ncurses-intro.doc deleted file mode 100644 index e45ca3530f20..000000000000 --- a/contrib/ncurses/misc/ncurses-intro.doc +++ /dev/null @@ -1,2530 +0,0 @@ - - Writing Programs with NCURSES - - by Eric S. Raymond and Zeyd M. Ben-Halim - updates since release 1.9.9e by Thomas Dickey - - Contents - - * Introduction - + A Brief History of Curses - + Scope of This Document - + Terminology - * The Curses Library - + An Overview of Curses - o Compiling Programs using Curses - o Updating the Screen - o Standard Windows and Function Naming Conventions - o Variables - + Using the Library - o Starting up - o Output - o Input - o Using Forms Characters - o Character Attributes and Color - o Mouse Interfacing - o Finishing Up - + Function Descriptions - o Initialization and Wrapup - o Causing Output to the Terminal - o Low-Level Capability Access - o Debugging - + Hints, Tips, and Tricks - o Some Notes of Caution - o Temporarily Leaving ncurses Mode - o Using ncurses under xterm - o Handling Multiple Terminal Screens - o Testing for Terminal Capabilities - o Tuning for Speed - o Special Features of ncurses - + Compatibility with Older Versions - o Refresh of Overlapping Windows - o Background Erase - + XSI Curses Conformance - * The Panels Library - + Compiling With the Panels Library - + Overview of Panels - + Panels, Input, and the Standard Screen - + Hiding Panels - + Miscellaneous Other Facilities - * The Menu Library - + Compiling with the menu Library - + Overview of Menus - + Selecting items - + Menu Display - + Menu Windows - + Processing Menu Input - + Miscellaneous Other Features - * The Forms Library - + Compiling with the forms Library - + Overview of Forms - + Creating and Freeing Fields and Forms - + Fetching and Changing Field Attributes - o Fetching Size and Location Data - o Changing the Field Location - o The Justification Attribute - o Field Display Attributes - o Field Option Bits - o Field Status - o Field User Pointer - + Variable-Sized Fields - + Field Validation - o TYPE_ALPHA - o TYPE_ALNUM - o TYPE_ENUM - o TYPE_INTEGER - o TYPE_NUMERIC - o TYPE_REGEXP - + Direct Field Buffer Manipulation - + Attributes of Forms - + Control of Form Display - + Input Processing in the Forms Driver - o Page Navigation Requests - o Inter-Field Navigation Requests - o Intra-Field Navigation Requests - o Scrolling Requests - o Field Editing Requests - o Order Requests - o Application Commands - + Field Change Hooks - + Field Change Commands - + Form Options - + Custom Validation Types - o Union Types - o New Field Types - o Validation Function Arguments - o Order Functions For Custom Types - o Avoiding Problems - _________________________________________________________________ - - Introduction - - This document is an introduction to programming with curses. It is not - an exhaustive reference for the curses Application Programming - Interface (API); that role is filled by the curses manual pages. - Rather, it is intended to help C programmers ease into using the - package. - - This document is aimed at C applications programmers not yet - specifically familiar with ncurses. If you are already an experienced - curses programmer, you should nevertheless read the sections on Mouse - Interfacing, Debugging, Compatibility with Older Versions, and Hints, - Tips, and Tricks. These will bring you up to speed on the special - features and quirks of the ncurses implementation. If you are not so - experienced, keep reading. - - The curses package is a subroutine library for terminal-independent - screen-painting and input-event handling which presents a high level - screen model to the programmer, hiding differences between terminal - types and doing automatic optimization of output to change one screen - full of text into another. Curses uses terminfo, which is a database - format that can describe the capabilities of thousands of different - terminals. - - The curses API may seem something of an archaism on UNIX desktops - increasingly dominated by X, Motif, and Tcl/Tk. Nevertheless, UNIX - still supports tty lines and X supports xterm(1); the curses API has - the advantage of (a) back-portability to character-cell terminals, and - (b) simplicity. For an application that does not require bit-mapped - graphics and multiple fonts, an interface implementation using curses - will typically be a great deal simpler and less expensive than one - using an X toolkit. - -A Brief History of Curses - - Historically, the first ancestor of curses was the routines written to - provide screen-handling for the game rogue; these used the - already-existing termcap database facility for describing terminal - capabilities. These routines were abstracted into a documented library - and first released with the early BSD UNIX versions. - - System III UNIX from Bell Labs featured a rewritten and much-improved - curses library. It introduced the terminfo format. Terminfo is based - on Berkeley's termcap database, but contains a number of improvements - and extensions. Parameterized capabilities strings were introduced, - making it possible to describe multiple video attributes, and colors - and to handle far more unusual terminals than possible with termcap. - In the later AT&T System V releases, curses evolved to use more - facilities and offer more capabilities, going far beyond BSD curses in - power and flexibility. - -Scope of This Document - - This document describes ncurses, a free implementation of the System V - curses API with some clearly marked extensions. It includes the - following System V curses features: - - * Support for multiple screen highlights (BSD curses could only - handle one `standout' highlight, usually reverse-video). - * Support for line- and box-drawing using forms characters. - * Recognition of function keys on input. - * Color support. - * Support for pads (windows of larger than screen size on which the - screen or a subwindow defines a viewport). - - Also, this package makes use of the insert and delete line and - character features of terminals so equipped, and determines how to - optimally use these features with no help from the programmer. It - allows arbitrary combinations of video attributes to be displayed, - even on terminals that leave ``magic cookies'' on the screen to mark - changes in attributes. - - The ncurses package can also capture and use event reports from a - mouse in some environments (notably, xterm under the X window system). - This document includes tips for using the mouse. - - The ncurses package was originated by Pavel Curtis. The original - maintainer of this package is Zeyd Ben-Halim <zmbenhal@netcom.com>. - Eric S. Raymond <esr@snark.thyrsus.com> wrote many of the new features - in versions after 1.8.1 and wrote most of this introduction. Jürgen - Pfeifer wrote all of the menu and forms code as well as the Ada95 - binding. Ongoing work is being done by Thomas Dickey and Jürgen - Pfeifer. Florian La Roche acts as the maintainer for the Free Software - Foundation, which holds the copyright on ncurses. Contact the current - maintainers at bug-ncurses@gnu.org. - - This document also describes the panels extension library, similarly - modeled on the SVr4 panels facility. This library allows you to - associate backing store with each of a stack or deck of overlapping - windows, and provides operations for moving windows around in the - stack that change their visibility in the natural way (handling window - overlaps). - - Finally, this document describes in detail the menus and forms - extension libraries, also cloned from System V, which support easy - construction and sequences of menus and fill-in forms. - -Terminology - - In this document, the following terminology is used with reasonable - consistency: - - window - A data structure describing a sub-rectangle of the screen - (possibly the entire screen). You can write to a window as - though it were a miniature screen, scrolling independently of - other windows on the physical screen. - - screens - A subset of windows which are as large as the terminal screen, - i.e., they start at the upper left hand corner and encompass - the lower right hand corner. One of these, stdscr, is - automatically provided for the programmer. - - terminal screen - The package's idea of what the terminal display currently looks - like, i.e., what the user sees now. This is a special screen. - - The Curses Library - -An Overview of Curses - - Compiling Programs using Curses - - In order to use the library, it is necessary to have certain types and - variables defined. Therefore, the programmer must have a line: - #include <curses.h> - - at the top of the program source. The screen package uses the Standard - I/O library, so <curses.h> includes <stdio.h>. <curses.h> also - includes <termios.h>, <termio.h>, or <sgtty.h> depending on your - system. It is redundant (but harmless) for the programmer to do these - includes, too. In linking with curses you need to have -lncurses in - your LDFLAGS or on the command line. There is no need for any other - libraries. - - Updating the Screen - - In order to update the screen optimally, it is necessary for the - routines to know what the screen currently looks like and what the - programmer wants it to look like next. For this purpose, a data type - (structure) named WINDOW is defined which describes a window image to - the routines, including its starting position on the screen (the (y, - x) coordinates of the upper left hand corner) and its size. One of - these (called curscr, for current screen) is a screen image of what - the terminal currently looks like. Another screen (called stdscr, for - standard screen) is provided by default to make changes on. - - A window is a purely internal representation. It is used to build and - store a potential image of a portion of the terminal. It doesn't bear - any necessary relation to what is really on the terminal screen; it's - more like a scratchpad or write buffer. - - To make the section of physical screen corresponding to a window - reflect the contents of the window structure, the routine refresh() - (or wrefresh() if the window is not stdscr) is called. - - A given physical screen section may be within the scope of any number - of overlapping windows. Also, changes can be made to windows in any - order, without regard to motion efficiency. Then, at will, the - programmer can effectively say ``make it look like this,'' and let the - package implementation determine the most efficient way to repaint the - screen. - - Standard Windows and Function Naming Conventions - - As hinted above, the routines can use several windows, but two are - automatically given: curscr, which knows what the terminal looks like, - and stdscr, which is what the programmer wants the terminal to look - like next. The user should never actually access curscr directly. - Changes should be made to through the API, and then the routine - refresh() (or wrefresh()) called. - - Many functions are defined to use stdscr as a default screen. For - example, to add a character to stdscr, one calls addch() with the - desired character as argument. To write to a different window. use the - routine waddch() (for `w'indow-specific addch()) is provided. This - convention of prepending function names with a `w' when they are to be - applied to specific windows is consistent. The only routines which do - not follow it are those for which a window must always be specified. - - In order to move the current (y, x) coordinates from one point to - another, the routines move() and wmove() are provided. However, it is - often desirable to first move and then perform some I/O operation. In - order to avoid clumsiness, most I/O routines can be preceded by the - prefix 'mv' and the desired (y, x) coordinates prepended to the - arguments to the function. For example, the calls - move(y, x); - addch(ch); - - can be replaced by - mvaddch(y, x, ch); - - and - wmove(win, y, x); - waddch(win, ch); - - can be replaced by - mvwaddch(win, y, x, ch); - - Note that the window description pointer (win) comes before the added - (y, x) coordinates. If a function requires a window pointer, it is - always the first parameter passed. - - Variables - - The curses library sets some variables describing the terminal - capabilities. - type name description - ------------------------------------------------------------------ - int LINES number of lines on the terminal - int COLS number of columns on the terminal - - The curses.h also introduces some #define constants and types of - general usefulness: - - bool - boolean type, actually a `char' (e.g., bool doneit;) - - TRUE - boolean `true' flag (1). - - FALSE - boolean `false' flag (0). - - ERR - error flag returned by routines on a failure (-1). - - OK - error flag returned by routines when things go right. - -Using the Library - - Now we describe how to actually use the screen package. In it, we - assume all updating, reading, etc. is applied to stdscr. These - instructions will work on any window, providing you change the - function names and parameters as mentioned above. - - Here is a sample program to motivate the discussion: - -#include <curses.h> -#include <signal.h> - -static void finish(int sig); - -main(int argc, char *argv[]) -{ - /* initialize your non-curses data structures here */ - - (void) signal(SIGINT, finish); /* arrange interrupts to terminate */ - - (void) initscr(); /* initialize the curses library */ - keypad(stdscr, TRUE); /* enable keyboard mapping */ - (void) nonl(); /* tell curses not to do NL->CR/NL on output */ - (void) cbreak(); /* take input chars one at a time, no wait for \n */ - (void) noecho(); /* don't echo input */ - - if (has_colors()) - { - start_color(); - - /* - * Simple color assignment, often all we need. - */ - init_pair(COLOR_BLACK, COLOR_BLACK, COLOR_BLACK); - init_pair(COLOR_GREEN, COLOR_GREEN, COLOR_BLACK); - init_pair(COLOR_RED, COLOR_RED, COLOR_BLACK); - init_pair(COLOR_CYAN, COLOR_CYAN, COLOR_BLACK); - init_pair(COLOR_WHITE, COLOR_WHITE, COLOR_BLACK); - init_pair(COLOR_MAGENTA, COLOR_MAGENTA, COLOR_BLACK); - init_pair(COLOR_BLUE, COLOR_BLUE, COLOR_BLACK); - init_pair(COLOR_YELLOW, COLOR_YELLOW, COLOR_BLACK); - } - - for (;;) - { - int c = getch(); /* refresh, accept single keystroke of input */ - - /* process the command keystroke */ - } - - finish(0); /* we're done */ -} - -static void finish(int sig) -{ - endwin(); - - /* do your non-curses wrapup here */ - - exit(0); -} - - Starting up - - In order to use the screen package, the routines must know about - terminal characteristics, and the space for curscr and stdscr must be - allocated. These function initscr() does both these things. Since it - must allocate space for the windows, it can overflow memory when - attempting to do so. On the rare occasions this happens, initscr() - will terminate the program with an error message. initscr() must - always be called before any of the routines which affect windows are - used. If it is not, the program will core dump as soon as either - curscr or stdscr are referenced. However, it is usually best to wait - to call it until after you are sure you will need it, like after - checking for startup errors. Terminal status changing routines like - nl() and cbreak() should be called after initscr(). - - Once the screen windows have been allocated, you can set them up for - your program. If you want to, say, allow a screen to scroll, use - scrollok(). If you want the cursor to be left in place after the last - change, use leaveok(). If this isn't done, refresh() will move the - cursor to the window's current (y, x) coordinates after updating it. - - You can create new windows of your own using the functions newwin(), - derwin(), and subwin(). The routine delwin() will allow you to get rid - of old windows. All the options described above can be applied to any - window. - - Output - - Now that we have set things up, we will want to actually update the - terminal. The basic functions used to change what will go on a window - are addch() and move(). addch() adds a character at the current (y, x) - coordinates. move() changes the current (y, x) coordinates to whatever - you want them to be. It returns ERR if you try to move off the window. - As mentioned above, you can combine the two into mvaddch() to do both - things at once. - - The other output functions, such as addstr() and printw(), all call - addch() to add characters to the window. - - After you have put on the window what you want there, when you want - the portion of the terminal covered by the window to be made to look - like it, you must call refresh(). In order to optimize finding - changes, refresh() assumes that any part of the window not changed - since the last refresh() of that window has not been changed on the - terminal, i.e., that you have not refreshed a portion of the terminal - with an overlapping window. If this is not the case, the routine - touchwin() is provided to make it look like the entire window has been - changed, thus making refresh() check the whole subsection of the - terminal for changes. - - If you call wrefresh() with curscr as its argument, it will make the - screen look like curscr thinks it looks like. This is useful for - implementing a command which would redraw the screen in case it get - messed up. - - Input - - The complementary function to addch() is getch() which, if echo is - set, will call addch() to echo the character. Since the screen package - needs to know what is on the terminal at all times, if characters are - to be echoed, the tty must be in raw or cbreak mode. Since initially - the terminal has echoing enabled and is in ordinary ``cooked'' mode, - one or the other has to changed before calling getch(); otherwise, the - program's output will be unpredictable. - - When you need to accept line-oriented input in a window, the functions - wgetstr() and friends are available. There is even a wscanw() function - that can do scanf()(3)-style multi-field parsing on window input. - These pseudo-line-oriented functions turn on echoing while they - execute. - - The example code above uses the call keypad(stdscr, TRUE) to enable - support for function-key mapping. With this feature, the getch() code - watches the input stream for character sequences that correspond to - arrow and function keys. These sequences are returned as - pseudo-character values. The #define values returned are listed in the - curses.h The mapping from sequences to #define values is determined by - key_ capabilities in the terminal's terminfo entry. - - Using Forms Characters - - The addch() function (and some others, including box() and border()) - can accept some pseudo-character arguments which are specially defined - by ncurses. These are #define values set up in the curses.h header; - see there for a complete list (look for the prefix ACS_). - - The most useful of the ACS defines are the forms-drawing characters. - You can use these to draw boxes and simple graphs on the screen. If - the terminal does not have such characters, curses.h will map them to - a recognizable (though ugly) set of ASCII defaults. - - Character Attributes and Color - - The ncurses package supports screen highlights including standout, - reverse-video, underline, and blink. It also supports color, which is - treated as another kind of highlight. - - Highlights are encoded, internally, as high bits of the - pseudo-character type (chtype) that curses.h uses to represent the - contents of a screen cell. See the curses.h header file for a complete - list of highlight mask values (look for the prefix A_). - - There are two ways to make highlights. One is to logical-or the value - of the highlights you want into the character argument of an addch() - call, or any other output call that takes a chtype argument. - - The other is to set the current-highlight value. This is logical-or'ed - with any highlight you specify the first way. You do this with the - functions attron(), attroff(), and attrset(); see the manual pages for - details. Color is a special kind of highlight. The package actually - thinks in terms of color pairs, combinations of foreground and - background colors. The sample code above sets up eight color pairs, - all of the guaranteed-available colors on black. Note that each color - pair is, in effect, given the name of its foreground color. Any other - range of eight non-conflicting values could have been used as the - first arguments of the init_pair() values. - - Once you've done an init_pair() that creates color-pair N, you can use - COLOR_PAIR(N) as a highlight that invokes that particular color - combination. Note that COLOR_PAIR(N), for constant N, is itself a - compile-time constant and can be used in initializers. - - Mouse Interfacing - - The ncurses library also provides a mouse interface. - - NOTE: this facility is specific to ncurses, it is not part of - either the XSI Curses standard, nor of System V Release 4, nor BSD - curses. System V Release 4 curses contains code with similar - interface definitions, however it is not documented. Other than by - disassembling the library, we have no way to determine exactly how - that mouse code works. Thus, we recommend that you wrap - mouse-related code in an #ifdef using the feature macro - NCURSES_MOUSE_VERSION so it will not be compiled and linked on - non-ncurses systems. - - Presently, mouse event reporting works in the following environments: - * xterm and similar programs such as rxvt. - * Linux console, when configured with gpm(1), Alessandro Rubini's - mouse server. - * OS/2 EMX - - The mouse interface is very simple. To activate it, you use the - function mousemask(), passing it as first argument a bit-mask that - specifies what kinds of events you want your program to be able to - see. It will return the bit-mask of events that actually become - visible, which may differ from the argument if the mouse device is not - capable of reporting some of the event types you specify. - - Once the mouse is active, your application's command loop should watch - for a return value of KEY_MOUSE from wgetch(). When you see this, a - mouse event report has been queued. To pick it off the queue, use the - function getmouse() (you must do this before the next wgetch(), - otherwise another mouse event might come in and make the first one - inaccessible). - - Each call to getmouse() fills a structure (the address of which you'll - pass it) with mouse event data. The event data includes zero-origin, - screen-relative character-cell coordinates of the mouse pointer. It - also includes an event mask. Bits in this mask will be set, - corresponding to the event type being reported. - - The mouse structure contains two additional fields which may be - significant in the future as ncurses interfaces to new kinds of - pointing device. In addition to x and y coordinates, there is a slot - for a z coordinate; this might be useful with touch-screens that can - return a pressure or duration parameter. There is also a device ID - field, which could be used to distinguish between multiple pointing - devices. - - The class of visible events may be changed at any time via - mousemask(). Events that can be reported include presses, releases, - single-, double- and triple-clicks (you can set the maximum - button-down time for clicks). If you don't make clicks visible, they - will be reported as press-release pairs. In some environments, the - event mask may include bits reporting the state of shift, alt, and - ctrl keys on the keyboard during the event. - - A function to check whether a mouse event fell within a given window - is also supplied. You can use this to see whether a given window - should consider a mouse event relevant to it. - - Because mouse event reporting will not be available in all - environments, it would be unwise to build ncurses applications that - require the use of a mouse. Rather, you should use the mouse as a - shortcut for point-and-shoot commands your application would normally - accept from the keyboard. Two of the test games in the ncurses - distribution (bs and knight) contain code that illustrates how this - can be done. - - See the manual page curs_mouse(3X) for full details of the - mouse-interface functions. - - Finishing Up - - In order to clean up after the ncurses routines, the routine endwin() - is provided. It restores tty modes to what they were when initscr() - was first called, and moves the cursor down to the lower-left corner. - Thus, anytime after the call to initscr, endwin() should be called - before exiting. - -Function Descriptions - - We describe the detailed behavior of some important curses functions - here, as a supplement to the manual page descriptions. - - Initialization and Wrapup - - initscr() - The first function called should almost always be initscr(). - This will determine the terminal type and initialize curses - data structures. initscr() also arranges that the first call to - refresh() will clear the screen. If an error occurs a message - is written to standard error and the program exits. Otherwise - it returns a pointer to stdscr. A few functions may be called - before initscr (slk_init(), filter(), ripofflines(), use_env(), - and, if you are using multiple terminals, newterm().) - - endwin() - Your program should always call endwin() before exiting or - shelling out of the program. This function will restore tty - modes, move the cursor to the lower left corner of the screen, - reset the terminal into the proper non-visual mode. Calling - refresh() or doupdate() after a temporary escape from the - program will restore the ncurses screen from before the escape. - - newterm(type, ofp, ifp) - A program which outputs to more than one terminal should use - newterm() instead of initscr(). newterm() should be called once - for each terminal. It returns a variable of type SCREEN * which - should be saved as a reference to that terminal. The arguments - are the type of the terminal (a string) and FILE pointers for - the output and input of the terminal. If type is NULL then the - environment variable $TERM is used. endwin() should called once - at wrapup time for each terminal opened using this function. - - set_term(new) - This function is used to switch to a different terminal - previously opened by newterm(). The screen reference for the - new terminal is passed as the parameter. The previous terminal - is returned by the function. All other calls affect only the - current terminal. - - delscreen(sp) - The inverse of newterm(); deallocates the data structures - associated with a given SCREEN reference. - - Causing Output to the Terminal - - refresh() and wrefresh(win) - These functions must be called to actually get any output on - the terminal, as other routines merely manipulate data - structures. wrefresh() copies the named window to the physical - terminal screen, taking into account what is already there in - order to do optimizations. refresh() does a refresh of - stdscr(). Unless leaveok() has been enabled, the physical - cursor of the terminal is left at the location of the window's - cursor. - - doupdate() and wnoutrefresh(win) - These two functions allow multiple updates with more efficiency - than wrefresh. To use them, it is important to understand how - curses works. In addition to all the window structures, curses - keeps two data structures representing the terminal screen: a - physical screen, describing what is actually on the screen, and - a virtual screen, describing what the programmer wants to have - on the screen. wrefresh works by first copying the named window - to the virtual screen (wnoutrefresh()), and then calling the - routine to update the screen (doupdate()). If the programmer - wishes to output several windows at once, a series of calls to - wrefresh will result in alternating calls to wnoutrefresh() and - doupdate(), causing several bursts of output to the screen. By - calling wnoutrefresh() for each window, it is then possible to - call doupdate() once, resulting in only one burst of output, - with fewer total characters transmitted (this also avoids a - visually annoying flicker at each update). - - Low-Level Capability Access - - setupterm(term, filenum, errret) - This routine is called to initialize a terminal's description, - without setting up the curses screen structures or changing the - tty-driver mode bits. term is the character string representing - the name of the terminal being used. filenum is the UNIX file - descriptor of the terminal to be used for output. errret is a - pointer to an integer, in which a success or failure indication - is returned. The values returned can be 1 (all is well), 0 (no - such terminal), or -1 (some problem locating the terminfo - database). - - The value of term can be given as NULL, which will cause the - value of TERM in the environment to be used. The errret pointer - can also be given as NULL, meaning no error code is wanted. If - errret is defaulted, and something goes wrong, setupterm() will - print an appropriate error message and exit, rather than - returning. Thus, a simple program can call setupterm(0, 1, 0) - and not worry about initialization errors. - - After the call to setupterm(), the global variable cur_term is - set to point to the current structure of terminal capabilities. - By calling setupterm() for each terminal, and saving and - restoring cur_term, it is possible for a program to use two or - more terminals at once. Setupterm() also stores the names - section of the terminal description in the global character - array ttytype[]. Subsequent calls to setupterm() will overwrite - this array, so you'll have to save it yourself if need be. - - Debugging - - NOTE: These functions are not part of the standard curses API! - - trace() - This function can be used to explicitly set a trace level. If - the trace level is nonzero, execution of your program will - generate a file called `trace' in the current working directory - containing a report on the library's actions. Higher trace - levels enable more detailed (and verbose) reporting -- see - comments attached to TRACE_ defines in the curses.h file for - details. (It is also possible to set a trace level by assigning - a trace level value to the environment variable NCURSES_TRACE). - - _tracef() - This function can be used to output your own debugging - information. It is only available only if you link with - -lncurses_g. It can be used the same way as printf(), only it - outputs a newline after the end of arguments. The output goes - to a file called trace in the current directory. - - Trace logs can be difficult to interpret due to the sheer volume of - data dumped in them. There is a script called tracemunch included with - the ncurses distribution that can alleviate this problem somewhat; it - compacts long sequences of similar operations into more succinct - single-line pseudo-operations. These pseudo-ops can be distinguished - by the fact that they are named in capital letters. - -Hints, Tips, and Tricks - - The ncurses manual pages are a complete reference for this library. In - the remainder of this document, we discuss various useful methods that - may not be obvious from the manual page descriptions. - - Some Notes of Caution - - If you find yourself thinking you need to use noraw() or nocbreak(), - think again and move carefully. It's probably better design to use - getstr() or one of its relatives to simulate cooked mode. The noraw() - and nocbreak() functions try to restore cooked mode, but they may end - up clobbering some control bits set before you started your - application. Also, they have always been poorly documented, and are - likely to hurt your application's usability with other curses - libraries. - - Bear in mind that refresh() is a synonym for wrefresh(stdscr). Don't - try to mix use of stdscr with use of windows declared by newwin(); a - refresh() call will blow them off the screen. The right way to handle - this is to use subwin(), or not touch stdscr at all and tile your - screen with declared windows which you then wnoutrefresh() somewhere - in your program event loop, with a single doupdate() call to trigger - actual repainting. - - You are much less likely to run into problems if you design your - screen layouts to use tiled rather than overlapping windows. - Historically, curses support for overlapping windows has been weak, - fragile, and poorly documented. The ncurses library is not yet an - exception to this rule. - - There is a panels library included in the ncurses distribution that - does a pretty good job of strengthening the overlapping-windows - facilities. - - Try to avoid using the global variables LINES and COLS. Use getmaxyx() - on the stdscr context instead. Reason: your code may be ported to run - in an environment with window resizes, in which case several screens - could be open with different sizes. - - Temporarily Leaving NCURSES Mode - - Sometimes you will want to write a program that spends most of its - time in screen mode, but occasionally returns to ordinary `cooked' - mode. A common reason for this is to support shell-out. This behavior - is simple to arrange in ncurses. - - To leave ncurses mode, call endwin() as you would if you were - intending to terminate the program. This will take the screen back to - cooked mode; you can do your shell-out. When you want to return to - ncurses mode, simply call refresh() or doupdate(). This will repaint - the screen. - - There is a boolean function, isendwin(), which code can use to test - whether ncurses screen mode is active. It returns TRUE in the interval - between an endwin() call and the following refresh(), FALSE otherwise. - - Here is some sample code for shellout: - addstr("Shelling out..."); - def_prog_mode(); /* save current tty modes */ - endwin(); /* restore original tty modes */ - system("sh"); /* run shell */ - addstr("returned.\n"); /* prepare return message */ - refresh(); /* restore save modes, repaint screen */ - - Using NCURSES under XTERM - - A resize operation in X sends SIGWINCH to the application running - under xterm. The ncurses library provides an experimental signal - handler, but in general does not catch this signal, because it cannot - know how you want the screen re-painted. You will usually have to - write the SIGWINCH handler yourself. Ncurses can give you some help. - - The easiest way to code your SIGWINCH handler is to have it do an - endwin, followed by an refresh and a screen repaint you code yourself. - The refresh will pick up the new screen size from the xterm's - environment. - - That is the standard way, of course (it even works with some vendor's - curses implementations). Its drawback is that it clears the screen to - reinitialize the display, and does not resize subwindows which must be - shrunk. Ncurses provides an extension which works better, the - resizeterm function. That function ensures that all windows are - limited to the new screen dimensions, and pads stdscr with blanks if - the screen is larger. - - Finally, ncurses can be configured to provide its own SIGWINCH - handler, based on resizeterm. - - Handling Multiple Terminal Screens - - The initscr() function actually calls a function named newterm() to do - most of its work. If you are writing a program that opens multiple - terminals, use newterm() directly. - - For each call, you will have to specify a terminal type and a pair of - file pointers; each call will return a screen reference, and stdscr - will be set to the last one allocated. You will switch between screens - with the set_term call. Note that you will also have to call - def_shell_mode and def_prog_mode on each tty yourself. - - Testing for Terminal Capabilities - - Sometimes you may want to write programs that test for the presence of - various capabilities before deciding whether to go into ncurses mode. - An easy way to do this is to call setupterm(), then use the functions - tigetflag(), tigetnum(), and tigetstr() to do your testing. - - A particularly useful case of this often comes up when you want to - test whether a given terminal type should be treated as `smart' - (cursor-addressable) or `stupid'. The right way to test this is to see - if the return value of tigetstr("cup") is non-NULL. Alternatively, you - can include the term.h file and test the value of the macro - cursor_address. - - Tuning for Speed - - Use the addchstr() family of functions for fast screen-painting of - text when you know the text doesn't contain any control characters. - Try to make attribute changes infrequent on your screens. Don't use - the immedok() option! - - Special Features of NCURSES - - The wresize() function allows you to resize a window in place. The - associated resizeterm() function simplifies the construction of - SIGWINCH handlers, for resizing all windows. - - The define_key() function allows you to define at runtime function-key - control sequences which are not in the terminal description. The - keyok() function allows you to temporarily enable or disable - interpretation of any function-key control sequence. - - The use_default_colors() function allows you to construct applications - which can use the terminal's default foreground and background colors - as an additional "default" color. Several terminal emulators support - this feature, which is based on ISO 6429. - - Ncurses supports up 16 colors, unlike SVr4 curses which defines only - 8. While most terminals which provide color allow only 8 colors, about - a quarter (including XFree86 xterm) support 16 colors. - -Compatibility with Older Versions - - Despite our best efforts, there are some differences between ncurses - and the (undocumented!) behavior of older curses implementations. - These arise from ambiguities or omissions in the documentation of the - API. - - Refresh of Overlapping Windows - - If you define two windows A and B that overlap, and then alternately - scribble on and refresh them, the changes made to the overlapping - region under historic curses versions were often not documented - precisely. - - To understand why this is a problem, remember that screen updates are - calculated between two representations of the entire display. The - documentation says that when you refresh a window, it is first copied - to to the virtual screen, and then changes are calculated to update - the physical screen (and applied to the terminal). But "copied to" is - not very specific, and subtle differences in how copying works can - produce different behaviors in the case where two overlapping windows - are each being refreshed at unpredictable intervals. - - What happens to the overlapping region depends on what wnoutrefresh() - does with its argument -- what portions of the argument window it - copies to the virtual screen. Some implementations do "change copy", - copying down only locations in the window that have changed (or been - marked changed with wtouchln() and friends). Some implementations do - "entire copy", copying all window locations to the virtual screen - whether or not they have changed. - - The ncurses library itself has not always been consistent on this - score. Due to a bug, versions 1.8.7 to 1.9.8a did entire copy. - Versions 1.8.6 and older, and versions 1.9.9 and newer, do change - copy. - - For most commercial curses implementations, it is not documented and - not known for sure (at least not to the ncurses maintainers) whether - they do change copy or entire copy. We know that System V release 3 - curses has logic in it that looks like an attempt to do change copy, - but the surrounding logic and data representations are sufficiently - complex, and our knowledge sufficiently indirect, that it's hard to - know whether this is reliable. It is not clear what the SVr4 - documentation and XSI standard intend. The XSI Curses standard barely - mentions wnoutrefresh(); the SVr4 documents seem to be describing - entire-copy, but it is possible with some effort and straining to read - them the other way. - - It might therefore be unwise to rely on either behavior in programs - that might have to be linked with other curses implementations. - Instead, you can do an explicit touchwin() before the wnoutrefresh() - call to guarantee an entire-contents copy anywhere. - - The really clean way to handle this is to use the panels library. If, - when you want a screen update, you do update_panels(), it will do all - the necessary wnoutrfresh() calls for whatever panel stacking order - you have defined. Then you can do one doupdate() and there will be a - single burst of physical I/O that will do all your updates. - - Background Erase - - If you have been using a very old versions of ncurses (1.8.7 or older) - you may be surprised by the behavior of the erase functions. In older - versions, erased areas of a window were filled with a blank modified - by the window's current attribute (as set by wattrset(), wattron(), - wattroff() and friends). - - In newer versions, this is not so. Instead, the attribute of erased - blanks is normal unless and until it is modified by the functions - bkgdset() or wbkgdset(). - - This change in behavior conforms ncurses to System V Release 4 and the - XSI Curses standard. - -XSI Curses Conformance - - The ncurses library is intended to be base-level conformant with the - XSI Curses standard from X/Open. Many extended-level features (in - fact, almost all features not directly concerned with wide characters - and internationalization) are also supported. - - One effect of XSI conformance is the change in behavior described - under "Background Erase -- Compatibility with Old Versions". - - Also, ncurses meets the XSI requirement that every macro entry point - have a corresponding function which may be linked (and will be - prototype-checked) if the macro definition is disabled with #undef. - - The Panels Library - - The ncurses library by itself provides good support for screen - displays in which the windows are tiled (non-overlapping). In the more - general case that windows may overlap, you have to use a series of - wnoutrefresh() calls followed by a doupdate(), and be careful about - the order you do the window refreshes in. It has to be bottom-upwards, - otherwise parts of windows that should be obscured will show through. - - When your interface design is such that windows may dive deeper into - the visibility stack or pop to the top at runtime, the resulting - book-keeping can be tedious and difficult to get right. Hence the - panels library. - - The panel library first appeared in AT&T System V. The version - documented here is the panel code distributed with ncurses. - -Compiling With the Panels Library - - Your panels-using modules must import the panels library declarations - with - #include <panel.h> - - and must be linked explicitly with the panels library using an -lpanel - argument. Note that they must also link the ncurses library with - -lncurses. Many linkers are two-pass and will accept either order, but - it is still good practice to put -lpanel first and -lncurses second. - -Overview of Panels - - A panel object is a window that is implicitly treated as part of a - deck including all other panel objects. The deck has an implicit - bottom-to-top visibility order. The panels library includes an update - function (analogous to refresh()) that displays all panels in the deck - in the proper order to resolve overlaps. The standard window, stdscr, - is considered below all panels. - - Details on the panels functions are available in the man pages. We'll - just hit the highlights here. - - You create a panel from a window by calling new_panel() on a window - pointer. It then becomes the top of the deck. The panel's window is - available as the value of panel_window() called with the panel pointer - as argument. - - You can delete a panel (removing it from the deck) with del_panel. - This will not deallocate the associated window; you have to do that - yourself. You can replace a panel's window with a different window by - calling replace_window. The new window may be of different size; the - panel code will re-compute all overlaps. This operation doesn't change - the panel's position in the deck. - - To move a panel's window, use move_panel(). The mvwin() function on - the panel's window isn't sufficient because it doesn't update the - panels library's representation of where the windows are. This - operation leaves the panel's depth, contents, and size unchanged. - - Two functions (top_panel(), bottom_panel()) are provided for - rearranging the deck. The first pops its argument window to the top of - the deck; the second sends it to the bottom. Either operation leaves - the panel's screen location, contents, and size unchanged. - - The function update_panels() does all the wnoutrefresh() calls needed - to prepare for doupdate() (which you must call yourself, afterwards). - - Typically, you will want to call update_panels() and doupdate() just - before accepting command input, once in each cycle of interaction with - the user. If you call update_panels() after each and every panel - write, you'll generate a lot of unnecessary refresh activity and - screen flicker. - -Panels, Input, and the Standard Screen - - You shouldn't mix wnoutrefresh() or wrefresh() operations with panels - code; this will work only if the argument window is either in the top - panel or unobscured by any other panels. - - The stsdcr window is a special case. It is considered below all - panels. Because changes to panels may obscure parts of stdscr, though, - you should call update_panels() before doupdate() even when you only - change stdscr. - - Note that wgetch automatically calls wrefresh. Therefore, before - requesting input from a panel window, you need to be sure that the - panel is totally unobscured. - - There is presently no way to display changes to one obscured panel - without repainting all panels. - -Hiding Panels - - It's possible to remove a panel from the deck temporarily; use - hide_panel for this. Use show_panel() to render it visible again. The - predicate function panel_hidden tests whether or not a panel is - hidden. - - The panel_update code ignores hidden panels. You cannot do top_panel() - or bottom_panel on a hidden panel(). Other panels operations are - applicable. - -Miscellaneous Other Facilities - - It's possible to navigate the deck using the functions panel_above() - and panel_below. Handed a panel pointer, they return the panel above - or below that panel. Handed NULL, they return the bottom-most or - top-most panel. - - Every panel has an associated user pointer, not used by the panel - code, to which you can attach application data. See the man page - documentation of set_panel_userptr() and panel_userptr for details. - - The Menu Library - - A menu is a screen display that assists the user to choose some subset - of a given set of items. The menu library is a curses extension that - supports easy programming of menu hierarchies with a uniform but - flexible interface. - - The menu library first appeared in AT&T System V. The version - documented here is the menu code distributed with ncurses. - -Compiling With the menu Library - - Your menu-using modules must import the menu library declarations with - #include <menu.h> - - and must be linked explicitly with the menus library using an -lmenu - argument. Note that they must also link the ncurses library with - -lncurses. Many linkers are two-pass and will accept either order, but - it is still good practice to put -lmenu first and -lncurses second. - -Overview of Menus - - The menus created by this library consist of collections of items - including a name string part and a description string part. To make - menus, you create groups of these items and connect them with menu - frame objects. - - The menu can then by posted, that is written to an associated window. - Actually, each menu has two associated windows; a containing window in - which the programmer can scribble titles or borders, and a subwindow - in which the menu items proper are displayed. If this subwindow is too - small to display all the items, it will be a scrollable viewport on - the collection of items. - - A menu may also be unposted (that is, undisplayed), and finally freed - to make the storage associated with it and its items available for - re-use. - - The general flow of control of a menu program looks like this: - 1. Initialize curses. - 2. Create the menu items, using new_item(). - 3. Create the menu using new_menu(). - 4. Post the menu using menu_post(). - 5. Refresh the screen. - 6. Process user requests via an input loop. - 7. Unpost the menu using menu_unpost(). - 8. Free the menu, using free_menu(). - 9. Free the items using free_item(). - 10. Terminate curses. - -Selecting items - - Menus may be multi-valued or (the default) single-valued (see the - manual page menu_opts(3x) to see how to change the default). Both - types always have a current item. - - From a single-valued menu you can read the selected value simply by - looking at the current item. From a multi-valued menu, you get the - selected set by looping through the items applying the item_value() - predicate function. Your menu-processing code can use the function - set_item_value() to flag the items in the select set. - - Menu items can be made unselectable using set_item_opts() or - item_opts_off() with the O_SELECTABLE argument. This is the only - option so far defined for menus, but it is good practice to code as - though other option bits might be on. - -Menu Display - - The menu library calculates a minimum display size for your window, - based on the following variables: - - * The number and maximum length of the menu items - * Whether the O_ROWMAJOR option is enabled - * Whether display of descriptions is enabled - * Whatever menu format may have been set by the programmer - * The length of the menu mark string used for highlighting selected - items - - The function set_menu_format() allows you to set the maximum size of - the viewport or menu page that will be used to display menu items. You - can retrieve any format associated with a menu with menu_format(). The - default format is rows=16, columns=1. - - The actual menu page may be smaller than the format size. This depends - on the item number and size and whether O_ROWMAJOR is on. This option - (on by default) causes menu items to be displayed in a `raster-scan' - pattern, so that if more than one item will fit horizontally the first - couple of items are side-by-side in the top row. The alternative is - column-major display, which tries to put the first several items in - the first column. - - As mentioned above, a menu format not large enough to allow all items - to fit on-screen will result in a menu display that is vertically - scrollable. - - You can scroll it with requests to the menu driver, which will be - described in the section on menu input handling. - - Each menu has a mark string used to visually tag selected items; see - the menu_mark(3x) manual page for details. The mark string length also - influences the menu page size. - - The function scale_menu() returns the minimum display size that the - menu code computes from all these factors. There are other menu - display attributes including a select attribute, an attribute for - selectable items, an attribute for unselectable items, and a pad - character used to separate item name text from description text. These - have reasonable defaults which the library allows you to change (see - the menu_attribs(3x) manual page. - -Menu Windows - - Each menu has, as mentioned previously, a pair of associated windows. - Both these windows are painted when the menu is posted and erased when - the menu is unposted. - - The outer or frame window is not otherwise touched by the menu - routines. It exists so the programmer can associate a title, a border, - or perhaps help text with the menu and have it properly refreshed or - erased at post/unpost time. The inner window or subwindow is where the - current menu page is displayed. - - By default, both windows are stdscr. You can set them with the - functions in menu_win(3x). - - When you call menu_post(), you write the menu to its subwindow. When - you call menu_unpost(), you erase the subwindow, However, neither of - these actually modifies the screen. To do that, call wrefresh() or - some equivalent. - -Processing Menu Input - - The main loop of your menu-processing code should call menu_driver() - repeatedly. The first argument of this routine is a menu pointer; the - second is a menu command code. You should write an input-fetching - routine that maps input characters to menu command codes, and pass its - output to menu_driver(). The menu command codes are fully documented - in menu_driver(3x). - - The simplest group of command codes is REQ_NEXT_ITEM, REQ_PREV_ITEM, - REQ_FIRST_ITEM, REQ_LAST_ITEM, REQ_UP_ITEM, REQ_DOWN_ITEM, - REQ_LEFT_ITEM, REQ_RIGHT_ITEM. These change the currently selected - item. These requests may cause scrolling of the menu page if it only - partially displayed. - - There are explicit requests for scrolling which also change the - current item (because the select location does not change, but the - item there does). These are REQ_SCR_DLINE, REQ_SCR_ULINE, - REQ_SCR_DPAGE, and REQ_SCR_UPAGE. - - The REQ_TOGGLE_ITEM selects or deselects the current item. It is for - use in multi-valued menus; if you use it with O_ONEVALUE on, you'll - get an error return (E_REQUEST_DENIED). - - Each menu has an associated pattern buffer. The menu_driver() logic - tries to accumulate printable ASCII characters passed in in that - buffer; when it matches a prefix of an item name, that item (or the - next matching item) is selected. If appending a character yields no - new match, that character is deleted from the pattern buffer, and - menu_driver() returns E_NO_MATCH. - - Some requests change the pattern buffer directly: REQ_CLEAR_PATTERN, - REQ_BACK_PATTERN, REQ_NEXT_MATCH, REQ_PREV_MATCH. The latter two are - useful when pattern buffer input matches more than one item in a - multi-valued menu. - - Each successful scroll or item navigation request clears the pattern - buffer. It is also possible to set the pattern buffer explicitly with - set_menu_pattern(). - - Finally, menu driver requests above the constant MAX_COMMAND are - considered application-specific commands. The menu_driver() code - ignores them and returns E_UNKNOWN_COMMAND. - -Miscellaneous Other Features - - Various menu options can affect the processing and visual appearance - and input processing of menus. See menu_opts(3x) for details. - - It is possible to change the current item from application code; this - is useful if you want to write your own navigation requests. It is - also possible to explicitly set the top row of the menu display. See - mitem_current(3x). If your application needs to change the menu - subwindow cursor for any reason, pos_menu_cursor() will restore it to - the correct location for continuing menu driver processing. - - It is possible to set hooks to be called at menu initialization and - wrapup time, and whenever the selected item changes. See - menu_hook(3x). - - Each item, and each menu, has an associated user pointer on which you - can hang application data. See mitem_userptr(3x) and menu_userptr(3x). - - The Forms Library - - The form library is a curses extension that supports easy programming - of on-screen forms for data entry and program control. - - The form library first appeared in AT&T System V. The version - documented here is the form code distributed with ncurses. - -Compiling With the form Library - - Your form-using modules must import the form library declarations with - #include <form.h> - - and must be linked explicitly with the forms library using an -lform - argument. Note that they must also link the ncurses library with - -lncurses. Many linkers are two-pass and will accept either order, but - it is still good practice to put -lform first and -lncurses second. - -Overview of Forms - - A form is a collection of fields; each field may be either a label - (explanatory text) or a data-entry location. Long forms may be - segmented into pages; each entry to a new page clears the screen. - - To make forms, you create groups of fields and connect them with form - frame objects; the form library makes this relatively simple. - - Once defined, a form can be posted, that is written to an associated - window. Actually, each form has two associated windows; a containing - window in which the programmer can scribble titles or borders, and a - subwindow in which the form fields proper are displayed. - - As the form user fills out the posted form, navigation and editing - keys support movement between fields, editing keys support modifying - field, and plain text adds to or changes data in a current field. The - form library allows you (the forms designer) to bind each navigation - and editing key to any keystroke accepted by curses Fields may have - validation conditions on them, so that they check input data for type - and value. The form library supplies a rich set of pre-defined field - types, and makes it relatively easy to define new ones. - - Once its transaction is completed (or aborted), a form may be unposted - (that is, undisplayed), and finally freed to make the storage - associated with it and its items available for re-use. - - The general flow of control of a form program looks like this: - 1. Initialize curses. - 2. Create the form fields, using new_field(). - 3. Create the form using new_form(). - 4. Post the form using form_post(). - 5. Refresh the screen. - 6. Process user requests via an input loop. - 7. Unpost the form using form_unpost(). - 8. Free the form, using free_form(). - 9. Free the fields using free_field(). - 10. Terminate curses. - - Note that this looks much like a menu program; the form library - handles tasks which are in many ways similar, and its interface was - obviously designed to resemble that of the menu library wherever - possible. - - In forms programs, however, the `process user requests' is somewhat - more complicated than for menus. Besides menu-like navigation - operations, the menu driver loop has to support field editing and data - validation. - -Creating and Freeing Fields and Forms - - The basic function for creating fields is new_field(): - -FIELD *new_field(int height, int width, /* new field size */ - int top, int left, /* upper left corner */ - int offscreen, /* number of offscreen rows */ - int nbuf); /* number of working buffers */ - - Menu items always occupy a single row, but forms fields may have - multiple rows. So new_field() requires you to specify a width and - height (the first two arguments, which mist both be greater than - zero). - - You must also specify the location of the field's upper left corner on - the screen (the third and fourth arguments, which must be zero or - greater). Note that these coordinates are relative to the form - subwindow, which will coincide with stdscr by default but need not be - stdscr if you've done an explicit set_form_window() call. - - The fifth argument allows you to specify a number of off-screen rows. - If this is zero, the entire field will always be displayed. If it is - nonzero, the form will be scrollable, with only one screen-full - (initially the top part) displayed at any given time. If you make a - field dynamic and grow it so it will no longer fit on the screen, the - form will become scrollable even if the offscreen argument was - initially zero. - - The forms library allocates one working buffer per field; the size of - each buffer is ((height + offscreen)*width + 1, one character for each - position in the field plus a NUL terminator. The sixth argument is the - number of additional data buffers to allocate for the field; your - application can use them for its own purposes. - -FIELD *dup_field(FIELD *field, /* field to copy */ - int top, int left); /* location of new copy */ - - The function dup_field() duplicates an existing field at a new - location. Size and buffering information are copied; some attribute - flags and status bits are not (see the form_field_new(3X) for - details). - -FIELD *link_field(FIELD *field, /* field to copy */ - int top, int left); /* location of new copy */ - - The function link_field() also duplicates an existing field at a new - location. The difference from dup_field() is that it arranges for the - new field's buffer to be shared with the old one. - - Besides the obvious use in making a field editable from two different - form pages, linked fields give you a way to hack in dynamic labels. If - you declare several fields linked to an original, and then make them - inactive, changes from the original will still be propagated to the - linked fields. - - As with duplicated fields, linked fields have attribute bits separate - from the original. - - As you might guess, all these field-allocations return NULL if the - field allocation is not possible due to an out-of-memory error or - out-of-bounds arguments. - - To connect fields to a form, use - -FORM *new_form(FIELD **fields); - - This function expects to see a NULL-terminated array of field - pointers. Said fields are connected to a newly-allocated form object; - its address is returned (or else NULL if the allocation fails). - - Note that new_field() does not copy the pointer array into private - storage; if you modify the contents of the pointer array during forms - processing, all manner of bizarre things might happen. Also note that - any given field may only be connected to one form. - - The functions free_field() and free_form are available to free field - and form objects. It is an error to attempt to free a field connected - to a form, but not vice-versa; thus, you will generally free your form - objects first. - -Fetching and Changing Field Attributes - - Each form field has a number of location and size attributes - associated with it. There are other field attributes used to control - display and editing of the field. Some (for example, the O_STATIC bit) - involve sufficient complications to be covered in sections of their - own later on. We cover the functions used to get and set several basic - attributes here. - - When a field is created, the attributes not specified by the new_field - function are copied from an invisible system default field. In - attribute-setting and -fetching functions, the argument NULL is taken - to mean this field. Changes to it persist as defaults until your forms - application terminates. - - Fetching Size and Location Data - - You can retrieve field sizes and locations through: - -int field_info(FIELD *field, /* field from which to fetch */ - int *height, *int width, /* field size */ - int *top, int *left, /* upper left corner */ - int *offscreen, /* number of offscreen rows */ - int *nbuf); /* number of working buffers */ - - This function is a sort of inverse of new_field(); instead of setting - size and location attributes of a new field, it fetches them from an - existing one. - - Changing the Field Location - - It is possible to move a field's location on the screen: - -int move_field(FIELD *field, /* field to alter */ - int top, int left); /* new upper-left corner */ - - You can, of course. query the current location through field_info(). - - The Justification Attribute - - One-line fields may be unjustified, justified right, justified left, - or centered. Here is how you manipulate this attribute: - -int set_field_just(FIELD *field, /* field to alter */ - int justmode); /* mode to set */ - -int field_just(FIELD *field); /* fetch mode of field */ - - The mode values accepted and returned by this functions are - preprocessor macros NO_JUSTIFICATION, JUSTIFY_RIGHT, JUSTIFY_LEFT, or - JUSTIFY_CENTER. - - Field Display Attributes - - For each field, you can set a foreground attribute for entered - characters, a background attribute for the entire field, and a pad - character for the unfilled portion of the field. You can also control - pagination of the form. - - This group of four field attributes controls the visual appearance of - the field on the screen, without affecting in any way the data in the - field buffer. - -int set_field_fore(FIELD *field, /* field to alter */ - chtype attr); /* attribute to set */ - -chtype field_fore(FIELD *field); /* field to query */ - -int set_field_back(FIELD *field, /* field to alter */ - chtype attr); /* attribute to set */ - -chtype field_back(FIELD *field); /* field to query */ - -int set_field_pad(FIELD *field, /* field to alter */ - int pad); /* pad character to set */ - -chtype field_pad(FIELD *field); - -int set_new_page(FIELD *field, /* field to alter */ - int flag); /* TRUE to force new page */ - -chtype new_page(FIELD *field); /* field to query */ - - The attributes set and returned by the first four functions are normal - curses(3x) display attribute values (A_STANDOUT, A_BOLD, A_REVERSE - etc). The page bit of a field controls whether it is displayed at the - start of a new form screen. - - Field Option Bits - - There is also a large collection of field option bits you can set to - control various aspects of forms processing. You can manipulate them - with these functions: -int set_field_opts(FIELD *field, /* field to alter */ - int attr); /* attribute to set */ - -int field_opts_on(FIELD *field, /* field to alter */ - int attr); /* attributes to turn on */ - -int field_opts_off(FIELD *field, /* field to alter */ - int attr); /* attributes to turn off */ - -int field_opts(FIELD *field); /* field to query */ - - By default, all options are on. Here are the available option bits: - - O_VISIBLE - Controls whether the field is visible on the screen. Can be - used during form processing to hide or pop up fields depending - on the value of parent fields. - - O_ACTIVE - Controls whether the field is active during forms processing - (i.e. visited by form navigation keys). Can be used to make - labels or derived fields with buffer values alterable by the - forms application, not the user. - - O_PUBLIC - Controls whether data is displayed during field entry. If this - option is turned off on a field, the library will accept and - edit data in that field, but it will not be displayed and the - visible field cursor will not move. You can turn off the - O_PUBLIC bit to define password fields. - - O_EDIT - Controls whether the field's data can be modified. When this - option is off, all editing requests except REQ_PREV_CHOICE and - REQ_NEXT_CHOICE will fail. Such read-only fields may be useful - for help messages. - - O_WRAP - Controls word-wrapping in multi-line fields. Normally, when any - character of a (blank-separated) word reaches the end of the - current line, the entire word is wrapped to the next line - (assuming there is one). When this option is off, the word will - be split across the line break. - - O_BLANK - Controls field blanking. When this option is on, entering a - character at the first field position erases the entire field - (except for the just-entered character). - - O_AUTOSKIP - Controls automatic skip to next field when this one fills. - Normally, when the forms user tries to type more data into a - field than will fit, the editing location jumps to next field. - When this option is off, the user's cursor will hang at the end - of the field. This option is ignored in dynamic fields that - have not reached their size limit. - - O_NULLOK - Controls whether validation is applied to blank fields. - Normally, it is not; the user can leave a field blank without - invoking the usual validation check on exit. If this option is - off on a field, exit from it will invoke a validation check. - - O_PASSOK - Controls whether validation occurs on every exit, or only after - the field is modified. Normally the latter is true. Setting - O_PASSOK may be useful if your field's validation function may - change during forms processing. - - O_STATIC - Controls whether the field is fixed to its initial dimensions. - If you turn this off, the field becomes dynamic and will - stretch to fit entered data. - - A field's options cannot be changed while the field is currently - selected. However, options may be changed on posted fields that are - not current. - - The option values are bit-masks and can be composed with logical-or in - the obvious way. - -Field Status - - Every field has a status flag, which is set to FALSE when the field is - created and TRUE when the value in field buffer 0 changes. This flag - can be queried and set directly: - -int set_field_status(FIELD *field, /* field to alter */ - int status); /* mode to set */ - -int field_status(FIELD *field); /* fetch mode of field */ - - Setting this flag under program control can be useful if you use the - same form repeatedly, looking for modified fields each time. - - Calling field_status() on a field not currently selected for input - will return a correct value. Calling field_status() on a field that is - currently selected for input may not necessarily give a correct field - status value, because entered data isn't necessarily copied to buffer - zero before the exit validation check. To guarantee that the returned - status value reflects reality, call field_status() either (1) in the - field's exit validation check routine, (2) from the field's or form's - initialization or termination hooks, or (3) just after a - REQ_VALIDATION request has been processed by the forms driver. - -Field User Pointer - - Each field structure contains one character pointer slot that is not - used by the forms library. It is intended to be used by applications - to store private per-field data. You can manipulate it with: -int set_field_userptr(FIELD *field, /* field to alter */ - char *userptr); /* mode to set */ - -char *field_userptr(FIELD *field); /* fetch mode of field */ - - (Properly, this user pointer field ought to have (void *) type. The - (char *) type is retained for System V compatibility.) - - It is valid to set the user pointer of the default field (with a - set_field_userptr() call passed a NULL field pointer.) When a new - field is created, the default-field user pointer is copied to - initialize the new field's user pointer. - -Variable-Sized Fields - - Normally, a field is fixed at the size specified for it at creation - time. If, however, you turn off its O_STATIC bit, it becomes dynamic - and will automatically resize itself to accommodate data as it is - entered. If the field has extra buffers associated with it, they will - grow right along with the main input buffer. - - A one-line dynamic field will have a fixed height (1) but variable - width, scrolling horizontally to display data within the field area as - originally dimensioned and located. A multi-line dynamic field will - have a fixed width, but variable height (number of rows), scrolling - vertically to display data within the field area as originally - dimensioned and located. - - Normally, a dynamic field is allowed to grow without limit. But it is - possible to set an upper limit on the size of a dynamic field. You do - it with this function: - -int set_max_field(FIELD *field, /* field to alter (may not be NULL) */ - int max_size); /* upper limit on field size */ - - If the field is one-line, max_size is taken to be a column size limit; - if it is multi-line, it is taken to be a line size limit. To disable - any limit, use an argument of zero. The growth limit can be changed - whether or not the O_STATIC bit is on, but has no effect until it is. - - The following properties of a field change when it becomes dynamic: - * If there is no growth limit, there is no final position of the - field; therefore O_AUTOSKIP and O_NL_OVERLOAD are ignored. - * Field justification will be ignored (though whatever justification - is set up will be retained internally and can be queried). - * The dup_field() and link_field() calls copy dynamic-buffer sizes. - If the O_STATIC option is set on one of a collection of links, - buffer resizing will occur only when the field is edited through - that link. - * The call field_info() will retrieve the original static size of - the field; use dynamic_field_info() to get the actual dynamic - size. - -Field Validation - - By default, a field will accept any data that will fit in its input - buffer. However, it is possible to attach a validation type to a - field. If you do this, any attempt to leave the field while it - contains data that doesn't match the validation type will fail. Some - validation types also have a character-validity check for each time a - character is entered in the field. - - A field's validation check (if any) is not called when - set_field_buffer() modifies the input buffer, nor when that buffer is - changed through a linked field. - - The form library provides a rich set of pre-defined validation types, - and gives you the capability to define custom ones of your own. You - can examine and change field validation attributes with the following - functions: - -int set_field_type(FIELD *field, /* field to alter */ - FIELDTYPE *ftype, /* type to associate */ - ...); /* additional arguments*/ - -FIELDTYPE *field_type(FIELD *field); /* field to query */ - - The validation type of a field is considered an attribute of the - field. As with other field attributes, Also, doing set_field_type() - with a NULL field default will change the system default for - validation of newly-created fields. - - Here are the pre-defined validation types: - - TYPE_ALPHA - - This field type accepts alphabetic data; no blanks, no digits, no - special characters (this is checked at character-entry time). It is - set up with: - -int set_field_type(FIELD *field, /* field to alter */ - TYPE_ALPHA, /* type to associate */ - int width); /* maximum width of field */ - - The width argument sets a minimum width of data. Typically you'll want - to set this to the field width; if it's greater than the field width, - the validation check will always fail. A minimum width of zero makes - field completion optional. - - TYPE_ALNUM - - This field type accepts alphabetic data and digits; no blanks, no - special characters (this is checked at character-entry time). It is - set up with: - -int set_field_type(FIELD *field, /* field to alter */ - TYPE_ALNUM, /* type to associate */ - int width); /* maximum width of field */ - - The width argument sets a minimum width of data. As with TYPE_ALPHA, - typically you'll want to set this to the field width; if it's greater - than the field width, the validation check will always fail. A minimum - width of zero makes field completion optional. - - TYPE_ENUM - - This type allows you to restrict a field's values to be among a - specified set of string values (for example, the two-letter postal - codes for U.S. states). It is set up with: - -int set_field_type(FIELD *field, /* field to alter */ - TYPE_ENUM, /* type to associate */ - char **valuelist; /* list of possible values */ - int checkcase; /* case-sensitive? */ - int checkunique); /* must specify uniquely? */ - - The valuelist parameter must point at a NULL-terminated list of valid - strings. The checkcase argument, if true, makes comparison with the - string case-sensitive. - - When the user exits a TYPE_ENUM field, the validation procedure tries - to complete the data in the buffer to a valid entry. If a complete - choice string has been entered, it is of course valid. But it is also - possible to enter a prefix of a valid string and have it completed for - you. - - By default, if you enter such a prefix and it matches more than one - value in the string list, the prefix will be completed to the first - matching value. But the checkunique argument, if true, requires prefix - matches to be unique in order to be valid. - - The REQ_NEXT_CHOICE and REQ_PREV_CHOICE input requests can be - particularly useful with these fields. - - TYPE_INTEGER - - This field type accepts an integer. It is set up as follows: - -int set_field_type(FIELD *field, /* field to alter */ - TYPE_INTEGER, /* type to associate */ - int padding, /* # places to zero-pad to */ - int vmin, int vmax); /* valid range */ - - Valid characters consist of an optional leading minus and digits. The - range check is performed on exit. If the range maximum is less than or - equal to the minimum, the range is ignored. - - If the value passes its range check, it is padded with as many leading - zero digits as necessary to meet the padding argument. - - A TYPE_INTEGER value buffer can conveniently be interpreted with the C - library function atoi(3). - - TYPE_NUMERIC - - This field type accepts a decimal number. It is set up as follows: - -int set_field_type(FIELD *field, /* field to alter */ - TYPE_NUMERIC, /* type to associate */ - int padding, /* # places of precision */ - double vmin, double vmax); /* valid range */ - - Valid characters consist of an optional leading minus and digits. - possibly including a decimal point. If your system supports locale's, - the decimal point character used must be the one defined by your - locale. The range check is performed on exit. If the range maximum is - less than or equal to the minimum, the range is ignored. - - If the value passes its range check, it is padded with as many - trailing zero digits as necessary to meet the padding argument. - - A TYPE_NUMERIC value buffer can conveniently be interpreted with the C - library function atof(3). - - TYPE_REGEXP - - This field type accepts data matching a regular expression. It is set - up as follows: - -int set_field_type(FIELD *field, /* field to alter */ - TYPE_REGEXP, /* type to associate */ - char *regexp); /* expression to match */ - - The syntax for regular expressions is that of regcomp(3). The check - for regular-expression match is performed on exit. - -Direct Field Buffer Manipulation - - The chief attribute of a field is its buffer contents. When a form has - been completed, your application usually needs to know the state of - each field buffer. You can find this out with: - -char *field_buffer(FIELD *field, /* field to query */ - int bufindex); /* number of buffer to query */ - - Normally, the state of the zero-numbered buffer for each field is set - by the user's editing actions on that field. It's sometimes useful to - be able to set the value of the zero-numbered (or some other) buffer - from your application: -int set_field_buffer(FIELD *field, /* field to alter */ - int bufindex, /* number of buffer to alter */ - char *value); /* string value to set */ - - If the field is not large enough and cannot be resized to a - sufficiently large size to contain the specified value, the value will - be truncated to fit. - - Calling field_buffer() with a null field pointer will raise an error. - Calling field_buffer() on a field not currently selected for input - will return a correct value. Calling field_buffer() on a field that is - currently selected for input may not necessarily give a correct field - buffer value, because entered data isn't necessarily copied to buffer - zero before the exit validation check. To guarantee that the returned - buffer value reflects on-screen reality, call field_buffer() either - (1) in the field's exit validation check routine, (2) from the field's - or form's initialization or termination hooks, or (3) just after a - REQ_VALIDATION request has been processed by the forms driver. - -Attributes of Forms - - As with field attributes, form attributes inherit a default from a - system default form structure. These defaults can be queried or set by - of these functions using a form-pointer argument of NULL. - - The principal attribute of a form is its field list. You can query and - change this list with: - -int set_form_fields(FORM *form, /* form to alter */ - FIELD **fields); /* fields to connect */ - -char *form_fields(FORM *form); /* fetch fields of form */ - -int field_count(FORM *form); /* count connect fields */ - - The second argument of set_form_fields() may be a NULL-terminated - field pointer array like the one required by new_form(). In that case, - the old fields of the form are disconnected but not freed (and - eligible to be connected to other forms), then the new fields are - connected. - - It may also be null, in which case the old fields are disconnected - (and not freed) but no new ones are connected. - - The field_count() function simply counts the number of fields - connected to a given from. It returns -1 if the form-pointer argument - is NULL. - -Control of Form Display - - In the overview section, you saw that to display a form you normally - start by defining its size (and fields), posting it, and refreshing - the screen. There is an hidden step before posting, which is the - association of the form with a frame window (actually, a pair of - windows) within which it will be displayed. By default, the forms - library associates every form with the full-screen window stdscr. - - By making this step explicit, you can associate a form with a declared - frame window on your screen display. This can be useful if you want to - adapt the form display to different screen sizes, dynamically tile - forms on the screen, or use a form as part of an interface layout - managed by panels. - - The two windows associated with each form have the same functions as - their analogues in the menu library. Both these windows are painted - when the form is posted and erased when the form is unposted. - - The outer or frame window is not otherwise touched by the form - routines. It exists so the programmer can associate a title, a border, - or perhaps help text with the form and have it properly refreshed or - erased at post/unpost time. The inner window or subwindow is where the - current form page is actually displayed. - - In order to declare your own frame window for a form, you'll need to - know the size of the form's bounding rectangle. You can get this - information with: - -int scale_form(FORM *form, /* form to query */ - int *rows, /* form rows */ - int *cols); /* form cols */ - - The form dimensions are passed back in the locations pointed to by the - arguments. Once you have this information, you can use it to declare - of windows, then use one of these functions: -int set_form_win(FORM *form, /* form to alter */ - WINDOW *win); /* frame window to connect */ - -WINDOW *form_win(FORM *form); /* fetch frame window of form */ - -int set_form_sub(FORM *form, /* form to alter */ - WINDOW *win); /* form subwindow to connect */ - -WINDOW *form_sub(FORM *form); /* fetch form subwindow of form */ - - Note that curses operations, including refresh(), on the form, should - be done on the frame window, not the form subwindow. - - It is possible to check from your application whether all of a - scrollable field is actually displayed within the menu subwindow. Use - these functions: - -int data_ahead(FORM *form); /* form to be queried */ - -int data_behind(FORM *form); /* form to be queried */ - - The function data_ahead() returns TRUE if (a) the current field is - one-line and has undisplayed data off to the right, (b) the current - field is multi-line and there is data off-screen below it. - - The function data_behind() returns TRUE if the first (upper left hand) - character position is off-screen (not being displayed). - - Finally, there is a function to restore the form window's cursor to - the value expected by the forms driver: - -int pos_form_cursor(FORM *) /* form to be queried */ - - If your application changes the form window cursor, call this function - before handing control back to the forms driver in order to - re-synchronize it. - -Input Processing in the Forms Driver - - The function form_driver() handles virtualized input requests for form - navigation, editing, and validation requests, just as menu_driver does - for menus (see the section on menu input handling). - -int form_driver(FORM *form, /* form to pass input to */ - int request); /* form request code */ - - Your input virtualization function needs to take input and then - convert it to either an alphanumeric character (which is treated as - data to be entered in the currently-selected field), or a forms - processing request. - - The forms driver provides hooks (through input-validation and - field-termination functions) with which your application code can - check that the input taken by the driver matched what was expected. - - Page Navigation Requests - - These requests cause page-level moves through the form, triggering - display of a new form screen. - - REQ_NEXT_PAGE - Move to the next form page. - - REQ_PREV_PAGE - Move to the previous form page. - - REQ_FIRST_PAGE - Move to the first form page. - - REQ_LAST_PAGE - Move to the last form page. - - These requests treat the list as cyclic; that is, REQ_NEXT_PAGE from - the last page goes to the first, and REQ_PREV_PAGE from the first page - goes to the last. - - Inter-Field Navigation Requests - - These requests handle navigation between fields on the same page. - - REQ_NEXT_FIELD - Move to next field. - - REQ_PREV_FIELD - Move to previous field. - - REQ_FIRST_FIELD - Move to the first field. - - REQ_LAST_FIELD - Move to the last field. - - REQ_SNEXT_FIELD - Move to sorted next field. - - REQ_SPREV_FIELD - Move to sorted previous field. - - REQ_SFIRST_FIELD - Move to the sorted first field. - - REQ_SLAST_FIELD - Move to the sorted last field. - - REQ_LEFT_FIELD - Move left to field. - - REQ_RIGHT_FIELD - Move right to field. - - REQ_UP_FIELD - Move up to field. - - REQ_DOWN_FIELD - Move down to field. - - These requests treat the list of fields on a page as cyclic; that is, - REQ_NEXT_FIELD from the last field goes to the first, and - REQ_PREV_FIELD from the first field goes to the last. The order of the - fields for these (and the REQ_FIRST_FIELD and REQ_LAST_FIELD requests) - is simply the order of the field pointers in the form array (as set up - by new_form() or set_form_fields() - - It is also possible to traverse the fields as if they had been sorted - in screen-position order, so the sequence goes left-to-right and - top-to-bottom. To do this, use the second group of four - sorted-movement requests. - - Finally, it is possible to move between fields using visual directions - up, down, right, and left. To accomplish this, use the third group of - four requests. Note, however, that the position of a form for purposes - of these requests is its upper-left corner. - - For example, suppose you have a multi-line field B, and two - single-line fields A and C on the same line with B, with A to the left - of B and C to the right of B. A REQ_MOVE_RIGHT from A will go to B - only if A, B, and C all share the same first line; otherwise it will - skip over B to C. - - Intra-Field Navigation Requests - - These requests drive movement of the edit cursor within the currently - selected field. - - REQ_NEXT_CHAR - Move to next character. - - REQ_PREV_CHAR - Move to previous character. - - REQ_NEXT_LINE - Move to next line. - - REQ_PREV_LINE - Move to previous line. - - REQ_NEXT_WORD - Move to next word. - - REQ_PREV_WORD - Move to previous word. - - REQ_BEG_FIELD - Move to beginning of field. - - REQ_END_FIELD - Move to end of field. - - REQ_BEG_LINE - Move to beginning of line. - - REQ_END_LINE - Move to end of line. - - REQ_LEFT_CHAR - Move left in field. - - REQ_RIGHT_CHAR - Move right in field. - - REQ_UP_CHAR - Move up in field. - - REQ_DOWN_CHAR - Move down in field. - - Each word is separated from the previous and next characters by - whitespace. The commands to move to beginning and end of line or field - look for the first or last non-pad character in their ranges. - - Scrolling Requests - - Fields that are dynamic and have grown and fields explicitly created - with offscreen rows are scrollable. One-line fields scroll - horizontally; multi-line fields scroll vertically. Most scrolling is - triggered by editing and intra-field movement (the library scrolls the - field to keep the cursor visible). It is possible to explicitly - request scrolling with the following requests: - - REQ_SCR_FLINE - Scroll vertically forward a line. - - REQ_SCR_BLINE - Scroll vertically backward a line. - - REQ_SCR_FPAGE - Scroll vertically forward a page. - - REQ_SCR_BPAGE - Scroll vertically backward a page. - - REQ_SCR_FHPAGE - Scroll vertically forward half a page. - - REQ_SCR_BHPAGE - Scroll vertically backward half a page. - - REQ_SCR_FCHAR - Scroll horizontally forward a character. - - REQ_SCR_BCHAR - Scroll horizontally backward a character. - - REQ_SCR_HFLINE - Scroll horizontally one field width forward. - - REQ_SCR_HBLINE - Scroll horizontally one field width backward. - - REQ_SCR_HFHALF - Scroll horizontally one half field width forward. - - REQ_SCR_HBHALF - Scroll horizontally one half field width backward. - - For scrolling purposes, a page of a field is the height of its visible - part. - - Editing Requests - - When you pass the forms driver an ASCII character, it is treated as a - request to add the character to the field's data buffer. Whether this - is an insertion or a replacement depends on the field's edit mode - (insertion is the default. - - The following requests support editing the field and changing the edit - mode: - - REQ_INS_MODE - Set insertion mode. - - REQ_OVL_MODE - Set overlay mode. - - REQ_NEW_LINE - New line request (see below for explanation). - - REQ_INS_CHAR - Insert space at character location. - - REQ_INS_LINE - Insert blank line at character location. - - REQ_DEL_CHAR - Delete character at cursor. - - REQ_DEL_PREV - Delete previous word at cursor. - - REQ_DEL_LINE - Delete line at cursor. - - REQ_DEL_WORD - Delete word at cursor. - - REQ_CLR_EOL - Clear to end of line. - - REQ_CLR_EOF - Clear to end of field. - - REQ_CLEAR_FIELD - Clear entire field. - - The behavior of the REQ_NEW_LINE and REQ_DEL_PREV requests is - complicated and partly controlled by a pair of forms options. The - special cases are triggered when the cursor is at the beginning of a - field, or on the last line of the field. - - First, we consider REQ_NEW_LINE: - - The normal behavior of REQ_NEW_LINE in insert mode is to break the - current line at the position of the edit cursor, inserting the portion - of the current line after the cursor as a new line following the - current and moving the cursor to the beginning of that new line (you - may think of this as inserting a newline in the field buffer). - - The normal behavior of REQ_NEW_LINE in overlay mode is to clear the - current line from the position of the edit cursor to end of line. The - cursor is then moved to the beginning of the next line. - - However, REQ_NEW_LINE at the beginning of a field, or on the last line - of a field, instead does a REQ_NEXT_FIELD. O_NL_OVERLOAD option is - off, this special action is disabled. - - Now, let us consider REQ_DEL_PREV: - - The normal behavior of REQ_DEL_PREV is to delete the previous - character. If insert mode is on, and the cursor is at the start of a - line, and the text on that line will fit on the previous one, it - instead appends the contents of the current line to the previous one - and deletes the current line (you may think of this as deleting a - newline from the field buffer). - - However, REQ_DEL_PREV at the beginning of a field is instead treated - as a REQ_PREV_FIELD. - - If the O_BS_OVERLOAD option is off, this special action is disabled - and the forms driver just returns E_REQUEST_DENIED. - - See Form Options for discussion of how to set and clear the overload - options. - - Order Requests - - If the type of your field is ordered, and has associated functions for - getting the next and previous values of the type from a given value, - there are requests that can fetch that value into the field buffer: - - REQ_NEXT_CHOICE - Place the successor value of the current value in the buffer. - - REQ_PREV_CHOICE - Place the predecessor value of the current value in the buffer. - - Of the built-in field types, only TYPE_ENUM has built-in successor and - predecessor functions. When you define a field type of your own (see - Custom Validation Types), you can associate our own ordering - functions. - - Application Commands - - Form requests are represented as integers above the curses value - greater than KEY_MAX and less than or equal to the constant - MAX_COMMAND. If your input-virtualization routine returns a value - above MAX_COMMAND, the forms driver will ignore it. - -Field Change Hooks - - It is possible to set function hooks to be executed whenever the - current field or form changes. Here are the functions that support - this: - -typedef void (*HOOK)(); /* pointer to function returning void */ - -int set_form_init(FORM *form, /* form to alter */ - HOOK hook); /* initialization hook */ - -HOOK form_init(FORM *form); /* form to query */ - -int set_form_term(FORM *form, /* form to alter */ - HOOK hook); /* termination hook */ - -HOOK form_term(FORM *form); /* form to query */ - -int set_field_init(FORM *form, /* form to alter */ - HOOK hook); /* initialization hook */ - -HOOK field_init(FORM *form); /* form to query */ - -int set_field_term(FORM *form, /* form to alter */ - HOOK hook); /* termination hook */ - -HOOK field_term(FORM *form); /* form to query */ - - These functions allow you to either set or query four different hooks. - In each of the set functions, the second argument should be the - address of a hook function. These functions differ only in the timing - of the hook call. - - form_init - This hook is called when the form is posted; also, just after - each page change operation. - - field_init - This hook is called when the form is posted; also, just after - each field change - - field_term - This hook is called just after field validation; that is, just - before the field is altered. It is also called when the form is - unposted. - - form_term - This hook is called when the form is unposted; also, just - before each page change operation. - - Calls to these hooks may be triggered - 1. When user editing requests are processed by the forms driver - 2. When the current page is changed by set_current_field() call - 3. When the current field is changed by a set_form_page() call - - See Field Change Commands for discussion of the latter two cases. - - You can set a default hook for all fields by passing one of the set - functions a NULL first argument. - - You can disable any of these hooks by (re)setting them to NULL, the - default value. - -Field Change Commands - - Normally, navigation through the form will be driven by the user's - input requests. But sometimes it is useful to be able to move the - focus for editing and viewing under control of your application, or - ask which field it currently is in. The following functions help you - accomplish this: - -int set_current_field(FORM *form, /* form to alter */ - FIELD *field); /* field to shift to */ - -FIELD *current_field(FORM *form); /* form to query */ - -int field_index(FORM *form, /* form to query */ - FIELD *field); /* field to get index of */ - - The function field_index() returns the index of the given field in the - given form's field array (the array passed to new_form() or - set_form_fields()). - - The initial current field of a form is the first active field on the - first page. The function set_form_fields() resets this. - - It is also possible to move around by pages. - -int set_form_page(FORM *form, /* form to alter */ - int page); /* page to go to (0-origin) */ - -int form_page(FORM *form); /* return form's current page */ - - The initial page of a newly-created form is 0. The function - set_form_fields() resets this. - -Form Options - - Like fields, forms may have control option bits. They can be changed - or queried with these functions: - -int set_form_opts(FORM *form, /* form to alter */ - int attr); /* attribute to set */ - -int form_opts_on(FORM *form, /* form to alter */ - int attr); /* attributes to turn on */ - -int form_opts_off(FORM *form, /* form to alter */ - int attr); /* attributes to turn off */ - -int form_opts(FORM *form); /* form to query */ - - By default, all options are on. Here are the available option bits: - - O_NL_OVERLOAD - Enable overloading of REQ_NEW_LINE as described in Editing - Requests. The value of this option is ignored on dynamic fields - that have not reached their size limit; these have no last - line, so the circumstances for triggering a REQ_NEXT_FIELD - never arise. - - O_BS_OVERLOAD - Enable overloading of REQ_DEL_PREV as described in Editing - Requests. - - The option values are bit-masks and can be composed with logical-or in - the obvious way. - -Custom Validation Types - - The form library gives you the capability to define custom validation - types of your own. Further, the optional additional arguments of - set_field_type effectively allow you to parameterize validation types. - Most of the complications in the validation-type interface have to do - with the handling of the additional arguments within custom validation - functions. - - Union Types - - The simplest way to create a custom data type is to compose it from - two preexisting ones: - -FIELD *link_fieldtype(FIELDTYPE *type1, - FIELDTYPE *type2); - - This function creates a field type that will accept any of the values - legal for either of its argument field types (which may be either - predefined or programmer-defined). If a set_field_type() call later - requires arguments, the new composite type expects all arguments for - the first type, than all arguments for the second. Order functions - (see Order Requests) associated with the component types will work on - the composite; what it does is check the validation function for the - first type, then for the second, to figure what type the buffer - contents should be treated as. - - New Field Types - - To create a field type from scratch, you need to specify one or both - of the following things: - - * A character-validation function, to check each character as it is - entered. - * A field-validation function to be applied on exit from the field. - - Here's how you do that: - -typedef int (*HOOK)(); /* pointer to function returning int */ - -FIELDTYPE *new_fieldtype(HOOK f_validate, /* field validator */ - HOOK c_validate) /* character validator */ - - -int free_fieldtype(FIELDTYPE *ftype); /* type to free */ - - At least one of the arguments of new_fieldtype() must be non-NULL. The - forms driver will automatically call the new type's validation - functions at appropriate points in processing a field of the new type. - - The function free_fieldtype() deallocates the argument fieldtype, - freeing all storage associated with it. - - Normally, a field validator is called when the user attempts to leave - the field. Its first argument is a field pointer, from which it can - get to field buffer 0 and test it. If the function returns TRUE, the - operation succeeds; if it returns FALSE, the edit cursor stays in the - field. - - A character validator gets the character passed in as a first - argument. It too should return TRUE if the character is valid, FALSE - otherwise. - - Validation Function Arguments - - Your field- and character- validation functions will be passed a - second argument as well. This second argument is the address of a - structure (which we'll call a pile) built from any of the - field-type-specific arguments passed to set_field_type(). If no such - arguments are defined for the field type, this pile pointer argument - will be NULL. - - In order to arrange for such arguments to be passed to your validation - functions, you must associate a small set of storage-management - functions with the type. The forms driver will use these to synthesize - a pile from the trailing arguments of each set_field_type() argument, - and a pointer to the pile will be passed to the validation functions. - - Here is how you make the association: - -typedef char *(*PTRHOOK)(); /* pointer to function returning (char *) */ -typedef void (*VOIDHOOK)(); /* pointer to function returning void */ - -int set_fieldtype_arg(FIELDTYPE *type, /* type to alter */ - PTRHOOK make_str, /* make structure from args */ - PTRHOOK copy_str, /* make copy of structure */ - VOIDHOOK free_str); /* free structure storage */ - - Here is how the storage-management hooks are used: - - make_str - This function is called by set_field_type(). It gets one - argument, a va_list of the type-specific arguments passed to - set_field_type(). It is expected to return a pile pointer to a - data structure that encapsulates those arguments. - - copy_str - This function is called by form library functions that allocate - new field instances. It is expected to take a pile pointer, - copy the pile to allocated storage, and return the address of - the pile copy. - - free_str - This function is called by field- and type-deallocation - routines in the library. It takes a pile pointer argument, and - is expected to free the storage of that pile. - - The make_str and copy_str functions may return NULL to signal - allocation failure. The library routines will that call them will - return error indication when this happens. Thus, your validation - functions should never see a NULL file pointer and need not check - specially for it. - - Order Functions For Custom Types - - Some custom field types are simply ordered in the same well-defined - way that TYPE_ENUM is. For such types, it is possible to define - successor and predecessor functions to support the REQ_NEXT_CHOICE and - REQ_PREV_CHOICE requests. Here's how: - -typedef int (*INTHOOK)(); /* pointer to function returning int */ - -int set_fieldtype_arg(FIELDTYPE *type, /* type to alter */ - INTHOOK succ, /* get successor value */ - INTHOOK pred); /* get predecessor value */ - - The successor and predecessor arguments will each be passed two - arguments; a field pointer, and a pile pointer (as for the validation - functions). They are expected to use the function field_buffer() to - read the current value, and set_field_buffer() on buffer 0 to set the - next or previous value. Either hook may return TRUE to indicate - success (a legal next or previous value was set) or FALSE to indicate - failure. - - Avoiding Problems - - The interface for defining custom types is complicated and tricky. - Rather than attempting to create a custom type entirely from scratch, - you should start by studying the library source code for whichever of - the pre-defined types seems to be closest to what you want. - - Use that code as a model, and evolve it towards what you really want. - You will avoid many problems and annoyances that way. The code in the - ncurses library has been specifically exempted from the package - copyright to support this. - - If your custom type defines order functions, have do something - intuitive with a blank field. A useful convention is to make the - successor of a blank field the types minimum value, and its - predecessor the maximum. |