ncurses-intro.doc revision 166124
1166124Srafan Writing Programs with NCURSES 276726Speter 376726Speter by Eric S. Raymond and Zeyd M. Ben-Halim 476726Speter updates since release 1.9.9e by Thomas Dickey 5166124Srafan 676726Speter Contents 7166124Srafan 876726Speter * Introduction 976726Speter + A Brief History of Curses 1076726Speter + Scope of This Document 1176726Speter + Terminology 1276726Speter * The Curses Library 1376726Speter + An Overview of Curses 1476726Speter o Compiling Programs using Curses 1576726Speter o Updating the Screen 1676726Speter o Standard Windows and Function Naming Conventions 1776726Speter o Variables 1876726Speter + Using the Library 1976726Speter o Starting up 2076726Speter o Output 2176726Speter o Input 2276726Speter o Using Forms Characters 2376726Speter o Character Attributes and Color 2476726Speter o Mouse Interfacing 2576726Speter o Finishing Up 2676726Speter + Function Descriptions 2776726Speter o Initialization and Wrapup 2876726Speter o Causing Output to the Terminal 2976726Speter o Low-Level Capability Access 3076726Speter o Debugging 3176726Speter + Hints, Tips, and Tricks 3276726Speter o Some Notes of Caution 3376726Speter o Temporarily Leaving ncurses Mode 3476726Speter o Using ncurses under xterm 3576726Speter o Handling Multiple Terminal Screens 3676726Speter o Testing for Terminal Capabilities 3776726Speter o Tuning for Speed 3876726Speter o Special Features of ncurses 3976726Speter + Compatibility with Older Versions 4076726Speter o Refresh of Overlapping Windows 4176726Speter o Background Erase 4276726Speter + XSI Curses Conformance 4376726Speter * The Panels Library 4476726Speter + Compiling With the Panels Library 4576726Speter + Overview of Panels 4676726Speter + Panels, Input, and the Standard Screen 4776726Speter + Hiding Panels 4876726Speter + Miscellaneous Other Facilities 4976726Speter * The Menu Library 5076726Speter + Compiling with the menu Library 5176726Speter + Overview of Menus 5276726Speter + Selecting items 5376726Speter + Menu Display 5476726Speter + Menu Windows 5576726Speter + Processing Menu Input 5676726Speter + Miscellaneous Other Features 5776726Speter * The Forms Library 5876726Speter + Compiling with the forms Library 5976726Speter + Overview of Forms 6076726Speter + Creating and Freeing Fields and Forms 6176726Speter + Fetching and Changing Field Attributes 6276726Speter o Fetching Size and Location Data 6376726Speter o Changing the Field Location 6476726Speter o The Justification Attribute 6576726Speter o Field Display Attributes 6676726Speter o Field Option Bits 6776726Speter o Field Status 6876726Speter o Field User Pointer 6976726Speter + Variable-Sized Fields 7076726Speter + Field Validation 7176726Speter o TYPE_ALPHA 7276726Speter o TYPE_ALNUM 7376726Speter o TYPE_ENUM 7476726Speter o TYPE_INTEGER 7576726Speter o TYPE_NUMERIC 7676726Speter o TYPE_REGEXP 7776726Speter + Direct Field Buffer Manipulation 7876726Speter + Attributes of Forms 7976726Speter + Control of Form Display 8076726Speter + Input Processing in the Forms Driver 8176726Speter o Page Navigation Requests 8276726Speter o Inter-Field Navigation Requests 8376726Speter o Intra-Field Navigation Requests 8476726Speter o Scrolling Requests 8576726Speter o Field Editing Requests 8676726Speter o Order Requests 8776726Speter o Application Commands 8876726Speter + Field Change Hooks 8976726Speter + Field Change Commands 9076726Speter + Form Options 9176726Speter + Custom Validation Types 9276726Speter o Union Types 9376726Speter o New Field Types 9476726Speter o Validation Function Arguments 9576726Speter o Order Functions For Custom Types 9676726Speter o Avoiding Problems 9776726Speter _________________________________________________________________ 98166124Srafan 9976726Speter Introduction 100166124Srafan 10176726Speter This document is an introduction to programming with curses. It is not 102166124Srafan an exhaustive reference for the curses Application Programming 103166124Srafan Interface (API); that role is filled by the curses manual pages. 104166124Srafan Rather, it is intended to help C programmers ease into using the 10576726Speter package. 106166124Srafan 107166124Srafan This document is aimed at C applications programmers not yet 108166124Srafan specifically familiar with ncurses. If you are already an experienced 109166124Srafan curses programmer, you should nevertheless read the sections on Mouse 110166124Srafan Interfacing, Debugging, Compatibility with Older Versions, and Hints, 111166124Srafan Tips, and Tricks. These will bring you up to speed on the special 112166124Srafan features and quirks of the ncurses implementation. If you are not so 11376726Speter experienced, keep reading. 114166124Srafan 115166124Srafan The curses package is a subroutine library for terminal-independent 116166124Srafan screen-painting and input-event handling which presents a high level 117166124Srafan screen model to the programmer, hiding differences between terminal 118166124Srafan types and doing automatic optimization of output to change one screen 119166124Srafan full of text into another. Curses uses terminfo, which is a database 120166124Srafan format that can describe the capabilities of thousands of different 12176726Speter terminals. 122166124Srafan 123166124Srafan The curses API may seem something of an archaism on UNIX desktops 124166124Srafan increasingly dominated by X, Motif, and Tcl/Tk. Nevertheless, UNIX 125166124Srafan still supports tty lines and X supports xterm(1); the curses API has 12676726Speter the advantage of (a) back-portability to character-cell terminals, and 127166124Srafan (b) simplicity. For an application that does not require bit-mapped 128166124Srafan graphics and multiple fonts, an interface implementation using curses 129166124Srafan will typically be a great deal simpler and less expensive than one 13076726Speter using an X toolkit. 131166124Srafan 13276726SpeterA Brief History of Curses 13376726Speter 13476726Speter Historically, the first ancestor of curses was the routines written to 135166124Srafan provide screen-handling for the game rogue; these used the 136166124Srafan already-existing termcap database facility for describing terminal 13776726Speter capabilities. These routines were abstracted into a documented library 13876726Speter and first released with the early BSD UNIX versions. 139166124Srafan 140166124Srafan System III UNIX from Bell Labs featured a rewritten and much-improved 141166124Srafan curses library. It introduced the terminfo format. Terminfo is based 142166124Srafan on Berkeley's termcap database, but contains a number of improvements 143166124Srafan and extensions. Parameterized capabilities strings were introduced, 144166124Srafan making it possible to describe multiple video attributes, and colors 145166124Srafan and to handle far more unusual terminals than possible with termcap. 146166124Srafan In the later AT&T System V releases, curses evolved to use more 14776726Speter facilities and offer more capabilities, going far beyond BSD curses in 14876726Speter power and flexibility. 149166124Srafan 15076726SpeterScope of This Document 15176726Speter 15276726Speter This document describes ncurses, a free implementation of the System V 153166124Srafan curses API with some clearly marked extensions. It includes the 15476726Speter following System V curses features: 155166124Srafan * Support for multiple screen highlights (BSD curses could only 15676726Speter handle one `standout' highlight, usually reverse-video). 15776726Speter * Support for line- and box-drawing using forms characters. 15876726Speter * Recognition of function keys on input. 15976726Speter * Color support. 160166124Srafan * Support for pads (windows of larger than screen size on which the 16176726Speter screen or a subwindow defines a viewport). 162166124Srafan 163166124Srafan Also, this package makes use of the insert and delete line and 164166124Srafan character features of terminals so equipped, and determines how to 165166124Srafan optimally use these features with no help from the programmer. It 166166124Srafan allows arbitrary combinations of video attributes to be displayed, 167166124Srafan even on terminals that leave ``magic cookies'' on the screen to mark 16876726Speter changes in attributes. 169166124Srafan 170166124Srafan The ncurses package can also capture and use event reports from a 17176726Speter mouse in some environments (notably, xterm under the X window system). 17276726Speter This document includes tips for using the mouse. 173166124Srafan 174166124Srafan The ncurses package was originated by Pavel Curtis. The original 175166124Srafan maintainer of this package is Zeyd Ben-Halim <zmbenhal@netcom.com>. 17676726Speter Eric S. Raymond <esr@snark.thyrsus.com> wrote many of the new features 177166124Srafan in versions after 1.8.1 and wrote most of this introduction. J�rgen 178166124Srafan Pfeifer wrote all of the menu and forms code as well as the Ada95 179166124Srafan binding. Ongoing work is being done by Thomas Dickey (maintainer). 180166124Srafan Contact the current maintainers at bug-ncurses@gnu.org. 181166124Srafan 182166124Srafan This document also describes the panels extension library, similarly 183166124Srafan modeled on the SVr4 panels facility. This library allows you to 184166124Srafan associate backing store with each of a stack or deck of overlapping 185166124Srafan windows, and provides operations for moving windows around in the 18676726Speter stack that change their visibility in the natural way (handling window 18776726Speter overlaps). 188166124Srafan 189166124Srafan Finally, this document describes in detail the menus and forms 190166124Srafan extension libraries, also cloned from System V, which support easy 19176726Speter construction and sequences of menus and fill-in forms. 192166124Srafan 19376726SpeterTerminology 19476726Speter 195166124Srafan In this document, the following terminology is used with reasonable 19676726Speter consistency: 197166124Srafan 19876726Speter window 199166124Srafan A data structure describing a sub-rectangle of the screen 200166124Srafan (possibly the entire screen). You can write to a window as 201166124Srafan though it were a miniature screen, scrolling independently of 20276726Speter other windows on the physical screen. 203166124Srafan 20476726Speter screens 205166124Srafan A subset of windows which are as large as the terminal screen, 206166124Srafan i.e., they start at the upper left hand corner and encompass 207166124Srafan the lower right hand corner. One of these, stdscr, is 20876726Speter automatically provided for the programmer. 209166124Srafan 21076726Speter terminal screen 21176726Speter The package's idea of what the terminal display currently looks 21276726Speter like, i.e., what the user sees now. This is a special screen. 213166124Srafan 21476726Speter The Curses Library 215166124Srafan 21676726SpeterAn Overview of Curses 21776726Speter 21876726Speter Compiling Programs using Curses 219166124Srafan 22076726Speter In order to use the library, it is necessary to have certain types and 22176726Speter variables defined. Therefore, the programmer must have a line: 22276726Speter #include <curses.h> 22376726Speter 22476726Speter at the top of the program source. The screen package uses the Standard 225166124Srafan I/O library, so <curses.h> includes <stdio.h>. <curses.h> also 226166124Srafan includes <termios.h>, <termio.h>, or <sgtty.h> depending on your 227166124Srafan system. It is redundant (but harmless) for the programmer to do these 228166124Srafan includes, too. In linking with curses you need to have -lncurses in 229166124Srafan your LDFLAGS or on the command line. There is no need for any other 23076726Speter libraries. 231166124Srafan 23276726Speter Updating the Screen 233166124Srafan 234166124Srafan In order to update the screen optimally, it is necessary for the 235166124Srafan routines to know what the screen currently looks like and what the 236166124Srafan programmer wants it to look like next. For this purpose, a data type 237166124Srafan (structure) named WINDOW is defined which describes a window image to 238166124Srafan the routines, including its starting position on the screen (the (y, 239166124Srafan x) coordinates of the upper left hand corner) and its size. One of 240166124Srafan these (called curscr, for current screen) is a screen image of what 241166124Srafan the terminal currently looks like. Another screen (called stdscr, for 24276726Speter standard screen) is provided by default to make changes on. 243166124Srafan 244166124Srafan A window is a purely internal representation. It is used to build and 245166124Srafan store a potential image of a portion of the terminal. It doesn't bear 246166124Srafan any necessary relation to what is really on the terminal screen; it's 24776726Speter more like a scratchpad or write buffer. 248166124Srafan 249166124Srafan To make the section of physical screen corresponding to a window 250166124Srafan reflect the contents of the window structure, the routine refresh() 25176726Speter (or wrefresh() if the window is not stdscr) is called. 252166124Srafan 253166124Srafan A given physical screen section may be within the scope of any number 254166124Srafan of overlapping windows. Also, changes can be made to windows in any 255166124Srafan order, without regard to motion efficiency. Then, at will, the 25676726Speter programmer can effectively say ``make it look like this,'' and let the 25776726Speter package implementation determine the most efficient way to repaint the 25876726Speter screen. 259166124Srafan 26076726Speter Standard Windows and Function Naming Conventions 261166124Srafan 262166124Srafan As hinted above, the routines can use several windows, but two are 26376726Speter automatically given: curscr, which knows what the terminal looks like, 264166124Srafan and stdscr, which is what the programmer wants the terminal to look 265166124Srafan like next. The user should never actually access curscr directly. 266166124Srafan Changes should be made to through the API, and then the routine 26776726Speter refresh() (or wrefresh()) called. 268166124Srafan 269166124Srafan Many functions are defined to use stdscr as a default screen. For 270166124Srafan example, to add a character to stdscr, one calls addch() with the 27176726Speter desired character as argument. To write to a different window. use the 272166124Srafan routine waddch() (for `w'indow-specific addch()) is provided. This 27376726Speter convention of prepending function names with a `w' when they are to be 274166124Srafan applied to specific windows is consistent. The only routines which do 27576726Speter not follow it are those for which a window must always be specified. 276166124Srafan 277166124Srafan In order to move the current (y, x) coordinates from one point to 278166124Srafan another, the routines move() and wmove() are provided. However, it is 279166124Srafan often desirable to first move and then perform some I/O operation. In 280166124Srafan order to avoid clumsiness, most I/O routines can be preceded by the 281166124Srafan prefix 'mv' and the desired (y, x) coordinates prepended to the 28276726Speter arguments to the function. For example, the calls 28376726Speter move(y, x); 28476726Speter addch(ch); 28576726Speter 28676726Speter can be replaced by 28776726Speter mvaddch(y, x, ch); 28876726Speter 28976726Speter and 29076726Speter wmove(win, y, x); 29176726Speter waddch(win, ch); 29276726Speter 29376726Speter can be replaced by 29476726Speter mvwaddch(win, y, x, ch); 29576726Speter 296166124Srafan Note that the window description pointer (win) comes before the added 297166124Srafan (y, x) coordinates. If a function requires a window pointer, it is 29876726Speter always the first parameter passed. 299166124Srafan 30076726Speter Variables 301166124Srafan 302166124Srafan The curses library sets some variables describing the terminal 30376726Speter capabilities. 30476726Speter type name description 30576726Speter ------------------------------------------------------------------ 30676726Speter int LINES number of lines on the terminal 30776726Speter int COLS number of columns on the terminal 30876726Speter 309166124Srafan The curses.h also introduces some #define constants and types of 31076726Speter general usefulness: 311166124Srafan 31276726Speter bool 31376726Speter boolean type, actually a `char' (e.g., bool doneit;) 314166124Srafan 31576726Speter TRUE 31676726Speter boolean `true' flag (1). 317166124Srafan 31876726Speter FALSE 31976726Speter boolean `false' flag (0). 320166124Srafan 32176726Speter ERR 32276726Speter error flag returned by routines on a failure (-1). 323166124Srafan 32476726Speter OK 32576726Speter error flag returned by routines when things go right. 326166124Srafan 32776726SpeterUsing the Library 32876726Speter 329166124Srafan Now we describe how to actually use the screen package. In it, we 330166124Srafan assume all updating, reading, etc. is applied to stdscr. These 331166124Srafan instructions will work on any window, providing you change the 33276726Speter function names and parameters as mentioned above. 333166124Srafan 33476726Speter Here is a sample program to motivate the discussion: 33576726Speter#include <curses.h> 33676726Speter#include <signal.h> 33776726Speter 33876726Speterstatic void finish(int sig); 33976726Speter 34076726Speterint 34176726Spetermain(int argc, char *argv[]) 34276726Speter{ 34376726Speter int num = 0; 34476726Speter 34576726Speter /* initialize your non-curses data structures here */ 34676726Speter 34776726Speter (void) signal(SIGINT, finish); /* arrange interrupts to terminate */ 34876726Speter 34976726Speter (void) initscr(); /* initialize the curses library */ 35076726Speter keypad(stdscr, TRUE); /* enable keyboard mapping */ 35176726Speter (void) nonl(); /* tell curses not to do NL->CR/NL on output */ 35276726Speter (void) cbreak(); /* take input chars one at a time, no wait for \n */ 35376726Speter (void) echo(); /* echo input - in color */ 35476726Speter 35576726Speter if (has_colors()) 35676726Speter { 35776726Speter start_color(); 35876726Speter 35976726Speter /* 36076726Speter * Simple color assignment, often all we need. Color pair 0 cannot 36176726Speter * be redefined. This example uses the same value for the color 36276726Speter * pair as for the foreground color, though of course that is not 36376726Speter * necessary: 36476726Speter */ 36576726Speter init_pair(1, COLOR_RED, COLOR_BLACK); 36676726Speter init_pair(2, COLOR_GREEN, COLOR_BLACK); 36776726Speter init_pair(3, COLOR_YELLOW, COLOR_BLACK); 36876726Speter init_pair(4, COLOR_BLUE, COLOR_BLACK); 36976726Speter init_pair(5, COLOR_CYAN, COLOR_BLACK); 37076726Speter init_pair(6, COLOR_MAGENTA, COLOR_BLACK); 37176726Speter init_pair(7, COLOR_WHITE, COLOR_BLACK); 37276726Speter } 37376726Speter 37476726Speter for (;;) 37576726Speter { 37676726Speter int c = getch(); /* refresh, accept single keystroke of input */ 37776726Speter attrset(COLOR_PAIR(num % 8)); 37876726Speter num++; 37976726Speter 38076726Speter /* process the command keystroke */ 38176726Speter } 38276726Speter 38376726Speter finish(0); /* we're done */ 38476726Speter} 38576726Speter 38676726Speterstatic void finish(int sig) 38776726Speter{ 38876726Speter endwin(); 38976726Speter 39076726Speter /* do your non-curses wrapup here */ 39176726Speter 39276726Speter exit(0); 39376726Speter} 39476726Speter 39576726Speter Starting up 396166124Srafan 397166124Srafan In order to use the screen package, the routines must know about 398166124Srafan terminal characteristics, and the space for curscr and stdscr must be 399166124Srafan allocated. These function initscr() does both these things. Since it 400166124Srafan must allocate space for the windows, it can overflow memory when 401166124Srafan attempting to do so. On the rare occasions this happens, initscr() 402166124Srafan will terminate the program with an error message. initscr() must 403166124Srafan always be called before any of the routines which affect windows are 404166124Srafan used. If it is not, the program will core dump as soon as either 405166124Srafan curscr or stdscr are referenced. However, it is usually best to wait 406166124Srafan to call it until after you are sure you will need it, like after 407166124Srafan checking for startup errors. Terminal status changing routines like 40876726Speter nl() and cbreak() should be called after initscr(). 409166124Srafan 410166124Srafan Once the screen windows have been allocated, you can set them up for 411166124Srafan your program. If you want to, say, allow a screen to scroll, use 412166124Srafan scrollok(). If you want the cursor to be left in place after the last 413166124Srafan change, use leaveok(). If this isn't done, refresh() will move the 41476726Speter cursor to the window's current (y, x) coordinates after updating it. 415166124Srafan 416166124Srafan You can create new windows of your own using the functions newwin(), 41776726Speter derwin(), and subwin(). The routine delwin() will allow you to get rid 418166124Srafan of old windows. All the options described above can be applied to any 41976726Speter window. 420166124Srafan 42176726Speter Output 422166124Srafan 423166124Srafan Now that we have set things up, we will want to actually update the 424166124Srafan terminal. The basic functions used to change what will go on a window 42576726Speter are addch() and move(). addch() adds a character at the current (y, x) 42676726Speter coordinates. move() changes the current (y, x) coordinates to whatever 42776726Speter you want them to be. It returns ERR if you try to move off the window. 428166124Srafan As mentioned above, you can combine the two into mvaddch() to do both 42976726Speter things at once. 430166124Srafan 431166124Srafan The other output functions, such as addstr() and printw(), all call 43276726Speter addch() to add characters to the window. 433166124Srafan 434166124Srafan After you have put on the window what you want there, when you want 435166124Srafan the portion of the terminal covered by the window to be made to look 436166124Srafan like it, you must call refresh(). In order to optimize finding 437166124Srafan changes, refresh() assumes that any part of the window not changed 438166124Srafan since the last refresh() of that window has not been changed on the 439166124Srafan terminal, i.e., that you have not refreshed a portion of the terminal 440166124Srafan with an overlapping window. If this is not the case, the routine 44176726Speter touchwin() is provided to make it look like the entire window has been 442166124Srafan changed, thus making refresh() check the whole subsection of the 44376726Speter terminal for changes. 444166124Srafan 445166124Srafan If you call wrefresh() with curscr as its argument, it will make the 446166124Srafan screen look like curscr thinks it looks like. This is useful for 447166124Srafan implementing a command which would redraw the screen in case it get 44876726Speter messed up. 449166124Srafan 45076726Speter Input 451166124Srafan 452166124Srafan The complementary function to addch() is getch() which, if echo is 45376726Speter set, will call addch() to echo the character. Since the screen package 454166124Srafan needs to know what is on the terminal at all times, if characters are 455166124Srafan to be echoed, the tty must be in raw or cbreak mode. Since initially 456166124Srafan the terminal has echoing enabled and is in ordinary ``cooked'' mode, 45776726Speter one or the other has to changed before calling getch(); otherwise, the 45876726Speter program's output will be unpredictable. 459166124Srafan 46076726Speter When you need to accept line-oriented input in a window, the functions 46176726Speter wgetstr() and friends are available. There is even a wscanw() function 462166124Srafan that can do scanf()(3)-style multi-field parsing on window input. 463166124Srafan These pseudo-line-oriented functions turn on echoing while they 46476726Speter execute. 465166124Srafan 466166124Srafan The example code above uses the call keypad(stdscr, TRUE) to enable 467166124Srafan support for function-key mapping. With this feature, the getch() code 468166124Srafan watches the input stream for character sequences that correspond to 469166124Srafan arrow and function keys. These sequences are returned as 47076726Speter pseudo-character values. The #define values returned are listed in the 47176726Speter curses.h The mapping from sequences to #define values is determined by 47276726Speter key_ capabilities in the terminal's terminfo entry. 473166124Srafan 47476726Speter Using Forms Characters 475166124Srafan 476166124Srafan The addch() function (and some others, including box() and border()) 47776726Speter can accept some pseudo-character arguments which are specially defined 478166124Srafan by ncurses. These are #define values set up in the curses.h header; 47976726Speter see there for a complete list (look for the prefix ACS_). 480166124Srafan 481166124Srafan The most useful of the ACS defines are the forms-drawing characters. 482166124Srafan You can use these to draw boxes and simple graphs on the screen. If 483166124Srafan the terminal does not have such characters, curses.h will map them to 48476726Speter a recognizable (though ugly) set of ASCII defaults. 485166124Srafan 48676726Speter Character Attributes and Color 487166124Srafan 488166124Srafan The ncurses package supports screen highlights including standout, 489166124Srafan reverse-video, underline, and blink. It also supports color, which is 49076726Speter treated as another kind of highlight. 491166124Srafan 492166124Srafan Highlights are encoded, internally, as high bits of the 493166124Srafan pseudo-character type (chtype) that curses.h uses to represent the 49476726Speter contents of a screen cell. See the curses.h header file for a complete 49576726Speter list of highlight mask values (look for the prefix A_). 496166124Srafan 497166124Srafan There are two ways to make highlights. One is to logical-or the value 498166124Srafan of the highlights you want into the character argument of an addch() 49976726Speter call, or any other output call that takes a chtype argument. 500166124Srafan 50176726Speter The other is to set the current-highlight value. This is logical-or'ed 502166124Srafan with any highlight you specify the first way. You do this with the 50376726Speter functions attron(), attroff(), and attrset(); see the manual pages for 504166124Srafan details. Color is a special kind of highlight. The package actually 505166124Srafan thinks in terms of color pairs, combinations of foreground and 506166124Srafan background colors. The sample code above sets up eight color pairs, 507166124Srafan all of the guaranteed-available colors on black. Note that each color 508166124Srafan pair is, in effect, given the name of its foreground color. Any other 509166124Srafan range of eight non-conflicting values could have been used as the 51076726Speter first arguments of the init_pair() values. 511166124Srafan 51276726Speter Once you've done an init_pair() that creates color-pair N, you can use 513166124Srafan COLOR_PAIR(N) as a highlight that invokes that particular color 514166124Srafan combination. Note that COLOR_PAIR(N), for constant N, is itself a 51576726Speter compile-time constant and can be used in initializers. 516166124Srafan 51776726Speter Mouse Interfacing 518166124Srafan 51976726Speter The ncurses library also provides a mouse interface. 520166124Srafan 521166124Srafan NOTE: this facility is specific to ncurses, it is not part of 522166124Srafan either the XSI Curses standard, nor of System V Release 4, nor BSD 523166124Srafan curses. System V Release 4 curses contains code with similar 524166124Srafan interface definitions, however it is not documented. Other than by 525166124Srafan disassembling the library, we have no way to determine exactly how 526166124Srafan that mouse code works. Thus, we recommend that you wrap 527166124Srafan mouse-related code in an #ifdef using the feature macro 528166124Srafan NCURSES_MOUSE_VERSION so it will not be compiled and linked on 52976726Speter non-ncurses systems. 530166124Srafan 53176726Speter Presently, mouse event reporting works in the following environments: 53276726Speter * xterm and similar programs such as rxvt. 533166124Srafan * Linux console, when configured with gpm(1), Alessandro Rubini's 53476726Speter mouse server. 535166124Srafan * FreeBSD sysmouse (console) 53676726Speter * OS/2 EMX 537166124Srafan 538166124Srafan The mouse interface is very simple. To activate it, you use the 539166124Srafan function mousemask(), passing it as first argument a bit-mask that 540166124Srafan specifies what kinds of events you want your program to be able to 541166124Srafan see. It will return the bit-mask of events that actually become 54276726Speter visible, which may differ from the argument if the mouse device is not 54376726Speter capable of reporting some of the event types you specify. 544166124Srafan 54576726Speter Once the mouse is active, your application's command loop should watch 546166124Srafan for a return value of KEY_MOUSE from wgetch(). When you see this, a 547166124Srafan mouse event report has been queued. To pick it off the queue, use the 548166124Srafan function getmouse() (you must do this before the next wgetch(), 549166124Srafan otherwise another mouse event might come in and make the first one 55076726Speter inaccessible). 551166124Srafan 55276726Speter Each call to getmouse() fills a structure (the address of which you'll 553166124Srafan pass it) with mouse event data. The event data includes zero-origin, 554166124Srafan screen-relative character-cell coordinates of the mouse pointer. It 555166124Srafan also includes an event mask. Bits in this mask will be set, 55676726Speter corresponding to the event type being reported. 557166124Srafan 558166124Srafan The mouse structure contains two additional fields which may be 559166124Srafan significant in the future as ncurses interfaces to new kinds of 560166124Srafan pointing device. In addition to x and y coordinates, there is a slot 561166124Srafan for a z coordinate; this might be useful with touch-screens that can 562166124Srafan return a pressure or duration parameter. There is also a device ID 563166124Srafan field, which could be used to distinguish between multiple pointing 56476726Speter devices. 565166124Srafan 566166124Srafan The class of visible events may be changed at any time via 567166124Srafan mousemask(). Events that can be reported include presses, releases, 568166124Srafan single-, double- and triple-clicks (you can set the maximum 569166124Srafan button-down time for clicks). If you don't make clicks visible, they 570166124Srafan will be reported as press-release pairs. In some environments, the 571166124Srafan event mask may include bits reporting the state of shift, alt, and 57276726Speter ctrl keys on the keyboard during the event. 573166124Srafan 574166124Srafan A function to check whether a mouse event fell within a given window 575166124Srafan is also supplied. You can use this to see whether a given window 57676726Speter should consider a mouse event relevant to it. 577166124Srafan 578166124Srafan Because mouse event reporting will not be available in all 579166124Srafan environments, it would be unwise to build ncurses applications that 580166124Srafan require the use of a mouse. Rather, you should use the mouse as a 581166124Srafan shortcut for point-and-shoot commands your application would normally 582166124Srafan accept from the keyboard. Two of the test games in the ncurses 583166124Srafan distribution (bs and knight) contain code that illustrates how this 58476726Speter can be done. 585166124Srafan 586166124Srafan See the manual page curs_mouse(3X) for full details of the 58776726Speter mouse-interface functions. 588166124Srafan 58976726Speter Finishing Up 590166124Srafan 591166124Srafan In order to clean up after the ncurses routines, the routine endwin() 592166124Srafan is provided. It restores tty modes to what they were when initscr() 593166124Srafan was first called, and moves the cursor down to the lower-left corner. 594166124Srafan Thus, anytime after the call to initscr, endwin() should be called 59576726Speter before exiting. 596166124Srafan 59776726SpeterFunction Descriptions 59876726Speter 599166124Srafan We describe the detailed behavior of some important curses functions 60076726Speter here, as a supplement to the manual page descriptions. 601166124Srafan 60276726Speter Initialization and Wrapup 603166124Srafan 60476726Speter initscr() 605166124Srafan The first function called should almost always be initscr(). 606166124Srafan This will determine the terminal type and initialize curses 60776726Speter data structures. initscr() also arranges that the first call to 608166124Srafan refresh() will clear the screen. If an error occurs a message 609166124Srafan is written to standard error and the program exits. Otherwise 610166124Srafan it returns a pointer to stdscr. A few functions may be called 611166124Srafan before initscr (slk_init(), filter(), ripoffline(), use_env(), 61276726Speter and, if you are using multiple terminals, newterm().) 613166124Srafan 61476726Speter endwin() 615166124Srafan Your program should always call endwin() before exiting or 616166124Srafan shelling out of the program. This function will restore tty 617166124Srafan modes, move the cursor to the lower left corner of the screen, 618166124Srafan reset the terminal into the proper non-visual mode. Calling 619166124Srafan refresh() or doupdate() after a temporary escape from the 62076726Speter program will restore the ncurses screen from before the escape. 621166124Srafan 62276726Speter newterm(type, ofp, ifp) 623166124Srafan A program which outputs to more than one terminal should use 62476726Speter newterm() instead of initscr(). newterm() should be called once 62576726Speter for each terminal. It returns a variable of type SCREEN * which 626166124Srafan should be saved as a reference to that terminal. (NOTE: a 627166124Srafan SCREEN variable is not a screen in the sense we are describing 628166124Srafan in this introduction, but a collection of parameters used to 629166124Srafan assist in optimizing the display.) The arguments are the type 630166124Srafan of the terminal (a string) and FILE pointers for the output and 631166124Srafan input of the terminal. If type is NULL then the environment 632166124Srafan variable $TERM is used. endwin() should called once at wrapup 633166124Srafan time for each terminal opened using this function. 634166124Srafan 63576726Speter set_term(new) 636166124Srafan This function is used to switch to a different terminal 637166124Srafan previously opened by newterm(). The screen reference for the 638166124Srafan new terminal is passed as the parameter. The previous terminal 639166124Srafan is returned by the function. All other calls affect only the 64076726Speter current terminal. 641166124Srafan 64276726Speter delscreen(sp) 643166124Srafan The inverse of newterm(); deallocates the data structures 64476726Speter associated with a given SCREEN reference. 645166124Srafan 64676726Speter Causing Output to the Terminal 647166124Srafan 64876726Speter refresh() and wrefresh(win) 649166124Srafan These functions must be called to actually get any output on 650166124Srafan the terminal, as other routines merely manipulate data 651166124Srafan structures. wrefresh() copies the named window to the physical 652166124Srafan terminal screen, taking into account what is already there in 653166124Srafan order to do optimizations. refresh() does a refresh of stdscr. 654166124Srafan Unless leaveok() has been enabled, the physical cursor of the 655166124Srafan terminal is left at the location of the window's cursor. 656166124Srafan 65776726Speter doupdate() and wnoutrefresh(win) 65876726Speter These two functions allow multiple updates with more efficiency 659166124Srafan than wrefresh. To use them, it is important to understand how 660166124Srafan curses works. In addition to all the window structures, curses 661166124Srafan keeps two data structures representing the terminal screen: a 66276726Speter physical screen, describing what is actually on the screen, and 663166124Srafan a virtual screen, describing what the programmer wants to have 66476726Speter on the screen. wrefresh works by first copying the named window 665166124Srafan to the virtual screen (wnoutrefresh()), and then calling the 666166124Srafan routine to update the screen (doupdate()). If the programmer 667166124Srafan wishes to output several windows at once, a series of calls to 66876726Speter wrefresh will result in alternating calls to wnoutrefresh() and 669166124Srafan doupdate(), causing several bursts of output to the screen. By 670166124Srafan calling wnoutrefresh() for each window, it is then possible to 671166124Srafan call doupdate() once, resulting in only one burst of output, 672166124Srafan with fewer total characters transmitted (this also avoids a 67376726Speter visually annoying flicker at each update). 674166124Srafan 67576726Speter Low-Level Capability Access 676166124Srafan 67776726Speter setupterm(term, filenum, errret) 678166124Srafan 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 681166124Srafan the name of the terminal being used. filenum is the UNIX file 682166124Srafan descriptor of the terminal to be used for output. errret is a 68376726Speter pointer to an integer, in which a success or failure indication 684166124Srafan is returned. The values returned can be 1 (all is well), 0 (no 685166124Srafan such terminal), or -1 (some problem locating the terminfo 68676726Speter database). 687166124Srafan 688166124Srafan 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 690166124Srafan can also be given as NULL, meaning no error code is wanted. If 69176726Speter errret is defaulted, and something goes wrong, setupterm() will 692166124Srafan print an appropriate error message and exit, rather than 693166124Srafan returning. Thus, a simple program can call setupterm(0, 1, 0) 69476726Speter and not worry about initialization errors. 695166124Srafan 696166124Srafan After the call to setupterm(), the global variable cur_term is 69776726Speter set to point to the current structure of terminal capabilities. 698166124Srafan By calling setupterm() for each terminal, and saving and 699166124Srafan restoring cur_term, it is possible for a program to use two or 700166124Srafan more terminals at once. Setupterm() also stores the names 701166124Srafan 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. 704166124Srafan 70576726Speter Debugging 706166124Srafan 70776726Speter NOTE: These functions are not part of the standard curses API! 708166124Srafan 70976726Speter trace() 710166124Srafan This function can be used to explicitly set a trace level. If 711166124Srafan the trace level is nonzero, execution of your program will 71276726Speter generate a file called `trace' in the current working directory 713166124Srafan containing a report on the library's actions. Higher trace 714166124Srafan levels enable more detailed (and verbose) reporting -- see 715166124Srafan 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). 718166124Srafan 71976726Speter _tracef() 720166124Srafan This function can be used to output your own debugging 721166124Srafan information. It is only available only if you link with 722166124Srafan -lncurses_g. It can be used the same way as printf(), only it 723166124Srafan outputs a newline after the end of arguments. The output goes 72476726Speter to a file called trace in the current directory. 725166124Srafan 726166124Srafan 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 728166124Srafan the ncurses distribution that can alleviate this problem somewhat; it 729166124Srafan compacts long sequences of similar operations into more succinct 730166124Srafan single-line pseudo-operations. These pseudo-ops can be distinguished 73176726Speter by the fact that they are named in capital letters. 732166124Srafan 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. 738166124Srafan 73976726Speter Some Notes of Caution 740166124Srafan 741166124Srafan If you find yourself thinking you need to use noraw() or nocbreak(), 742166124Srafan think again and move carefully. It's probably better design to use 743166124Srafan getstr() or one of its relatives to simulate cooked mode. The noraw() 744166124Srafan and nocbreak() functions try to restore cooked mode, but they may end 745166124Srafan up clobbering some control bits set before you started your 746166124Srafan application. Also, they have always been poorly documented, and are 747166124Srafan likely to hurt your application's usability with other curses 74876726Speter libraries. 749166124Srafan 750166124Srafan Bear in mind that refresh() is a synonym for wrefresh(stdscr). Don't 751166124Srafan try to mix use of stdscr with use of windows declared by newwin(); a 752166124Srafan refresh() call will blow them off the screen. The right way to handle 753166124Srafan this is to use subwin(), or not touch stdscr at all and tile your 754166124Srafan screen with declared windows which you then wnoutrefresh() somewhere 755166124Srafan in your program event loop, with a single doupdate() call to trigger 75676726Speter actual repainting. 757166124Srafan 758166124Srafan You are much less likely to run into problems if you design your 759166124Srafan screen layouts to use tiled rather than overlapping windows. 760166124Srafan Historically, curses support for overlapping windows has been weak, 761166124Srafan fragile, and poorly documented. The ncurses library is not yet an 76276726Speter exception to this rule. 763166124Srafan 764166124Srafan There is a panels library included in the ncurses distribution that 765166124Srafan does a pretty good job of strengthening the overlapping-windows 76676726Speter facilities. 767166124Srafan 76876726Speter Try to avoid using the global variables LINES and COLS. Use getmaxyx() 769166124Srafan on the stdscr context instead. Reason: your code may be ported to run 770166124Srafan in an environment with window resizes, in which case several screens 77176726Speter could be open with different sizes. 772166124Srafan 77376726Speter Temporarily Leaving NCURSES Mode 774166124Srafan 775166124Srafan Sometimes you will want to write a program that spends most of its 776166124Srafan time in screen mode, but occasionally returns to ordinary `cooked' 777166124Srafan mode. A common reason for this is to support shell-out. This behavior 77876726Speter is simple to arrange in ncurses. 779166124Srafan 780166124Srafan To leave ncurses mode, call endwin() as you would if you were 781166124Srafan intending to terminate the program. This will take the screen back to 782166124Srafan cooked mode; you can do your shell-out. When you want to return to 783166124Srafan ncurses mode, simply call refresh() or doupdate(). This will repaint 78476726Speter the screen. 785166124Srafan 786166124Srafan 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. 789166124Srafan 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 799166124Srafan 800166124Srafan A resize operation in X sends SIGWINCH to the application running 801166124Srafan under xterm. The ncurses library provides an experimental signal 802166124Srafan handler, but in general does not catch this signal, because it cannot 803166124Srafan 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. 805166124Srafan 806166124Srafan 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. 808166124Srafan The refresh will pick up the new screen size from the xterm's 80976726Speter environment. 810166124Srafan 811166124Srafan That is the standard way, of course (it even works with some vendor's 812166124Srafan curses implementations). Its drawback is that it clears the screen to 81376726Speter reinitialize the display, and does not resize subwindows which must be 814166124Srafan shrunk. Ncurses provides an extension which works better, the 815166124Srafan resizeterm function. That function ensures that all windows are 816166124Srafan limited to the new screen dimensions, and pads stdscr with blanks if 81776726Speter the screen is larger. 818166124Srafan 819166124Srafan Finally, ncurses can be configured to provide its own SIGWINCH 82076726Speter handler, based on resizeterm. 821166124Srafan 82276726Speter Handling Multiple Terminal Screens 823166124Srafan 82476726Speter The initscr() function actually calls a function named newterm() to do 825166124Srafan most of its work. If you are writing a program that opens multiple 82676726Speter terminals, use newterm() directly. 827166124Srafan 828166124Srafan For each call, you will have to specify a terminal type and a pair of 829166124Srafan 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 831166124Srafan 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. 833166124Srafan 83476726Speter Testing for Terminal Capabilities 835166124Srafan 83676726Speter Sometimes you may want to write programs that test for the presence of 837166124Srafan various capabilities before deciding whether to go into ncurses mode. 838166124Srafan An easy way to do this is to call setupterm(), then use the functions 83976726Speter tigetflag(), tigetnum(), and tigetstr() to do your testing. 840166124Srafan 841166124Srafan A particularly useful case of this often comes up when you want to 842166124Srafan 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 845166124Srafan can include the term.h file and test the value of the macro 84676726Speter cursor_address. 847166124Srafan 84876726Speter Tuning for Speed 849166124Srafan 850166124Srafan Use the addchstr() family of functions for fast screen-painting of 851166124Srafan text when you know the text doesn't contain any control characters. 852166124Srafan Try to make attribute changes infrequent on your screens. Don't use 85376726Speter the immedok() option! 854166124Srafan 85576726Speter Special Features of NCURSES 856166124Srafan 857166124Srafan The wresize() function allows you to resize a window in place. The 858166124Srafan associated resizeterm() function simplifies the construction of 85976726Speter SIGWINCH handlers, for resizing all windows. 860166124Srafan 86176726Speter The define_key() function allows you to define at runtime function-key 862166124Srafan control sequences which are not in the terminal description. The 863166124Srafan keyok() function allows you to temporarily enable or disable 86476726Speter interpretation of any function-key control sequence. 865166124Srafan 86676726Speter The use_default_colors() function allows you to construct applications 867166124Srafan which can use the terminal's default foreground and background colors 868166124Srafan as an additional "default" color. Several terminal emulators support 86976726Speter this feature, which is based on ISO 6429. 870166124Srafan 871166124Srafan 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. 874166124Srafan 87576726SpeterCompatibility with Older Versions 87676726Speter 877166124Srafan Despite our best efforts, there are some differences between ncurses 878166124Srafan and the (undocumented!) behavior of older curses implementations. 879166124Srafan These arise from ambiguities or omissions in the documentation of the 88076726Speter API. 881166124Srafan 88276726Speter Refresh of Overlapping Windows 883166124Srafan 884166124Srafan If you define two windows A and B that overlap, and then alternately 885166124Srafan scribble on and refresh them, the changes made to the overlapping 886166124Srafan region under historic curses versions were often not documented 88776726Speter precisely. 888166124Srafan 889166124Srafan To understand why this is a problem, remember that screen updates are 890166124Srafan calculated between two representations of the entire display. The 891166124Srafan documentation says that when you refresh a window, it is first copied 892166124Srafan to the virtual screen, and then changes are calculated to update 893166124Srafan the physical screen (and applied to the terminal). But "copied to" is 894166124Srafan not very specific, and subtle differences in how copying works can 895166124Srafan produce different behaviors in the case where two overlapping windows 89676726Speter are each being refreshed at unpredictable intervals. 897166124Srafan 898166124Srafan What happens to the overlapping region depends on what wnoutrefresh() 899166124Srafan does with its argument -- what portions of the argument window it 900166124Srafan copies to the virtual screen. Some implementations do "change copy", 901166124Srafan copying down only locations in the window that have changed (or been 902166124Srafan marked changed with wtouchln() and friends). Some implementations do 903166124Srafan "entire copy", copying all window locations to the virtual screen 90476726Speter whether or not they have changed. 905166124Srafan 906166124Srafan The ncurses library itself has not always been consistent on this 907166124Srafan score. Due to a bug, versions 1.8.7 to 1.9.8a did entire copy. 908166124Srafan Versions 1.8.6 and older, and versions 1.9.9 and newer, do change 90976726Speter copy. 910166124Srafan 911166124Srafan For most commercial curses implementations, it is not documented and 912166124Srafan not known for sure (at least not to the ncurses maintainers) whether 913166124Srafan they do change copy or entire copy. We know that System V release 3 914166124Srafan curses has logic in it that looks like an attempt to do change copy, 915166124Srafan but the surrounding logic and data representations are sufficiently 916166124Srafan complex, and our knowledge sufficiently indirect, that it's hard to 917166124Srafan know whether this is reliable. It is not clear what the SVr4 918166124Srafan documentation and XSI standard intend. The XSI Curses standard barely 919166124Srafan 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. 922166124Srafan 923166124Srafan It might therefore be unwise to rely on either behavior in programs 924166124Srafan that might have to be linked with other curses implementations. 925166124Srafan Instead, you can do an explicit touchwin() before the wnoutrefresh() 92676726Speter call to guarantee an entire-contents copy anywhere. 927166124Srafan 928166124Srafan The really clean way to handle this is to use the panels library. If, 929166124Srafan when you want a screen update, you do update_panels(), it will do all 930166124Srafan the necessary wnoutrefresh() calls for whatever panel stacking order 931166124Srafan 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. 933166124Srafan 93476726Speter Background Erase 935166124Srafan 93676726Speter If you have been using a very old versions of ncurses (1.8.7 or older) 937166124Srafan you may be surprised by the behavior of the erase functions. In older 938166124Srafan versions, erased areas of a window were filled with a blank modified 939166124Srafan by the window's current attribute (as set by wattrset(), wattron(), 94076726Speter wattroff() and friends). 941166124Srafan 942166124Srafan In newer versions, this is not so. Instead, the attribute of erased 943166124Srafan blanks is normal unless and until it is modified by the functions 94476726Speter bkgdset() or wbkgdset(). 945166124Srafan 94676726Speter This change in behavior conforms ncurses to System V Release 4 and the 94776726Speter XSI Curses standard. 948166124Srafan 94976726SpeterXSI Curses Conformance 95076726Speter 951166124Srafan The ncurses library is intended to be base-level conformant with the 952166124Srafan XSI Curses standard from X/Open. Many extended-level features (in 953166124Srafan fact, almost all features not directly concerned with wide characters 95476726Speter and internationalization) are also supported. 955166124Srafan 956166124Srafan One effect of XSI conformance is the change in behavior described 95776726Speter under "Background Erase -- Compatibility with Old Versions". 958166124Srafan 959166124Srafan Also, ncurses meets the XSI requirement that every macro entry point 960166124Srafan have a corresponding function which may be linked (and will be 96176726Speter prototype-checked) if the macro definition is disabled with #undef. 962166124Srafan 96376726Speter The Panels Library 964166124Srafan 965166124Srafan The ncurses library by itself provides good support for screen 96676726Speter displays in which the windows are tiled (non-overlapping). In the more 967166124Srafan general case that windows may overlap, you have to use a series of 968166124Srafan 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. 971166124Srafan 972166124Srafan When your interface design is such that windows may dive deeper into 973166124Srafan the visibility stack or pop to the top at runtime, the resulting 974166124Srafan book-keeping can be tedious and difficult to get right. Hence the 97576726Speter panels library. 976166124Srafan 977166124Srafan The panel library first appeared in AT&T System V. The version 97876726Speter documented here is the panel code distributed with ncurses. 979166124Srafan 98076726SpeterCompiling With the Panels Library 98176726Speter 982166124Srafan 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 987166124Srafan 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. 990166124Srafan 99176726SpeterOverview of Panels 99276726Speter 993166124Srafan A panel object is a window that is implicitly treated as part of a 994166124Srafan deck including all other panel objects. The deck has an implicit 995166124Srafan bottom-to-top visibility order. The panels library includes an update 99676726Speter function (analogous to refresh()) that displays all panels in the deck 997166124Srafan in the proper order to resolve overlaps. The standard window, stdscr, 99876726Speter is considered below all panels. 999166124Srafan 1000166124Srafan Details on the panels functions are available in the man pages. We'll 100176726Speter just hit the highlights here. 1002166124Srafan 1003166124Srafan You create a panel from a window by calling new_panel() on a window 1004166124Srafan 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. 1007166124Srafan 1008166124Srafan You can delete a panel (removing it from the deck) with del_panel. 1009166124Srafan This will not deallocate the associated window; you have to do that 1010166124Srafan yourself. You can replace a panel's window with a different window by 1011166124Srafan 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. 1014166124Srafan 1015166124Srafan To move a panel's window, use move_panel(). The mvwin() function on 1016166124Srafan the panel's window isn't sufficient because it doesn't update the 1017166124Srafan panels library's representation of where the windows are. This 101876726Speter operation leaves the panel's depth, contents, and size unchanged. 1019166124Srafan 1020166124Srafan Two functions (top_panel(), bottom_panel()) are provided for 102176726Speter rearranging the deck. The first pops its argument window to the top of 1022166124Srafan the deck; the second sends it to the bottom. Either operation leaves 102376726Speter the panel's screen location, contents, and size unchanged. 1024166124Srafan 1025166124Srafan The function update_panels() does all the wnoutrefresh() calls needed 102676726Speter to prepare for doupdate() (which you must call yourself, afterwards). 1027166124Srafan 1028166124Srafan Typically, you will want to call update_panels() and doupdate() just 102976726Speter before accepting command input, once in each cycle of interaction with 1030166124Srafan the user. If you call update_panels() after each and every panel 1031166124Srafan write, you'll generate a lot of unnecessary refresh activity and 103276726Speter screen flicker. 1033166124Srafan 103476726SpeterPanels, Input, and the Standard Screen 103576726Speter 1036166124Srafan You shouldn't mix wnoutrefresh() or wrefresh() operations with panels 1037166124Srafan code; this will work only if the argument window is either in the top 103876726Speter panel or unobscured by any other panels. 1039166124Srafan 1040166124Srafan The stsdcr window is a special case. It is considered below all 104176726Speter panels. Because changes to panels may obscure parts of stdscr, though, 1042166124Srafan you should call update_panels() before doupdate() even when you only 104376726Speter change stdscr. 1044166124Srafan 1045166124Srafan Note that wgetch automatically calls wrefresh. Therefore, before 1046166124Srafan requesting input from a panel window, you need to be sure that the 104776726Speter panel is totally unobscured. 1048166124Srafan 1049166124Srafan There is presently no way to display changes to one obscured panel 105076726Speter without repainting all panels. 1051166124Srafan 105276726SpeterHiding Panels 105376726Speter 1054166124Srafan It's possible to remove a panel from the deck temporarily; use 1055166124Srafan hide_panel for this. Use show_panel() to render it visible again. The 1056166124Srafan predicate function panel_hidden tests whether or not a panel is 105776726Speter hidden. 1058166124Srafan 105976726Speter The panel_update code ignores hidden panels. You cannot do top_panel() 1060166124Srafan or bottom_panel on a hidden panel(). Other panels operations are 106176726Speter applicable. 1062166124Srafan 106376726SpeterMiscellaneous Other Facilities 106476726Speter 1065166124Srafan It's possible to navigate the deck using the functions panel_above() 1066166124Srafan and panel_below. Handed a panel pointer, they return the panel above 1067166124Srafan or below that panel. Handed NULL, they return the bottom-most or 106876726Speter top-most panel. 1069166124Srafan 1070166124Srafan Every panel has an associated user pointer, not used by the panel 1071166124Srafan code, to which you can attach application data. See the man page 107276726Speter documentation of set_panel_userptr() and panel_userptr for details. 1073166124Srafan 107476726Speter The Menu Library 1075166124Srafan 107676726Speter A menu is a screen display that assists the user to choose some subset 1077166124Srafan of a given set of items. The menu library is a curses extension that 1078166124Srafan supports easy programming of menu hierarchies with a uniform but 107976726Speter flexible interface. 1080166124Srafan 1081166124Srafan The menu library first appeared in AT&T System V. The version 108276726Speter documented here is the menu code distributed with ncurses. 1083166124Srafan 108476726SpeterCompiling With the menu Library 108576726Speter 108676726Speter Your menu-using modules must import the menu library declarations with 108776726Speter #include <menu.h> 108876726Speter 1089166124Srafan and must be linked explicitly with the menus library using an -lmenu 1090166124Srafan 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. 1093166124Srafan 109476726SpeterOverview of Menus 109576726Speter 1096166124Srafan The menus created by this library consist of collections of items 1097166124Srafan including a name string part and a description string part. To make 1098166124Srafan menus, you create groups of these items and connect them with menu 109976726Speter frame objects. 1100166124Srafan 1101166124Srafan 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 1103166124Srafan 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 1105166124Srafan small to display all the items, it will be a scrollable viewport on 110676726Speter the collection of items. 1107166124Srafan 1108166124Srafan A menu may also be unposted (that is, undisplayed), and finally freed 1109166124Srafan to make the storage associated with it and its items available for 111076726Speter re-use. 1111166124Srafan 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(). 1116166124Srafan 4. Post the menu using post_menu(). 111776726Speter 5. Refresh the screen. 111876726Speter 6. Process user requests via an input loop. 1119166124Srafan 7. Unpost the menu using unpost_menu(). 112076726Speter 8. Free the menu, using free_menu(). 112176726Speter 9. Free the items using free_item(). 112276726Speter 10. Terminate curses. 1123166124Srafan 112476726SpeterSelecting items 112576726Speter 1126166124Srafan Menus may be multi-valued or (the default) single-valued (see the 1127166124Srafan manual page menu_opts(3x) to see how to change the default). Both 112876726Speter types always have a current item. 1129166124Srafan 1130166124Srafan From a single-valued menu you can read the selected value simply by 1131166124Srafan looking at the current item. From a multi-valued menu, you get the 1132166124Srafan selected set by looping through the items applying the item_value() 1133166124Srafan predicate function. Your menu-processing code can use the function 113476726Speter set_item_value() to flag the items in the select set. 1135166124Srafan 1136166124Srafan Menu items can be made unselectable using set_item_opts() or 1137166124Srafan item_opts_off() with the O_SELECTABLE argument. This is the only 1138166124Srafan option so far defined for menus, but it is good practice to code as 113976726Speter though other option bits might be on. 1140166124Srafan 114176726SpeterMenu Display 114276726Speter 1143166124Srafan 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 1149166124Srafan * The length of the menu mark string used for highlighting selected 115076726Speter items 1151166124Srafan 1152166124Srafan 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. 1156166124Srafan 115776726Speter The actual menu page may be smaller than the format size. This depends 1158166124Srafan on the item number and size and whether O_ROWMAJOR is on. This option 1159166124Srafan (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 1161166124Srafan couple of items are side-by-side in the top row. The alternative is 1162166124Srafan column-major display, which tries to put the first several items in 116376726Speter the first column. 1164166124Srafan 1165166124Srafan As mentioned above, a menu format not large enough to allow all items 1166166124Srafan to fit on-screen will result in a menu display that is vertically 116776726Speter scrollable. 1168166124Srafan 1169166124Srafan You can scroll it with requests to the menu driver, which will be 117076726Speter described in the section on menu input handling. 1171166124Srafan 1172166124Srafan 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. 1175166124Srafan 1176166124Srafan The function scale_menu() returns the minimum display size that the 1177166124Srafan menu code computes from all these factors. There are other menu 1178166124Srafan display attributes including a select attribute, an attribute for 1179166124Srafan selectable items, an attribute for unselectable items, and a pad 118076726Speter character used to separate item name text from description text. These 1181166124Srafan have reasonable defaults which the library allows you to change (see 118276726Speter the menu_attribs(3x) manual page. 1183166124Srafan 118476726SpeterMenu Windows 118576726Speter 1186166124Srafan 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. 1189166124Srafan 1190166124Srafan 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, 1192166124Srafan 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. 1195166124Srafan 1196166124Srafan By default, both windows are stdscr. You can set them with the 119776726Speter functions in menu_win(3x). 1198166124Srafan 1199166124Srafan When you call post_menu(), you write the menu to its subwindow. When 1200166124Srafan you call unpost_menu(), you erase the subwindow, However, neither of 1201166124Srafan these actually modifies the screen. To do that, call wrefresh() or 120276726Speter some equivalent. 1203166124Srafan 120476726SpeterProcessing Menu Input 120576726Speter 1206166124Srafan The main loop of your menu-processing code should call menu_driver() 1207166124Srafan repeatedly. The first argument of this routine is a menu pointer; the 1208166124Srafan 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 1210166124Srafan output to menu_driver(). The menu command codes are fully documented 121176726Speter in menu_driver(3x). 1212166124Srafan 1213166124Srafan The simplest group of command codes is REQ_NEXT_ITEM, REQ_PREV_ITEM, 1214166124Srafan REQ_FIRST_ITEM, REQ_LAST_ITEM, REQ_UP_ITEM, REQ_DOWN_ITEM, 1215166124Srafan REQ_LEFT_ITEM, REQ_RIGHT_ITEM. These change the currently selected 1216166124Srafan item. These requests may cause scrolling of the menu page if it only 121776726Speter partially displayed. 1218166124Srafan 1219166124Srafan There are explicit requests for scrolling which also change the 1220166124Srafan current item (because the select location does not change, but the 1221166124Srafan item there does). These are REQ_SCR_DLINE, REQ_SCR_ULINE, 122276726Speter REQ_SCR_DPAGE, and REQ_SCR_UPAGE. 1223166124Srafan 1224166124Srafan The REQ_TOGGLE_ITEM selects or deselects the current item. It is for 1225166124Srafan use in multi-valued menus; if you use it with O_ONEVALUE on, you'll 122676726Speter get an error return (E_REQUEST_DENIED). 1227166124Srafan 1228166124Srafan Each menu has an associated pattern buffer. The menu_driver() logic 1229166124Srafan tries to accumulate printable ASCII characters passed in in that 1230166124Srafan buffer; when it matches a prefix of an item name, that item (or the 1231166124Srafan next matching item) is selected. If appending a character yields no 1232166124Srafan new match, that character is deleted from the pattern buffer, and 123376726Speter menu_driver() returns E_NO_MATCH. 1234166124Srafan 1235166124Srafan Some requests change the pattern buffer directly: REQ_CLEAR_PATTERN, 1236166124Srafan REQ_BACK_PATTERN, REQ_NEXT_MATCH, REQ_PREV_MATCH. The latter two are 1237166124Srafan useful when pattern buffer input matches more than one item in a 123876726Speter multi-valued menu. 1239166124Srafan 1240166124Srafan Each successful scroll or item navigation request clears the pattern 1241166124Srafan buffer. It is also possible to set the pattern buffer explicitly with 124276726Speter set_menu_pattern(). 1243166124Srafan 1244166124Srafan Finally, menu driver requests above the constant MAX_COMMAND are 1245166124Srafan considered application-specific commands. The menu_driver() code 124676726Speter ignores them and returns E_UNKNOWN_COMMAND. 1247166124Srafan 124876726SpeterMiscellaneous Other Features 124976726Speter 1250166124Srafan Various menu options can affect the processing and visual appearance 125176726Speter and input processing of menus. See menu_opts(3x) for details. 1252166124Srafan 1253166124Srafan It is possible to change the current item from application code; this 1254166124Srafan is useful if you want to write your own navigation requests. It is 1255166124Srafan also possible to explicitly set the top row of the menu display. See 1256166124Srafan mitem_current(3x). If your application needs to change the menu 1257166124Srafan subwindow cursor for any reason, pos_menu_cursor() will restore it to 125876726Speter the correct location for continuing menu driver processing. 1259166124Srafan 1260166124Srafan It is possible to set hooks to be called at menu initialization and 1261166124Srafan wrapup time, and whenever the selected item changes. See 126276726Speter menu_hook(3x). 1263166124Srafan 1264166124Srafan 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). 1266166124Srafan 126776726Speter The Forms Library 1268166124Srafan 1269166124Srafan The form library is a curses extension that supports easy programming 127076726Speter of on-screen forms for data entry and program control. 1271166124Srafan 1272166124Srafan The form library first appeared in AT&T System V. The version 127376726Speter documented here is the form code distributed with ncurses. 1274166124Srafan 127576726SpeterCompiling With the form Library 127676726Speter 127776726Speter Your form-using modules must import the form library declarations with 127876726Speter #include <form.h> 127976726Speter 1280166124Srafan and must be linked explicitly with the forms library using an -lform 1281166124Srafan 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. 1284166124Srafan 128576726SpeterOverview of Forms 128676726Speter 1287166124Srafan A form is a collection of fields; each field may be either a label 1288166124Srafan (explanatory text) or a data-entry location. Long forms may be 128976726Speter segmented into pages; each entry to a new page clears the screen. 1290166124Srafan 1291166124Srafan To make forms, you create groups of fields and connect them with form 129276726Speter frame objects; the form library makes this relatively simple. 1293166124Srafan 1294166124Srafan Once defined, a form can be posted, that is written to an associated 1295166124Srafan window. Actually, each form has two associated windows; a containing 1296166124Srafan window in which the programmer can scribble titles or borders, and a 129776726Speter subwindow in which the form fields proper are displayed. 1298166124Srafan 1299166124Srafan As the form user fills out the posted form, navigation and editing 1300166124Srafan keys support movement between fields, editing keys support modifying 1301166124Srafan field, and plain text adds to or changes data in a current field. The 1302166124Srafan form library allows you (the forms designer) to bind each navigation 1303166124Srafan and editing key to any keystroke accepted by curses Fields may have 1304166124Srafan validation conditions on them, so that they check input data for type 1305166124Srafan and value. The form library supplies a rich set of pre-defined field 130676726Speter types, and makes it relatively easy to define new ones. 1307166124Srafan 130876726Speter Once its transaction is completed (or aborted), a form may be unposted 1309166124Srafan (that is, undisplayed), and finally freed to make the storage 131076726Speter associated with it and its items available for re-use. 1311166124Srafan 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(). 1316166124Srafan 4. Post the form using post_form(). 131776726Speter 5. Refresh the screen. 131876726Speter 6. Process user requests via an input loop. 1319166124Srafan 7. Unpost the form using unpost_form(). 132076726Speter 8. Free the form, using free_form(). 132176726Speter 9. Free the fields using free_field(). 132276726Speter 10. Terminate curses. 1323166124Srafan 1324166124Srafan Note that this looks much like a menu program; the form library 1325166124Srafan handles tasks which are in many ways similar, and its interface was 1326166124Srafan obviously designed to resemble that of the menu library wherever 132776726Speter possible. 1328166124Srafan 1329166124Srafan In forms programs, however, the `process user requests' is somewhat 1330166124Srafan more complicated than for menus. Besides menu-like navigation 133176726Speter operations, the menu driver loop has to support field editing and data 133276726Speter validation. 1333166124Srafan 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 1342166124Srafan Menu items always occupy a single row, but forms fields may have 1343166124Srafan multiple rows. So new_field() requires you to specify a width and 1344166124Srafan height (the first two arguments, which mist both be greater than 134576726Speter zero). 1346166124Srafan 134776726Speter You must also specify the location of the field's upper left corner on 1348166124Srafan the screen (the third and fourth arguments, which must be zero or 1349166124Srafan greater). Note that these coordinates are relative to the form 1350166124Srafan subwindow, which will coincide with stdscr by default but need not be 1351166124Srafan stdscr if you've done an explicit set_form_win() call. 1352166124Srafan 1353166124Srafan The fifth argument allows you to specify a number of off-screen rows. 1354166124Srafan If this is zero, the entire field will always be displayed. If it is 1355166124Srafan nonzero, the form will be scrollable, with only one screen-full 1356166124Srafan (initially the top part) displayed at any given time. If you make a 1357166124Srafan field dynamic and grow it so it will no longer fit on the screen, the 1358166124Srafan form will become scrollable even if the offscreen argument was 135976726Speter initially zero. 1360166124Srafan 1361166124Srafan 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 1364166124Srafan 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 1369166124Srafan The function dup_field() duplicates an existing field at a new 1370166124Srafan location. Size and buffering information are copied; some attribute 1371166124Srafan 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 1376166124Srafan The function link_field() also duplicates an existing field at a new 1377166124Srafan location. The difference from dup_field() is that it arranges for the 137876726Speter new field's buffer to be shared with the old one. 1379166124Srafan 1380166124Srafan 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 1382166124Srafan you declare several fields linked to an original, and then make them 1383166124Srafan inactive, changes from the original will still be propagated to the 138476726Speter linked fields. 1385166124Srafan 1386166124Srafan As with duplicated fields, linked fields have attribute bits separate 138776726Speter from the original. 1388166124Srafan 1389166124Srafan As you might guess, all these field-allocations return NULL if the 1390166124Srafan field allocation is not possible due to an out-of-memory error or 139176726Speter out-of-bounds arguments. 1392166124Srafan 139376726Speter To connect fields to a form, use 139476726SpeterFORM *new_form(FIELD **fields); 139576726Speter 1396166124Srafan This function expects to see a NULL-terminated array of field 1397166124Srafan pointers. Said fields are connected to a newly-allocated form object; 139876726Speter its address is returned (or else NULL if the allocation fails). 1399166124Srafan 1400166124Srafan Note that new_field() does not copy the pointer array into private 1401166124Srafan storage; if you modify the contents of the pointer array during forms 1402166124Srafan processing, all manner of bizarre things might happen. Also note that 140376726Speter any given field may only be connected to one form. 1404166124Srafan 1405166124Srafan The functions free_field() and free_form are available to free field 1406166124Srafan 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. 1409166124Srafan 141076726SpeterFetching and Changing Field Attributes 141176726Speter 1412166124Srafan Each form field has a number of location and size attributes 1413166124Srafan 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) 1415166124Srafan 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. 1418166124Srafan 141976726Speter When a field is created, the attributes not specified by the new_field 1420166124Srafan function are copied from an invisible system default field. In 1421166124Srafan 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. 1424166124Srafan 142576726Speter Fetching Size and Location Data 1426166124Srafan 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 1434166124Srafan This function is a sort of inverse of new_field(); instead of setting 1435166124Srafan size and location attributes of a new field, it fetches them from an 143676726Speter existing one. 1437166124Srafan 143876726Speter Changing the Field Location 1439166124Srafan 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(). 1445166124Srafan 144676726Speter The Justification Attribute 1447166124Srafan 1448166124Srafan 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 1455166124Srafan The mode values accepted and returned by this functions are 1456166124Srafan preprocessor macros NO_JUSTIFICATION, JUSTIFY_RIGHT, JUSTIFY_LEFT, or 145776726Speter JUSTIFY_CENTER. 1458166124Srafan 145976726Speter Field Display Attributes 1460166124Srafan 1461166124Srafan For each field, you can set a foreground attribute for entered 1462166124Srafan characters, a background attribute for the entire field, and a pad 1463166124Srafan character for the unfilled portion of the field. You can also control 146476726Speter pagination of the form. 1465166124Srafan 1466166124Srafan This group of four field attributes controls the visual appearance of 1467166124Srafan 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 1490166124Srafan curses(3x) display attribute values (A_STANDOUT, A_BOLD, A_REVERSE 1491166124Srafan etc). The page bit of a field controls whether it is displayed at the 149276726Speter start of a new form screen. 1493166124Srafan 149476726Speter Field Option Bits 1495166124Srafan 1496166124Srafan There is also a large collection of field option bits you can set to 1497166124Srafan 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: 1511166124Srafan 151276726Speter O_VISIBLE 1513166124Srafan Controls whether the field is visible on the screen. Can be 1514166124Srafan used during form processing to hide or pop up fields depending 151576726Speter on the value of parent fields. 1516166124Srafan 151776726Speter O_ACTIVE 1518166124Srafan Controls whether the field is active during forms processing 1519166124Srafan (i.e. visited by form navigation keys). Can be used to make 1520166124Srafan labels or derived fields with buffer values alterable by the 152176726Speter forms application, not the user. 1522166124Srafan 152376726Speter O_PUBLIC 1524166124Srafan Controls whether data is displayed during field entry. If this 1525166124Srafan option is turned off on a field, the library will accept and 1526166124Srafan edit data in that field, but it will not be displayed and the 1527166124Srafan visible field cursor will not move. You can turn off the 152876726Speter O_PUBLIC bit to define password fields. 1529166124Srafan 153076726Speter O_EDIT 1531166124Srafan Controls whether the field's data can be modified. When this 1532166124Srafan option is off, all editing requests except REQ_PREV_CHOICE and 1533166124Srafan REQ_NEXT_CHOICE will fail. Such read-only fields may be useful 153476726Speter for help messages. 1535166124Srafan 153676726Speter O_WRAP 153776726Speter Controls word-wrapping in multi-line fields. Normally, when any 1538166124Srafan character of a (blank-separated) word reaches the end of the 1539166124Srafan 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. 1542166124Srafan 154376726Speter O_BLANK 1544166124Srafan Controls field blanking. When this option is on, entering a 1545166124Srafan character at the first field position erases the entire field 154676726Speter (except for the just-entered character). 1547166124Srafan 154876726Speter O_AUTOSKIP 1549166124Srafan Controls automatic skip to next field when this one fills. 1550166124Srafan Normally, when the forms user tries to type more data into a 1551166124Srafan 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 1553166124Srafan of the field. This option is ignored in dynamic fields that 155476726Speter have not reached their size limit. 1555166124Srafan 155676726Speter O_NULLOK 1557166124Srafan Controls whether validation is applied to blank fields. 1558166124Srafan Normally, it is not; the user can leave a field blank without 1559166124Srafan invoking the usual validation check on exit. If this option is 156076726Speter off on a field, exit from it will invoke a validation check. 1561166124Srafan 156276726Speter O_PASSOK 156376726Speter Controls whether validation occurs on every exit, or only after 1564166124Srafan the field is modified. Normally the latter is true. Setting 1565166124Srafan O_PASSOK may be useful if your field's validation function may 156676726Speter change during forms processing. 1567166124Srafan 156876726Speter O_STATIC 1569166124Srafan Controls whether the field is fixed to its initial dimensions. 1570166124Srafan If you turn this off, the field becomes dynamic and will 157176726Speter stretch to fit entered data. 1572166124Srafan 1573166124Srafan A field's options cannot be changed while the field is currently 1574166124Srafan selected. However, options may be changed on posted fields that are 157576726Speter not current. 1576166124Srafan 157776726Speter The option values are bit-masks and can be composed with logical-or in 157876726Speter the obvious way. 1579166124Srafan 158076726SpeterField Status 158176726Speter 158276726Speter Every field has a status flag, which is set to FALSE when the field is 1583166124Srafan 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 1590166124Srafan Setting this flag under program control can be useful if you use the 159176726Speter same form repeatedly, looking for modified fields each time. 1592166124Srafan 1593166124Srafan 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 1595166124Srafan currently selected for input may not necessarily give a correct field 1596166124Srafan status value, because entered data isn't necessarily copied to buffer 1597166124Srafan zero before the exit validation check. To guarantee that the returned 1598166124Srafan status value reflects reality, call field_status() either (1) in the 1599166124Srafan field's exit validation check routine, (2) from the field's or form's 1600166124Srafan initialization or termination hooks, or (3) just after a 160176726Speter REQ_VALIDATION request has been processed by the forms driver. 1602166124Srafan 160376726SpeterField User Pointer 160476726Speter 1605166124Srafan Each field structure contains one character pointer slot that is not 1606166124Srafan 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 1613166124Srafan (Properly, this user pointer field ought to have (void *) type. The 161476726Speter (char *) type is retained for System V compatibility.) 1615166124Srafan 1616166124Srafan It is valid to set the user pointer of the default field (with a 1617166124Srafan set_field_userptr() call passed a NULL field pointer.) When a new 1618166124Srafan field is created, the default-field user pointer is copied to 161976726Speter initialize the new field's user pointer. 1620166124Srafan 162176726SpeterVariable-Sized Fields 162276726Speter 1623166124Srafan Normally, a field is fixed at the size specified for it at creation 1624166124Srafan time. If, however, you turn off its O_STATIC bit, it becomes dynamic 1625166124Srafan and will automatically resize itself to accommodate data as it is 1626166124Srafan entered. If the field has extra buffers associated with it, they will 162776726Speter grow right along with the main input buffer. 1628166124Srafan 1629166124Srafan 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 1631166124Srafan originally dimensioned and located. A multi-line dynamic field will 1632166124Srafan have a fixed width, but variable height (number of rows), scrolling 1633166124Srafan vertically to display data within the field area as originally 163476726Speter dimensioned and located. 1635166124Srafan 1636166124Srafan Normally, a dynamic field is allowed to grow without limit. But it is 1637166124Srafan 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; 1643166124Srafan if it is multi-line, it is taken to be a line size limit. To disable 1644166124Srafan 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. 1646166124Srafan 164776726Speter The following properties of a field change when it becomes dynamic: 1648166124Srafan * 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). 1652166124Srafan * The dup_field() and link_field() calls copy dynamic-buffer sizes. 1653166124Srafan If the O_STATIC option is set on one of a collection of links, 1654166124Srafan buffer resizing will occur only when the field is edited through 165576726Speter that link. 1656166124Srafan * The call field_info() will retrieve the original static size of 1657166124Srafan the field; use dynamic_field_info() to get the actual dynamic 165876726Speter size. 1659166124Srafan 166076726SpeterField Validation 166176726Speter 1662166124Srafan By default, a field will accept any data that will fit in its input 1663166124Srafan buffer. However, it is possible to attach a validation type to a 1664166124Srafan field. If you do this, any attempt to leave the field while it 1665166124Srafan contains data that doesn't match the validation type will fail. Some 1666166124Srafan validation types also have a character-validity check for each time a 166776726Speter character is entered in the field. 1668166124Srafan 1669166124Srafan A field's validation check (if any) is not called when 1670166124Srafan set_field_buffer() modifies the input buffer, nor when that buffer is 167176726Speter changed through a linked field. 1672166124Srafan 1673166124Srafan The form library provides a rich set of pre-defined validation types, 1674166124Srafan and gives you the capability to define custom ones of your own. You 1675166124Srafan 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 1683166124Srafan The validation type of a field is considered an attribute of the 1684166124Srafan field. As with other field attributes, Also, doing set_field_type() 1685166124Srafan with a NULL field default will change the system default for 168676726Speter validation of newly-created fields. 1687166124Srafan 168876726Speter Here are the pre-defined validation types: 1689166124Srafan 169076726Speter TYPE_ALPHA 1691166124Srafan 1692166124Srafan This field type accepts alphabetic data; no blanks, no digits, no 1693166124Srafan 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 1700166124Srafan to set this to the field width; if it's greater than the field width, 1701166124Srafan the validation check will always fail. A minimum width of zero makes 170276726Speter field completion optional. 1703166124Srafan 170476726Speter TYPE_ALNUM 1705166124Srafan 1706166124Srafan This field type accepts alphabetic data and digits; no blanks, no 1707166124Srafan 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 1713166124Srafan The width argument sets a minimum width of data. As with TYPE_ALPHA, 1714166124Srafan 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. 1717166124Srafan 171876726Speter TYPE_ENUM 1719166124Srafan 1720166124Srafan This type allows you to restrict a field's values to be among a 1721166124Srafan 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 1729166124Srafan The valuelist parameter must point at a NULL-terminated list of valid 1730166124Srafan strings. The checkcase argument, if true, makes comparison with the 173176726Speter string case-sensitive. 1732166124Srafan 1733166124Srafan When the user exits a TYPE_ENUM field, the validation procedure tries 1734166124Srafan to complete the data in the buffer to a valid entry. If a complete 1735166124Srafan 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. 1738166124Srafan 1739166124Srafan By default, if you enter such a prefix and it matches more than one 1740166124Srafan 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. 1743166124Srafan 1744166124Srafan The REQ_NEXT_CHOICE and REQ_PREV_CHOICE input requests can be 174576726Speter particularly useful with these fields. 1746166124Srafan 174776726Speter TYPE_INTEGER 1748166124Srafan 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 1755166124Srafan 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. 1758166124Srafan 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. 1761166124Srafan 176276726Speter A TYPE_INTEGER value buffer can conveniently be interpreted with the C 176376726Speter library function atoi(3). 1764166124Srafan 176576726Speter TYPE_NUMERIC 1766166124Srafan 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 1773166124Srafan Valid characters consist of an optional leading minus and digits. 1774166124Srafan possibly including a decimal point. If your system supports locale's, 1775166124Srafan the decimal point character used must be the one defined by your 1776166124Srafan 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. 1778166124Srafan 1779166124Srafan If the value passes its range check, it is padded with as many 178076726Speter trailing zero digits as necessary to meet the padding argument. 1781166124Srafan 178276726Speter A TYPE_NUMERIC value buffer can conveniently be interpreted with the C 178376726Speter library function atof(3). 1784166124Srafan 178576726Speter TYPE_REGEXP 1786166124Srafan 1787166124Srafan 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 1793166124Srafan The syntax for regular expressions is that of regcomp(3). The check 179476726Speter for regular-expression match is performed on exit. 1795166124Srafan 179676726SpeterDirect Field Buffer Manipulation 179776726Speter 179876726Speter The chief attribute of a field is its buffer contents. When a form has 1799166124Srafan 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 1804166124Srafan Normally, the state of the zero-numbered buffer for each field is set 1805166124Srafan by the user's editing actions on that field. It's sometimes useful to 1806166124Srafan 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 1812166124Srafan 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. 1815166124Srafan 1816166124Srafan Calling field_buffer() with a null field pointer will raise an error. 1817166124Srafan 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 1819166124Srafan currently selected for input may not necessarily give a correct field 1820166124Srafan buffer value, because entered data isn't necessarily copied to buffer 1821166124Srafan zero before the exit validation check. To guarantee that the returned 1822166124Srafan 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 1824166124Srafan or form's initialization or termination hooks, or (3) just after a 182576726Speter REQ_VALIDATION request has been processed by the forms driver. 1826166124Srafan 182776726SpeterAttributes of Forms 182876726Speter 1829166124Srafan 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. 1832166124Srafan 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 1842166124Srafan 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, 1844166124Srafan the old fields of the form are disconnected but not freed (and 1845166124Srafan eligible to be connected to other forms), then the new fields are 184676726Speter connected. 1847166124Srafan 1848166124Srafan It may also be null, in which case the old fields are disconnected 184976726Speter (and not freed) but no new ones are connected. 1850166124Srafan 1851166124Srafan The field_count() function simply counts the number of fields 1852166124Srafan connected to a given from. It returns -1 if the form-pointer argument 185376726Speter is NULL. 1854166124Srafan 185576726SpeterControl of Form Display 185676726Speter 1857166124Srafan In the overview section, you saw that to display a form you normally 1858166124Srafan start by defining its size (and fields), posting it, and refreshing 1859166124Srafan the screen. There is an hidden step before posting, which is the 1860166124Srafan association of the form with a frame window (actually, a pair of 1861166124Srafan windows) within which it will be displayed. By default, the forms 186276726Speter library associates every form with the full-screen window stdscr. 1863166124Srafan 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 1866166124Srafan adapt the form display to different screen sizes, dynamically tile 1867166124Srafan forms on the screen, or use a form as part of an interface layout 186876726Speter managed by panels. 1869166124Srafan 1870166124Srafan The two windows associated with each form have the same functions as 1871166124Srafan their analogues in the menu library. Both these windows are painted 187276726Speter when the form is posted and erased when the form is unposted. 1873166124Srafan 1874166124Srafan 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, 1876166124Srafan 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. 1879166124Srafan 1880166124Srafan In order to declare your own frame window for a form, you'll need to 1881166124Srafan 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 1888166124Srafan 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 1900166124Srafan Note that curses operations, including refresh(), on the form, should 190176726Speter be done on the frame window, not the form subwindow. 1902166124Srafan 1903166124Srafan It is possible to check from your application whether all of a 1904166124Srafan 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 1910166124Srafan The function data_ahead() returns TRUE if (a) the current field is 1911166124Srafan 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. 1913166124Srafan 191476726Speter The function data_behind() returns TRUE if the first (upper left hand) 191576726Speter character position is off-screen (not being displayed). 1916166124Srafan 1917166124Srafan 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 1922166124Srafan before handing control back to the forms driver in order to 192376726Speter re-synchronize it. 1924166124Srafan 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 1933166124Srafan Your input virtualization function needs to take input and then 1934166124Srafan convert it to either an alphanumeric character (which is treated as 1935166124Srafan data to be entered in the currently-selected field), or a forms 193676726Speter processing request. 1937166124Srafan 1938166124Srafan The forms driver provides hooks (through input-validation and 1939166124Srafan field-termination functions) with which your application code can 194076726Speter check that the input taken by the driver matched what was expected. 1941166124Srafan 194276726Speter Page Navigation Requests 1943166124Srafan 1944166124Srafan These requests cause page-level moves through the form, triggering 194576726Speter display of a new form screen. 1946166124Srafan 194776726Speter REQ_NEXT_PAGE 194876726Speter Move to the next form page. 1949166124Srafan 195076726Speter REQ_PREV_PAGE 195176726Speter Move to the previous form page. 1952166124Srafan 195376726Speter REQ_FIRST_PAGE 195476726Speter Move to the first form page. 1955166124Srafan 195676726Speter REQ_LAST_PAGE 195776726Speter Move to the last form page. 1958166124Srafan 1959166124Srafan 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. 1962166124Srafan 196376726Speter Inter-Field Navigation Requests 1964166124Srafan 196576726Speter These requests handle navigation between fields on the same page. 1966166124Srafan 196776726Speter REQ_NEXT_FIELD 196876726Speter Move to next field. 1969166124Srafan 197076726Speter REQ_PREV_FIELD 197176726Speter Move to previous field. 1972166124Srafan 197376726Speter REQ_FIRST_FIELD 197476726Speter Move to the first field. 1975166124Srafan 197676726Speter REQ_LAST_FIELD 197776726Speter Move to the last field. 1978166124Srafan 197976726Speter REQ_SNEXT_FIELD 198076726Speter Move to sorted next field. 1981166124Srafan 198276726Speter REQ_SPREV_FIELD 198376726Speter Move to sorted previous field. 1984166124Srafan 198576726Speter REQ_SFIRST_FIELD 198676726Speter Move to the sorted first field. 1987166124Srafan 198876726Speter REQ_SLAST_FIELD 198976726Speter Move to the sorted last field. 1990166124Srafan 199176726Speter REQ_LEFT_FIELD 199276726Speter Move left to field. 1993166124Srafan 199476726Speter REQ_RIGHT_FIELD 199576726Speter Move right to field. 1996166124Srafan 199776726Speter REQ_UP_FIELD 199876726Speter Move up to field. 1999166124Srafan 200076726Speter REQ_DOWN_FIELD 200176726Speter Move down to field. 2002166124Srafan 2003166124Srafan These requests treat the list of fields on a page as cyclic; that is, 2004166124Srafan 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() 2009166124Srafan 2010166124Srafan It is also possible to traverse the fields as if they had been sorted 2011166124Srafan in screen-position order, so the sequence goes left-to-right and 2012166124Srafan top-to-bottom. To do this, use the second group of four 201376726Speter sorted-movement requests. 2014166124Srafan 201576726Speter Finally, it is possible to move between fields using visual directions 2016166124Srafan 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. 2019166124Srafan 2020166124Srafan 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 2022166124Srafan of B and C to the right of B. A REQ_MOVE_RIGHT from A will go to B 2023166124Srafan only if A, B, and C all share the same first line; otherwise it will 202476726Speter skip over B to C. 2025166124Srafan 202676726Speter Intra-Field Navigation Requests 2027166124Srafan 2028166124Srafan These requests drive movement of the edit cursor within the currently 202976726Speter selected field. 2030166124Srafan 203176726Speter REQ_NEXT_CHAR 203276726Speter Move to next character. 2033166124Srafan 203476726Speter REQ_PREV_CHAR 203576726Speter Move to previous character. 2036166124Srafan 203776726Speter REQ_NEXT_LINE 203876726Speter Move to next line. 2039166124Srafan 204076726Speter REQ_PREV_LINE 204176726Speter Move to previous line. 2042166124Srafan 204376726Speter REQ_NEXT_WORD 204476726Speter Move to next word. 2045166124Srafan 204676726Speter REQ_PREV_WORD 204776726Speter Move to previous word. 2048166124Srafan 204976726Speter REQ_BEG_FIELD 205076726Speter Move to beginning of field. 2051166124Srafan 205276726Speter REQ_END_FIELD 205376726Speter Move to end of field. 2054166124Srafan 205576726Speter REQ_BEG_LINE 205676726Speter Move to beginning of line. 2057166124Srafan 205876726Speter REQ_END_LINE 205976726Speter Move to end of line. 2060166124Srafan 206176726Speter REQ_LEFT_CHAR 206276726Speter Move left in field. 2063166124Srafan 206476726Speter REQ_RIGHT_CHAR 206576726Speter Move right in field. 2066166124Srafan 206776726Speter REQ_UP_CHAR 206876726Speter Move up in field. 2069166124Srafan 207076726Speter REQ_DOWN_CHAR 207176726Speter Move down in field. 2072166124Srafan 2073166124Srafan 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. 2076166124Srafan 207776726Speter Scrolling Requests 2078166124Srafan 2079166124Srafan Fields that are dynamic and have grown and fields explicitly created 2080166124Srafan with offscreen rows are scrollable. One-line fields scroll 2081166124Srafan horizontally; multi-line fields scroll vertically. Most scrolling is 208276726Speter triggered by editing and intra-field movement (the library scrolls the 2083166124Srafan field to keep the cursor visible). It is possible to explicitly 208476726Speter request scrolling with the following requests: 2085166124Srafan 208676726Speter REQ_SCR_FLINE 208776726Speter Scroll vertically forward a line. 2088166124Srafan 208976726Speter REQ_SCR_BLINE 209076726Speter Scroll vertically backward a line. 2091166124Srafan 209276726Speter REQ_SCR_FPAGE 209376726Speter Scroll vertically forward a page. 2094166124Srafan 209576726Speter REQ_SCR_BPAGE 209676726Speter Scroll vertically backward a page. 2097166124Srafan 209876726Speter REQ_SCR_FHPAGE 209976726Speter Scroll vertically forward half a page. 2100166124Srafan 210176726Speter REQ_SCR_BHPAGE 210276726Speter Scroll vertically backward half a page. 2103166124Srafan 210476726Speter REQ_SCR_FCHAR 210576726Speter Scroll horizontally forward a character. 2106166124Srafan 210776726Speter REQ_SCR_BCHAR 210876726Speter Scroll horizontally backward a character. 2109166124Srafan 211076726Speter REQ_SCR_HFLINE 211176726Speter Scroll horizontally one field width forward. 2112166124Srafan 211376726Speter REQ_SCR_HBLINE 211476726Speter Scroll horizontally one field width backward. 2115166124Srafan 211676726Speter REQ_SCR_HFHALF 211776726Speter Scroll horizontally one half field width forward. 2118166124Srafan 211976726Speter REQ_SCR_HBHALF 212076726Speter Scroll horizontally one half field width backward. 2121166124Srafan 212276726Speter For scrolling purposes, a page of a field is the height of its visible 212376726Speter part. 2124166124Srafan 212576726Speter Editing Requests 2126166124Srafan 2127166124Srafan When you pass the forms driver an ASCII character, it is treated as a 2128166124Srafan request to add the character to the field's data buffer. Whether this 2129166124Srafan is an insertion or a replacement depends on the field's edit mode 213076726Speter (insertion is the default. 2131166124Srafan 213276726Speter The following requests support editing the field and changing the edit 213376726Speter mode: 2134166124Srafan 213576726Speter REQ_INS_MODE 213676726Speter Set insertion mode. 2137166124Srafan 213876726Speter REQ_OVL_MODE 213976726Speter Set overlay mode. 2140166124Srafan 214176726Speter REQ_NEW_LINE 214276726Speter New line request (see below for explanation). 2143166124Srafan 214476726Speter REQ_INS_CHAR 214576726Speter Insert space at character location. 2146166124Srafan 214776726Speter REQ_INS_LINE 214876726Speter Insert blank line at character location. 2149166124Srafan 215076726Speter REQ_DEL_CHAR 215176726Speter Delete character at cursor. 2152166124Srafan 215376726Speter REQ_DEL_PREV 215476726Speter Delete previous word at cursor. 2155166124Srafan 215676726Speter REQ_DEL_LINE 215776726Speter Delete line at cursor. 2158166124Srafan 215976726Speter REQ_DEL_WORD 216076726Speter Delete word at cursor. 2161166124Srafan 216276726Speter REQ_CLR_EOL 216376726Speter Clear to end of line. 2164166124Srafan 216576726Speter REQ_CLR_EOF 216676726Speter Clear to end of field. 2167166124Srafan 216876726Speter REQ_CLEAR_FIELD 216976726Speter Clear entire field. 2170166124Srafan 2171166124Srafan The behavior of the REQ_NEW_LINE and REQ_DEL_PREV requests is 2172166124Srafan complicated and partly controlled by a pair of forms options. The 2173166124Srafan special cases are triggered when the cursor is at the beginning of a 217476726Speter field, or on the last line of the field. 2175166124Srafan 217676726Speter First, we consider REQ_NEW_LINE: 2177166124Srafan 2178166124Srafan 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 2180166124Srafan of the current line after the cursor as a new line following the 2181166124Srafan 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). 2183166124Srafan 2184166124Srafan The normal behavior of REQ_NEW_LINE in overlay mode is to clear the 2185166124Srafan 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. 2187166124Srafan 218876726Speter However, REQ_NEW_LINE at the beginning of a field, or on the last line 2189166124Srafan of a field, instead does a REQ_NEXT_FIELD. O_NL_OVERLOAD option is 219076726Speter off, this special action is disabled. 2191166124Srafan 219276726Speter Now, let us consider REQ_DEL_PREV: 2193166124Srafan 2194166124Srafan The normal behavior of REQ_DEL_PREV is to delete the previous 2195166124Srafan character. If insert mode is on, and the cursor is at the start of a 2196166124Srafan line, and the text on that line will fit on the previous one, it 2197166124Srafan instead appends the contents of the current line to the previous one 2198166124Srafan and deletes the current line (you may think of this as deleting a 219976726Speter newline from the field buffer). 2200166124Srafan 2201166124Srafan However, REQ_DEL_PREV at the beginning of a field is instead treated 220276726Speter as a REQ_PREV_FIELD. 2203166124Srafan 2204166124Srafan If the O_BS_OVERLOAD option is off, this special action is disabled 220576726Speter and the forms driver just returns E_REQUEST_DENIED. 2206166124Srafan 2207166124Srafan See Form Options for discussion of how to set and clear the overload 220876726Speter options. 2209166124Srafan 221076726Speter Order Requests 2211166124Srafan 221276726Speter If the type of your field is ordered, and has associated functions for 2213166124Srafan 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: 2215166124Srafan 221676726Speter REQ_NEXT_CHOICE 221776726Speter Place the successor value of the current value in the buffer. 2218166124Srafan 221976726Speter REQ_PREV_CHOICE 222076726Speter Place the predecessor value of the current value in the buffer. 2221166124Srafan 222276726Speter Of the built-in field types, only TYPE_ENUM has built-in successor and 2223166124Srafan predecessor functions. When you define a field type of your own (see 2224166124Srafan Custom Validation Types), you can associate our own ordering 222576726Speter functions. 2226166124Srafan 222776726Speter Application Commands 2228166124Srafan 2229166124Srafan Form requests are represented as integers above the curses value 2230166124Srafan greater than KEY_MAX and less than or equal to the constant 2231166124Srafan MAX_COMMAND. If your input-virtualization routine returns a value 223276726Speter above MAX_COMMAND, the forms driver will ignore it. 2233166124Srafan 223476726SpeterField Change Hooks 223576726Speter 2236166124Srafan It is possible to set function hooks to be executed whenever the 2237166124Srafan 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. 2262166124Srafan In each of the set functions, the second argument should be the 2263166124Srafan address of a hook function. These functions differ only in the timing 226476726Speter of the hook call. 2265166124Srafan 226676726Speter form_init 2267166124Srafan This hook is called when the form is posted; also, just after 226876726Speter each page change operation. 2269166124Srafan 227076726Speter field_init 2271166124Srafan This hook is called when the form is posted; also, just after 227276726Speter each field change 2273166124Srafan 227476726Speter field_term 2275166124Srafan 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. 2278166124Srafan 227976726Speter form_term 2280166124Srafan This hook is called when the form is unposted; also, just 228176726Speter before each page change operation. 2282166124Srafan 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 2287166124Srafan 228876726Speter See Field Change Commands for discussion of the latter two cases. 2289166124Srafan 2290166124Srafan You can set a default hook for all fields by passing one of the set 229176726Speter functions a NULL first argument. 2292166124Srafan 2293166124Srafan You can disable any of these hooks by (re)setting them to NULL, the 229476726Speter default value. 2295166124Srafan 229676726SpeterField Change Commands 229776726Speter 2298166124Srafan Normally, navigation through the form will be driven by the user's 2299166124Srafan input requests. But sometimes it is useful to be able to move the 2300166124Srafan focus for editing and viewing under control of your application, or 2301166124Srafan 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 2312166124Srafan given form's field array (the array passed to new_form() or 231376726Speter set_form_fields()). 2314166124Srafan 2315166124Srafan The initial current field of a form is the first active field on the 231676726Speter first page. The function set_form_fields() resets this. 2317166124Srafan 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 2324166124Srafan The initial page of a newly-created form is 0. The function 232576726Speter set_form_fields() resets this. 2326166124Srafan 232776726SpeterForm Options 232876726Speter 2329166124Srafan 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: 2343166124Srafan 234476726Speter O_NL_OVERLOAD 2345166124Srafan Enable overloading of REQ_NEW_LINE as described in Editing 234676726Speter Requests. The value of this option is ignored on dynamic fields 2347166124Srafan that have not reached their size limit; these have no last 2348166124Srafan line, so the circumstances for triggering a REQ_NEXT_FIELD 234976726Speter never arise. 2350166124Srafan 235176726Speter O_BS_OVERLOAD 2352166124Srafan Enable overloading of REQ_DEL_PREV as described in Editing 235376726Speter Requests. 2354166124Srafan 235576726Speter The option values are bit-masks and can be composed with logical-or in 235676726Speter the obvious way. 2357166124Srafan 235876726SpeterCustom Validation Types 235976726Speter 2360166124Srafan The form library gives you the capability to define custom validation 2361166124Srafan types of your own. Further, the optional additional arguments of 236276726Speter set_field_type effectively allow you to parameterize validation types. 2363166124Srafan 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. 2366166124Srafan 236776726Speter Union Types 2368166124Srafan 2369166124Srafan 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 2374166124Srafan This function creates a field type that will accept any of the values 2375166124Srafan legal for either of its argument field types (which may be either 2376166124Srafan predefined or programmer-defined). If a set_field_type() call later 2377166124Srafan requires arguments, the new composite type expects all arguments for 2378166124Srafan the first type, than all arguments for the second. Order functions 2379166124Srafan (see Order Requests) associated with the component types will work on 2380166124Srafan the composite; what it does is check the validation function for the 2381166124Srafan first type, then for the second, to figure what type the buffer 238276726Speter contents should be treated as. 2383166124Srafan 238476726Speter New Field Types 2385166124Srafan 2386166124Srafan To create a field type from scratch, you need to specify one or both 238776726Speter of the following things: 2388166124Srafan * 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. 2391166124Srafan 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 2402166124Srafan forms driver will automatically call the new type's validation 240376726Speter functions at appropriate points in processing a field of the new type. 2404166124Srafan 2405166124Srafan The function free_fieldtype() deallocates the argument fieldtype, 240676726Speter freeing all storage associated with it. 2407166124Srafan 2408166124Srafan Normally, a field validator is called when the user attempts to leave 2409166124Srafan the field. Its first argument is a field pointer, from which it can 2410166124Srafan get to field buffer 0 and test it. If the function returns TRUE, the 2411166124Srafan operation succeeds; if it returns FALSE, the edit cursor stays in the 241276726Speter field. 2413166124Srafan 2414166124Srafan A character validator gets the character passed in as a first 2415166124Srafan argument. It too should return TRUE if the character is valid, FALSE 241676726Speter otherwise. 2417166124Srafan 241876726Speter Validation Function Arguments 2419166124Srafan 2420166124Srafan Your field- and character- validation functions will be passed a 2421166124Srafan second argument as well. This second argument is the address of a 2422166124Srafan structure (which we'll call a pile) built from any of the 2423166124Srafan field-type-specific arguments passed to set_field_type(). If no such 2424166124Srafan arguments are defined for the field type, this pile pointer argument 242576726Speter will be NULL. 2426166124Srafan 242776726Speter In order to arrange for such arguments to be passed to your validation 2428166124Srafan functions, you must associate a small set of storage-management 242976726Speter functions with the type. The forms driver will use these to synthesize 2430166124Srafan 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. 2432166124Srafan 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: 2443166124Srafan 244476726Speter make_str 2445166124Srafan This function is called by set_field_type(). It gets one 2446166124Srafan argument, a va_list of the type-specific arguments passed to 2447166124Srafan set_field_type(). It is expected to return a pile pointer to a 244876726Speter data structure that encapsulates those arguments. 2449166124Srafan 245076726Speter copy_str 245176726Speter This function is called by form library functions that allocate 2452166124Srafan new field instances. It is expected to take a pile pointer, 2453166124Srafan copy the pile to allocated storage, and return the address of 245476726Speter the pile copy. 2455166124Srafan 245676726Speter free_str 2457166124Srafan This function is called by field- and type-deallocation 2458166124Srafan routines in the library. It takes a pile pointer argument, and 245976726Speter is expected to free the storage of that pile. 2460166124Srafan 2461166124Srafan The make_str and copy_str functions may return NULL to signal 2462166124Srafan allocation failure. The library routines will that call them will 2463166124Srafan return error indication when this happens. Thus, your validation 2464166124Srafan functions should never see a NULL file pointer and need not check 246576726Speter specially for it. 2466166124Srafan 246776726Speter Order Functions For Custom Types 2468166124Srafan 2469166124Srafan Some custom field types are simply ordered in the same well-defined 2470166124Srafan 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 2479166124Srafan The successor and predecessor arguments will each be passed two 2480166124Srafan arguments; a field pointer, and a pile pointer (as for the validation 2481166124Srafan functions). They are expected to use the function field_buffer() to 2482166124Srafan read the current value, and set_field_buffer() on buffer 0 to set the 2483166124Srafan next or previous value. Either hook may return TRUE to indicate 2484166124Srafan success (a legal next or previous value was set) or FALSE to indicate 248576726Speter failure. 2486166124Srafan 248776726Speter Avoiding Problems 2488166124Srafan 2489166124Srafan The interface for defining custom types is complicated and tricky. 2490166124Srafan Rather than attempting to create a custom type entirely from scratch, 2491166124Srafan 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. 2493166124Srafan 2494166124Srafan Use that code as a model, and evolve it towards what you really want. 2495166124Srafan You will avoid many problems and annoyances that way. The code in the 2496166124Srafan ncurses library has been specifically exempted from the package 249776726Speter copyright to support this. 2498166124Srafan 2499166124Srafan If your custom type defines order functions, have do something 2500166124Srafan intuitive with a blank field. A useful convention is to make the 2501166124Srafan successor of a blank field the types minimum value, and its 250276726Speter predecessor the maximum. 2503