ncurses-intro.doc revision 76726
176726Speter 276726Speter Writing Programs with NCURSES 376726Speter 476726Speter by Eric S. Raymond and Zeyd M. Ben-Halim 576726Speter updates since release 1.9.9e by Thomas Dickey 676726Speter 776726Speter Contents 876726Speter 976726Speter * Introduction 1076726Speter + A Brief History of Curses 1176726Speter + Scope of This Document 1276726Speter + Terminology 1376726Speter * The Curses Library 1476726Speter + An Overview of Curses 1576726Speter o Compiling Programs using Curses 1676726Speter o Updating the Screen 1776726Speter o Standard Windows and Function Naming Conventions 1876726Speter o Variables 1976726Speter + Using the Library 2076726Speter o Starting up 2176726Speter o Output 2276726Speter o Input 2376726Speter o Using Forms Characters 2476726Speter o Character Attributes and Color 2576726Speter o Mouse Interfacing 2676726Speter o Finishing Up 2776726Speter + Function Descriptions 2876726Speter o Initialization and Wrapup 2976726Speter o Causing Output to the Terminal 3076726Speter o Low-Level Capability Access 3176726Speter o Debugging 3276726Speter + Hints, Tips, and Tricks 3376726Speter o Some Notes of Caution 3476726Speter o Temporarily Leaving ncurses Mode 3576726Speter o Using ncurses under xterm 3676726Speter o Handling Multiple Terminal Screens 3776726Speter o Testing for Terminal Capabilities 3876726Speter o Tuning for Speed 3976726Speter o Special Features of ncurses 4076726Speter + Compatibility with Older Versions 4176726Speter o Refresh of Overlapping Windows 4276726Speter o Background Erase 4376726Speter + XSI Curses Conformance 4476726Speter * The Panels Library 4576726Speter + Compiling With the Panels Library 4676726Speter + Overview of Panels 4776726Speter + Panels, Input, and the Standard Screen 4876726Speter + Hiding Panels 4976726Speter + Miscellaneous Other Facilities 5076726Speter * The Menu Library 5176726Speter + Compiling with the menu Library 5276726Speter + Overview of Menus 5376726Speter + Selecting items 5476726Speter + Menu Display 5576726Speter + Menu Windows 5676726Speter + Processing Menu Input 5776726Speter + Miscellaneous Other Features 5876726Speter * The Forms Library 5976726Speter + Compiling with the forms Library 6076726Speter + Overview of Forms 6176726Speter + Creating and Freeing Fields and Forms 6276726Speter + Fetching and Changing Field Attributes 6376726Speter o Fetching Size and Location Data 6476726Speter o Changing the Field Location 6576726Speter o The Justification Attribute 6676726Speter o Field Display Attributes 6776726Speter o Field Option Bits 6876726Speter o Field Status 6976726Speter o Field User Pointer 7076726Speter + Variable-Sized Fields 7176726Speter + Field Validation 7276726Speter o TYPE_ALPHA 7376726Speter o TYPE_ALNUM 7476726Speter o TYPE_ENUM 7576726Speter o TYPE_INTEGER 7676726Speter o TYPE_NUMERIC 7776726Speter o TYPE_REGEXP 7876726Speter + Direct Field Buffer Manipulation 7976726Speter + Attributes of Forms 8076726Speter + Control of Form Display 8176726Speter + Input Processing in the Forms Driver 8276726Speter o Page Navigation Requests 8376726Speter o Inter-Field Navigation Requests 8476726Speter o Intra-Field Navigation Requests 8576726Speter o Scrolling Requests 8676726Speter o Field Editing Requests 8776726Speter o Order Requests 8876726Speter o Application Commands 8976726Speter + Field Change Hooks 9076726Speter + Field Change Commands 9176726Speter + Form Options 9276726Speter + Custom Validation Types 9376726Speter o Union Types 9476726Speter o New Field Types 9576726Speter o Validation Function Arguments 9676726Speter o Order Functions For Custom Types 9776726Speter o Avoiding Problems 9876726Speter _________________________________________________________________ 9976726Speter 10076726Speter Introduction 10176726Speter 10276726Speter This document is an introduction to programming with curses. It is not 10376726Speter an exhaustive reference for the curses Application Programming 10476726Speter Interface (API); that role is filled by the curses manual pages. 10576726Speter Rather, it is intended to help C programmers ease into using the 10676726Speter package. 10776726Speter 10876726Speter This document is aimed at C applications programmers not yet 10976726Speter specifically familiar with ncurses. If you are already an experienced 11076726Speter curses programmer, you should nevertheless read the sections on Mouse 11176726Speter Interfacing, Debugging, Compatibility with Older Versions, and Hints, 11276726Speter Tips, and Tricks. These will bring you up to speed on the special 11376726Speter features and quirks of the ncurses implementation. If you are not so 11476726Speter experienced, keep reading. 11576726Speter 11676726Speter The curses package is a subroutine library for terminal-independent 11776726Speter screen-painting and input-event handling which presents a high level 11876726Speter screen model to the programmer, hiding differences between terminal 11976726Speter types and doing automatic optimization of output to change one screen 12076726Speter full of text into another. Curses uses terminfo, which is a database 12176726Speter format that can describe the capabilities of thousands of different 12276726Speter terminals. 12376726Speter 12476726Speter The curses API may seem something of an archaism on UNIX desktops 12576726Speter increasingly dominated by X, Motif, and Tcl/Tk. Nevertheless, UNIX 12676726Speter still supports tty lines and X supports xterm(1); the curses API has 12776726Speter the advantage of (a) back-portability to character-cell terminals, and 12876726Speter (b) simplicity. For an application that does not require bit-mapped 12976726Speter graphics and multiple fonts, an interface implementation using curses 13076726Speter will typically be a great deal simpler and less expensive than one 13176726Speter using an X toolkit. 13276726Speter 13376726SpeterA Brief History of Curses 13476726Speter 13576726Speter Historically, the first ancestor of curses was the routines written to 13676726Speter provide screen-handling for the game rogue; these used the 13776726Speter already-existing termcap database facility for describing terminal 13876726Speter capabilities. These routines were abstracted into a documented library 13976726Speter and first released with the early BSD UNIX versions. 14076726Speter 14176726Speter System III UNIX from Bell Labs featured a rewritten and much-improved 14276726Speter curses library. It introduced the terminfo format. Terminfo is based 14376726Speter on Berkeley's termcap database, but contains a number of improvements 14476726Speter and extensions. Parameterized capabilities strings were introduced, 14576726Speter making it possible to describe multiple video attributes, and colors 14676726Speter and to handle far more unusual terminals than possible with termcap. 14776726Speter In the later AT&T System V releases, curses evolved to use more 14876726Speter facilities and offer more capabilities, going far beyond BSD curses in 14976726Speter power and flexibility. 15076726Speter 15176726SpeterScope of This Document 15276726Speter 15376726Speter This document describes ncurses, a free implementation of the System V 15476726Speter curses API with some clearly marked extensions. It includes the 15576726Speter following System V curses features: 15676726Speter * Support for multiple screen highlights (BSD curses could only 15776726Speter handle one `standout' highlight, usually reverse-video). 15876726Speter * Support for line- and box-drawing using forms characters. 15976726Speter * Recognition of function keys on input. 16076726Speter * Color support. 16176726Speter * Support for pads (windows of larger than screen size on which the 16276726Speter screen or a subwindow defines a viewport). 16376726Speter 16476726Speter Also, this package makes use of the insert and delete line and 16576726Speter character features of terminals so equipped, and determines how to 16676726Speter optimally use these features with no help from the programmer. It 16776726Speter allows arbitrary combinations of video attributes to be displayed, 16876726Speter even on terminals that leave ``magic cookies'' on the screen to mark 16976726Speter changes in attributes. 17076726Speter 17176726Speter The ncurses package can also capture and use event reports from a 17276726Speter mouse in some environments (notably, xterm under the X window system). 17376726Speter This document includes tips for using the mouse. 17476726Speter 17576726Speter The ncurses package was originated by Pavel Curtis. The original 17676726Speter maintainer of this package is Zeyd Ben-Halim <zmbenhal@netcom.com>. 17776726Speter Eric S. Raymond <esr@snark.thyrsus.com> wrote many of the new features 17876726Speter in versions after 1.8.1 and wrote most of this introduction. J�rgen 17976726Speter Pfeifer wrote all of the menu and forms code as well as the Ada95 18076726Speter binding. Ongoing work is being done by Thomas Dickey and J�rgen 18176726Speter Pfeifer. Florian La Roche acts as the maintainer for the Free Software 18276726Speter Foundation, which holds the copyright on ncurses. Contact the current 18376726Speter maintainers at bug-ncurses@gnu.org. 18476726Speter 18576726Speter This document also describes the panels extension library, similarly 18676726Speter modeled on the SVr4 panels facility. This library allows you to 18776726Speter associate backing store with each of a stack or deck of overlapping 18876726Speter windows, and provides operations for moving windows around in the 18976726Speter stack that change their visibility in the natural way (handling window 19076726Speter overlaps). 19176726Speter 19276726Speter Finally, this document describes in detail the menus and forms 19376726Speter extension libraries, also cloned from System V, which support easy 19476726Speter construction and sequences of menus and fill-in forms. 19576726Speter 19676726SpeterTerminology 19776726Speter 19876726Speter In this document, the following terminology is used with reasonable 19976726Speter consistency: 20076726Speter 20176726Speter window 20276726Speter A data structure describing a sub-rectangle of the screen 20376726Speter (possibly the entire screen). You can write to a window as 20476726Speter though it were a miniature screen, scrolling independently of 20576726Speter other windows on the physical screen. 20676726Speter 20776726Speter screens 20876726Speter A subset of windows which are as large as the terminal screen, 20976726Speter i.e., they start at the upper left hand corner and encompass 21076726Speter the lower right hand corner. One of these, stdscr, is 21176726Speter automatically provided for the programmer. 21276726Speter 21376726Speter terminal screen 21476726Speter The package's idea of what the terminal display currently looks 21576726Speter like, i.e., what the user sees now. This is a special screen. 21676726Speter 21776726Speter The Curses Library 21876726Speter 21976726SpeterAn Overview of Curses 22076726Speter 22176726Speter Compiling Programs using Curses 22276726Speter 22376726Speter In order to use the library, it is necessary to have certain types and 22476726Speter variables defined. Therefore, the programmer must have a line: 22576726Speter #include <curses.h> 22676726Speter 22776726Speter at the top of the program source. The screen package uses the Standard 22876726Speter I/O library, so <curses.h> includes <stdio.h>. <curses.h> also 22976726Speter includes <termios.h>, <termio.h>, or <sgtty.h> depending on your 23076726Speter system. It is redundant (but harmless) for the programmer to do these 23176726Speter includes, too. In linking with curses you need to have -lncurses in 23276726Speter your LDFLAGS or on the command line. There is no need for any other 23376726Speter libraries. 23476726Speter 23576726Speter Updating the Screen 23676726Speter 23776726Speter In order to update the screen optimally, it is necessary for the 23876726Speter routines to know what the screen currently looks like and what the 23976726Speter programmer wants it to look like next. For this purpose, a data type 24076726Speter (structure) named WINDOW is defined which describes a window image to 24176726Speter the routines, including its starting position on the screen (the (y, 24276726Speter x) coordinates of the upper left hand corner) and its size. One of 24376726Speter these (called curscr, for current screen) is a screen image of what 24476726Speter the terminal currently looks like. Another screen (called stdscr, for 24576726Speter standard screen) is provided by default to make changes on. 24676726Speter 24776726Speter A window is a purely internal representation. It is used to build and 24876726Speter store a potential image of a portion of the terminal. It doesn't bear 24976726Speter any necessary relation to what is really on the terminal screen; it's 25076726Speter more like a scratchpad or write buffer. 25176726Speter 25276726Speter To make the section of physical screen corresponding to a window 25376726Speter reflect the contents of the window structure, the routine refresh() 25476726Speter (or wrefresh() if the window is not stdscr) is called. 25576726Speter 25676726Speter A given physical screen section may be within the scope of any number 25776726Speter of overlapping windows. Also, changes can be made to windows in any 25876726Speter order, without regard to motion efficiency. Then, at will, the 25976726Speter programmer can effectively say ``make it look like this,'' and let the 26076726Speter package implementation determine the most efficient way to repaint the 26176726Speter screen. 26276726Speter 26376726Speter Standard Windows and Function Naming Conventions 26476726Speter 26576726Speter As hinted above, the routines can use several windows, but two are 26676726Speter automatically given: curscr, which knows what the terminal looks like, 26776726Speter and stdscr, which is what the programmer wants the terminal to look 26876726Speter like next. The user should never actually access curscr directly. 26976726Speter Changes should be made to through the API, and then the routine 27076726Speter refresh() (or wrefresh()) called. 27176726Speter 27276726Speter Many functions are defined to use stdscr as a default screen. For 27376726Speter example, to add a character to stdscr, one calls addch() with the 27476726Speter desired character as argument. To write to a different window. use the 27576726Speter routine waddch() (for `w'indow-specific addch()) is provided. This 27676726Speter convention of prepending function names with a `w' when they are to be 27776726Speter applied to specific windows is consistent. The only routines which do 27876726Speter not follow it are those for which a window must always be specified. 27976726Speter 28076726Speter In order to move the current (y, x) coordinates from one point to 28176726Speter another, the routines move() and wmove() are provided. However, it is 28276726Speter often desirable to first move and then perform some I/O operation. In 28376726Speter order to avoid clumsiness, most I/O routines can be preceded by the 28476726Speter prefix 'mv' and the desired (y, x) coordinates prepended to the 28576726Speter arguments to the function. For example, the calls 28676726Speter move(y, x); 28776726Speter addch(ch); 28876726Speter 28976726Speter can be replaced by 29076726Speter mvaddch(y, x, ch); 29176726Speter 29276726Speter and 29376726Speter wmove(win, y, x); 29476726Speter waddch(win, ch); 29576726Speter 29676726Speter can be replaced by 29776726Speter mvwaddch(win, y, x, ch); 29876726Speter 29976726Speter Note that the window description pointer (win) comes before the added 30076726Speter (y, x) coordinates. If a function requires a window pointer, it is 30176726Speter always the first parameter passed. 30276726Speter 30376726Speter Variables 30476726Speter 30576726Speter The curses library sets some variables describing the terminal 30676726Speter capabilities. 30776726Speter type name description 30876726Speter ------------------------------------------------------------------ 30976726Speter int LINES number of lines on the terminal 31076726Speter int COLS number of columns on the terminal 31176726Speter 31276726Speter The curses.h also introduces some #define constants and types of 31376726Speter general usefulness: 31476726Speter 31576726Speter bool 31676726Speter boolean type, actually a `char' (e.g., bool doneit;) 31776726Speter 31876726Speter TRUE 31976726Speter boolean `true' flag (1). 32076726Speter 32176726Speter FALSE 32276726Speter boolean `false' flag (0). 32376726Speter 32476726Speter ERR 32576726Speter error flag returned by routines on a failure (-1). 32676726Speter 32776726Speter OK 32876726Speter error flag returned by routines when things go right. 32976726Speter 33076726SpeterUsing the Library 33176726Speter 33276726Speter Now we describe how to actually use the screen package. In it, we 33376726Speter assume all updating, reading, etc. is applied to stdscr. These 33476726Speter instructions will work on any window, providing you change the 33576726Speter function names and parameters as mentioned above. 33676726Speter 33776726Speter Here is a sample program to motivate the discussion: 33876726Speter#include <curses.h> 33976726Speter#include <signal.h> 34076726Speter 34176726Speterstatic void finish(int sig); 34276726Speter 34376726Speterint 34476726Spetermain(int argc, char *argv[]) 34576726Speter{ 34676726Speter int num = 0; 34776726Speter 34876726Speter /* initialize your non-curses data structures here */ 34976726Speter 35076726Speter (void) signal(SIGINT, finish); /* arrange interrupts to terminate */ 35176726Speter 35276726Speter (void) initscr(); /* initialize the curses library */ 35376726Speter keypad(stdscr, TRUE); /* enable keyboard mapping */ 35476726Speter (void) nonl(); /* tell curses not to do NL->CR/NL on output */ 35576726Speter (void) cbreak(); /* take input chars one at a time, no wait for \n */ 35676726Speter (void) echo(); /* echo input - in color */ 35776726Speter 35876726Speter if (has_colors()) 35976726Speter { 36076726Speter start_color(); 36176726Speter 36276726Speter /* 36376726Speter * Simple color assignment, often all we need. Color pair 0 cannot 36476726Speter * be redefined. This example uses the same value for the color 36576726Speter * pair as for the foreground color, though of course that is not 36676726Speter * necessary: 36776726Speter */ 36876726Speter init_pair(1, COLOR_RED, COLOR_BLACK); 36976726Speter init_pair(2, COLOR_GREEN, COLOR_BLACK); 37076726Speter init_pair(3, COLOR_YELLOW, COLOR_BLACK); 37176726Speter init_pair(4, COLOR_BLUE, COLOR_BLACK); 37276726Speter init_pair(5, COLOR_CYAN, COLOR_BLACK); 37376726Speter init_pair(6, COLOR_MAGENTA, COLOR_BLACK); 37476726Speter init_pair(7, COLOR_WHITE, COLOR_BLACK); 37576726Speter } 37676726Speter 37776726Speter for (;;) 37876726Speter { 37976726Speter int c = getch(); /* refresh, accept single keystroke of input */ 38076726Speter attrset(COLOR_PAIR(num % 8)); 38176726Speter num++; 38276726Speter 38376726Speter /* process the command keystroke */ 38476726Speter } 38576726Speter 38676726Speter finish(0); /* we're done */ 38776726Speter} 38876726Speter 38976726Speterstatic void finish(int sig) 39076726Speter{ 39176726Speter endwin(); 39276726Speter 39376726Speter /* do your non-curses wrapup here */ 39476726Speter 39576726Speter exit(0); 39676726Speter} 39776726Speter 39876726Speter Starting up 39976726Speter 40076726Speter In order to use the screen package, the routines must know about 40176726Speter terminal characteristics, and the space for curscr and stdscr must be 40276726Speter allocated. These function initscr() does both these things. Since it 40376726Speter must allocate space for the windows, it can overflow memory when 40476726Speter attempting to do so. On the rare occasions this happens, initscr() 40576726Speter will terminate the program with an error message. initscr() must 40676726Speter always be called before any of the routines which affect windows are 40776726Speter used. If it is not, the program will core dump as soon as either 40876726Speter curscr or stdscr are referenced. However, it is usually best to wait 40976726Speter to call it until after you are sure you will need it, like after 41076726Speter checking for startup errors. Terminal status changing routines like 41176726Speter nl() and cbreak() should be called after initscr(). 41276726Speter 41376726Speter Once the screen windows have been allocated, you can set them up for 41476726Speter your program. If you want to, say, allow a screen to scroll, use 41576726Speter scrollok(). If you want the cursor to be left in place after the last 41676726Speter change, use leaveok(). If this isn't done, refresh() will move the 41776726Speter cursor to the window's current (y, x) coordinates after updating it. 41876726Speter 41976726Speter You can create new windows of your own using the functions newwin(), 42076726Speter derwin(), and subwin(). The routine delwin() will allow you to get rid 42176726Speter of old windows. All the options described above can be applied to any 42276726Speter window. 42376726Speter 42476726Speter Output 42576726Speter 42676726Speter Now that we have set things up, we will want to actually update the 42776726Speter terminal. The basic functions used to change what will go on a window 42876726Speter are addch() and move(). addch() adds a character at the current (y, x) 42976726Speter coordinates. move() changes the current (y, x) coordinates to whatever 43076726Speter you want them to be. It returns ERR if you try to move off the window. 43176726Speter As mentioned above, you can combine the two into mvaddch() to do both 43276726Speter things at once. 43376726Speter 43476726Speter The other output functions, such as addstr() and printw(), all call 43576726Speter addch() to add characters to the window. 43676726Speter 43776726Speter After you have put on the window what you want there, when you want 43876726Speter the portion of the terminal covered by the window to be made to look 43976726Speter like it, you must call refresh(). In order to optimize finding 44076726Speter changes, refresh() assumes that any part of the window not changed 44176726Speter since the last refresh() of that window has not been changed on the 44276726Speter terminal, i.e., that you have not refreshed a portion of the terminal 44376726Speter with an overlapping window. If this is not the case, the routine 44476726Speter touchwin() is provided to make it look like the entire window has been 44576726Speter changed, thus making refresh() check the whole subsection of the 44676726Speter terminal for changes. 44776726Speter 44876726Speter If you call wrefresh() with curscr as its argument, it will make the 44976726Speter screen look like curscr thinks it looks like. This is useful for 45076726Speter implementing a command which would redraw the screen in case it get 45176726Speter messed up. 45276726Speter 45376726Speter Input 45476726Speter 45576726Speter The complementary function to addch() is getch() which, if echo is 45676726Speter set, will call addch() to echo the character. Since the screen package 45776726Speter needs to know what is on the terminal at all times, if characters are 45876726Speter to be echoed, the tty must be in raw or cbreak mode. Since initially 45976726Speter the terminal has echoing enabled and is in ordinary ``cooked'' mode, 46076726Speter one or the other has to changed before calling getch(); otherwise, the 46176726Speter program's output will be unpredictable. 46276726Speter 46376726Speter When you need to accept line-oriented input in a window, the functions 46476726Speter wgetstr() and friends are available. There is even a wscanw() function 46576726Speter that can do scanf()(3)-style multi-field parsing on window input. 46676726Speter These pseudo-line-oriented functions turn on echoing while they 46776726Speter execute. 46876726Speter 46976726Speter The example code above uses the call keypad(stdscr, TRUE) to enable 47076726Speter support for function-key mapping. With this feature, the getch() code 47176726Speter watches the input stream for character sequences that correspond to 47276726Speter arrow and function keys. These sequences are returned as 47376726Speter pseudo-character values. The #define values returned are listed in the 47476726Speter curses.h The mapping from sequences to #define values is determined by 47576726Speter key_ capabilities in the terminal's terminfo entry. 47676726Speter 47776726Speter Using Forms Characters 47876726Speter 47976726Speter The addch() function (and some others, including box() and border()) 48076726Speter can accept some pseudo-character arguments which are specially defined 48176726Speter by ncurses. These are #define values set up in the curses.h header; 48276726Speter see there for a complete list (look for the prefix ACS_). 48376726Speter 48476726Speter The most useful of the ACS defines are the forms-drawing characters. 48576726Speter You can use these to draw boxes and simple graphs on the screen. If 48676726Speter the terminal does not have such characters, curses.h will map them to 48776726Speter a recognizable (though ugly) set of ASCII defaults. 48876726Speter 48976726Speter Character Attributes and Color 49076726Speter 49176726Speter The ncurses package supports screen highlights including standout, 49276726Speter reverse-video, underline, and blink. It also supports color, which is 49376726Speter treated as another kind of highlight. 49476726Speter 49576726Speter Highlights are encoded, internally, as high bits of the 49676726Speter pseudo-character type (chtype) that curses.h uses to represent the 49776726Speter contents of a screen cell. See the curses.h header file for a complete 49876726Speter list of highlight mask values (look for the prefix A_). 49976726Speter 50076726Speter There are two ways to make highlights. One is to logical-or the value 50176726Speter of the highlights you want into the character argument of an addch() 50276726Speter call, or any other output call that takes a chtype argument. 50376726Speter 50476726Speter The other is to set the current-highlight value. This is logical-or'ed 50576726Speter with any highlight you specify the first way. You do this with the 50676726Speter functions attron(), attroff(), and attrset(); see the manual pages for 50776726Speter details. Color is a special kind of highlight. The package actually 50876726Speter thinks in terms of color pairs, combinations of foreground and 50976726Speter background colors. The sample code above sets up eight color pairs, 51076726Speter all of the guaranteed-available colors on black. Note that each color 51176726Speter pair is, in effect, given the name of its foreground color. Any other 51276726Speter range of eight non-conflicting values could have been used as the 51376726Speter first arguments of the init_pair() values. 51476726Speter 51576726Speter Once you've done an init_pair() that creates color-pair N, you can use 51676726Speter COLOR_PAIR(N) as a highlight that invokes that particular color 51776726Speter combination. Note that COLOR_PAIR(N), for constant N, is itself a 51876726Speter compile-time constant and can be used in initializers. 51976726Speter 52076726Speter Mouse Interfacing 52176726Speter 52276726Speter The ncurses library also provides a mouse interface. 52376726Speter 52476726Speter NOTE: this facility is specific to ncurses, it is not part of 52576726Speter either the XSI Curses standard, nor of System V Release 4, nor BSD 52676726Speter curses. System V Release 4 curses contains code with similar 52776726Speter interface definitions, however it is not documented. Other than by 52876726Speter disassembling the library, we have no way to determine exactly how 52976726Speter that mouse code works. Thus, we recommend that you wrap 53076726Speter mouse-related code in an #ifdef using the feature macro 53176726Speter NCURSES_MOUSE_VERSION so it will not be compiled and linked on 53276726Speter non-ncurses systems. 53376726Speter 53476726Speter Presently, mouse event reporting works in the following environments: 53576726Speter * xterm and similar programs such as rxvt. 53676726Speter * Linux console, when configured with gpm(1), Alessandro Rubini's 53776726Speter mouse server. 53876726Speter * OS/2 EMX 53976726Speter 54076726Speter The mouse interface is very simple. To activate it, you use the 54176726Speter function mousemask(), passing it as first argument a bit-mask that 54276726Speter specifies what kinds of events you want your program to be able to 54376726Speter see. It will return the bit-mask of events that actually become 54476726Speter visible, which may differ from the argument if the mouse device is not 54576726Speter capable of reporting some of the event types you specify. 54676726Speter 54776726Speter Once the mouse is active, your application's command loop should watch 54876726Speter for a return value of KEY_MOUSE from wgetch(). When you see this, a 54976726Speter mouse event report has been queued. To pick it off the queue, use the 55076726Speter function getmouse() (you must do this before the next wgetch(), 55176726Speter otherwise another mouse event might come in and make the first one 55276726Speter inaccessible). 55376726Speter 55476726Speter Each call to getmouse() fills a structure (the address of which you'll 55576726Speter pass it) with mouse event data. The event data includes zero-origin, 55676726Speter screen-relative character-cell coordinates of the mouse pointer. It 55776726Speter also includes an event mask. Bits in this mask will be set, 55876726Speter corresponding to the event type being reported. 55976726Speter 56076726Speter The mouse structure contains two additional fields which may be 56176726Speter significant in the future as ncurses interfaces to new kinds of 56276726Speter pointing device. In addition to x and y coordinates, there is a slot 56376726Speter for a z coordinate; this might be useful with touch-screens that can 56476726Speter return a pressure or duration parameter. There is also a device ID 56576726Speter field, which could be used to distinguish between multiple pointing 56676726Speter devices. 56776726Speter 56876726Speter The class of visible events may be changed at any time via 56976726Speter mousemask(). Events that can be reported include presses, releases, 57076726Speter single-, double- and triple-clicks (you can set the maximum 57176726Speter button-down time for clicks). If you don't make clicks visible, they 57276726Speter will be reported as press-release pairs. In some environments, the 57376726Speter event mask may include bits reporting the state of shift, alt, and 57476726Speter ctrl keys on the keyboard during the event. 57576726Speter 57676726Speter A function to check whether a mouse event fell within a given window 57776726Speter is also supplied. You can use this to see whether a given window 57876726Speter should consider a mouse event relevant to it. 57976726Speter 58076726Speter Because mouse event reporting will not be available in all 58176726Speter environments, it would be unwise to build ncurses applications that 58276726Speter require the use of a mouse. Rather, you should use the mouse as a 58376726Speter shortcut for point-and-shoot commands your application would normally 58476726Speter accept from the keyboard. Two of the test games in the ncurses 58576726Speter distribution (bs and knight) contain code that illustrates how this 58676726Speter can be done. 58776726Speter 58876726Speter See the manual page curs_mouse(3X) for full details of the 58976726Speter mouse-interface functions. 59076726Speter 59176726Speter Finishing Up 59276726Speter 59376726Speter In order to clean up after the ncurses routines, the routine endwin() 59476726Speter is provided. It restores tty modes to what they were when initscr() 59576726Speter was first called, and moves the cursor down to the lower-left corner. 59676726Speter Thus, anytime after the call to initscr, endwin() should be called 59776726Speter before exiting. 59876726Speter 59976726SpeterFunction Descriptions 60076726Speter 60176726Speter We describe the detailed behavior of some important curses functions 60276726Speter here, as a supplement to the manual page descriptions. 60376726Speter 60476726Speter Initialization and Wrapup 60576726Speter 60676726Speter initscr() 60776726Speter The first function called should almost always be initscr(). 60876726Speter This will determine the terminal type and initialize curses 60976726Speter data structures. initscr() also arranges that the first call to 61076726Speter refresh() will clear the screen. If an error occurs a message 61176726Speter is written to standard error and the program exits. Otherwise 61276726Speter it returns a pointer to stdscr. A few functions may be called 61376726Speter before initscr (slk_init(), filter(), ripofflines(), use_env(), 61476726Speter and, if you are using multiple terminals, newterm().) 61576726Speter 61676726Speter endwin() 61776726Speter Your program should always call endwin() before exiting or 61876726Speter shelling out of the program. This function will restore tty 61976726Speter modes, move the cursor to the lower left corner of the screen, 62076726Speter reset the terminal into the proper non-visual mode. Calling 62176726Speter refresh() or doupdate() after a temporary escape from the 62276726Speter program will restore the ncurses screen from before the escape. 62376726Speter 62476726Speter newterm(type, ofp, ifp) 62576726Speter A program which outputs to more than one terminal should use 62676726Speter newterm() instead of initscr(). newterm() should be called once 62776726Speter for each terminal. It returns a variable of type SCREEN * which 62876726Speter should be saved as a reference to that terminal. The arguments 62976726Speter are the type of the terminal (a string) and FILE pointers for 63076726Speter the output and input of the terminal. If type is NULL then the 63176726Speter environment variable $TERM is used. endwin() should called once 63276726Speter at wrapup time for each terminal opened using this function. 63376726Speter 63476726Speter set_term(new) 63576726Speter This function is used to switch to a different terminal 63676726Speter previously opened by newterm(). The screen reference for the 63776726Speter new terminal is passed as the parameter. The previous terminal 63876726Speter is returned by the function. All other calls affect only the 63976726Speter current terminal. 64076726Speter 64176726Speter delscreen(sp) 64276726Speter The inverse of newterm(); deallocates the data structures 64376726Speter associated with a given SCREEN reference. 64476726Speter 64576726Speter Causing Output to the Terminal 64676726Speter 64776726Speter refresh() and wrefresh(win) 64876726Speter These functions must be called to actually get any output on 64976726Speter the terminal, as other routines merely manipulate data 65076726Speter structures. wrefresh() copies the named window to the physical 65176726Speter terminal screen, taking into account what is already there in 65276726Speter order to do optimizations. refresh() does a refresh of 65376726Speter stdscr(). Unless leaveok() has been enabled, the physical 65476726Speter cursor of the terminal is left at the location of the window's 65576726Speter cursor. 65676726Speter 65776726Speter doupdate() and wnoutrefresh(win) 65876726Speter These two functions allow multiple updates with more efficiency 65976726Speter than wrefresh. To use them, it is important to understand how 66076726Speter curses works. In addition to all the window structures, curses 66176726Speter keeps two data structures representing the terminal screen: a 66276726Speter physical screen, describing what is actually on the screen, and 66376726Speter a virtual screen, describing what the programmer wants to have 66476726Speter on the screen. wrefresh works by first copying the named window 66576726Speter to the virtual screen (wnoutrefresh()), and then calling the 66676726Speter routine to update the screen (doupdate()). If the programmer 66776726Speter wishes to output several windows at once, a series of calls to 66876726Speter wrefresh will result in alternating calls to wnoutrefresh() and 66976726Speter doupdate(), causing several bursts of output to the screen. By 67076726Speter calling wnoutrefresh() for each window, it is then possible to 67176726Speter call doupdate() once, resulting in only one burst of output, 67276726Speter with fewer total characters transmitted (this also avoids a 67376726Speter visually annoying flicker at each update). 67476726Speter 67576726Speter Low-Level Capability Access 67676726Speter 67776726Speter setupterm(term, filenum, errret) 67876726Speter This routine is called to initialize a terminal's description, 67976726Speter without setting up the curses screen structures or changing the 68076726Speter tty-driver mode bits. term is the character string representing 68176726Speter the name of the terminal being used. filenum is the UNIX file 68276726Speter descriptor of the terminal to be used for output. errret is a 68376726Speter pointer to an integer, in which a success or failure indication 68476726Speter is returned. The values returned can be 1 (all is well), 0 (no 68576726Speter such terminal), or -1 (some problem locating the terminfo 68676726Speter database). 68776726Speter 68876726Speter The value of term can be given as NULL, which will cause the 68976726Speter value of TERM in the environment to be used. The errret pointer 69076726Speter can also be given as NULL, meaning no error code is wanted. If 69176726Speter errret is defaulted, and something goes wrong, setupterm() will 69276726Speter print an appropriate error message and exit, rather than 69376726Speter returning. Thus, a simple program can call setupterm(0, 1, 0) 69476726Speter and not worry about initialization errors. 69576726Speter 69676726Speter After the call to setupterm(), the global variable cur_term is 69776726Speter set to point to the current structure of terminal capabilities. 69876726Speter By calling setupterm() for each terminal, and saving and 69976726Speter restoring cur_term, it is possible for a program to use two or 70076726Speter more terminals at once. Setupterm() also stores the names 70176726Speter section of the terminal description in the global character 70276726Speter array ttytype[]. Subsequent calls to setupterm() will overwrite 70376726Speter this array, so you'll have to save it yourself if need be. 70476726Speter 70576726Speter Debugging 70676726Speter 70776726Speter NOTE: These functions are not part of the standard curses API! 70876726Speter 70976726Speter trace() 71076726Speter This function can be used to explicitly set a trace level. If 71176726Speter the trace level is nonzero, execution of your program will 71276726Speter generate a file called `trace' in the current working directory 71376726Speter containing a report on the library's actions. Higher trace 71476726Speter levels enable more detailed (and verbose) reporting -- see 71576726Speter comments attached to TRACE_ defines in the curses.h file for 71676726Speter details. (It is also possible to set a trace level by assigning 71776726Speter a trace level value to the environment variable NCURSES_TRACE). 71876726Speter 71976726Speter _tracef() 72076726Speter This function can be used to output your own debugging 72176726Speter information. It is only available only if you link with 72276726Speter -lncurses_g. It can be used the same way as printf(), only it 72376726Speter outputs a newline after the end of arguments. The output goes 72476726Speter to a file called trace in the current directory. 72576726Speter 72676726Speter Trace logs can be difficult to interpret due to the sheer volume of 72776726Speter data dumped in them. There is a script called tracemunch included with 72876726Speter the ncurses distribution that can alleviate this problem somewhat; it 72976726Speter compacts long sequences of similar operations into more succinct 73076726Speter single-line pseudo-operations. These pseudo-ops can be distinguished 73176726Speter by the fact that they are named in capital letters. 73276726Speter 73376726SpeterHints, Tips, and Tricks 73476726Speter 73576726Speter The ncurses manual pages are a complete reference for this library. In 73676726Speter the remainder of this document, we discuss various useful methods that 73776726Speter may not be obvious from the manual page descriptions. 73876726Speter 73976726Speter Some Notes of Caution 74076726Speter 74176726Speter If you find yourself thinking you need to use noraw() or nocbreak(), 74276726Speter think again and move carefully. It's probably better design to use 74376726Speter getstr() or one of its relatives to simulate cooked mode. The noraw() 74476726Speter and nocbreak() functions try to restore cooked mode, but they may end 74576726Speter up clobbering some control bits set before you started your 74676726Speter application. Also, they have always been poorly documented, and are 74776726Speter likely to hurt your application's usability with other curses 74876726Speter libraries. 74976726Speter 75076726Speter Bear in mind that refresh() is a synonym for wrefresh(stdscr). Don't 75176726Speter try to mix use of stdscr with use of windows declared by newwin(); a 75276726Speter refresh() call will blow them off the screen. The right way to handle 75376726Speter this is to use subwin(), or not touch stdscr at all and tile your 75476726Speter screen with declared windows which you then wnoutrefresh() somewhere 75576726Speter in your program event loop, with a single doupdate() call to trigger 75676726Speter actual repainting. 75776726Speter 75876726Speter You are much less likely to run into problems if you design your 75976726Speter screen layouts to use tiled rather than overlapping windows. 76076726Speter Historically, curses support for overlapping windows has been weak, 76176726Speter fragile, and poorly documented. The ncurses library is not yet an 76276726Speter exception to this rule. 76376726Speter 76476726Speter There is a panels library included in the ncurses distribution that 76576726Speter does a pretty good job of strengthening the overlapping-windows 76676726Speter facilities. 76776726Speter 76876726Speter Try to avoid using the global variables LINES and COLS. Use getmaxyx() 76976726Speter on the stdscr context instead. Reason: your code may be ported to run 77076726Speter in an environment with window resizes, in which case several screens 77176726Speter could be open with different sizes. 77276726Speter 77376726Speter Temporarily Leaving NCURSES Mode 77476726Speter 77576726Speter Sometimes you will want to write a program that spends most of its 77676726Speter time in screen mode, but occasionally returns to ordinary `cooked' 77776726Speter mode. A common reason for this is to support shell-out. This behavior 77876726Speter is simple to arrange in ncurses. 77976726Speter 78076726Speter To leave ncurses mode, call endwin() as you would if you were 78176726Speter intending to terminate the program. This will take the screen back to 78276726Speter cooked mode; you can do your shell-out. When you want to return to 78376726Speter ncurses mode, simply call refresh() or doupdate(). This will repaint 78476726Speter the screen. 78576726Speter 78676726Speter There is a boolean function, isendwin(), which code can use to test 78776726Speter whether ncurses screen mode is active. It returns TRUE in the interval 78876726Speter between an endwin() call and the following refresh(), FALSE otherwise. 78976726Speter 79076726Speter Here is some sample code for shellout: 79176726Speter addstr("Shelling out..."); 79276726Speter def_prog_mode(); /* save current tty modes */ 79376726Speter endwin(); /* restore original tty modes */ 79476726Speter system("sh"); /* run shell */ 79576726Speter addstr("returned.\n"); /* prepare return message */ 79676726Speter refresh(); /* restore save modes, repaint screen */ 79776726Speter 79876726Speter Using NCURSES under XTERM 79976726Speter 80076726Speter A resize operation in X sends SIGWINCH to the application running 80176726Speter under xterm. The ncurses library provides an experimental signal 80276726Speter handler, but in general does not catch this signal, because it cannot 80376726Speter know how you want the screen re-painted. You will usually have to 80476726Speter write the SIGWINCH handler yourself. Ncurses can give you some help. 80576726Speter 80676726Speter The easiest way to code your SIGWINCH handler is to have it do an 80776726Speter endwin, followed by an refresh and a screen repaint you code yourself. 80876726Speter The refresh will pick up the new screen size from the xterm's 80976726Speter environment. 81076726Speter 81176726Speter That is the standard way, of course (it even works with some vendor's 81276726Speter curses implementations). Its drawback is that it clears the screen to 81376726Speter reinitialize the display, and does not resize subwindows which must be 81476726Speter shrunk. Ncurses provides an extension which works better, the 81576726Speter resizeterm function. That function ensures that all windows are 81676726Speter limited to the new screen dimensions, and pads stdscr with blanks if 81776726Speter the screen is larger. 81876726Speter 81976726Speter Finally, ncurses can be configured to provide its own SIGWINCH 82076726Speter handler, based on resizeterm. 82176726Speter 82276726Speter Handling Multiple Terminal Screens 82376726Speter 82476726Speter The initscr() function actually calls a function named newterm() to do 82576726Speter most of its work. If you are writing a program that opens multiple 82676726Speter terminals, use newterm() directly. 82776726Speter 82876726Speter For each call, you will have to specify a terminal type and a pair of 82976726Speter file pointers; each call will return a screen reference, and stdscr 83076726Speter will be set to the last one allocated. You will switch between screens 83176726Speter with the set_term call. Note that you will also have to call 83276726Speter def_shell_mode and def_prog_mode on each tty yourself. 83376726Speter 83476726Speter Testing for Terminal Capabilities 83576726Speter 83676726Speter Sometimes you may want to write programs that test for the presence of 83776726Speter various capabilities before deciding whether to go into ncurses mode. 83876726Speter An easy way to do this is to call setupterm(), then use the functions 83976726Speter tigetflag(), tigetnum(), and tigetstr() to do your testing. 84076726Speter 84176726Speter A particularly useful case of this often comes up when you want to 84276726Speter test whether a given terminal type should be treated as `smart' 84376726Speter (cursor-addressable) or `stupid'. The right way to test this is to see 84476726Speter if the return value of tigetstr("cup") is non-NULL. Alternatively, you 84576726Speter can include the term.h file and test the value of the macro 84676726Speter cursor_address. 84776726Speter 84876726Speter Tuning for Speed 84976726Speter 85076726Speter Use the addchstr() family of functions for fast screen-painting of 85176726Speter text when you know the text doesn't contain any control characters. 85276726Speter Try to make attribute changes infrequent on your screens. Don't use 85376726Speter the immedok() option! 85476726Speter 85576726Speter Special Features of NCURSES 85676726Speter 85776726Speter The wresize() function allows you to resize a window in place. The 85876726Speter associated resizeterm() function simplifies the construction of 85976726Speter SIGWINCH handlers, for resizing all windows. 86076726Speter 86176726Speter The define_key() function allows you to define at runtime function-key 86276726Speter control sequences which are not in the terminal description. The 86376726Speter keyok() function allows you to temporarily enable or disable 86476726Speter interpretation of any function-key control sequence. 86576726Speter 86676726Speter The use_default_colors() function allows you to construct applications 86776726Speter which can use the terminal's default foreground and background colors 86876726Speter as an additional "default" color. Several terminal emulators support 86976726Speter this feature, which is based on ISO 6429. 87076726Speter 87176726Speter Ncurses supports up 16 colors, unlike SVr4 curses which defines only 87276726Speter 8. While most terminals which provide color allow only 8 colors, about 87376726Speter a quarter (including XFree86 xterm) support 16 colors. 87476726Speter 87576726SpeterCompatibility with Older Versions 87676726Speter 87776726Speter Despite our best efforts, there are some differences between ncurses 87876726Speter and the (undocumented!) behavior of older curses implementations. 87976726Speter These arise from ambiguities or omissions in the documentation of the 88076726Speter API. 88176726Speter 88276726Speter Refresh of Overlapping Windows 88376726Speter 88476726Speter If you define two windows A and B that overlap, and then alternately 88576726Speter scribble on and refresh them, the changes made to the overlapping 88676726Speter region under historic curses versions were often not documented 88776726Speter precisely. 88876726Speter 88976726Speter To understand why this is a problem, remember that screen updates are 89076726Speter calculated between two representations of the entire display. The 89176726Speter documentation says that when you refresh a window, it is first copied 89276726Speter to to the virtual screen, and then changes are calculated to update 89376726Speter the physical screen (and applied to the terminal). But "copied to" is 89476726Speter not very specific, and subtle differences in how copying works can 89576726Speter produce different behaviors in the case where two overlapping windows 89676726Speter are each being refreshed at unpredictable intervals. 89776726Speter 89876726Speter What happens to the overlapping region depends on what wnoutrefresh() 89976726Speter does with its argument -- what portions of the argument window it 90076726Speter copies to the virtual screen. Some implementations do "change copy", 90176726Speter copying down only locations in the window that have changed (or been 90276726Speter marked changed with wtouchln() and friends). Some implementations do 90376726Speter "entire copy", copying all window locations to the virtual screen 90476726Speter whether or not they have changed. 90576726Speter 90676726Speter The ncurses library itself has not always been consistent on this 90776726Speter score. Due to a bug, versions 1.8.7 to 1.9.8a did entire copy. 90876726Speter Versions 1.8.6 and older, and versions 1.9.9 and newer, do change 90976726Speter copy. 91076726Speter 91176726Speter For most commercial curses implementations, it is not documented and 91276726Speter not known for sure (at least not to the ncurses maintainers) whether 91376726Speter they do change copy or entire copy. We know that System V release 3 91476726Speter curses has logic in it that looks like an attempt to do change copy, 91576726Speter but the surrounding logic and data representations are sufficiently 91676726Speter complex, and our knowledge sufficiently indirect, that it's hard to 91776726Speter know whether this is reliable. It is not clear what the SVr4 91876726Speter documentation and XSI standard intend. The XSI Curses standard barely 91976726Speter mentions wnoutrefresh(); the SVr4 documents seem to be describing 92076726Speter entire-copy, but it is possible with some effort and straining to read 92176726Speter them the other way. 92276726Speter 92376726Speter It might therefore be unwise to rely on either behavior in programs 92476726Speter that might have to be linked with other curses implementations. 92576726Speter Instead, you can do an explicit touchwin() before the wnoutrefresh() 92676726Speter call to guarantee an entire-contents copy anywhere. 92776726Speter 92876726Speter The really clean way to handle this is to use the panels library. If, 92976726Speter when you want a screen update, you do update_panels(), it will do all 93076726Speter the necessary wnoutrfresh() calls for whatever panel stacking order 93176726Speter you have defined. Then you can do one doupdate() and there will be a 93276726Speter single burst of physical I/O that will do all your updates. 93376726Speter 93476726Speter Background Erase 93576726Speter 93676726Speter If you have been using a very old versions of ncurses (1.8.7 or older) 93776726Speter you may be surprised by the behavior of the erase functions. In older 93876726Speter versions, erased areas of a window were filled with a blank modified 93976726Speter by the window's current attribute (as set by wattrset(), wattron(), 94076726Speter wattroff() and friends). 94176726Speter 94276726Speter In newer versions, this is not so. Instead, the attribute of erased 94376726Speter blanks is normal unless and until it is modified by the functions 94476726Speter bkgdset() or wbkgdset(). 94576726Speter 94676726Speter This change in behavior conforms ncurses to System V Release 4 and the 94776726Speter XSI Curses standard. 94876726Speter 94976726SpeterXSI Curses Conformance 95076726Speter 95176726Speter The ncurses library is intended to be base-level conformant with the 95276726Speter XSI Curses standard from X/Open. Many extended-level features (in 95376726Speter fact, almost all features not directly concerned with wide characters 95476726Speter and internationalization) are also supported. 95576726Speter 95676726Speter One effect of XSI conformance is the change in behavior described 95776726Speter under "Background Erase -- Compatibility with Old Versions". 95876726Speter 95976726Speter Also, ncurses meets the XSI requirement that every macro entry point 96076726Speter have a corresponding function which may be linked (and will be 96176726Speter prototype-checked) if the macro definition is disabled with #undef. 96276726Speter 96376726Speter The Panels Library 96476726Speter 96576726Speter The ncurses library by itself provides good support for screen 96676726Speter displays in which the windows are tiled (non-overlapping). In the more 96776726Speter general case that windows may overlap, you have to use a series of 96876726Speter wnoutrefresh() calls followed by a doupdate(), and be careful about 96976726Speter the order you do the window refreshes in. It has to be bottom-upwards, 97076726Speter otherwise parts of windows that should be obscured will show through. 97176726Speter 97276726Speter When your interface design is such that windows may dive deeper into 97376726Speter the visibility stack or pop to the top at runtime, the resulting 97476726Speter book-keeping can be tedious and difficult to get right. Hence the 97576726Speter panels library. 97676726Speter 97776726Speter The panel library first appeared in AT&T System V. The version 97876726Speter documented here is the panel code distributed with ncurses. 97976726Speter 98076726SpeterCompiling With the Panels Library 98176726Speter 98276726Speter Your panels-using modules must import the panels library declarations 98376726Speter with 98476726Speter #include <panel.h> 98576726Speter 98676726Speter and must be linked explicitly with the panels library using an -lpanel 98776726Speter argument. Note that they must also link the ncurses library with 98876726Speter -lncurses. Many linkers are two-pass and will accept either order, but 98976726Speter it is still good practice to put -lpanel first and -lncurses second. 99076726Speter 99176726SpeterOverview of Panels 99276726Speter 99376726Speter A panel object is a window that is implicitly treated as part of a 99476726Speter deck including all other panel objects. The deck has an implicit 99576726Speter bottom-to-top visibility order. The panels library includes an update 99676726Speter function (analogous to refresh()) that displays all panels in the deck 99776726Speter in the proper order to resolve overlaps. The standard window, stdscr, 99876726Speter is considered below all panels. 99976726Speter 100076726Speter Details on the panels functions are available in the man pages. We'll 100176726Speter just hit the highlights here. 100276726Speter 100376726Speter You create a panel from a window by calling new_panel() on a window 100476726Speter pointer. It then becomes the top of the deck. The panel's window is 100576726Speter available as the value of panel_window() called with the panel pointer 100676726Speter as argument. 100776726Speter 100876726Speter You can delete a panel (removing it from the deck) with del_panel. 100976726Speter This will not deallocate the associated window; you have to do that 101076726Speter yourself. You can replace a panel's window with a different window by 101176726Speter calling replace_window. The new window may be of different size; the 101276726Speter panel code will re-compute all overlaps. This operation doesn't change 101376726Speter the panel's position in the deck. 101476726Speter 101576726Speter To move a panel's window, use move_panel(). The mvwin() function on 101676726Speter the panel's window isn't sufficient because it doesn't update the 101776726Speter panels library's representation of where the windows are. This 101876726Speter operation leaves the panel's depth, contents, and size unchanged. 101976726Speter 102076726Speter Two functions (top_panel(), bottom_panel()) are provided for 102176726Speter rearranging the deck. The first pops its argument window to the top of 102276726Speter the deck; the second sends it to the bottom. Either operation leaves 102376726Speter the panel's screen location, contents, and size unchanged. 102476726Speter 102576726Speter The function update_panels() does all the wnoutrefresh() calls needed 102676726Speter to prepare for doupdate() (which you must call yourself, afterwards). 102776726Speter 102876726Speter Typically, you will want to call update_panels() and doupdate() just 102976726Speter before accepting command input, once in each cycle of interaction with 103076726Speter the user. If you call update_panels() after each and every panel 103176726Speter write, you'll generate a lot of unnecessary refresh activity and 103276726Speter screen flicker. 103376726Speter 103476726SpeterPanels, Input, and the Standard Screen 103576726Speter 103676726Speter You shouldn't mix wnoutrefresh() or wrefresh() operations with panels 103776726Speter code; this will work only if the argument window is either in the top 103876726Speter panel or unobscured by any other panels. 103976726Speter 104076726Speter The stsdcr window is a special case. It is considered below all 104176726Speter panels. Because changes to panels may obscure parts of stdscr, though, 104276726Speter you should call update_panels() before doupdate() even when you only 104376726Speter change stdscr. 104476726Speter 104576726Speter Note that wgetch automatically calls wrefresh. Therefore, before 104676726Speter requesting input from a panel window, you need to be sure that the 104776726Speter panel is totally unobscured. 104876726Speter 104976726Speter There is presently no way to display changes to one obscured panel 105076726Speter without repainting all panels. 105176726Speter 105276726SpeterHiding Panels 105376726Speter 105476726Speter It's possible to remove a panel from the deck temporarily; use 105576726Speter hide_panel for this. Use show_panel() to render it visible again. The 105676726Speter predicate function panel_hidden tests whether or not a panel is 105776726Speter hidden. 105876726Speter 105976726Speter The panel_update code ignores hidden panels. You cannot do top_panel() 106076726Speter or bottom_panel on a hidden panel(). Other panels operations are 106176726Speter applicable. 106276726Speter 106376726SpeterMiscellaneous Other Facilities 106476726Speter 106576726Speter It's possible to navigate the deck using the functions panel_above() 106676726Speter and panel_below. Handed a panel pointer, they return the panel above 106776726Speter or below that panel. Handed NULL, they return the bottom-most or 106876726Speter top-most panel. 106976726Speter 107076726Speter Every panel has an associated user pointer, not used by the panel 107176726Speter code, to which you can attach application data. See the man page 107276726Speter documentation of set_panel_userptr() and panel_userptr for details. 107376726Speter 107476726Speter The Menu Library 107576726Speter 107676726Speter A menu is a screen display that assists the user to choose some subset 107776726Speter of a given set of items. The menu library is a curses extension that 107876726Speter supports easy programming of menu hierarchies with a uniform but 107976726Speter flexible interface. 108076726Speter 108176726Speter The menu library first appeared in AT&T System V. The version 108276726Speter documented here is the menu code distributed with ncurses. 108376726Speter 108476726SpeterCompiling With the menu Library 108576726Speter 108676726Speter Your menu-using modules must import the menu library declarations with 108776726Speter #include <menu.h> 108876726Speter 108976726Speter and must be linked explicitly with the menus library using an -lmenu 109076726Speter argument. Note that they must also link the ncurses library with 109176726Speter -lncurses. Many linkers are two-pass and will accept either order, but 109276726Speter it is still good practice to put -lmenu first and -lncurses second. 109376726Speter 109476726SpeterOverview of Menus 109576726Speter 109676726Speter The menus created by this library consist of collections of items 109776726Speter including a name string part and a description string part. To make 109876726Speter menus, you create groups of these items and connect them with menu 109976726Speter frame objects. 110076726Speter 110176726Speter The menu can then by posted, that is written to an associated window. 110276726Speter Actually, each menu has two associated windows; a containing window in 110376726Speter which the programmer can scribble titles or borders, and a subwindow 110476726Speter in which the menu items proper are displayed. If this subwindow is too 110576726Speter small to display all the items, it will be a scrollable viewport on 110676726Speter the collection of items. 110776726Speter 110876726Speter A menu may also be unposted (that is, undisplayed), and finally freed 110976726Speter to make the storage associated with it and its items available for 111076726Speter re-use. 111176726Speter 111276726Speter The general flow of control of a menu program looks like this: 111376726Speter 1. Initialize curses. 111476726Speter 2. Create the menu items, using new_item(). 111576726Speter 3. Create the menu using new_menu(). 111676726Speter 4. Post the menu using menu_post(). 111776726Speter 5. Refresh the screen. 111876726Speter 6. Process user requests via an input loop. 111976726Speter 7. Unpost the menu using menu_unpost(). 112076726Speter 8. Free the menu, using free_menu(). 112176726Speter 9. Free the items using free_item(). 112276726Speter 10. Terminate curses. 112376726Speter 112476726SpeterSelecting items 112576726Speter 112676726Speter Menus may be multi-valued or (the default) single-valued (see the 112776726Speter manual page menu_opts(3x) to see how to change the default). Both 112876726Speter types always have a current item. 112976726Speter 113076726Speter From a single-valued menu you can read the selected value simply by 113176726Speter looking at the current item. From a multi-valued menu, you get the 113276726Speter selected set by looping through the items applying the item_value() 113376726Speter predicate function. Your menu-processing code can use the function 113476726Speter set_item_value() to flag the items in the select set. 113576726Speter 113676726Speter Menu items can be made unselectable using set_item_opts() or 113776726Speter item_opts_off() with the O_SELECTABLE argument. This is the only 113876726Speter option so far defined for menus, but it is good practice to code as 113976726Speter though other option bits might be on. 114076726Speter 114176726SpeterMenu Display 114276726Speter 114376726Speter The menu library calculates a minimum display size for your window, 114476726Speter based on the following variables: 114576726Speter * The number and maximum length of the menu items 114676726Speter * Whether the O_ROWMAJOR option is enabled 114776726Speter * Whether display of descriptions is enabled 114876726Speter * Whatever menu format may have been set by the programmer 114976726Speter * The length of the menu mark string used for highlighting selected 115076726Speter items 115176726Speter 115276726Speter The function set_menu_format() allows you to set the maximum size of 115376726Speter the viewport or menu page that will be used to display menu items. You 115476726Speter can retrieve any format associated with a menu with menu_format(). The 115576726Speter default format is rows=16, columns=1. 115676726Speter 115776726Speter The actual menu page may be smaller than the format size. This depends 115876726Speter on the item number and size and whether O_ROWMAJOR is on. This option 115976726Speter (on by default) causes menu items to be displayed in a `raster-scan' 116076726Speter pattern, so that if more than one item will fit horizontally the first 116176726Speter couple of items are side-by-side in the top row. The alternative is 116276726Speter column-major display, which tries to put the first several items in 116376726Speter the first column. 116476726Speter 116576726Speter As mentioned above, a menu format not large enough to allow all items 116676726Speter to fit on-screen will result in a menu display that is vertically 116776726Speter scrollable. 116876726Speter 116976726Speter You can scroll it with requests to the menu driver, which will be 117076726Speter described in the section on menu input handling. 117176726Speter 117276726Speter Each menu has a mark string used to visually tag selected items; see 117376726Speter the menu_mark(3x) manual page for details. The mark string length also 117476726Speter influences the menu page size. 117576726Speter 117676726Speter The function scale_menu() returns the minimum display size that the 117776726Speter menu code computes from all these factors. There are other menu 117876726Speter display attributes including a select attribute, an attribute for 117976726Speter selectable items, an attribute for unselectable items, and a pad 118076726Speter character used to separate item name text from description text. These 118176726Speter have reasonable defaults which the library allows you to change (see 118276726Speter the menu_attribs(3x) manual page. 118376726Speter 118476726SpeterMenu Windows 118576726Speter 118676726Speter Each menu has, as mentioned previously, a pair of associated windows. 118776726Speter Both these windows are painted when the menu is posted and erased when 118876726Speter the menu is unposted. 118976726Speter 119076726Speter The outer or frame window is not otherwise touched by the menu 119176726Speter routines. It exists so the programmer can associate a title, a border, 119276726Speter or perhaps help text with the menu and have it properly refreshed or 119376726Speter erased at post/unpost time. The inner window or subwindow is where the 119476726Speter current menu page is displayed. 119576726Speter 119676726Speter By default, both windows are stdscr. You can set them with the 119776726Speter functions in menu_win(3x). 119876726Speter 119976726Speter When you call menu_post(), you write the menu to its subwindow. When 120076726Speter you call menu_unpost(), you erase the subwindow, However, neither of 120176726Speter these actually modifies the screen. To do that, call wrefresh() or 120276726Speter some equivalent. 120376726Speter 120476726SpeterProcessing Menu Input 120576726Speter 120676726Speter The main loop of your menu-processing code should call menu_driver() 120776726Speter repeatedly. The first argument of this routine is a menu pointer; the 120876726Speter second is a menu command code. You should write an input-fetching 120976726Speter routine that maps input characters to menu command codes, and pass its 121076726Speter output to menu_driver(). The menu command codes are fully documented 121176726Speter in menu_driver(3x). 121276726Speter 121376726Speter The simplest group of command codes is REQ_NEXT_ITEM, REQ_PREV_ITEM, 121476726Speter REQ_FIRST_ITEM, REQ_LAST_ITEM, REQ_UP_ITEM, REQ_DOWN_ITEM, 121576726Speter REQ_LEFT_ITEM, REQ_RIGHT_ITEM. These change the currently selected 121676726Speter item. These requests may cause scrolling of the menu page if it only 121776726Speter partially displayed. 121876726Speter 121976726Speter There are explicit requests for scrolling which also change the 122076726Speter current item (because the select location does not change, but the 122176726Speter item there does). These are REQ_SCR_DLINE, REQ_SCR_ULINE, 122276726Speter REQ_SCR_DPAGE, and REQ_SCR_UPAGE. 122376726Speter 122476726Speter The REQ_TOGGLE_ITEM selects or deselects the current item. It is for 122576726Speter use in multi-valued menus; if you use it with O_ONEVALUE on, you'll 122676726Speter get an error return (E_REQUEST_DENIED). 122776726Speter 122876726Speter Each menu has an associated pattern buffer. The menu_driver() logic 122976726Speter tries to accumulate printable ASCII characters passed in in that 123076726Speter buffer; when it matches a prefix of an item name, that item (or the 123176726Speter next matching item) is selected. If appending a character yields no 123276726Speter new match, that character is deleted from the pattern buffer, and 123376726Speter menu_driver() returns E_NO_MATCH. 123476726Speter 123576726Speter Some requests change the pattern buffer directly: REQ_CLEAR_PATTERN, 123676726Speter REQ_BACK_PATTERN, REQ_NEXT_MATCH, REQ_PREV_MATCH. The latter two are 123776726Speter useful when pattern buffer input matches more than one item in a 123876726Speter multi-valued menu. 123976726Speter 124076726Speter Each successful scroll or item navigation request clears the pattern 124176726Speter buffer. It is also possible to set the pattern buffer explicitly with 124276726Speter set_menu_pattern(). 124376726Speter 124476726Speter Finally, menu driver requests above the constant MAX_COMMAND are 124576726Speter considered application-specific commands. The menu_driver() code 124676726Speter ignores them and returns E_UNKNOWN_COMMAND. 124776726Speter 124876726SpeterMiscellaneous Other Features 124976726Speter 125076726Speter Various menu options can affect the processing and visual appearance 125176726Speter and input processing of menus. See menu_opts(3x) for details. 125276726Speter 125376726Speter It is possible to change the current item from application code; this 125476726Speter is useful if you want to write your own navigation requests. It is 125576726Speter also possible to explicitly set the top row of the menu display. See 125676726Speter mitem_current(3x). If your application needs to change the menu 125776726Speter subwindow cursor for any reason, pos_menu_cursor() will restore it to 125876726Speter the correct location for continuing menu driver processing. 125976726Speter 126076726Speter It is possible to set hooks to be called at menu initialization and 126176726Speter wrapup time, and whenever the selected item changes. See 126276726Speter menu_hook(3x). 126376726Speter 126476726Speter Each item, and each menu, has an associated user pointer on which you 126576726Speter can hang application data. See mitem_userptr(3x) and menu_userptr(3x). 126676726Speter 126776726Speter The Forms Library 126876726Speter 126976726Speter The form library is a curses extension that supports easy programming 127076726Speter of on-screen forms for data entry and program control. 127176726Speter 127276726Speter The form library first appeared in AT&T System V. The version 127376726Speter documented here is the form code distributed with ncurses. 127476726Speter 127576726SpeterCompiling With the form Library 127676726Speter 127776726Speter Your form-using modules must import the form library declarations with 127876726Speter #include <form.h> 127976726Speter 128076726Speter and must be linked explicitly with the forms library using an -lform 128176726Speter argument. Note that they must also link the ncurses library with 128276726Speter -lncurses. Many linkers are two-pass and will accept either order, but 128376726Speter it is still good practice to put -lform first and -lncurses second. 128476726Speter 128576726SpeterOverview of Forms 128676726Speter 128776726Speter A form is a collection of fields; each field may be either a label 128876726Speter (explanatory text) or a data-entry location. Long forms may be 128976726Speter segmented into pages; each entry to a new page clears the screen. 129076726Speter 129176726Speter To make forms, you create groups of fields and connect them with form 129276726Speter frame objects; the form library makes this relatively simple. 129376726Speter 129476726Speter Once defined, a form can be posted, that is written to an associated 129576726Speter window. Actually, each form has two associated windows; a containing 129676726Speter window in which the programmer can scribble titles or borders, and a 129776726Speter subwindow in which the form fields proper are displayed. 129876726Speter 129976726Speter As the form user fills out the posted form, navigation and editing 130076726Speter keys support movement between fields, editing keys support modifying 130176726Speter field, and plain text adds to or changes data in a current field. The 130276726Speter form library allows you (the forms designer) to bind each navigation 130376726Speter and editing key to any keystroke accepted by curses Fields may have 130476726Speter validation conditions on them, so that they check input data for type 130576726Speter and value. The form library supplies a rich set of pre-defined field 130676726Speter types, and makes it relatively easy to define new ones. 130776726Speter 130876726Speter Once its transaction is completed (or aborted), a form may be unposted 130976726Speter (that is, undisplayed), and finally freed to make the storage 131076726Speter associated with it and its items available for re-use. 131176726Speter 131276726Speter The general flow of control of a form program looks like this: 131376726Speter 1. Initialize curses. 131476726Speter 2. Create the form fields, using new_field(). 131576726Speter 3. Create the form using new_form(). 131676726Speter 4. Post the form using form_post(). 131776726Speter 5. Refresh the screen. 131876726Speter 6. Process user requests via an input loop. 131976726Speter 7. Unpost the form using form_unpost(). 132076726Speter 8. Free the form, using free_form(). 132176726Speter 9. Free the fields using free_field(). 132276726Speter 10. Terminate curses. 132376726Speter 132476726Speter Note that this looks much like a menu program; the form library 132576726Speter handles tasks which are in many ways similar, and its interface was 132676726Speter obviously designed to resemble that of the menu library wherever 132776726Speter possible. 132876726Speter 132976726Speter In forms programs, however, the `process user requests' is somewhat 133076726Speter more complicated than for menus. Besides menu-like navigation 133176726Speter operations, the menu driver loop has to support field editing and data 133276726Speter validation. 133376726Speter 133476726SpeterCreating and Freeing Fields and Forms 133576726Speter 133676726Speter The basic function for creating fields is new_field(): 133776726SpeterFIELD *new_field(int height, int width, /* new field size */ 133876726Speter int top, int left, /* upper left corner */ 133976726Speter int offscreen, /* number of offscreen rows */ 134076726Speter int nbuf); /* number of working buffers */ 134176726Speter 134276726Speter Menu items always occupy a single row, but forms fields may have 134376726Speter multiple rows. So new_field() requires you to specify a width and 134476726Speter height (the first two arguments, which mist both be greater than 134576726Speter zero). 134676726Speter 134776726Speter You must also specify the location of the field's upper left corner on 134876726Speter the screen (the third and fourth arguments, which must be zero or 134976726Speter greater). Note that these coordinates are relative to the form 135076726Speter subwindow, which will coincide with stdscr by default but need not be 135176726Speter stdscr if you've done an explicit set_form_window() call. 135276726Speter 135376726Speter The fifth argument allows you to specify a number of off-screen rows. 135476726Speter If this is zero, the entire field will always be displayed. If it is 135576726Speter nonzero, the form will be scrollable, with only one screen-full 135676726Speter (initially the top part) displayed at any given time. If you make a 135776726Speter field dynamic and grow it so it will no longer fit on the screen, the 135876726Speter form will become scrollable even if the offscreen argument was 135976726Speter initially zero. 136076726Speter 136176726Speter The forms library allocates one working buffer per field; the size of 136276726Speter each buffer is ((height + offscreen)*width + 1, one character for each 136376726Speter position in the field plus a NUL terminator. The sixth argument is the 136476726Speter number of additional data buffers to allocate for the field; your 136576726Speter application can use them for its own purposes. 136676726SpeterFIELD *dup_field(FIELD *field, /* field to copy */ 136776726Speter int top, int left); /* location of new copy */ 136876726Speter 136976726Speter The function dup_field() duplicates an existing field at a new 137076726Speter location. Size and buffering information are copied; some attribute 137176726Speter flags and status bits are not (see the form_field_new(3X) for 137276726Speter details). 137376726SpeterFIELD *link_field(FIELD *field, /* field to copy */ 137476726Speter int top, int left); /* location of new copy */ 137576726Speter 137676726Speter The function link_field() also duplicates an existing field at a new 137776726Speter location. The difference from dup_field() is that it arranges for the 137876726Speter new field's buffer to be shared with the old one. 137976726Speter 138076726Speter Besides the obvious use in making a field editable from two different 138176726Speter form pages, linked fields give you a way to hack in dynamic labels. If 138276726Speter you declare several fields linked to an original, and then make them 138376726Speter inactive, changes from the original will still be propagated to the 138476726Speter linked fields. 138576726Speter 138676726Speter As with duplicated fields, linked fields have attribute bits separate 138776726Speter from the original. 138876726Speter 138976726Speter As you might guess, all these field-allocations return NULL if the 139076726Speter field allocation is not possible due to an out-of-memory error or 139176726Speter out-of-bounds arguments. 139276726Speter 139376726Speter To connect fields to a form, use 139476726SpeterFORM *new_form(FIELD **fields); 139576726Speter 139676726Speter This function expects to see a NULL-terminated array of field 139776726Speter pointers. Said fields are connected to a newly-allocated form object; 139876726Speter its address is returned (or else NULL if the allocation fails). 139976726Speter 140076726Speter Note that new_field() does not copy the pointer array into private 140176726Speter storage; if you modify the contents of the pointer array during forms 140276726Speter processing, all manner of bizarre things might happen. Also note that 140376726Speter any given field may only be connected to one form. 140476726Speter 140576726Speter The functions free_field() and free_form are available to free field 140676726Speter and form objects. It is an error to attempt to free a field connected 140776726Speter to a form, but not vice-versa; thus, you will generally free your form 140876726Speter objects first. 140976726Speter 141076726SpeterFetching and Changing Field Attributes 141176726Speter 141276726Speter Each form field has a number of location and size attributes 141376726Speter associated with it. There are other field attributes used to control 141476726Speter display and editing of the field. Some (for example, the O_STATIC bit) 141576726Speter involve sufficient complications to be covered in sections of their 141676726Speter own later on. We cover the functions used to get and set several basic 141776726Speter attributes here. 141876726Speter 141976726Speter When a field is created, the attributes not specified by the new_field 142076726Speter function are copied from an invisible system default field. In 142176726Speter attribute-setting and -fetching functions, the argument NULL is taken 142276726Speter to mean this field. Changes to it persist as defaults until your forms 142376726Speter application terminates. 142476726Speter 142576726Speter Fetching Size and Location Data 142676726Speter 142776726Speter You can retrieve field sizes and locations through: 142876726Speterint field_info(FIELD *field, /* field from which to fetch */ 142976726Speter int *height, *int width, /* field size */ 143076726Speter int *top, int *left, /* upper left corner */ 143176726Speter int *offscreen, /* number of offscreen rows */ 143276726Speter int *nbuf); /* number of working buffers */ 143376726Speter 143476726Speter This function is a sort of inverse of new_field(); instead of setting 143576726Speter size and location attributes of a new field, it fetches them from an 143676726Speter existing one. 143776726Speter 143876726Speter Changing the Field Location 143976726Speter 144076726Speter It is possible to move a field's location on the screen: 144176726Speterint move_field(FIELD *field, /* field to alter */ 144276726Speter int top, int left); /* new upper-left corner */ 144376726Speter 144476726Speter You can, of course. query the current location through field_info(). 144576726Speter 144676726Speter The Justification Attribute 144776726Speter 144876726Speter One-line fields may be unjustified, justified right, justified left, 144976726Speter or centered. Here is how you manipulate this attribute: 145076726Speterint set_field_just(FIELD *field, /* field to alter */ 145176726Speter int justmode); /* mode to set */ 145276726Speter 145376726Speterint field_just(FIELD *field); /* fetch mode of field */ 145476726Speter 145576726Speter The mode values accepted and returned by this functions are 145676726Speter preprocessor macros NO_JUSTIFICATION, JUSTIFY_RIGHT, JUSTIFY_LEFT, or 145776726Speter JUSTIFY_CENTER. 145876726Speter 145976726Speter Field Display Attributes 146076726Speter 146176726Speter For each field, you can set a foreground attribute for entered 146276726Speter characters, a background attribute for the entire field, and a pad 146376726Speter character for the unfilled portion of the field. You can also control 146476726Speter pagination of the form. 146576726Speter 146676726Speter This group of four field attributes controls the visual appearance of 146776726Speter the field on the screen, without affecting in any way the data in the 146876726Speter field buffer. 146976726Speterint set_field_fore(FIELD *field, /* field to alter */ 147076726Speter chtype attr); /* attribute to set */ 147176726Speter 147276726Speterchtype field_fore(FIELD *field); /* field to query */ 147376726Speter 147476726Speterint set_field_back(FIELD *field, /* field to alter */ 147576726Speter chtype attr); /* attribute to set */ 147676726Speter 147776726Speterchtype field_back(FIELD *field); /* field to query */ 147876726Speter 147976726Speterint set_field_pad(FIELD *field, /* field to alter */ 148076726Speter int pad); /* pad character to set */ 148176726Speter 148276726Speterchtype field_pad(FIELD *field); 148376726Speter 148476726Speterint set_new_page(FIELD *field, /* field to alter */ 148576726Speter int flag); /* TRUE to force new page */ 148676726Speter 148776726Speterchtype new_page(FIELD *field); /* field to query */ 148876726Speter 148976726Speter The attributes set and returned by the first four functions are normal 149076726Speter curses(3x) display attribute values (A_STANDOUT, A_BOLD, A_REVERSE 149176726Speter etc). The page bit of a field controls whether it is displayed at the 149276726Speter start of a new form screen. 149376726Speter 149476726Speter Field Option Bits 149576726Speter 149676726Speter There is also a large collection of field option bits you can set to 149776726Speter control various aspects of forms processing. You can manipulate them 149876726Speter with these functions: 149976726Speterint set_field_opts(FIELD *field, /* field to alter */ 150076726Speter int attr); /* attribute to set */ 150176726Speter 150276726Speterint field_opts_on(FIELD *field, /* field to alter */ 150376726Speter int attr); /* attributes to turn on */ 150476726Speter 150576726Speterint field_opts_off(FIELD *field, /* field to alter */ 150676726Speter int attr); /* attributes to turn off */ 150776726Speter 150876726Speterint field_opts(FIELD *field); /* field to query */ 150976726Speter 151076726Speter By default, all options are on. Here are the available option bits: 151176726Speter 151276726Speter O_VISIBLE 151376726Speter Controls whether the field is visible on the screen. Can be 151476726Speter used during form processing to hide or pop up fields depending 151576726Speter on the value of parent fields. 151676726Speter 151776726Speter O_ACTIVE 151876726Speter Controls whether the field is active during forms processing 151976726Speter (i.e. visited by form navigation keys). Can be used to make 152076726Speter labels or derived fields with buffer values alterable by the 152176726Speter forms application, not the user. 152276726Speter 152376726Speter O_PUBLIC 152476726Speter Controls whether data is displayed during field entry. If this 152576726Speter option is turned off on a field, the library will accept and 152676726Speter edit data in that field, but it will not be displayed and the 152776726Speter visible field cursor will not move. You can turn off the 152876726Speter O_PUBLIC bit to define password fields. 152976726Speter 153076726Speter O_EDIT 153176726Speter Controls whether the field's data can be modified. When this 153276726Speter option is off, all editing requests except REQ_PREV_CHOICE and 153376726Speter REQ_NEXT_CHOICE will fail. Such read-only fields may be useful 153476726Speter for help messages. 153576726Speter 153676726Speter O_WRAP 153776726Speter Controls word-wrapping in multi-line fields. Normally, when any 153876726Speter character of a (blank-separated) word reaches the end of the 153976726Speter current line, the entire word is wrapped to the next line 154076726Speter (assuming there is one). When this option is off, the word will 154176726Speter be split across the line break. 154276726Speter 154376726Speter O_BLANK 154476726Speter Controls field blanking. When this option is on, entering a 154576726Speter character at the first field position erases the entire field 154676726Speter (except for the just-entered character). 154776726Speter 154876726Speter O_AUTOSKIP 154976726Speter Controls automatic skip to next field when this one fills. 155076726Speter Normally, when the forms user tries to type more data into a 155176726Speter field than will fit, the editing location jumps to next field. 155276726Speter When this option is off, the user's cursor will hang at the end 155376726Speter of the field. This option is ignored in dynamic fields that 155476726Speter have not reached their size limit. 155576726Speter 155676726Speter O_NULLOK 155776726Speter Controls whether validation is applied to blank fields. 155876726Speter Normally, it is not; the user can leave a field blank without 155976726Speter invoking the usual validation check on exit. If this option is 156076726Speter off on a field, exit from it will invoke a validation check. 156176726Speter 156276726Speter O_PASSOK 156376726Speter Controls whether validation occurs on every exit, or only after 156476726Speter the field is modified. Normally the latter is true. Setting 156576726Speter O_PASSOK may be useful if your field's validation function may 156676726Speter change during forms processing. 156776726Speter 156876726Speter O_STATIC 156976726Speter Controls whether the field is fixed to its initial dimensions. 157076726Speter If you turn this off, the field becomes dynamic and will 157176726Speter stretch to fit entered data. 157276726Speter 157376726Speter A field's options cannot be changed while the field is currently 157476726Speter selected. However, options may be changed on posted fields that are 157576726Speter not current. 157676726Speter 157776726Speter The option values are bit-masks and can be composed with logical-or in 157876726Speter the obvious way. 157976726Speter 158076726SpeterField Status 158176726Speter 158276726Speter Every field has a status flag, which is set to FALSE when the field is 158376726Speter created and TRUE when the value in field buffer 0 changes. This flag 158476726Speter can be queried and set directly: 158576726Speterint set_field_status(FIELD *field, /* field to alter */ 158676726Speter int status); /* mode to set */ 158776726Speter 158876726Speterint field_status(FIELD *field); /* fetch mode of field */ 158976726Speter 159076726Speter Setting this flag under program control can be useful if you use the 159176726Speter same form repeatedly, looking for modified fields each time. 159276726Speter 159376726Speter Calling field_status() on a field not currently selected for input 159476726Speter will return a correct value. Calling field_status() on a field that is 159576726Speter currently selected for input may not necessarily give a correct field 159676726Speter status value, because entered data isn't necessarily copied to buffer 159776726Speter zero before the exit validation check. To guarantee that the returned 159876726Speter status value reflects reality, call field_status() either (1) in the 159976726Speter field's exit validation check routine, (2) from the field's or form's 160076726Speter initialization or termination hooks, or (3) just after a 160176726Speter REQ_VALIDATION request has been processed by the forms driver. 160276726Speter 160376726SpeterField User Pointer 160476726Speter 160576726Speter Each field structure contains one character pointer slot that is not 160676726Speter used by the forms library. It is intended to be used by applications 160776726Speter to store private per-field data. You can manipulate it with: 160876726Speterint set_field_userptr(FIELD *field, /* field to alter */ 160976726Speter char *userptr); /* mode to set */ 161076726Speter 161176726Speterchar *field_userptr(FIELD *field); /* fetch mode of field */ 161276726Speter 161376726Speter (Properly, this user pointer field ought to have (void *) type. The 161476726Speter (char *) type is retained for System V compatibility.) 161576726Speter 161676726Speter It is valid to set the user pointer of the default field (with a 161776726Speter set_field_userptr() call passed a NULL field pointer.) When a new 161876726Speter field is created, the default-field user pointer is copied to 161976726Speter initialize the new field's user pointer. 162076726Speter 162176726SpeterVariable-Sized Fields 162276726Speter 162376726Speter Normally, a field is fixed at the size specified for it at creation 162476726Speter time. If, however, you turn off its O_STATIC bit, it becomes dynamic 162576726Speter and will automatically resize itself to accommodate data as it is 162676726Speter entered. If the field has extra buffers associated with it, they will 162776726Speter grow right along with the main input buffer. 162876726Speter 162976726Speter A one-line dynamic field will have a fixed height (1) but variable 163076726Speter width, scrolling horizontally to display data within the field area as 163176726Speter originally dimensioned and located. A multi-line dynamic field will 163276726Speter have a fixed width, but variable height (number of rows), scrolling 163376726Speter vertically to display data within the field area as originally 163476726Speter dimensioned and located. 163576726Speter 163676726Speter Normally, a dynamic field is allowed to grow without limit. But it is 163776726Speter possible to set an upper limit on the size of a dynamic field. You do 163876726Speter it with this function: 163976726Speterint set_max_field(FIELD *field, /* field to alter (may not be NULL) */ 164076726Speter int max_size); /* upper limit on field size */ 164176726Speter 164276726Speter If the field is one-line, max_size is taken to be a column size limit; 164376726Speter if it is multi-line, it is taken to be a line size limit. To disable 164476726Speter any limit, use an argument of zero. The growth limit can be changed 164576726Speter whether or not the O_STATIC bit is on, but has no effect until it is. 164676726Speter 164776726Speter The following properties of a field change when it becomes dynamic: 164876726Speter * If there is no growth limit, there is no final position of the 164976726Speter field; therefore O_AUTOSKIP and O_NL_OVERLOAD are ignored. 165076726Speter * Field justification will be ignored (though whatever justification 165176726Speter is set up will be retained internally and can be queried). 165276726Speter * The dup_field() and link_field() calls copy dynamic-buffer sizes. 165376726Speter If the O_STATIC option is set on one of a collection of links, 165476726Speter buffer resizing will occur only when the field is edited through 165576726Speter that link. 165676726Speter * The call field_info() will retrieve the original static size of 165776726Speter the field; use dynamic_field_info() to get the actual dynamic 165876726Speter size. 165976726Speter 166076726SpeterField Validation 166176726Speter 166276726Speter By default, a field will accept any data that will fit in its input 166376726Speter buffer. However, it is possible to attach a validation type to a 166476726Speter field. If you do this, any attempt to leave the field while it 166576726Speter contains data that doesn't match the validation type will fail. Some 166676726Speter validation types also have a character-validity check for each time a 166776726Speter character is entered in the field. 166876726Speter 166976726Speter A field's validation check (if any) is not called when 167076726Speter set_field_buffer() modifies the input buffer, nor when that buffer is 167176726Speter changed through a linked field. 167276726Speter 167376726Speter The form library provides a rich set of pre-defined validation types, 167476726Speter and gives you the capability to define custom ones of your own. You 167576726Speter can examine and change field validation attributes with the following 167676726Speter functions: 167776726Speterint set_field_type(FIELD *field, /* field to alter */ 167876726Speter FIELDTYPE *ftype, /* type to associate */ 167976726Speter ...); /* additional arguments*/ 168076726Speter 168176726SpeterFIELDTYPE *field_type(FIELD *field); /* field to query */ 168276726Speter 168376726Speter The validation type of a field is considered an attribute of the 168476726Speter field. As with other field attributes, Also, doing set_field_type() 168576726Speter with a NULL field default will change the system default for 168676726Speter validation of newly-created fields. 168776726Speter 168876726Speter Here are the pre-defined validation types: 168976726Speter 169076726Speter TYPE_ALPHA 169176726Speter 169276726Speter This field type accepts alphabetic data; no blanks, no digits, no 169376726Speter special characters (this is checked at character-entry time). It is 169476726Speter set up with: 169576726Speterint set_field_type(FIELD *field, /* field to alter */ 169676726Speter TYPE_ALPHA, /* type to associate */ 169776726Speter int width); /* maximum width of field */ 169876726Speter 169976726Speter The width argument sets a minimum width of data. Typically you'll want 170076726Speter to set this to the field width; if it's greater than the field width, 170176726Speter the validation check will always fail. A minimum width of zero makes 170276726Speter field completion optional. 170376726Speter 170476726Speter TYPE_ALNUM 170576726Speter 170676726Speter This field type accepts alphabetic data and digits; no blanks, no 170776726Speter special characters (this is checked at character-entry time). It is 170876726Speter set up with: 170976726Speterint set_field_type(FIELD *field, /* field to alter */ 171076726Speter TYPE_ALNUM, /* type to associate */ 171176726Speter int width); /* maximum width of field */ 171276726Speter 171376726Speter The width argument sets a minimum width of data. As with TYPE_ALPHA, 171476726Speter typically you'll want to set this to the field width; if it's greater 171576726Speter than the field width, the validation check will always fail. A minimum 171676726Speter width of zero makes field completion optional. 171776726Speter 171876726Speter TYPE_ENUM 171976726Speter 172076726Speter This type allows you to restrict a field's values to be among a 172176726Speter specified set of string values (for example, the two-letter postal 172276726Speter codes for U.S. states). It is set up with: 172376726Speterint set_field_type(FIELD *field, /* field to alter */ 172476726Speter TYPE_ENUM, /* type to associate */ 172576726Speter char **valuelist; /* list of possible values */ 172676726Speter int checkcase; /* case-sensitive? */ 172776726Speter int checkunique); /* must specify uniquely? */ 172876726Speter 172976726Speter The valuelist parameter must point at a NULL-terminated list of valid 173076726Speter strings. The checkcase argument, if true, makes comparison with the 173176726Speter string case-sensitive. 173276726Speter 173376726Speter When the user exits a TYPE_ENUM field, the validation procedure tries 173476726Speter to complete the data in the buffer to a valid entry. If a complete 173576726Speter choice string has been entered, it is of course valid. But it is also 173676726Speter possible to enter a prefix of a valid string and have it completed for 173776726Speter you. 173876726Speter 173976726Speter By default, if you enter such a prefix and it matches more than one 174076726Speter value in the string list, the prefix will be completed to the first 174176726Speter matching value. But the checkunique argument, if true, requires prefix 174276726Speter matches to be unique in order to be valid. 174376726Speter 174476726Speter The REQ_NEXT_CHOICE and REQ_PREV_CHOICE input requests can be 174576726Speter particularly useful with these fields. 174676726Speter 174776726Speter TYPE_INTEGER 174876726Speter 174976726Speter This field type accepts an integer. It is set up as follows: 175076726Speterint set_field_type(FIELD *field, /* field to alter */ 175176726Speter TYPE_INTEGER, /* type to associate */ 175276726Speter int padding, /* # places to zero-pad to */ 175376726Speter int vmin, int vmax); /* valid range */ 175476726Speter 175576726Speter Valid characters consist of an optional leading minus and digits. The 175676726Speter range check is performed on exit. If the range maximum is less than or 175776726Speter equal to the minimum, the range is ignored. 175876726Speter 175976726Speter If the value passes its range check, it is padded with as many leading 176076726Speter zero digits as necessary to meet the padding argument. 176176726Speter 176276726Speter A TYPE_INTEGER value buffer can conveniently be interpreted with the C 176376726Speter library function atoi(3). 176476726Speter 176576726Speter TYPE_NUMERIC 176676726Speter 176776726Speter This field type accepts a decimal number. It is set up as follows: 176876726Speterint set_field_type(FIELD *field, /* field to alter */ 176976726Speter TYPE_NUMERIC, /* type to associate */ 177076726Speter int padding, /* # places of precision */ 177176726Speter double vmin, double vmax); /* valid range */ 177276726Speter 177376726Speter Valid characters consist of an optional leading minus and digits. 177476726Speter possibly including a decimal point. If your system supports locale's, 177576726Speter the decimal point character used must be the one defined by your 177676726Speter locale. The range check is performed on exit. If the range maximum is 177776726Speter less than or equal to the minimum, the range is ignored. 177876726Speter 177976726Speter If the value passes its range check, it is padded with as many 178076726Speter trailing zero digits as necessary to meet the padding argument. 178176726Speter 178276726Speter A TYPE_NUMERIC value buffer can conveniently be interpreted with the C 178376726Speter library function atof(3). 178476726Speter 178576726Speter TYPE_REGEXP 178676726Speter 178776726Speter This field type accepts data matching a regular expression. It is set 178876726Speter up as follows: 178976726Speterint set_field_type(FIELD *field, /* field to alter */ 179076726Speter TYPE_REGEXP, /* type to associate */ 179176726Speter char *regexp); /* expression to match */ 179276726Speter 179376726Speter The syntax for regular expressions is that of regcomp(3). The check 179476726Speter for regular-expression match is performed on exit. 179576726Speter 179676726SpeterDirect Field Buffer Manipulation 179776726Speter 179876726Speter The chief attribute of a field is its buffer contents. When a form has 179976726Speter been completed, your application usually needs to know the state of 180076726Speter each field buffer. You can find this out with: 180176726Speterchar *field_buffer(FIELD *field, /* field to query */ 180276726Speter int bufindex); /* number of buffer to query */ 180376726Speter 180476726Speter Normally, the state of the zero-numbered buffer for each field is set 180576726Speter by the user's editing actions on that field. It's sometimes useful to 180676726Speter be able to set the value of the zero-numbered (or some other) buffer 180776726Speter from your application: 180876726Speterint set_field_buffer(FIELD *field, /* field to alter */ 180976726Speter int bufindex, /* number of buffer to alter */ 181076726Speter char *value); /* string value to set */ 181176726Speter 181276726Speter If the field is not large enough and cannot be resized to a 181376726Speter sufficiently large size to contain the specified value, the value will 181476726Speter be truncated to fit. 181576726Speter 181676726Speter Calling field_buffer() with a null field pointer will raise an error. 181776726Speter Calling field_buffer() on a field not currently selected for input 181876726Speter will return a correct value. Calling field_buffer() on a field that is 181976726Speter currently selected for input may not necessarily give a correct field 182076726Speter buffer value, because entered data isn't necessarily copied to buffer 182176726Speter zero before the exit validation check. To guarantee that the returned 182276726Speter buffer value reflects on-screen reality, call field_buffer() either 182376726Speter (1) in the field's exit validation check routine, (2) from the field's 182476726Speter or form's initialization or termination hooks, or (3) just after a 182576726Speter REQ_VALIDATION request has been processed by the forms driver. 182676726Speter 182776726SpeterAttributes of Forms 182876726Speter 182976726Speter As with field attributes, form attributes inherit a default from a 183076726Speter system default form structure. These defaults can be queried or set by 183176726Speter of these functions using a form-pointer argument of NULL. 183276726Speter 183376726Speter The principal attribute of a form is its field list. You can query and 183476726Speter change this list with: 183576726Speterint set_form_fields(FORM *form, /* form to alter */ 183676726Speter FIELD **fields); /* fields to connect */ 183776726Speter 183876726Speterchar *form_fields(FORM *form); /* fetch fields of form */ 183976726Speter 184076726Speterint field_count(FORM *form); /* count connect fields */ 184176726Speter 184276726Speter The second argument of set_form_fields() may be a NULL-terminated 184376726Speter field pointer array like the one required by new_form(). In that case, 184476726Speter the old fields of the form are disconnected but not freed (and 184576726Speter eligible to be connected to other forms), then the new fields are 184676726Speter connected. 184776726Speter 184876726Speter It may also be null, in which case the old fields are disconnected 184976726Speter (and not freed) but no new ones are connected. 185076726Speter 185176726Speter The field_count() function simply counts the number of fields 185276726Speter connected to a given from. It returns -1 if the form-pointer argument 185376726Speter is NULL. 185476726Speter 185576726SpeterControl of Form Display 185676726Speter 185776726Speter In the overview section, you saw that to display a form you normally 185876726Speter start by defining its size (and fields), posting it, and refreshing 185976726Speter the screen. There is an hidden step before posting, which is the 186076726Speter association of the form with a frame window (actually, a pair of 186176726Speter windows) within which it will be displayed. By default, the forms 186276726Speter library associates every form with the full-screen window stdscr. 186376726Speter 186476726Speter By making this step explicit, you can associate a form with a declared 186576726Speter frame window on your screen display. This can be useful if you want to 186676726Speter adapt the form display to different screen sizes, dynamically tile 186776726Speter forms on the screen, or use a form as part of an interface layout 186876726Speter managed by panels. 186976726Speter 187076726Speter The two windows associated with each form have the same functions as 187176726Speter their analogues in the menu library. Both these windows are painted 187276726Speter when the form is posted and erased when the form is unposted. 187376726Speter 187476726Speter The outer or frame window is not otherwise touched by the form 187576726Speter routines. It exists so the programmer can associate a title, a border, 187676726Speter or perhaps help text with the form and have it properly refreshed or 187776726Speter erased at post/unpost time. The inner window or subwindow is where the 187876726Speter current form page is actually displayed. 187976726Speter 188076726Speter In order to declare your own frame window for a form, you'll need to 188176726Speter know the size of the form's bounding rectangle. You can get this 188276726Speter information with: 188376726Speterint scale_form(FORM *form, /* form to query */ 188476726Speter int *rows, /* form rows */ 188576726Speter int *cols); /* form cols */ 188676726Speter 188776726Speter The form dimensions are passed back in the locations pointed to by the 188876726Speter arguments. Once you have this information, you can use it to declare 188976726Speter of windows, then use one of these functions: 189076726Speterint set_form_win(FORM *form, /* form to alter */ 189176726Speter WINDOW *win); /* frame window to connect */ 189276726Speter 189376726SpeterWINDOW *form_win(FORM *form); /* fetch frame window of form */ 189476726Speter 189576726Speterint set_form_sub(FORM *form, /* form to alter */ 189676726Speter WINDOW *win); /* form subwindow to connect */ 189776726Speter 189876726SpeterWINDOW *form_sub(FORM *form); /* fetch form subwindow of form */ 189976726Speter 190076726Speter Note that curses operations, including refresh(), on the form, should 190176726Speter be done on the frame window, not the form subwindow. 190276726Speter 190376726Speter It is possible to check from your application whether all of a 190476726Speter scrollable field is actually displayed within the menu subwindow. Use 190576726Speter these functions: 190676726Speterint data_ahead(FORM *form); /* form to be queried */ 190776726Speter 190876726Speterint data_behind(FORM *form); /* form to be queried */ 190976726Speter 191076726Speter The function data_ahead() returns TRUE if (a) the current field is 191176726Speter one-line and has undisplayed data off to the right, (b) the current 191276726Speter field is multi-line and there is data off-screen below it. 191376726Speter 191476726Speter The function data_behind() returns TRUE if the first (upper left hand) 191576726Speter character position is off-screen (not being displayed). 191676726Speter 191776726Speter Finally, there is a function to restore the form window's cursor to 191876726Speter the value expected by the forms driver: 191976726Speterint pos_form_cursor(FORM *) /* form to be queried */ 192076726Speter 192176726Speter If your application changes the form window cursor, call this function 192276726Speter before handing control back to the forms driver in order to 192376726Speter re-synchronize it. 192476726Speter 192576726SpeterInput Processing in the Forms Driver 192676726Speter 192776726Speter The function form_driver() handles virtualized input requests for form 192876726Speter navigation, editing, and validation requests, just as menu_driver does 192976726Speter for menus (see the section on menu input handling). 193076726Speterint form_driver(FORM *form, /* form to pass input to */ 193176726Speter int request); /* form request code */ 193276726Speter 193376726Speter Your input virtualization function needs to take input and then 193476726Speter convert it to either an alphanumeric character (which is treated as 193576726Speter data to be entered in the currently-selected field), or a forms 193676726Speter processing request. 193776726Speter 193876726Speter The forms driver provides hooks (through input-validation and 193976726Speter field-termination functions) with which your application code can 194076726Speter check that the input taken by the driver matched what was expected. 194176726Speter 194276726Speter Page Navigation Requests 194376726Speter 194476726Speter These requests cause page-level moves through the form, triggering 194576726Speter display of a new form screen. 194676726Speter 194776726Speter REQ_NEXT_PAGE 194876726Speter Move to the next form page. 194976726Speter 195076726Speter REQ_PREV_PAGE 195176726Speter Move to the previous form page. 195276726Speter 195376726Speter REQ_FIRST_PAGE 195476726Speter Move to the first form page. 195576726Speter 195676726Speter REQ_LAST_PAGE 195776726Speter Move to the last form page. 195876726Speter 195976726Speter These requests treat the list as cyclic; that is, REQ_NEXT_PAGE from 196076726Speter the last page goes to the first, and REQ_PREV_PAGE from the first page 196176726Speter goes to the last. 196276726Speter 196376726Speter Inter-Field Navigation Requests 196476726Speter 196576726Speter These requests handle navigation between fields on the same page. 196676726Speter 196776726Speter REQ_NEXT_FIELD 196876726Speter Move to next field. 196976726Speter 197076726Speter REQ_PREV_FIELD 197176726Speter Move to previous field. 197276726Speter 197376726Speter REQ_FIRST_FIELD 197476726Speter Move to the first field. 197576726Speter 197676726Speter REQ_LAST_FIELD 197776726Speter Move to the last field. 197876726Speter 197976726Speter REQ_SNEXT_FIELD 198076726Speter Move to sorted next field. 198176726Speter 198276726Speter REQ_SPREV_FIELD 198376726Speter Move to sorted previous field. 198476726Speter 198576726Speter REQ_SFIRST_FIELD 198676726Speter Move to the sorted first field. 198776726Speter 198876726Speter REQ_SLAST_FIELD 198976726Speter Move to the sorted last field. 199076726Speter 199176726Speter REQ_LEFT_FIELD 199276726Speter Move left to field. 199376726Speter 199476726Speter REQ_RIGHT_FIELD 199576726Speter Move right to field. 199676726Speter 199776726Speter REQ_UP_FIELD 199876726Speter Move up to field. 199976726Speter 200076726Speter REQ_DOWN_FIELD 200176726Speter Move down to field. 200276726Speter 200376726Speter These requests treat the list of fields on a page as cyclic; that is, 200476726Speter REQ_NEXT_FIELD from the last field goes to the first, and 200576726Speter REQ_PREV_FIELD from the first field goes to the last. The order of the 200676726Speter fields for these (and the REQ_FIRST_FIELD and REQ_LAST_FIELD requests) 200776726Speter is simply the order of the field pointers in the form array (as set up 200876726Speter by new_form() or set_form_fields() 200976726Speter 201076726Speter It is also possible to traverse the fields as if they had been sorted 201176726Speter in screen-position order, so the sequence goes left-to-right and 201276726Speter top-to-bottom. To do this, use the second group of four 201376726Speter sorted-movement requests. 201476726Speter 201576726Speter Finally, it is possible to move between fields using visual directions 201676726Speter up, down, right, and left. To accomplish this, use the third group of 201776726Speter four requests. Note, however, that the position of a form for purposes 201876726Speter of these requests is its upper-left corner. 201976726Speter 202076726Speter For example, suppose you have a multi-line field B, and two 202176726Speter single-line fields A and C on the same line with B, with A to the left 202276726Speter of B and C to the right of B. A REQ_MOVE_RIGHT from A will go to B 202376726Speter only if A, B, and C all share the same first line; otherwise it will 202476726Speter skip over B to C. 202576726Speter 202676726Speter Intra-Field Navigation Requests 202776726Speter 202876726Speter These requests drive movement of the edit cursor within the currently 202976726Speter selected field. 203076726Speter 203176726Speter REQ_NEXT_CHAR 203276726Speter Move to next character. 203376726Speter 203476726Speter REQ_PREV_CHAR 203576726Speter Move to previous character. 203676726Speter 203776726Speter REQ_NEXT_LINE 203876726Speter Move to next line. 203976726Speter 204076726Speter REQ_PREV_LINE 204176726Speter Move to previous line. 204276726Speter 204376726Speter REQ_NEXT_WORD 204476726Speter Move to next word. 204576726Speter 204676726Speter REQ_PREV_WORD 204776726Speter Move to previous word. 204876726Speter 204976726Speter REQ_BEG_FIELD 205076726Speter Move to beginning of field. 205176726Speter 205276726Speter REQ_END_FIELD 205376726Speter Move to end of field. 205476726Speter 205576726Speter REQ_BEG_LINE 205676726Speter Move to beginning of line. 205776726Speter 205876726Speter REQ_END_LINE 205976726Speter Move to end of line. 206076726Speter 206176726Speter REQ_LEFT_CHAR 206276726Speter Move left in field. 206376726Speter 206476726Speter REQ_RIGHT_CHAR 206576726Speter Move right in field. 206676726Speter 206776726Speter REQ_UP_CHAR 206876726Speter Move up in field. 206976726Speter 207076726Speter REQ_DOWN_CHAR 207176726Speter Move down in field. 207276726Speter 207376726Speter Each word is separated from the previous and next characters by 207476726Speter whitespace. The commands to move to beginning and end of line or field 207576726Speter look for the first or last non-pad character in their ranges. 207676726Speter 207776726Speter Scrolling Requests 207876726Speter 207976726Speter Fields that are dynamic and have grown and fields explicitly created 208076726Speter with offscreen rows are scrollable. One-line fields scroll 208176726Speter horizontally; multi-line fields scroll vertically. Most scrolling is 208276726Speter triggered by editing and intra-field movement (the library scrolls the 208376726Speter field to keep the cursor visible). It is possible to explicitly 208476726Speter request scrolling with the following requests: 208576726Speter 208676726Speter REQ_SCR_FLINE 208776726Speter Scroll vertically forward a line. 208876726Speter 208976726Speter REQ_SCR_BLINE 209076726Speter Scroll vertically backward a line. 209176726Speter 209276726Speter REQ_SCR_FPAGE 209376726Speter Scroll vertically forward a page. 209476726Speter 209576726Speter REQ_SCR_BPAGE 209676726Speter Scroll vertically backward a page. 209776726Speter 209876726Speter REQ_SCR_FHPAGE 209976726Speter Scroll vertically forward half a page. 210076726Speter 210176726Speter REQ_SCR_BHPAGE 210276726Speter Scroll vertically backward half a page. 210376726Speter 210476726Speter REQ_SCR_FCHAR 210576726Speter Scroll horizontally forward a character. 210676726Speter 210776726Speter REQ_SCR_BCHAR 210876726Speter Scroll horizontally backward a character. 210976726Speter 211076726Speter REQ_SCR_HFLINE 211176726Speter Scroll horizontally one field width forward. 211276726Speter 211376726Speter REQ_SCR_HBLINE 211476726Speter Scroll horizontally one field width backward. 211576726Speter 211676726Speter REQ_SCR_HFHALF 211776726Speter Scroll horizontally one half field width forward. 211876726Speter 211976726Speter REQ_SCR_HBHALF 212076726Speter Scroll horizontally one half field width backward. 212176726Speter 212276726Speter For scrolling purposes, a page of a field is the height of its visible 212376726Speter part. 212476726Speter 212576726Speter Editing Requests 212676726Speter 212776726Speter When you pass the forms driver an ASCII character, it is treated as a 212876726Speter request to add the character to the field's data buffer. Whether this 212976726Speter is an insertion or a replacement depends on the field's edit mode 213076726Speter (insertion is the default. 213176726Speter 213276726Speter The following requests support editing the field and changing the edit 213376726Speter mode: 213476726Speter 213576726Speter REQ_INS_MODE 213676726Speter Set insertion mode. 213776726Speter 213876726Speter REQ_OVL_MODE 213976726Speter Set overlay mode. 214076726Speter 214176726Speter REQ_NEW_LINE 214276726Speter New line request (see below for explanation). 214376726Speter 214476726Speter REQ_INS_CHAR 214576726Speter Insert space at character location. 214676726Speter 214776726Speter REQ_INS_LINE 214876726Speter Insert blank line at character location. 214976726Speter 215076726Speter REQ_DEL_CHAR 215176726Speter Delete character at cursor. 215276726Speter 215376726Speter REQ_DEL_PREV 215476726Speter Delete previous word at cursor. 215576726Speter 215676726Speter REQ_DEL_LINE 215776726Speter Delete line at cursor. 215876726Speter 215976726Speter REQ_DEL_WORD 216076726Speter Delete word at cursor. 216176726Speter 216276726Speter REQ_CLR_EOL 216376726Speter Clear to end of line. 216476726Speter 216576726Speter REQ_CLR_EOF 216676726Speter Clear to end of field. 216776726Speter 216876726Speter REQ_CLEAR_FIELD 216976726Speter Clear entire field. 217076726Speter 217176726Speter The behavior of the REQ_NEW_LINE and REQ_DEL_PREV requests is 217276726Speter complicated and partly controlled by a pair of forms options. The 217376726Speter special cases are triggered when the cursor is at the beginning of a 217476726Speter field, or on the last line of the field. 217576726Speter 217676726Speter First, we consider REQ_NEW_LINE: 217776726Speter 217876726Speter The normal behavior of REQ_NEW_LINE in insert mode is to break the 217976726Speter current line at the position of the edit cursor, inserting the portion 218076726Speter of the current line after the cursor as a new line following the 218176726Speter current and moving the cursor to the beginning of that new line (you 218276726Speter may think of this as inserting a newline in the field buffer). 218376726Speter 218476726Speter The normal behavior of REQ_NEW_LINE in overlay mode is to clear the 218576726Speter current line from the position of the edit cursor to end of line. The 218676726Speter cursor is then moved to the beginning of the next line. 218776726Speter 218876726Speter However, REQ_NEW_LINE at the beginning of a field, or on the last line 218976726Speter of a field, instead does a REQ_NEXT_FIELD. O_NL_OVERLOAD option is 219076726Speter off, this special action is disabled. 219176726Speter 219276726Speter Now, let us consider REQ_DEL_PREV: 219376726Speter 219476726Speter The normal behavior of REQ_DEL_PREV is to delete the previous 219576726Speter character. If insert mode is on, and the cursor is at the start of a 219676726Speter line, and the text on that line will fit on the previous one, it 219776726Speter instead appends the contents of the current line to the previous one 219876726Speter and deletes the current line (you may think of this as deleting a 219976726Speter newline from the field buffer). 220076726Speter 220176726Speter However, REQ_DEL_PREV at the beginning of a field is instead treated 220276726Speter as a REQ_PREV_FIELD. 220376726Speter 220476726Speter If the O_BS_OVERLOAD option is off, this special action is disabled 220576726Speter and the forms driver just returns E_REQUEST_DENIED. 220676726Speter 220776726Speter See Form Options for discussion of how to set and clear the overload 220876726Speter options. 220976726Speter 221076726Speter Order Requests 221176726Speter 221276726Speter If the type of your field is ordered, and has associated functions for 221376726Speter getting the next and previous values of the type from a given value, 221476726Speter there are requests that can fetch that value into the field buffer: 221576726Speter 221676726Speter REQ_NEXT_CHOICE 221776726Speter Place the successor value of the current value in the buffer. 221876726Speter 221976726Speter REQ_PREV_CHOICE 222076726Speter Place the predecessor value of the current value in the buffer. 222176726Speter 222276726Speter Of the built-in field types, only TYPE_ENUM has built-in successor and 222376726Speter predecessor functions. When you define a field type of your own (see 222476726Speter Custom Validation Types), you can associate our own ordering 222576726Speter functions. 222676726Speter 222776726Speter Application Commands 222876726Speter 222976726Speter Form requests are represented as integers above the curses value 223076726Speter greater than KEY_MAX and less than or equal to the constant 223176726Speter MAX_COMMAND. If your input-virtualization routine returns a value 223276726Speter above MAX_COMMAND, the forms driver will ignore it. 223376726Speter 223476726SpeterField Change Hooks 223576726Speter 223676726Speter It is possible to set function hooks to be executed whenever the 223776726Speter current field or form changes. Here are the functions that support 223876726Speter this: 223976726Spetertypedef void (*HOOK)(); /* pointer to function returning void */ 224076726Speter 224176726Speterint set_form_init(FORM *form, /* form to alter */ 224276726Speter HOOK hook); /* initialization hook */ 224376726Speter 224476726SpeterHOOK form_init(FORM *form); /* form to query */ 224576726Speter 224676726Speterint set_form_term(FORM *form, /* form to alter */ 224776726Speter HOOK hook); /* termination hook */ 224876726Speter 224976726SpeterHOOK form_term(FORM *form); /* form to query */ 225076726Speter 225176726Speterint set_field_init(FORM *form, /* form to alter */ 225276726Speter HOOK hook); /* initialization hook */ 225376726Speter 225476726SpeterHOOK field_init(FORM *form); /* form to query */ 225576726Speter 225676726Speterint set_field_term(FORM *form, /* form to alter */ 225776726Speter HOOK hook); /* termination hook */ 225876726Speter 225976726SpeterHOOK field_term(FORM *form); /* form to query */ 226076726Speter 226176726Speter These functions allow you to either set or query four different hooks. 226276726Speter In each of the set functions, the second argument should be the 226376726Speter address of a hook function. These functions differ only in the timing 226476726Speter of the hook call. 226576726Speter 226676726Speter form_init 226776726Speter This hook is called when the form is posted; also, just after 226876726Speter each page change operation. 226976726Speter 227076726Speter field_init 227176726Speter This hook is called when the form is posted; also, just after 227276726Speter each field change 227376726Speter 227476726Speter field_term 227576726Speter This hook is called just after field validation; that is, just 227676726Speter before the field is altered. It is also called when the form is 227776726Speter unposted. 227876726Speter 227976726Speter form_term 228076726Speter This hook is called when the form is unposted; also, just 228176726Speter before each page change operation. 228276726Speter 228376726Speter Calls to these hooks may be triggered 228476726Speter 1. When user editing requests are processed by the forms driver 228576726Speter 2. When the current page is changed by set_current_field() call 228676726Speter 3. When the current field is changed by a set_form_page() call 228776726Speter 228876726Speter See Field Change Commands for discussion of the latter two cases. 228976726Speter 229076726Speter You can set a default hook for all fields by passing one of the set 229176726Speter functions a NULL first argument. 229276726Speter 229376726Speter You can disable any of these hooks by (re)setting them to NULL, the 229476726Speter default value. 229576726Speter 229676726SpeterField Change Commands 229776726Speter 229876726Speter Normally, navigation through the form will be driven by the user's 229976726Speter input requests. But sometimes it is useful to be able to move the 230076726Speter focus for editing and viewing under control of your application, or 230176726Speter ask which field it currently is in. The following functions help you 230276726Speter accomplish this: 230376726Speterint set_current_field(FORM *form, /* form to alter */ 230476726Speter FIELD *field); /* field to shift to */ 230576726Speter 230676726SpeterFIELD *current_field(FORM *form); /* form to query */ 230776726Speter 230876726Speterint field_index(FORM *form, /* form to query */ 230976726Speter FIELD *field); /* field to get index of */ 231076726Speter 231176726Speter The function field_index() returns the index of the given field in the 231276726Speter given form's field array (the array passed to new_form() or 231376726Speter set_form_fields()). 231476726Speter 231576726Speter The initial current field of a form is the first active field on the 231676726Speter first page. The function set_form_fields() resets this. 231776726Speter 231876726Speter It is also possible to move around by pages. 231976726Speterint set_form_page(FORM *form, /* form to alter */ 232076726Speter int page); /* page to go to (0-origin) */ 232176726Speter 232276726Speterint form_page(FORM *form); /* return form's current page */ 232376726Speter 232476726Speter The initial page of a newly-created form is 0. The function 232576726Speter set_form_fields() resets this. 232676726Speter 232776726SpeterForm Options 232876726Speter 232976726Speter Like fields, forms may have control option bits. They can be changed 233076726Speter or queried with these functions: 233176726Speterint set_form_opts(FORM *form, /* form to alter */ 233276726Speter int attr); /* attribute to set */ 233376726Speter 233476726Speterint form_opts_on(FORM *form, /* form to alter */ 233576726Speter int attr); /* attributes to turn on */ 233676726Speter 233776726Speterint form_opts_off(FORM *form, /* form to alter */ 233876726Speter int attr); /* attributes to turn off */ 233976726Speter 234076726Speterint form_opts(FORM *form); /* form to query */ 234176726Speter 234276726Speter By default, all options are on. Here are the available option bits: 234376726Speter 234476726Speter O_NL_OVERLOAD 234576726Speter Enable overloading of REQ_NEW_LINE as described in Editing 234676726Speter Requests. The value of this option is ignored on dynamic fields 234776726Speter that have not reached their size limit; these have no last 234876726Speter line, so the circumstances for triggering a REQ_NEXT_FIELD 234976726Speter never arise. 235076726Speter 235176726Speter O_BS_OVERLOAD 235276726Speter Enable overloading of REQ_DEL_PREV as described in Editing 235376726Speter Requests. 235476726Speter 235576726Speter The option values are bit-masks and can be composed with logical-or in 235676726Speter the obvious way. 235776726Speter 235876726SpeterCustom Validation Types 235976726Speter 236076726Speter The form library gives you the capability to define custom validation 236176726Speter types of your own. Further, the optional additional arguments of 236276726Speter set_field_type effectively allow you to parameterize validation types. 236376726Speter Most of the complications in the validation-type interface have to do 236476726Speter with the handling of the additional arguments within custom validation 236576726Speter functions. 236676726Speter 236776726Speter Union Types 236876726Speter 236976726Speter The simplest way to create a custom data type is to compose it from 237076726Speter two preexisting ones: 237176726SpeterFIELD *link_fieldtype(FIELDTYPE *type1, 237276726Speter FIELDTYPE *type2); 237376726Speter 237476726Speter This function creates a field type that will accept any of the values 237576726Speter legal for either of its argument field types (which may be either 237676726Speter predefined or programmer-defined). If a set_field_type() call later 237776726Speter requires arguments, the new composite type expects all arguments for 237876726Speter the first type, than all arguments for the second. Order functions 237976726Speter (see Order Requests) associated with the component types will work on 238076726Speter the composite; what it does is check the validation function for the 238176726Speter first type, then for the second, to figure what type the buffer 238276726Speter contents should be treated as. 238376726Speter 238476726Speter New Field Types 238576726Speter 238676726Speter To create a field type from scratch, you need to specify one or both 238776726Speter of the following things: 238876726Speter * A character-validation function, to check each character as it is 238976726Speter entered. 239076726Speter * A field-validation function to be applied on exit from the field. 239176726Speter 239276726Speter Here's how you do that: 239376726Spetertypedef int (*HOOK)(); /* pointer to function returning int */ 239476726Speter 239576726SpeterFIELDTYPE *new_fieldtype(HOOK f_validate, /* field validator */ 239676726Speter HOOK c_validate) /* character validator */ 239776726Speter 239876726Speter 239976726Speterint free_fieldtype(FIELDTYPE *ftype); /* type to free */ 240076726Speter 240176726Speter At least one of the arguments of new_fieldtype() must be non-NULL. The 240276726Speter forms driver will automatically call the new type's validation 240376726Speter functions at appropriate points in processing a field of the new type. 240476726Speter 240576726Speter The function free_fieldtype() deallocates the argument fieldtype, 240676726Speter freeing all storage associated with it. 240776726Speter 240876726Speter Normally, a field validator is called when the user attempts to leave 240976726Speter the field. Its first argument is a field pointer, from which it can 241076726Speter get to field buffer 0 and test it. If the function returns TRUE, the 241176726Speter operation succeeds; if it returns FALSE, the edit cursor stays in the 241276726Speter field. 241376726Speter 241476726Speter A character validator gets the character passed in as a first 241576726Speter argument. It too should return TRUE if the character is valid, FALSE 241676726Speter otherwise. 241776726Speter 241876726Speter Validation Function Arguments 241976726Speter 242076726Speter Your field- and character- validation functions will be passed a 242176726Speter second argument as well. This second argument is the address of a 242276726Speter structure (which we'll call a pile) built from any of the 242376726Speter field-type-specific arguments passed to set_field_type(). If no such 242476726Speter arguments are defined for the field type, this pile pointer argument 242576726Speter will be NULL. 242676726Speter 242776726Speter In order to arrange for such arguments to be passed to your validation 242876726Speter functions, you must associate a small set of storage-management 242976726Speter functions with the type. The forms driver will use these to synthesize 243076726Speter a pile from the trailing arguments of each set_field_type() argument, 243176726Speter and a pointer to the pile will be passed to the validation functions. 243276726Speter 243376726Speter Here is how you make the association: 243476726Spetertypedef char *(*PTRHOOK)(); /* pointer to function returning (char *) */ 243576726Spetertypedef void (*VOIDHOOK)(); /* pointer to function returning void */ 243676726Speter 243776726Speterint set_fieldtype_arg(FIELDTYPE *type, /* type to alter */ 243876726Speter PTRHOOK make_str, /* make structure from args */ 243976726Speter PTRHOOK copy_str, /* make copy of structure */ 244076726Speter VOIDHOOK free_str); /* free structure storage */ 244176726Speter 244276726Speter Here is how the storage-management hooks are used: 244376726Speter 244476726Speter make_str 244576726Speter This function is called by set_field_type(). It gets one 244676726Speter argument, a va_list of the type-specific arguments passed to 244776726Speter set_field_type(). It is expected to return a pile pointer to a 244876726Speter data structure that encapsulates those arguments. 244976726Speter 245076726Speter copy_str 245176726Speter This function is called by form library functions that allocate 245276726Speter new field instances. It is expected to take a pile pointer, 245376726Speter copy the pile to allocated storage, and return the address of 245476726Speter the pile copy. 245576726Speter 245676726Speter free_str 245776726Speter This function is called by field- and type-deallocation 245876726Speter routines in the library. It takes a pile pointer argument, and 245976726Speter is expected to free the storage of that pile. 246076726Speter 246176726Speter The make_str and copy_str functions may return NULL to signal 246276726Speter allocation failure. The library routines will that call them will 246376726Speter return error indication when this happens. Thus, your validation 246476726Speter functions should never see a NULL file pointer and need not check 246576726Speter specially for it. 246676726Speter 246776726Speter Order Functions For Custom Types 246876726Speter 246976726Speter Some custom field types are simply ordered in the same well-defined 247076726Speter way that TYPE_ENUM is. For such types, it is possible to define 247176726Speter successor and predecessor functions to support the REQ_NEXT_CHOICE and 247276726Speter REQ_PREV_CHOICE requests. Here's how: 247376726Spetertypedef int (*INTHOOK)(); /* pointer to function returning int */ 247476726Speter 247576726Speterint set_fieldtype_arg(FIELDTYPE *type, /* type to alter */ 247676726Speter INTHOOK succ, /* get successor value */ 247776726Speter INTHOOK pred); /* get predecessor value */ 247876726Speter 247976726Speter The successor and predecessor arguments will each be passed two 248076726Speter arguments; a field pointer, and a pile pointer (as for the validation 248176726Speter functions). They are expected to use the function field_buffer() to 248276726Speter read the current value, and set_field_buffer() on buffer 0 to set the 248376726Speter next or previous value. Either hook may return TRUE to indicate 248476726Speter success (a legal next or previous value was set) or FALSE to indicate 248576726Speter failure. 248676726Speter 248776726Speter Avoiding Problems 248876726Speter 248976726Speter The interface for defining custom types is complicated and tricky. 249076726Speter Rather than attempting to create a custom type entirely from scratch, 249176726Speter you should start by studying the library source code for whichever of 249276726Speter the pre-defined types seems to be closest to what you want. 249376726Speter 249476726Speter Use that code as a model, and evolve it towards what you really want. 249576726Speter You will avoid many problems and annoyances that way. The code in the 249676726Speter ncurses library has been specifically exempted from the package 249776726Speter copyright to support this. 249876726Speter 249976726Speter If your custom type defines order functions, have do something 250076726Speter intuitive with a blank field. A useful convention is to make the 250176726Speter successor of a blank field the types minimum value, and its 250276726Speter predecessor the maximum. 2503