ncurses-intro.doc revision 174993
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 177174993Srafan in versions after 1.8.1 and wrote most of this introduction. Juergen 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 801174993Srafan under xterm. The easiest way to handle SIGWINCH is to do an endwin, 802174993Srafan followed by an refresh and a screen repaint you code yourself. The 803174993Srafan refresh will pick up the new screen size from the xterm's environment. 804166124Srafan 805166124Srafan That is the standard way, of course (it even works with some vendor's 806166124Srafan curses implementations). Its drawback is that it clears the screen to 80776726Speter reinitialize the display, and does not resize subwindows which must be 808166124Srafan shrunk. Ncurses provides an extension which works better, the 809166124Srafan resizeterm function. That function ensures that all windows are 810166124Srafan limited to the new screen dimensions, and pads stdscr with blanks if 81176726Speter the screen is larger. 812166124Srafan 813174993Srafan The ncurses library provides a SIGWINCH signal handler, which pushes a 814174993Srafan KEY_RESIZE via the wgetch() calls. When ncurses returns that code, it 815174993Srafan calls resizeterm to update the size of the standard screen's window, 816174993Srafan repainting that (filling with blanks or truncating as needed). It also 817174993Srafan resizes other windows, but its effect may be less satisfactory because 818174993Srafan it cannot know how you want the screen re-painted. You will usually 819174993Srafan have to write special-purpose code to handle KEY_RESIZE yourself. 820166124Srafan 82176726Speter Handling Multiple Terminal Screens 822166124Srafan 82376726Speter The initscr() function actually calls a function named newterm() to do 824166124Srafan most of its work. If you are writing a program that opens multiple 82576726Speter terminals, use newterm() directly. 826166124Srafan 827166124Srafan For each call, you will have to specify a terminal type and a pair of 828166124Srafan file pointers; each call will return a screen reference, and stdscr 82976726Speter will be set to the last one allocated. You will switch between screens 830166124Srafan with the set_term call. Note that you will also have to call 83176726Speter def_shell_mode and def_prog_mode on each tty yourself. 832166124Srafan 83376726Speter Testing for Terminal Capabilities 834166124Srafan 83576726Speter Sometimes you may want to write programs that test for the presence of 836166124Srafan various capabilities before deciding whether to go into ncurses mode. 837166124Srafan An easy way to do this is to call setupterm(), then use the functions 83876726Speter tigetflag(), tigetnum(), and tigetstr() to do your testing. 839166124Srafan 840166124Srafan A particularly useful case of this often comes up when you want to 841166124Srafan test whether a given terminal type should be treated as `smart' 84276726Speter (cursor-addressable) or `stupid'. The right way to test this is to see 84376726Speter if the return value of tigetstr("cup") is non-NULL. Alternatively, you 844166124Srafan can include the term.h file and test the value of the macro 84576726Speter cursor_address. 846166124Srafan 84776726Speter Tuning for Speed 848166124Srafan 849166124Srafan Use the addchstr() family of functions for fast screen-painting of 850166124Srafan text when you know the text doesn't contain any control characters. 851166124Srafan Try to make attribute changes infrequent on your screens. Don't use 85276726Speter the immedok() option! 853166124Srafan 85476726Speter Special Features of NCURSES 855166124Srafan 856166124Srafan The wresize() function allows you to resize a window in place. The 857166124Srafan associated resizeterm() function simplifies the construction of 85876726Speter SIGWINCH handlers, for resizing all windows. 859166124Srafan 86076726Speter The define_key() function allows you to define at runtime function-key 861166124Srafan control sequences which are not in the terminal description. The 862166124Srafan keyok() function allows you to temporarily enable or disable 86376726Speter interpretation of any function-key control sequence. 864166124Srafan 86576726Speter The use_default_colors() function allows you to construct applications 866166124Srafan which can use the terminal's default foreground and background colors 867166124Srafan as an additional "default" color. Several terminal emulators support 86876726Speter this feature, which is based on ISO 6429. 869166124Srafan 870166124Srafan Ncurses supports up 16 colors, unlike SVr4 curses which defines only 87176726Speter 8. While most terminals which provide color allow only 8 colors, about 87276726Speter a quarter (including XFree86 xterm) support 16 colors. 873166124Srafan 87476726SpeterCompatibility with Older Versions 87576726Speter 876166124Srafan Despite our best efforts, there are some differences between ncurses 877166124Srafan and the (undocumented!) behavior of older curses implementations. 878166124Srafan These arise from ambiguities or omissions in the documentation of the 87976726Speter API. 880166124Srafan 88176726Speter Refresh of Overlapping Windows 882166124Srafan 883166124Srafan If you define two windows A and B that overlap, and then alternately 884166124Srafan scribble on and refresh them, the changes made to the overlapping 885166124Srafan region under historic curses versions were often not documented 88676726Speter precisely. 887166124Srafan 888166124Srafan To understand why this is a problem, remember that screen updates are 889166124Srafan calculated between two representations of the entire display. The 890166124Srafan documentation says that when you refresh a window, it is first copied 891174993Srafan to the virtual screen, and then changes are calculated to update the 892174993Srafan physical screen (and applied to the terminal). But "copied to" is not 893174993Srafan very specific, and subtle differences in how copying works can produce 894174993Srafan different behaviors in the case where two overlapping windows are each 895174993Srafan being refreshed at unpredictable intervals. 896166124Srafan 897166124Srafan What happens to the overlapping region depends on what wnoutrefresh() 898166124Srafan does with its argument -- what portions of the argument window it 899166124Srafan copies to the virtual screen. Some implementations do "change copy", 900166124Srafan copying down only locations in the window that have changed (or been 901166124Srafan marked changed with wtouchln() and friends). Some implementations do 902166124Srafan "entire copy", copying all window locations to the virtual screen 90376726Speter whether or not they have changed. 904166124Srafan 905166124Srafan The ncurses library itself has not always been consistent on this 906166124Srafan score. Due to a bug, versions 1.8.7 to 1.9.8a did entire copy. 907166124Srafan Versions 1.8.6 and older, and versions 1.9.9 and newer, do change 90876726Speter copy. 909166124Srafan 910166124Srafan For most commercial curses implementations, it is not documented and 911166124Srafan not known for sure (at least not to the ncurses maintainers) whether 912166124Srafan they do change copy or entire copy. We know that System V release 3 913166124Srafan curses has logic in it that looks like an attempt to do change copy, 914166124Srafan but the surrounding logic and data representations are sufficiently 915166124Srafan complex, and our knowledge sufficiently indirect, that it's hard to 916166124Srafan know whether this is reliable. It is not clear what the SVr4 917166124Srafan documentation and XSI standard intend. The XSI Curses standard barely 918166124Srafan mentions wnoutrefresh(); the SVr4 documents seem to be describing 91976726Speter entire-copy, but it is possible with some effort and straining to read 92076726Speter them the other way. 921166124Srafan 922166124Srafan It might therefore be unwise to rely on either behavior in programs 923166124Srafan that might have to be linked with other curses implementations. 924166124Srafan Instead, you can do an explicit touchwin() before the wnoutrefresh() 92576726Speter call to guarantee an entire-contents copy anywhere. 926166124Srafan 927166124Srafan The really clean way to handle this is to use the panels library. If, 928166124Srafan when you want a screen update, you do update_panels(), it will do all 929166124Srafan the necessary wnoutrefresh() calls for whatever panel stacking order 930166124Srafan you have defined. Then you can do one doupdate() and there will be a 93176726Speter single burst of physical I/O that will do all your updates. 932166124Srafan 93376726Speter Background Erase 934166124Srafan 93576726Speter If you have been using a very old versions of ncurses (1.8.7 or older) 936166124Srafan you may be surprised by the behavior of the erase functions. In older 937166124Srafan versions, erased areas of a window were filled with a blank modified 938166124Srafan by the window's current attribute (as set by wattrset(), wattron(), 93976726Speter wattroff() and friends). 940166124Srafan 941166124Srafan In newer versions, this is not so. Instead, the attribute of erased 942166124Srafan blanks is normal unless and until it is modified by the functions 94376726Speter bkgdset() or wbkgdset(). 944166124Srafan 94576726Speter This change in behavior conforms ncurses to System V Release 4 and the 94676726Speter XSI Curses standard. 947166124Srafan 94876726SpeterXSI Curses Conformance 94976726Speter 950166124Srafan The ncurses library is intended to be base-level conformant with the 951166124Srafan XSI Curses standard from X/Open. Many extended-level features (in 952166124Srafan fact, almost all features not directly concerned with wide characters 95376726Speter and internationalization) are also supported. 954166124Srafan 955166124Srafan One effect of XSI conformance is the change in behavior described 95676726Speter under "Background Erase -- Compatibility with Old Versions". 957166124Srafan 958166124Srafan Also, ncurses meets the XSI requirement that every macro entry point 959166124Srafan have a corresponding function which may be linked (and will be 96076726Speter prototype-checked) if the macro definition is disabled with #undef. 961166124Srafan 96276726Speter The Panels Library 963166124Srafan 964166124Srafan The ncurses library by itself provides good support for screen 96576726Speter displays in which the windows are tiled (non-overlapping). In the more 966166124Srafan general case that windows may overlap, you have to use a series of 967166124Srafan wnoutrefresh() calls followed by a doupdate(), and be careful about 96876726Speter the order you do the window refreshes in. It has to be bottom-upwards, 96976726Speter otherwise parts of windows that should be obscured will show through. 970166124Srafan 971166124Srafan When your interface design is such that windows may dive deeper into 972166124Srafan the visibility stack or pop to the top at runtime, the resulting 973166124Srafan book-keeping can be tedious and difficult to get right. Hence the 97476726Speter panels library. 975166124Srafan 976166124Srafan The panel library first appeared in AT&T System V. The version 97776726Speter documented here is the panel code distributed with ncurses. 978166124Srafan 97976726SpeterCompiling With the Panels Library 98076726Speter 981166124Srafan Your panels-using modules must import the panels library declarations 98276726Speter with 98376726Speter #include <panel.h> 98476726Speter 98576726Speter and must be linked explicitly with the panels library using an -lpanel 986166124Srafan argument. Note that they must also link the ncurses library with 98776726Speter -lncurses. Many linkers are two-pass and will accept either order, but 98876726Speter it is still good practice to put -lpanel first and -lncurses second. 989166124Srafan 99076726SpeterOverview of Panels 99176726Speter 992166124Srafan A panel object is a window that is implicitly treated as part of a 993166124Srafan deck including all other panel objects. The deck has an implicit 994166124Srafan bottom-to-top visibility order. The panels library includes an update 99576726Speter function (analogous to refresh()) that displays all panels in the deck 996166124Srafan in the proper order to resolve overlaps. The standard window, stdscr, 99776726Speter is considered below all panels. 998166124Srafan 999166124Srafan Details on the panels functions are available in the man pages. We'll 100076726Speter just hit the highlights here. 1001166124Srafan 1002166124Srafan You create a panel from a window by calling new_panel() on a window 1003166124Srafan pointer. It then becomes the top of the deck. The panel's window is 100476726Speter available as the value of panel_window() called with the panel pointer 100576726Speter as argument. 1006166124Srafan 1007166124Srafan You can delete a panel (removing it from the deck) with del_panel. 1008166124Srafan This will not deallocate the associated window; you have to do that 1009166124Srafan yourself. You can replace a panel's window with a different window by 1010166124Srafan calling replace_window. The new window may be of different size; the 101176726Speter panel code will re-compute all overlaps. This operation doesn't change 101276726Speter the panel's position in the deck. 1013166124Srafan 1014166124Srafan To move a panel's window, use move_panel(). The mvwin() function on 1015166124Srafan the panel's window isn't sufficient because it doesn't update the 1016166124Srafan panels library's representation of where the windows are. This 101776726Speter operation leaves the panel's depth, contents, and size unchanged. 1018166124Srafan 1019166124Srafan Two functions (top_panel(), bottom_panel()) are provided for 102076726Speter rearranging the deck. The first pops its argument window to the top of 1021166124Srafan the deck; the second sends it to the bottom. Either operation leaves 102276726Speter the panel's screen location, contents, and size unchanged. 1023166124Srafan 1024166124Srafan The function update_panels() does all the wnoutrefresh() calls needed 102576726Speter to prepare for doupdate() (which you must call yourself, afterwards). 1026166124Srafan 1027166124Srafan Typically, you will want to call update_panels() and doupdate() just 102876726Speter before accepting command input, once in each cycle of interaction with 1029166124Srafan the user. If you call update_panels() after each and every panel 1030166124Srafan write, you'll generate a lot of unnecessary refresh activity and 103176726Speter screen flicker. 1032166124Srafan 103376726SpeterPanels, Input, and the Standard Screen 103476726Speter 1035166124Srafan You shouldn't mix wnoutrefresh() or wrefresh() operations with panels 1036166124Srafan code; this will work only if the argument window is either in the top 103776726Speter panel or unobscured by any other panels. 1038166124Srafan 1039166124Srafan The stsdcr window is a special case. It is considered below all 104076726Speter panels. Because changes to panels may obscure parts of stdscr, though, 1041166124Srafan you should call update_panels() before doupdate() even when you only 104276726Speter change stdscr. 1043166124Srafan 1044166124Srafan Note that wgetch automatically calls wrefresh. Therefore, before 1045166124Srafan requesting input from a panel window, you need to be sure that the 104676726Speter panel is totally unobscured. 1047166124Srafan 1048166124Srafan There is presently no way to display changes to one obscured panel 104976726Speter without repainting all panels. 1050166124Srafan 105176726SpeterHiding Panels 105276726Speter 1053166124Srafan It's possible to remove a panel from the deck temporarily; use 1054166124Srafan hide_panel for this. Use show_panel() to render it visible again. The 1055166124Srafan predicate function panel_hidden tests whether or not a panel is 105676726Speter hidden. 1057166124Srafan 105876726Speter The panel_update code ignores hidden panels. You cannot do top_panel() 1059166124Srafan or bottom_panel on a hidden panel(). Other panels operations are 106076726Speter applicable. 1061166124Srafan 106276726SpeterMiscellaneous Other Facilities 106376726Speter 1064166124Srafan It's possible to navigate the deck using the functions panel_above() 1065166124Srafan and panel_below. Handed a panel pointer, they return the panel above 1066166124Srafan or below that panel. Handed NULL, they return the bottom-most or 106776726Speter top-most panel. 1068166124Srafan 1069166124Srafan Every panel has an associated user pointer, not used by the panel 1070166124Srafan code, to which you can attach application data. See the man page 107176726Speter documentation of set_panel_userptr() and panel_userptr for details. 1072166124Srafan 107376726Speter The Menu Library 1074166124Srafan 107576726Speter A menu is a screen display that assists the user to choose some subset 1076166124Srafan of a given set of items. The menu library is a curses extension that 1077166124Srafan supports easy programming of menu hierarchies with a uniform but 107876726Speter flexible interface. 1079166124Srafan 1080166124Srafan The menu library first appeared in AT&T System V. The version 108176726Speter documented here is the menu code distributed with ncurses. 1082166124Srafan 108376726SpeterCompiling With the menu Library 108476726Speter 108576726Speter Your menu-using modules must import the menu library declarations with 108676726Speter #include <menu.h> 108776726Speter 1088166124Srafan and must be linked explicitly with the menus library using an -lmenu 1089166124Srafan argument. Note that they must also link the ncurses library with 109076726Speter -lncurses. Many linkers are two-pass and will accept either order, but 109176726Speter it is still good practice to put -lmenu first and -lncurses second. 1092166124Srafan 109376726SpeterOverview of Menus 109476726Speter 1095166124Srafan The menus created by this library consist of collections of items 1096166124Srafan including a name string part and a description string part. To make 1097166124Srafan menus, you create groups of these items and connect them with menu 109876726Speter frame objects. 1099166124Srafan 1100166124Srafan The menu can then by posted, that is written to an associated window. 110176726Speter Actually, each menu has two associated windows; a containing window in 1102166124Srafan which the programmer can scribble titles or borders, and a subwindow 110376726Speter in which the menu items proper are displayed. If this subwindow is too 1104166124Srafan small to display all the items, it will be a scrollable viewport on 110576726Speter the collection of items. 1106166124Srafan 1107166124Srafan A menu may also be unposted (that is, undisplayed), and finally freed 1108166124Srafan to make the storage associated with it and its items available for 110976726Speter re-use. 1110166124Srafan 111176726Speter The general flow of control of a menu program looks like this: 111276726Speter 1. Initialize curses. 111376726Speter 2. Create the menu items, using new_item(). 111476726Speter 3. Create the menu using new_menu(). 1115166124Srafan 4. Post the menu using post_menu(). 111676726Speter 5. Refresh the screen. 111776726Speter 6. Process user requests via an input loop. 1118166124Srafan 7. Unpost the menu using unpost_menu(). 111976726Speter 8. Free the menu, using free_menu(). 112076726Speter 9. Free the items using free_item(). 112176726Speter 10. Terminate curses. 1122166124Srafan 112376726SpeterSelecting items 112476726Speter 1125166124Srafan Menus may be multi-valued or (the default) single-valued (see the 1126166124Srafan manual page menu_opts(3x) to see how to change the default). Both 112776726Speter types always have a current item. 1128166124Srafan 1129166124Srafan From a single-valued menu you can read the selected value simply by 1130166124Srafan looking at the current item. From a multi-valued menu, you get the 1131166124Srafan selected set by looping through the items applying the item_value() 1132166124Srafan predicate function. Your menu-processing code can use the function 113376726Speter set_item_value() to flag the items in the select set. 1134166124Srafan 1135166124Srafan Menu items can be made unselectable using set_item_opts() or 1136166124Srafan item_opts_off() with the O_SELECTABLE argument. This is the only 1137166124Srafan option so far defined for menus, but it is good practice to code as 113876726Speter though other option bits might be on. 1139166124Srafan 114076726SpeterMenu Display 114176726Speter 1142166124Srafan The menu library calculates a minimum display size for your window, 114376726Speter based on the following variables: 114476726Speter * The number and maximum length of the menu items 114576726Speter * Whether the O_ROWMAJOR option is enabled 114676726Speter * Whether display of descriptions is enabled 114776726Speter * Whatever menu format may have been set by the programmer 1148166124Srafan * The length of the menu mark string used for highlighting selected 114976726Speter items 1150166124Srafan 1151166124Srafan The function set_menu_format() allows you to set the maximum size of 115276726Speter the viewport or menu page that will be used to display menu items. You 115376726Speter can retrieve any format associated with a menu with menu_format(). The 115476726Speter default format is rows=16, columns=1. 1155166124Srafan 115676726Speter The actual menu page may be smaller than the format size. This depends 1157166124Srafan on the item number and size and whether O_ROWMAJOR is on. This option 1158166124Srafan (on by default) causes menu items to be displayed in a `raster-scan' 115976726Speter pattern, so that if more than one item will fit horizontally the first 1160166124Srafan couple of items are side-by-side in the top row. The alternative is 1161166124Srafan column-major display, which tries to put the first several items in 116276726Speter the first column. 1163166124Srafan 1164166124Srafan As mentioned above, a menu format not large enough to allow all items 1165166124Srafan to fit on-screen will result in a menu display that is vertically 116676726Speter scrollable. 1167166124Srafan 1168166124Srafan You can scroll it with requests to the menu driver, which will be 116976726Speter described in the section on menu input handling. 1170166124Srafan 1171166124Srafan Each menu has a mark string used to visually tag selected items; see 117276726Speter the menu_mark(3x) manual page for details. The mark string length also 117376726Speter influences the menu page size. 1174166124Srafan 1175166124Srafan The function scale_menu() returns the minimum display size that the 1176166124Srafan menu code computes from all these factors. There are other menu 1177166124Srafan display attributes including a select attribute, an attribute for 1178166124Srafan selectable items, an attribute for unselectable items, and a pad 117976726Speter character used to separate item name text from description text. These 1180166124Srafan have reasonable defaults which the library allows you to change (see 118176726Speter the menu_attribs(3x) manual page. 1182166124Srafan 118376726SpeterMenu Windows 118476726Speter 1185166124Srafan Each menu has, as mentioned previously, a pair of associated windows. 118676726Speter Both these windows are painted when the menu is posted and erased when 118776726Speter the menu is unposted. 1188166124Srafan 1189166124Srafan The outer or frame window is not otherwise touched by the menu 119076726Speter routines. It exists so the programmer can associate a title, a border, 1191166124Srafan or perhaps help text with the menu and have it properly refreshed or 119276726Speter erased at post/unpost time. The inner window or subwindow is where the 119376726Speter current menu page is displayed. 1194166124Srafan 1195166124Srafan By default, both windows are stdscr. You can set them with the 119676726Speter functions in menu_win(3x). 1197166124Srafan 1198166124Srafan When you call post_menu(), you write the menu to its subwindow. When 1199166124Srafan you call unpost_menu(), you erase the subwindow, However, neither of 1200166124Srafan these actually modifies the screen. To do that, call wrefresh() or 120176726Speter some equivalent. 1202166124Srafan 120376726SpeterProcessing Menu Input 120476726Speter 1205166124Srafan The main loop of your menu-processing code should call menu_driver() 1206166124Srafan repeatedly. The first argument of this routine is a menu pointer; the 1207166124Srafan second is a menu command code. You should write an input-fetching 120876726Speter routine that maps input characters to menu command codes, and pass its 1209166124Srafan output to menu_driver(). The menu command codes are fully documented 121076726Speter in menu_driver(3x). 1211166124Srafan 1212166124Srafan The simplest group of command codes is REQ_NEXT_ITEM, REQ_PREV_ITEM, 1213166124Srafan REQ_FIRST_ITEM, REQ_LAST_ITEM, REQ_UP_ITEM, REQ_DOWN_ITEM, 1214166124Srafan REQ_LEFT_ITEM, REQ_RIGHT_ITEM. These change the currently selected 1215166124Srafan item. These requests may cause scrolling of the menu page if it only 121676726Speter partially displayed. 1217166124Srafan 1218166124Srafan There are explicit requests for scrolling which also change the 1219166124Srafan current item (because the select location does not change, but the 1220166124Srafan item there does). These are REQ_SCR_DLINE, REQ_SCR_ULINE, 122176726Speter REQ_SCR_DPAGE, and REQ_SCR_UPAGE. 1222166124Srafan 1223166124Srafan The REQ_TOGGLE_ITEM selects or deselects the current item. It is for 1224166124Srafan use in multi-valued menus; if you use it with O_ONEVALUE on, you'll 122576726Speter get an error return (E_REQUEST_DENIED). 1226166124Srafan 1227166124Srafan Each menu has an associated pattern buffer. The menu_driver() logic 1228166124Srafan tries to accumulate printable ASCII characters passed in in that 1229166124Srafan buffer; when it matches a prefix of an item name, that item (or the 1230166124Srafan next matching item) is selected. If appending a character yields no 1231166124Srafan new match, that character is deleted from the pattern buffer, and 123276726Speter menu_driver() returns E_NO_MATCH. 1233166124Srafan 1234166124Srafan Some requests change the pattern buffer directly: REQ_CLEAR_PATTERN, 1235166124Srafan REQ_BACK_PATTERN, REQ_NEXT_MATCH, REQ_PREV_MATCH. The latter two are 1236166124Srafan useful when pattern buffer input matches more than one item in a 123776726Speter multi-valued menu. 1238166124Srafan 1239166124Srafan Each successful scroll or item navigation request clears the pattern 1240166124Srafan buffer. It is also possible to set the pattern buffer explicitly with 124176726Speter set_menu_pattern(). 1242166124Srafan 1243166124Srafan Finally, menu driver requests above the constant MAX_COMMAND are 1244166124Srafan considered application-specific commands. The menu_driver() code 124576726Speter ignores them and returns E_UNKNOWN_COMMAND. 1246166124Srafan 124776726SpeterMiscellaneous Other Features 124876726Speter 1249166124Srafan Various menu options can affect the processing and visual appearance 125076726Speter and input processing of menus. See menu_opts(3x) for details. 1251166124Srafan 1252166124Srafan It is possible to change the current item from application code; this 1253166124Srafan is useful if you want to write your own navigation requests. It is 1254166124Srafan also possible to explicitly set the top row of the menu display. See 1255166124Srafan mitem_current(3x). If your application needs to change the menu 1256166124Srafan subwindow cursor for any reason, pos_menu_cursor() will restore it to 125776726Speter the correct location for continuing menu driver processing. 1258166124Srafan 1259166124Srafan It is possible to set hooks to be called at menu initialization and 1260166124Srafan wrapup time, and whenever the selected item changes. See 126176726Speter menu_hook(3x). 1262166124Srafan 1263166124Srafan Each item, and each menu, has an associated user pointer on which you 126476726Speter can hang application data. See mitem_userptr(3x) and menu_userptr(3x). 1265166124Srafan 126676726Speter The Forms Library 1267166124Srafan 1268166124Srafan The form library is a curses extension that supports easy programming 126976726Speter of on-screen forms for data entry and program control. 1270166124Srafan 1271166124Srafan The form library first appeared in AT&T System V. The version 127276726Speter documented here is the form code distributed with ncurses. 1273166124Srafan 127476726SpeterCompiling With the form Library 127576726Speter 127676726Speter Your form-using modules must import the form library declarations with 127776726Speter #include <form.h> 127876726Speter 1279166124Srafan and must be linked explicitly with the forms library using an -lform 1280166124Srafan argument. Note that they must also link the ncurses library with 128176726Speter -lncurses. Many linkers are two-pass and will accept either order, but 128276726Speter it is still good practice to put -lform first and -lncurses second. 1283166124Srafan 128476726SpeterOverview of Forms 128576726Speter 1286166124Srafan A form is a collection of fields; each field may be either a label 1287166124Srafan (explanatory text) or a data-entry location. Long forms may be 128876726Speter segmented into pages; each entry to a new page clears the screen. 1289166124Srafan 1290166124Srafan To make forms, you create groups of fields and connect them with form 129176726Speter frame objects; the form library makes this relatively simple. 1292166124Srafan 1293166124Srafan Once defined, a form can be posted, that is written to an associated 1294166124Srafan window. Actually, each form has two associated windows; a containing 1295166124Srafan window in which the programmer can scribble titles or borders, and a 129676726Speter subwindow in which the form fields proper are displayed. 1297166124Srafan 1298166124Srafan As the form user fills out the posted form, navigation and editing 1299166124Srafan keys support movement between fields, editing keys support modifying 1300166124Srafan field, and plain text adds to or changes data in a current field. The 1301166124Srafan form library allows you (the forms designer) to bind each navigation 1302166124Srafan and editing key to any keystroke accepted by curses Fields may have 1303166124Srafan validation conditions on them, so that they check input data for type 1304166124Srafan and value. The form library supplies a rich set of pre-defined field 130576726Speter types, and makes it relatively easy to define new ones. 1306166124Srafan 130776726Speter Once its transaction is completed (or aborted), a form may be unposted 1308166124Srafan (that is, undisplayed), and finally freed to make the storage 130976726Speter associated with it and its items available for re-use. 1310166124Srafan 131176726Speter The general flow of control of a form program looks like this: 131276726Speter 1. Initialize curses. 131376726Speter 2. Create the form fields, using new_field(). 131476726Speter 3. Create the form using new_form(). 1315166124Srafan 4. Post the form using post_form(). 131676726Speter 5. Refresh the screen. 131776726Speter 6. Process user requests via an input loop. 1318166124Srafan 7. Unpost the form using unpost_form(). 131976726Speter 8. Free the form, using free_form(). 132076726Speter 9. Free the fields using free_field(). 132176726Speter 10. Terminate curses. 1322166124Srafan 1323166124Srafan Note that this looks much like a menu program; the form library 1324166124Srafan handles tasks which are in many ways similar, and its interface was 1325166124Srafan obviously designed to resemble that of the menu library wherever 132676726Speter possible. 1327166124Srafan 1328166124Srafan In forms programs, however, the `process user requests' is somewhat 1329166124Srafan more complicated than for menus. Besides menu-like navigation 133076726Speter operations, the menu driver loop has to support field editing and data 133176726Speter validation. 1332166124Srafan 133376726SpeterCreating and Freeing Fields and Forms 133476726Speter 133576726Speter The basic function for creating fields is new_field(): 133676726SpeterFIELD *new_field(int height, int width, /* new field size */ 133776726Speter int top, int left, /* upper left corner */ 133876726Speter int offscreen, /* number of offscreen rows */ 133976726Speter int nbuf); /* number of working buffers */ 134076726Speter 1341166124Srafan Menu items always occupy a single row, but forms fields may have 1342166124Srafan multiple rows. So new_field() requires you to specify a width and 1343166124Srafan height (the first two arguments, which mist both be greater than 134476726Speter zero). 1345166124Srafan 134676726Speter You must also specify the location of the field's upper left corner on 1347166124Srafan the screen (the third and fourth arguments, which must be zero or 1348166124Srafan greater). Note that these coordinates are relative to the form 1349166124Srafan subwindow, which will coincide with stdscr by default but need not be 1350166124Srafan stdscr if you've done an explicit set_form_win() call. 1351166124Srafan 1352166124Srafan The fifth argument allows you to specify a number of off-screen rows. 1353166124Srafan If this is zero, the entire field will always be displayed. If it is 1354166124Srafan nonzero, the form will be scrollable, with only one screen-full 1355166124Srafan (initially the top part) displayed at any given time. If you make a 1356166124Srafan field dynamic and grow it so it will no longer fit on the screen, the 1357166124Srafan form will become scrollable even if the offscreen argument was 135876726Speter initially zero. 1359166124Srafan 1360166124Srafan The forms library allocates one working buffer per field; the size of 136176726Speter each buffer is ((height + offscreen)*width + 1, one character for each 136276726Speter position in the field plus a NUL terminator. The sixth argument is the 1363166124Srafan number of additional data buffers to allocate for the field; your 136476726Speter application can use them for its own purposes. 136576726SpeterFIELD *dup_field(FIELD *field, /* field to copy */ 136676726Speter int top, int left); /* location of new copy */ 136776726Speter 1368166124Srafan The function dup_field() duplicates an existing field at a new 1369166124Srafan location. Size and buffering information are copied; some attribute 1370166124Srafan flags and status bits are not (see the form_field_new(3X) for 137176726Speter details). 137276726SpeterFIELD *link_field(FIELD *field, /* field to copy */ 137376726Speter int top, int left); /* location of new copy */ 137476726Speter 1375166124Srafan The function link_field() also duplicates an existing field at a new 1376166124Srafan location. The difference from dup_field() is that it arranges for the 137776726Speter new field's buffer to be shared with the old one. 1378166124Srafan 1379166124Srafan Besides the obvious use in making a field editable from two different 138076726Speter form pages, linked fields give you a way to hack in dynamic labels. If 1381166124Srafan you declare several fields linked to an original, and then make them 1382166124Srafan inactive, changes from the original will still be propagated to the 138376726Speter linked fields. 1384166124Srafan 1385166124Srafan As with duplicated fields, linked fields have attribute bits separate 138676726Speter from the original. 1387166124Srafan 1388166124Srafan As you might guess, all these field-allocations return NULL if the 1389166124Srafan field allocation is not possible due to an out-of-memory error or 139076726Speter out-of-bounds arguments. 1391166124Srafan 139276726Speter To connect fields to a form, use 139376726SpeterFORM *new_form(FIELD **fields); 139476726Speter 1395166124Srafan This function expects to see a NULL-terminated array of field 1396166124Srafan pointers. Said fields are connected to a newly-allocated form object; 139776726Speter its address is returned (or else NULL if the allocation fails). 1398166124Srafan 1399166124Srafan Note that new_field() does not copy the pointer array into private 1400166124Srafan storage; if you modify the contents of the pointer array during forms 1401166124Srafan processing, all manner of bizarre things might happen. Also note that 140276726Speter any given field may only be connected to one form. 1403166124Srafan 1404166124Srafan The functions free_field() and free_form are available to free field 1405166124Srafan and form objects. It is an error to attempt to free a field connected 140676726Speter to a form, but not vice-versa; thus, you will generally free your form 140776726Speter objects first. 1408166124Srafan 140976726SpeterFetching and Changing Field Attributes 141076726Speter 1411166124Srafan Each form field has a number of location and size attributes 1412166124Srafan associated with it. There are other field attributes used to control 141376726Speter display and editing of the field. Some (for example, the O_STATIC bit) 1414166124Srafan involve sufficient complications to be covered in sections of their 141576726Speter own later on. We cover the functions used to get and set several basic 141676726Speter attributes here. 1417166124Srafan 141876726Speter When a field is created, the attributes not specified by the new_field 1419166124Srafan function are copied from an invisible system default field. In 1420166124Srafan attribute-setting and -fetching functions, the argument NULL is taken 142176726Speter to mean this field. Changes to it persist as defaults until your forms 142276726Speter application terminates. 1423166124Srafan 142476726Speter Fetching Size and Location Data 1425166124Srafan 142676726Speter You can retrieve field sizes and locations through: 142776726Speterint field_info(FIELD *field, /* field from which to fetch */ 142876726Speter int *height, *int width, /* field size */ 142976726Speter int *top, int *left, /* upper left corner */ 143076726Speter int *offscreen, /* number of offscreen rows */ 143176726Speter int *nbuf); /* number of working buffers */ 143276726Speter 1433166124Srafan This function is a sort of inverse of new_field(); instead of setting 1434166124Srafan size and location attributes of a new field, it fetches them from an 143576726Speter existing one. 1436166124Srafan 143776726Speter Changing the Field Location 1438166124Srafan 143976726Speter It is possible to move a field's location on the screen: 144076726Speterint move_field(FIELD *field, /* field to alter */ 144176726Speter int top, int left); /* new upper-left corner */ 144276726Speter 144376726Speter You can, of course. query the current location through field_info(). 1444166124Srafan 144576726Speter The Justification Attribute 1446166124Srafan 1447166124Srafan One-line fields may be unjustified, justified right, justified left, 144876726Speter or centered. Here is how you manipulate this attribute: 144976726Speterint set_field_just(FIELD *field, /* field to alter */ 145076726Speter int justmode); /* mode to set */ 145176726Speter 145276726Speterint field_just(FIELD *field); /* fetch mode of field */ 145376726Speter 1454166124Srafan The mode values accepted and returned by this functions are 1455166124Srafan preprocessor macros NO_JUSTIFICATION, JUSTIFY_RIGHT, JUSTIFY_LEFT, or 145676726Speter JUSTIFY_CENTER. 1457166124Srafan 145876726Speter Field Display Attributes 1459166124Srafan 1460166124Srafan For each field, you can set a foreground attribute for entered 1461166124Srafan characters, a background attribute for the entire field, and a pad 1462166124Srafan character for the unfilled portion of the field. You can also control 146376726Speter pagination of the form. 1464166124Srafan 1465166124Srafan This group of four field attributes controls the visual appearance of 1466166124Srafan the field on the screen, without affecting in any way the data in the 146776726Speter field buffer. 146876726Speterint set_field_fore(FIELD *field, /* field to alter */ 146976726Speter chtype attr); /* attribute to set */ 147076726Speter 147176726Speterchtype field_fore(FIELD *field); /* field to query */ 147276726Speter 147376726Speterint set_field_back(FIELD *field, /* field to alter */ 147476726Speter chtype attr); /* attribute to set */ 147576726Speter 147676726Speterchtype field_back(FIELD *field); /* field to query */ 147776726Speter 147876726Speterint set_field_pad(FIELD *field, /* field to alter */ 147976726Speter int pad); /* pad character to set */ 148076726Speter 148176726Speterchtype field_pad(FIELD *field); 148276726Speter 148376726Speterint set_new_page(FIELD *field, /* field to alter */ 148476726Speter int flag); /* TRUE to force new page */ 148576726Speter 148676726Speterchtype new_page(FIELD *field); /* field to query */ 148776726Speter 148876726Speter The attributes set and returned by the first four functions are normal 1489166124Srafan curses(3x) display attribute values (A_STANDOUT, A_BOLD, A_REVERSE 1490166124Srafan etc). The page bit of a field controls whether it is displayed at the 149176726Speter start of a new form screen. 1492166124Srafan 149376726Speter Field Option Bits 1494166124Srafan 1495166124Srafan There is also a large collection of field option bits you can set to 1496166124Srafan control various aspects of forms processing. You can manipulate them 149776726Speter with these functions: 149876726Speterint set_field_opts(FIELD *field, /* field to alter */ 149976726Speter int attr); /* attribute to set */ 150076726Speter 150176726Speterint field_opts_on(FIELD *field, /* field to alter */ 150276726Speter int attr); /* attributes to turn on */ 150376726Speter 150476726Speterint field_opts_off(FIELD *field, /* field to alter */ 150576726Speter int attr); /* attributes to turn off */ 150676726Speter 150776726Speterint field_opts(FIELD *field); /* field to query */ 150876726Speter 150976726Speter By default, all options are on. Here are the available option bits: 1510166124Srafan 151176726Speter O_VISIBLE 1512166124Srafan Controls whether the field is visible on the screen. Can be 1513166124Srafan used during form processing to hide or pop up fields depending 151476726Speter on the value of parent fields. 1515166124Srafan 151676726Speter O_ACTIVE 1517166124Srafan Controls whether the field is active during forms processing 1518166124Srafan (i.e. visited by form navigation keys). Can be used to make 1519166124Srafan labels or derived fields with buffer values alterable by the 152076726Speter forms application, not the user. 1521166124Srafan 152276726Speter O_PUBLIC 1523166124Srafan Controls whether data is displayed during field entry. If this 1524166124Srafan option is turned off on a field, the library will accept and 1525166124Srafan edit data in that field, but it will not be displayed and the 1526166124Srafan visible field cursor will not move. You can turn off the 152776726Speter O_PUBLIC bit to define password fields. 1528166124Srafan 152976726Speter O_EDIT 1530166124Srafan Controls whether the field's data can be modified. When this 1531166124Srafan option is off, all editing requests except REQ_PREV_CHOICE and 1532166124Srafan REQ_NEXT_CHOICE will fail. Such read-only fields may be useful 153376726Speter for help messages. 1534166124Srafan 153576726Speter O_WRAP 153676726Speter Controls word-wrapping in multi-line fields. Normally, when any 1537166124Srafan character of a (blank-separated) word reaches the end of the 1538166124Srafan current line, the entire word is wrapped to the next line 153976726Speter (assuming there is one). When this option is off, the word will 154076726Speter be split across the line break. 1541166124Srafan 154276726Speter O_BLANK 1543166124Srafan Controls field blanking. When this option is on, entering a 1544166124Srafan character at the first field position erases the entire field 154576726Speter (except for the just-entered character). 1546166124Srafan 154776726Speter O_AUTOSKIP 1548166124Srafan Controls automatic skip to next field when this one fills. 1549166124Srafan Normally, when the forms user tries to type more data into a 1550166124Srafan field than will fit, the editing location jumps to next field. 155176726Speter When this option is off, the user's cursor will hang at the end 1552166124Srafan of the field. This option is ignored in dynamic fields that 155376726Speter have not reached their size limit. 1554166124Srafan 155576726Speter O_NULLOK 1556166124Srafan Controls whether validation is applied to blank fields. 1557166124Srafan Normally, it is not; the user can leave a field blank without 1558166124Srafan invoking the usual validation check on exit. If this option is 155976726Speter off on a field, exit from it will invoke a validation check. 1560166124Srafan 156176726Speter O_PASSOK 156276726Speter Controls whether validation occurs on every exit, or only after 1563166124Srafan the field is modified. Normally the latter is true. Setting 1564166124Srafan O_PASSOK may be useful if your field's validation function may 156576726Speter change during forms processing. 1566166124Srafan 156776726Speter O_STATIC 1568166124Srafan Controls whether the field is fixed to its initial dimensions. 1569166124Srafan If you turn this off, the field becomes dynamic and will 157076726Speter stretch to fit entered data. 1571166124Srafan 1572166124Srafan A field's options cannot be changed while the field is currently 1573166124Srafan selected. However, options may be changed on posted fields that are 157476726Speter not current. 1575166124Srafan 157676726Speter The option values are bit-masks and can be composed with logical-or in 157776726Speter the obvious way. 1578166124Srafan 157976726SpeterField Status 158076726Speter 158176726Speter Every field has a status flag, which is set to FALSE when the field is 1582166124Srafan created and TRUE when the value in field buffer 0 changes. This flag 158376726Speter can be queried and set directly: 158476726Speterint set_field_status(FIELD *field, /* field to alter */ 158576726Speter int status); /* mode to set */ 158676726Speter 158776726Speterint field_status(FIELD *field); /* fetch mode of field */ 158876726Speter 1589166124Srafan Setting this flag under program control can be useful if you use the 159076726Speter same form repeatedly, looking for modified fields each time. 1591166124Srafan 1592166124Srafan Calling field_status() on a field not currently selected for input 159376726Speter will return a correct value. Calling field_status() on a field that is 1594166124Srafan currently selected for input may not necessarily give a correct field 1595166124Srafan status value, because entered data isn't necessarily copied to buffer 1596166124Srafan zero before the exit validation check. To guarantee that the returned 1597166124Srafan status value reflects reality, call field_status() either (1) in the 1598166124Srafan field's exit validation check routine, (2) from the field's or form's 1599166124Srafan initialization or termination hooks, or (3) just after a 160076726Speter REQ_VALIDATION request has been processed by the forms driver. 1601166124Srafan 160276726SpeterField User Pointer 160376726Speter 1604166124Srafan Each field structure contains one character pointer slot that is not 1605166124Srafan used by the forms library. It is intended to be used by applications 160676726Speter to store private per-field data. You can manipulate it with: 160776726Speterint set_field_userptr(FIELD *field, /* field to alter */ 160876726Speter char *userptr); /* mode to set */ 160976726Speter 161076726Speterchar *field_userptr(FIELD *field); /* fetch mode of field */ 161176726Speter 1612166124Srafan (Properly, this user pointer field ought to have (void *) type. The 161376726Speter (char *) type is retained for System V compatibility.) 1614166124Srafan 1615166124Srafan It is valid to set the user pointer of the default field (with a 1616166124Srafan set_field_userptr() call passed a NULL field pointer.) When a new 1617166124Srafan field is created, the default-field user pointer is copied to 161876726Speter initialize the new field's user pointer. 1619166124Srafan 162076726SpeterVariable-Sized Fields 162176726Speter 1622166124Srafan Normally, a field is fixed at the size specified for it at creation 1623166124Srafan time. If, however, you turn off its O_STATIC bit, it becomes dynamic 1624166124Srafan and will automatically resize itself to accommodate data as it is 1625166124Srafan entered. If the field has extra buffers associated with it, they will 162676726Speter grow right along with the main input buffer. 1627166124Srafan 1628166124Srafan A one-line dynamic field will have a fixed height (1) but variable 162976726Speter width, scrolling horizontally to display data within the field area as 1630166124Srafan originally dimensioned and located. A multi-line dynamic field will 1631166124Srafan have a fixed width, but variable height (number of rows), scrolling 1632166124Srafan vertically to display data within the field area as originally 163376726Speter dimensioned and located. 1634166124Srafan 1635166124Srafan Normally, a dynamic field is allowed to grow without limit. But it is 1636166124Srafan possible to set an upper limit on the size of a dynamic field. You do 163776726Speter it with this function: 163876726Speterint set_max_field(FIELD *field, /* field to alter (may not be NULL) */ 163976726Speter int max_size); /* upper limit on field size */ 164076726Speter 164176726Speter If the field is one-line, max_size is taken to be a column size limit; 1642166124Srafan if it is multi-line, it is taken to be a line size limit. To disable 1643166124Srafan any limit, use an argument of zero. The growth limit can be changed 164476726Speter whether or not the O_STATIC bit is on, but has no effect until it is. 1645166124Srafan 164676726Speter The following properties of a field change when it becomes dynamic: 1647166124Srafan * If there is no growth limit, there is no final position of the 164876726Speter field; therefore O_AUTOSKIP and O_NL_OVERLOAD are ignored. 164976726Speter * Field justification will be ignored (though whatever justification 165076726Speter is set up will be retained internally and can be queried). 1651166124Srafan * The dup_field() and link_field() calls copy dynamic-buffer sizes. 1652166124Srafan If the O_STATIC option is set on one of a collection of links, 1653166124Srafan buffer resizing will occur only when the field is edited through 165476726Speter that link. 1655166124Srafan * The call field_info() will retrieve the original static size of 1656166124Srafan the field; use dynamic_field_info() to get the actual dynamic 165776726Speter size. 1658166124Srafan 165976726SpeterField Validation 166076726Speter 1661166124Srafan By default, a field will accept any data that will fit in its input 1662166124Srafan buffer. However, it is possible to attach a validation type to a 1663166124Srafan field. If you do this, any attempt to leave the field while it 1664166124Srafan contains data that doesn't match the validation type will fail. Some 1665166124Srafan validation types also have a character-validity check for each time a 166676726Speter character is entered in the field. 1667166124Srafan 1668166124Srafan A field's validation check (if any) is not called when 1669166124Srafan set_field_buffer() modifies the input buffer, nor when that buffer is 167076726Speter changed through a linked field. 1671166124Srafan 1672166124Srafan The form library provides a rich set of pre-defined validation types, 1673166124Srafan and gives you the capability to define custom ones of your own. You 1674166124Srafan can examine and change field validation attributes with the following 167576726Speter functions: 167676726Speterint set_field_type(FIELD *field, /* field to alter */ 167776726Speter FIELDTYPE *ftype, /* type to associate */ 167876726Speter ...); /* additional arguments*/ 167976726Speter 168076726SpeterFIELDTYPE *field_type(FIELD *field); /* field to query */ 168176726Speter 1682166124Srafan The validation type of a field is considered an attribute of the 1683166124Srafan field. As with other field attributes, Also, doing set_field_type() 1684166124Srafan with a NULL field default will change the system default for 168576726Speter validation of newly-created fields. 1686166124Srafan 168776726Speter Here are the pre-defined validation types: 1688166124Srafan 168976726Speter TYPE_ALPHA 1690166124Srafan 1691166124Srafan This field type accepts alphabetic data; no blanks, no digits, no 1692166124Srafan special characters (this is checked at character-entry time). It is 169376726Speter set up with: 169476726Speterint set_field_type(FIELD *field, /* field to alter */ 169576726Speter TYPE_ALPHA, /* type to associate */ 169676726Speter int width); /* maximum width of field */ 169776726Speter 169876726Speter The width argument sets a minimum width of data. Typically you'll want 1699166124Srafan to set this to the field width; if it's greater than the field width, 1700166124Srafan the validation check will always fail. A minimum width of zero makes 170176726Speter field completion optional. 1702166124Srafan 170376726Speter TYPE_ALNUM 1704166124Srafan 1705166124Srafan This field type accepts alphabetic data and digits; no blanks, no 1706166124Srafan special characters (this is checked at character-entry time). It is 170776726Speter set up with: 170876726Speterint set_field_type(FIELD *field, /* field to alter */ 170976726Speter TYPE_ALNUM, /* type to associate */ 171076726Speter int width); /* maximum width of field */ 171176726Speter 1712166124Srafan The width argument sets a minimum width of data. As with TYPE_ALPHA, 1713166124Srafan typically you'll want to set this to the field width; if it's greater 171476726Speter than the field width, the validation check will always fail. A minimum 171576726Speter width of zero makes field completion optional. 1716166124Srafan 171776726Speter TYPE_ENUM 1718166124Srafan 1719166124Srafan This type allows you to restrict a field's values to be among a 1720166124Srafan specified set of string values (for example, the two-letter postal 172176726Speter codes for U.S. states). It is set up with: 172276726Speterint set_field_type(FIELD *field, /* field to alter */ 172376726Speter TYPE_ENUM, /* type to associate */ 172476726Speter char **valuelist; /* list of possible values */ 172576726Speter int checkcase; /* case-sensitive? */ 172676726Speter int checkunique); /* must specify uniquely? */ 172776726Speter 1728166124Srafan The valuelist parameter must point at a NULL-terminated list of valid 1729166124Srafan strings. The checkcase argument, if true, makes comparison with the 173076726Speter string case-sensitive. 1731166124Srafan 1732166124Srafan When the user exits a TYPE_ENUM field, the validation procedure tries 1733166124Srafan to complete the data in the buffer to a valid entry. If a complete 1734166124Srafan choice string has been entered, it is of course valid. But it is also 173576726Speter possible to enter a prefix of a valid string and have it completed for 173676726Speter you. 1737166124Srafan 1738166124Srafan By default, if you enter such a prefix and it matches more than one 1739166124Srafan value in the string list, the prefix will be completed to the first 174076726Speter matching value. But the checkunique argument, if true, requires prefix 174176726Speter matches to be unique in order to be valid. 1742166124Srafan 1743166124Srafan The REQ_NEXT_CHOICE and REQ_PREV_CHOICE input requests can be 174476726Speter particularly useful with these fields. 1745166124Srafan 174676726Speter TYPE_INTEGER 1747166124Srafan 174876726Speter This field type accepts an integer. It is set up as follows: 174976726Speterint set_field_type(FIELD *field, /* field to alter */ 175076726Speter TYPE_INTEGER, /* type to associate */ 175176726Speter int padding, /* # places to zero-pad to */ 175276726Speter int vmin, int vmax); /* valid range */ 175376726Speter 1754166124Srafan Valid characters consist of an optional leading minus and digits. The 175576726Speter range check is performed on exit. If the range maximum is less than or 175676726Speter equal to the minimum, the range is ignored. 1757166124Srafan 175876726Speter If the value passes its range check, it is padded with as many leading 175976726Speter zero digits as necessary to meet the padding argument. 1760166124Srafan 176176726Speter A TYPE_INTEGER value buffer can conveniently be interpreted with the C 176276726Speter library function atoi(3). 1763166124Srafan 176476726Speter TYPE_NUMERIC 1765166124Srafan 176676726Speter This field type accepts a decimal number. It is set up as follows: 176776726Speterint set_field_type(FIELD *field, /* field to alter */ 176876726Speter TYPE_NUMERIC, /* type to associate */ 176976726Speter int padding, /* # places of precision */ 177076726Speter double vmin, double vmax); /* valid range */ 177176726Speter 1772166124Srafan Valid characters consist of an optional leading minus and digits. 1773166124Srafan possibly including a decimal point. If your system supports locale's, 1774166124Srafan the decimal point character used must be the one defined by your 1775166124Srafan locale. The range check is performed on exit. If the range maximum is 177676726Speter less than or equal to the minimum, the range is ignored. 1777166124Srafan 1778166124Srafan If the value passes its range check, it is padded with as many 177976726Speter trailing zero digits as necessary to meet the padding argument. 1780166124Srafan 178176726Speter A TYPE_NUMERIC value buffer can conveniently be interpreted with the C 178276726Speter library function atof(3). 1783166124Srafan 178476726Speter TYPE_REGEXP 1785166124Srafan 1786166124Srafan This field type accepts data matching a regular expression. It is set 178776726Speter up as follows: 178876726Speterint set_field_type(FIELD *field, /* field to alter */ 178976726Speter TYPE_REGEXP, /* type to associate */ 179076726Speter char *regexp); /* expression to match */ 179176726Speter 1792166124Srafan The syntax for regular expressions is that of regcomp(3). The check 179376726Speter for regular-expression match is performed on exit. 1794166124Srafan 179576726SpeterDirect Field Buffer Manipulation 179676726Speter 179776726Speter The chief attribute of a field is its buffer contents. When a form has 1798166124Srafan been completed, your application usually needs to know the state of 179976726Speter each field buffer. You can find this out with: 180076726Speterchar *field_buffer(FIELD *field, /* field to query */ 180176726Speter int bufindex); /* number of buffer to query */ 180276726Speter 1803166124Srafan Normally, the state of the zero-numbered buffer for each field is set 1804166124Srafan by the user's editing actions on that field. It's sometimes useful to 1805166124Srafan be able to set the value of the zero-numbered (or some other) buffer 180676726Speter from your application: 180776726Speterint set_field_buffer(FIELD *field, /* field to alter */ 180876726Speter int bufindex, /* number of buffer to alter */ 180976726Speter char *value); /* string value to set */ 181076726Speter 1811166124Srafan If the field is not large enough and cannot be resized to a 181276726Speter sufficiently large size to contain the specified value, the value will 181376726Speter be truncated to fit. 1814166124Srafan 1815166124Srafan Calling field_buffer() with a null field pointer will raise an error. 1816166124Srafan Calling field_buffer() on a field not currently selected for input 181776726Speter will return a correct value. Calling field_buffer() on a field that is 1818166124Srafan currently selected for input may not necessarily give a correct field 1819166124Srafan buffer value, because entered data isn't necessarily copied to buffer 1820166124Srafan zero before the exit validation check. To guarantee that the returned 1821166124Srafan buffer value reflects on-screen reality, call field_buffer() either 182276726Speter (1) in the field's exit validation check routine, (2) from the field's 1823166124Srafan or form's initialization or termination hooks, or (3) just after a 182476726Speter REQ_VALIDATION request has been processed by the forms driver. 1825166124Srafan 182676726SpeterAttributes of Forms 182776726Speter 1828166124Srafan As with field attributes, form attributes inherit a default from a 182976726Speter system default form structure. These defaults can be queried or set by 183076726Speter of these functions using a form-pointer argument of NULL. 1831166124Srafan 183276726Speter The principal attribute of a form is its field list. You can query and 183376726Speter change this list with: 183476726Speterint set_form_fields(FORM *form, /* form to alter */ 183576726Speter FIELD **fields); /* fields to connect */ 183676726Speter 183776726Speterchar *form_fields(FORM *form); /* fetch fields of form */ 183876726Speter 183976726Speterint field_count(FORM *form); /* count connect fields */ 184076726Speter 1841166124Srafan The second argument of set_form_fields() may be a NULL-terminated 184276726Speter field pointer array like the one required by new_form(). In that case, 1843166124Srafan the old fields of the form are disconnected but not freed (and 1844166124Srafan eligible to be connected to other forms), then the new fields are 184576726Speter connected. 1846166124Srafan 1847166124Srafan It may also be null, in which case the old fields are disconnected 184876726Speter (and not freed) but no new ones are connected. 1849166124Srafan 1850166124Srafan The field_count() function simply counts the number of fields 1851166124Srafan connected to a given from. It returns -1 if the form-pointer argument 185276726Speter is NULL. 1853166124Srafan 185476726SpeterControl of Form Display 185576726Speter 1856166124Srafan In the overview section, you saw that to display a form you normally 1857166124Srafan start by defining its size (and fields), posting it, and refreshing 1858166124Srafan the screen. There is an hidden step before posting, which is the 1859166124Srafan association of the form with a frame window (actually, a pair of 1860166124Srafan windows) within which it will be displayed. By default, the forms 186176726Speter library associates every form with the full-screen window stdscr. 1862166124Srafan 186376726Speter By making this step explicit, you can associate a form with a declared 186476726Speter frame window on your screen display. This can be useful if you want to 1865166124Srafan adapt the form display to different screen sizes, dynamically tile 1866166124Srafan forms on the screen, or use a form as part of an interface layout 186776726Speter managed by panels. 1868166124Srafan 1869166124Srafan The two windows associated with each form have the same functions as 1870166124Srafan their analogues in the menu library. Both these windows are painted 187176726Speter when the form is posted and erased when the form is unposted. 1872166124Srafan 1873166124Srafan The outer or frame window is not otherwise touched by the form 187476726Speter routines. It exists so the programmer can associate a title, a border, 1875166124Srafan or perhaps help text with the form and have it properly refreshed or 187676726Speter erased at post/unpost time. The inner window or subwindow is where the 187776726Speter current form page is actually displayed. 1878166124Srafan 1879166124Srafan In order to declare your own frame window for a form, you'll need to 1880166124Srafan know the size of the form's bounding rectangle. You can get this 188176726Speter information with: 188276726Speterint scale_form(FORM *form, /* form to query */ 188376726Speter int *rows, /* form rows */ 188476726Speter int *cols); /* form cols */ 188576726Speter 188676726Speter The form dimensions are passed back in the locations pointed to by the 1887166124Srafan arguments. Once you have this information, you can use it to declare 188876726Speter of windows, then use one of these functions: 188976726Speterint set_form_win(FORM *form, /* form to alter */ 189076726Speter WINDOW *win); /* frame window to connect */ 189176726Speter 189276726SpeterWINDOW *form_win(FORM *form); /* fetch frame window of form */ 189376726Speter 189476726Speterint set_form_sub(FORM *form, /* form to alter */ 189576726Speter WINDOW *win); /* form subwindow to connect */ 189676726Speter 189776726SpeterWINDOW *form_sub(FORM *form); /* fetch form subwindow of form */ 189876726Speter 1899166124Srafan Note that curses operations, including refresh(), on the form, should 190076726Speter be done on the frame window, not the form subwindow. 1901166124Srafan 1902166124Srafan It is possible to check from your application whether all of a 1903166124Srafan scrollable field is actually displayed within the menu subwindow. Use 190476726Speter these functions: 190576726Speterint data_ahead(FORM *form); /* form to be queried */ 190676726Speter 190776726Speterint data_behind(FORM *form); /* form to be queried */ 190876726Speter 1909166124Srafan The function data_ahead() returns TRUE if (a) the current field is 1910166124Srafan one-line and has undisplayed data off to the right, (b) the current 191176726Speter field is multi-line and there is data off-screen below it. 1912166124Srafan 191376726Speter The function data_behind() returns TRUE if the first (upper left hand) 191476726Speter character position is off-screen (not being displayed). 1915166124Srafan 1916166124Srafan Finally, there is a function to restore the form window's cursor to 191776726Speter the value expected by the forms driver: 191876726Speterint pos_form_cursor(FORM *) /* form to be queried */ 191976726Speter 192076726Speter If your application changes the form window cursor, call this function 1921166124Srafan before handing control back to the forms driver in order to 192276726Speter re-synchronize it. 1923166124Srafan 192476726SpeterInput Processing in the Forms Driver 192576726Speter 192676726Speter The function form_driver() handles virtualized input requests for form 192776726Speter navigation, editing, and validation requests, just as menu_driver does 192876726Speter for menus (see the section on menu input handling). 192976726Speterint form_driver(FORM *form, /* form to pass input to */ 193076726Speter int request); /* form request code */ 193176726Speter 1932166124Srafan Your input virtualization function needs to take input and then 1933166124Srafan convert it to either an alphanumeric character (which is treated as 1934166124Srafan data to be entered in the currently-selected field), or a forms 193576726Speter processing request. 1936166124Srafan 1937166124Srafan The forms driver provides hooks (through input-validation and 1938166124Srafan field-termination functions) with which your application code can 193976726Speter check that the input taken by the driver matched what was expected. 1940166124Srafan 194176726Speter Page Navigation Requests 1942166124Srafan 1943166124Srafan These requests cause page-level moves through the form, triggering 194476726Speter display of a new form screen. 1945166124Srafan 194676726Speter REQ_NEXT_PAGE 194776726Speter Move to the next form page. 1948166124Srafan 194976726Speter REQ_PREV_PAGE 195076726Speter Move to the previous form page. 1951166124Srafan 195276726Speter REQ_FIRST_PAGE 195376726Speter Move to the first form page. 1954166124Srafan 195576726Speter REQ_LAST_PAGE 195676726Speter Move to the last form page. 1957166124Srafan 1958166124Srafan These requests treat the list as cyclic; that is, REQ_NEXT_PAGE from 195976726Speter the last page goes to the first, and REQ_PREV_PAGE from the first page 196076726Speter goes to the last. 1961166124Srafan 196276726Speter Inter-Field Navigation Requests 1963166124Srafan 196476726Speter These requests handle navigation between fields on the same page. 1965166124Srafan 196676726Speter REQ_NEXT_FIELD 196776726Speter Move to next field. 1968166124Srafan 196976726Speter REQ_PREV_FIELD 197076726Speter Move to previous field. 1971166124Srafan 197276726Speter REQ_FIRST_FIELD 197376726Speter Move to the first field. 1974166124Srafan 197576726Speter REQ_LAST_FIELD 197676726Speter Move to the last field. 1977166124Srafan 197876726Speter REQ_SNEXT_FIELD 197976726Speter Move to sorted next field. 1980166124Srafan 198176726Speter REQ_SPREV_FIELD 198276726Speter Move to sorted previous field. 1983166124Srafan 198476726Speter REQ_SFIRST_FIELD 198576726Speter Move to the sorted first field. 1986166124Srafan 198776726Speter REQ_SLAST_FIELD 198876726Speter Move to the sorted last field. 1989166124Srafan 199076726Speter REQ_LEFT_FIELD 199176726Speter Move left to field. 1992166124Srafan 199376726Speter REQ_RIGHT_FIELD 199476726Speter Move right to field. 1995166124Srafan 199676726Speter REQ_UP_FIELD 199776726Speter Move up to field. 1998166124Srafan 199976726Speter REQ_DOWN_FIELD 200076726Speter Move down to field. 2001166124Srafan 2002166124Srafan These requests treat the list of fields on a page as cyclic; that is, 2003166124Srafan REQ_NEXT_FIELD from the last field goes to the first, and 200476726Speter REQ_PREV_FIELD from the first field goes to the last. The order of the 200576726Speter fields for these (and the REQ_FIRST_FIELD and REQ_LAST_FIELD requests) 200676726Speter is simply the order of the field pointers in the form array (as set up 200776726Speter by new_form() or set_form_fields() 2008166124Srafan 2009166124Srafan It is also possible to traverse the fields as if they had been sorted 2010166124Srafan in screen-position order, so the sequence goes left-to-right and 2011166124Srafan top-to-bottom. To do this, use the second group of four 201276726Speter sorted-movement requests. 2013166124Srafan 201476726Speter Finally, it is possible to move between fields using visual directions 2015166124Srafan up, down, right, and left. To accomplish this, use the third group of 201676726Speter four requests. Note, however, that the position of a form for purposes 201776726Speter of these requests is its upper-left corner. 2018166124Srafan 2019166124Srafan For example, suppose you have a multi-line field B, and two 202076726Speter single-line fields A and C on the same line with B, with A to the left 2021166124Srafan of B and C to the right of B. A REQ_MOVE_RIGHT from A will go to B 2022166124Srafan only if A, B, and C all share the same first line; otherwise it will 202376726Speter skip over B to C. 2024166124Srafan 202576726Speter Intra-Field Navigation Requests 2026166124Srafan 2027166124Srafan These requests drive movement of the edit cursor within the currently 202876726Speter selected field. 2029166124Srafan 203076726Speter REQ_NEXT_CHAR 203176726Speter Move to next character. 2032166124Srafan 203376726Speter REQ_PREV_CHAR 203476726Speter Move to previous character. 2035166124Srafan 203676726Speter REQ_NEXT_LINE 203776726Speter Move to next line. 2038166124Srafan 203976726Speter REQ_PREV_LINE 204076726Speter Move to previous line. 2041166124Srafan 204276726Speter REQ_NEXT_WORD 204376726Speter Move to next word. 2044166124Srafan 204576726Speter REQ_PREV_WORD 204676726Speter Move to previous word. 2047166124Srafan 204876726Speter REQ_BEG_FIELD 204976726Speter Move to beginning of field. 2050166124Srafan 205176726Speter REQ_END_FIELD 205276726Speter Move to end of field. 2053166124Srafan 205476726Speter REQ_BEG_LINE 205576726Speter Move to beginning of line. 2056166124Srafan 205776726Speter REQ_END_LINE 205876726Speter Move to end of line. 2059166124Srafan 206076726Speter REQ_LEFT_CHAR 206176726Speter Move left in field. 2062166124Srafan 206376726Speter REQ_RIGHT_CHAR 206476726Speter Move right in field. 2065166124Srafan 206676726Speter REQ_UP_CHAR 206776726Speter Move up in field. 2068166124Srafan 206976726Speter REQ_DOWN_CHAR 207076726Speter Move down in field. 2071166124Srafan 2072166124Srafan Each word is separated from the previous and next characters by 207376726Speter whitespace. The commands to move to beginning and end of line or field 207476726Speter look for the first or last non-pad character in their ranges. 2075166124Srafan 207676726Speter Scrolling Requests 2077166124Srafan 2078166124Srafan Fields that are dynamic and have grown and fields explicitly created 2079166124Srafan with offscreen rows are scrollable. One-line fields scroll 2080166124Srafan horizontally; multi-line fields scroll vertically. Most scrolling is 208176726Speter triggered by editing and intra-field movement (the library scrolls the 2082166124Srafan field to keep the cursor visible). It is possible to explicitly 208376726Speter request scrolling with the following requests: 2084166124Srafan 208576726Speter REQ_SCR_FLINE 208676726Speter Scroll vertically forward a line. 2087166124Srafan 208876726Speter REQ_SCR_BLINE 208976726Speter Scroll vertically backward a line. 2090166124Srafan 209176726Speter REQ_SCR_FPAGE 209276726Speter Scroll vertically forward a page. 2093166124Srafan 209476726Speter REQ_SCR_BPAGE 209576726Speter Scroll vertically backward a page. 2096166124Srafan 209776726Speter REQ_SCR_FHPAGE 209876726Speter Scroll vertically forward half a page. 2099166124Srafan 210076726Speter REQ_SCR_BHPAGE 210176726Speter Scroll vertically backward half a page. 2102166124Srafan 210376726Speter REQ_SCR_FCHAR 210476726Speter Scroll horizontally forward a character. 2105166124Srafan 210676726Speter REQ_SCR_BCHAR 210776726Speter Scroll horizontally backward a character. 2108166124Srafan 210976726Speter REQ_SCR_HFLINE 211076726Speter Scroll horizontally one field width forward. 2111166124Srafan 211276726Speter REQ_SCR_HBLINE 211376726Speter Scroll horizontally one field width backward. 2114166124Srafan 211576726Speter REQ_SCR_HFHALF 211676726Speter Scroll horizontally one half field width forward. 2117166124Srafan 211876726Speter REQ_SCR_HBHALF 211976726Speter Scroll horizontally one half field width backward. 2120166124Srafan 212176726Speter For scrolling purposes, a page of a field is the height of its visible 212276726Speter part. 2123166124Srafan 212476726Speter Editing Requests 2125166124Srafan 2126166124Srafan When you pass the forms driver an ASCII character, it is treated as a 2127166124Srafan request to add the character to the field's data buffer. Whether this 2128166124Srafan is an insertion or a replacement depends on the field's edit mode 212976726Speter (insertion is the default. 2130166124Srafan 213176726Speter The following requests support editing the field and changing the edit 213276726Speter mode: 2133166124Srafan 213476726Speter REQ_INS_MODE 213576726Speter Set insertion mode. 2136166124Srafan 213776726Speter REQ_OVL_MODE 213876726Speter Set overlay mode. 2139166124Srafan 214076726Speter REQ_NEW_LINE 214176726Speter New line request (see below for explanation). 2142166124Srafan 214376726Speter REQ_INS_CHAR 214476726Speter Insert space at character location. 2145166124Srafan 214676726Speter REQ_INS_LINE 214776726Speter Insert blank line at character location. 2148166124Srafan 214976726Speter REQ_DEL_CHAR 215076726Speter Delete character at cursor. 2151166124Srafan 215276726Speter REQ_DEL_PREV 215376726Speter Delete previous word at cursor. 2154166124Srafan 215576726Speter REQ_DEL_LINE 215676726Speter Delete line at cursor. 2157166124Srafan 215876726Speter REQ_DEL_WORD 215976726Speter Delete word at cursor. 2160166124Srafan 216176726Speter REQ_CLR_EOL 216276726Speter Clear to end of line. 2163166124Srafan 216476726Speter REQ_CLR_EOF 216576726Speter Clear to end of field. 2166166124Srafan 216776726Speter REQ_CLEAR_FIELD 216876726Speter Clear entire field. 2169166124Srafan 2170166124Srafan The behavior of the REQ_NEW_LINE and REQ_DEL_PREV requests is 2171166124Srafan complicated and partly controlled by a pair of forms options. The 2172166124Srafan special cases are triggered when the cursor is at the beginning of a 217376726Speter field, or on the last line of the field. 2174166124Srafan 217576726Speter First, we consider REQ_NEW_LINE: 2176166124Srafan 2177166124Srafan The normal behavior of REQ_NEW_LINE in insert mode is to break the 217876726Speter current line at the position of the edit cursor, inserting the portion 2179166124Srafan of the current line after the cursor as a new line following the 2180166124Srafan current and moving the cursor to the beginning of that new line (you 218176726Speter may think of this as inserting a newline in the field buffer). 2182166124Srafan 2183166124Srafan The normal behavior of REQ_NEW_LINE in overlay mode is to clear the 2184166124Srafan current line from the position of the edit cursor to end of line. The 218576726Speter cursor is then moved to the beginning of the next line. 2186166124Srafan 218776726Speter However, REQ_NEW_LINE at the beginning of a field, or on the last line 2188166124Srafan of a field, instead does a REQ_NEXT_FIELD. O_NL_OVERLOAD option is 218976726Speter off, this special action is disabled. 2190166124Srafan 219176726Speter Now, let us consider REQ_DEL_PREV: 2192166124Srafan 2193166124Srafan The normal behavior of REQ_DEL_PREV is to delete the previous 2194166124Srafan character. If insert mode is on, and the cursor is at the start of a 2195166124Srafan line, and the text on that line will fit on the previous one, it 2196166124Srafan instead appends the contents of the current line to the previous one 2197166124Srafan and deletes the current line (you may think of this as deleting a 219876726Speter newline from the field buffer). 2199166124Srafan 2200166124Srafan However, REQ_DEL_PREV at the beginning of a field is instead treated 220176726Speter as a REQ_PREV_FIELD. 2202166124Srafan 2203166124Srafan If the O_BS_OVERLOAD option is off, this special action is disabled 220476726Speter and the forms driver just returns E_REQUEST_DENIED. 2205166124Srafan 2206166124Srafan See Form Options for discussion of how to set and clear the overload 220776726Speter options. 2208166124Srafan 220976726Speter Order Requests 2210166124Srafan 221176726Speter If the type of your field is ordered, and has associated functions for 2212166124Srafan getting the next and previous values of the type from a given value, 221376726Speter there are requests that can fetch that value into the field buffer: 2214166124Srafan 221576726Speter REQ_NEXT_CHOICE 221676726Speter Place the successor value of the current value in the buffer. 2217166124Srafan 221876726Speter REQ_PREV_CHOICE 221976726Speter Place the predecessor value of the current value in the buffer. 2220166124Srafan 222176726Speter Of the built-in field types, only TYPE_ENUM has built-in successor and 2222166124Srafan predecessor functions. When you define a field type of your own (see 2223166124Srafan Custom Validation Types), you can associate our own ordering 222476726Speter functions. 2225166124Srafan 222676726Speter Application Commands 2227166124Srafan 2228166124Srafan Form requests are represented as integers above the curses value 2229166124Srafan greater than KEY_MAX and less than or equal to the constant 2230166124Srafan MAX_COMMAND. If your input-virtualization routine returns a value 223176726Speter above MAX_COMMAND, the forms driver will ignore it. 2232166124Srafan 223376726SpeterField Change Hooks 223476726Speter 2235166124Srafan It is possible to set function hooks to be executed whenever the 2236166124Srafan current field or form changes. Here are the functions that support 223776726Speter this: 223876726Spetertypedef void (*HOOK)(); /* pointer to function returning void */ 223976726Speter 224076726Speterint set_form_init(FORM *form, /* form to alter */ 224176726Speter HOOK hook); /* initialization hook */ 224276726Speter 224376726SpeterHOOK form_init(FORM *form); /* form to query */ 224476726Speter 224576726Speterint set_form_term(FORM *form, /* form to alter */ 224676726Speter HOOK hook); /* termination hook */ 224776726Speter 224876726SpeterHOOK form_term(FORM *form); /* form to query */ 224976726Speter 225076726Speterint set_field_init(FORM *form, /* form to alter */ 225176726Speter HOOK hook); /* initialization hook */ 225276726Speter 225376726SpeterHOOK field_init(FORM *form); /* form to query */ 225476726Speter 225576726Speterint set_field_term(FORM *form, /* form to alter */ 225676726Speter HOOK hook); /* termination hook */ 225776726Speter 225876726SpeterHOOK field_term(FORM *form); /* form to query */ 225976726Speter 226076726Speter These functions allow you to either set or query four different hooks. 2261166124Srafan In each of the set functions, the second argument should be the 2262166124Srafan address of a hook function. These functions differ only in the timing 226376726Speter of the hook call. 2264166124Srafan 226576726Speter form_init 2266166124Srafan This hook is called when the form is posted; also, just after 226776726Speter each page change operation. 2268166124Srafan 226976726Speter field_init 2270166124Srafan This hook is called when the form is posted; also, just after 227176726Speter each field change 2272166124Srafan 227376726Speter field_term 2274166124Srafan This hook is called just after field validation; that is, just 227576726Speter before the field is altered. It is also called when the form is 227676726Speter unposted. 2277166124Srafan 227876726Speter form_term 2279166124Srafan This hook is called when the form is unposted; also, just 228076726Speter before each page change operation. 2281166124Srafan 228276726Speter Calls to these hooks may be triggered 228376726Speter 1. When user editing requests are processed by the forms driver 228476726Speter 2. When the current page is changed by set_current_field() call 228576726Speter 3. When the current field is changed by a set_form_page() call 2286166124Srafan 228776726Speter See Field Change Commands for discussion of the latter two cases. 2288166124Srafan 2289166124Srafan You can set a default hook for all fields by passing one of the set 229076726Speter functions a NULL first argument. 2291166124Srafan 2292166124Srafan You can disable any of these hooks by (re)setting them to NULL, the 229376726Speter default value. 2294166124Srafan 229576726SpeterField Change Commands 229676726Speter 2297166124Srafan Normally, navigation through the form will be driven by the user's 2298166124Srafan input requests. But sometimes it is useful to be able to move the 2299166124Srafan focus for editing and viewing under control of your application, or 2300166124Srafan ask which field it currently is in. The following functions help you 230176726Speter accomplish this: 230276726Speterint set_current_field(FORM *form, /* form to alter */ 230376726Speter FIELD *field); /* field to shift to */ 230476726Speter 230576726SpeterFIELD *current_field(FORM *form); /* form to query */ 230676726Speter 230776726Speterint field_index(FORM *form, /* form to query */ 230876726Speter FIELD *field); /* field to get index of */ 230976726Speter 231076726Speter The function field_index() returns the index of the given field in the 2311166124Srafan given form's field array (the array passed to new_form() or 231276726Speter set_form_fields()). 2313166124Srafan 2314166124Srafan The initial current field of a form is the first active field on the 231576726Speter first page. The function set_form_fields() resets this. 2316166124Srafan 231776726Speter It is also possible to move around by pages. 231876726Speterint set_form_page(FORM *form, /* form to alter */ 231976726Speter int page); /* page to go to (0-origin) */ 232076726Speter 232176726Speterint form_page(FORM *form); /* return form's current page */ 232276726Speter 2323166124Srafan The initial page of a newly-created form is 0. The function 232476726Speter set_form_fields() resets this. 2325166124Srafan 232676726SpeterForm Options 232776726Speter 2328166124Srafan Like fields, forms may have control option bits. They can be changed 232976726Speter or queried with these functions: 233076726Speterint set_form_opts(FORM *form, /* form to alter */ 233176726Speter int attr); /* attribute to set */ 233276726Speter 233376726Speterint form_opts_on(FORM *form, /* form to alter */ 233476726Speter int attr); /* attributes to turn on */ 233576726Speter 233676726Speterint form_opts_off(FORM *form, /* form to alter */ 233776726Speter int attr); /* attributes to turn off */ 233876726Speter 233976726Speterint form_opts(FORM *form); /* form to query */ 234076726Speter 234176726Speter By default, all options are on. Here are the available option bits: 2342166124Srafan 234376726Speter O_NL_OVERLOAD 2344166124Srafan Enable overloading of REQ_NEW_LINE as described in Editing 234576726Speter Requests. The value of this option is ignored on dynamic fields 2346166124Srafan that have not reached their size limit; these have no last 2347166124Srafan line, so the circumstances for triggering a REQ_NEXT_FIELD 234876726Speter never arise. 2349166124Srafan 235076726Speter O_BS_OVERLOAD 2351166124Srafan Enable overloading of REQ_DEL_PREV as described in Editing 235276726Speter Requests. 2353166124Srafan 235476726Speter The option values are bit-masks and can be composed with logical-or in 235576726Speter the obvious way. 2356166124Srafan 235776726SpeterCustom Validation Types 235876726Speter 2359166124Srafan The form library gives you the capability to define custom validation 2360166124Srafan types of your own. Further, the optional additional arguments of 236176726Speter set_field_type effectively allow you to parameterize validation types. 2362166124Srafan Most of the complications in the validation-type interface have to do 236376726Speter with the handling of the additional arguments within custom validation 236476726Speter functions. 2365166124Srafan 236676726Speter Union Types 2367166124Srafan 2368166124Srafan The simplest way to create a custom data type is to compose it from 236976726Speter two preexisting ones: 237076726SpeterFIELD *link_fieldtype(FIELDTYPE *type1, 237176726Speter FIELDTYPE *type2); 237276726Speter 2373166124Srafan This function creates a field type that will accept any of the values 2374166124Srafan legal for either of its argument field types (which may be either 2375166124Srafan predefined or programmer-defined). If a set_field_type() call later 2376166124Srafan requires arguments, the new composite type expects all arguments for 2377166124Srafan the first type, than all arguments for the second. Order functions 2378166124Srafan (see Order Requests) associated with the component types will work on 2379166124Srafan the composite; what it does is check the validation function for the 2380166124Srafan first type, then for the second, to figure what type the buffer 238176726Speter contents should be treated as. 2382166124Srafan 238376726Speter New Field Types 2384166124Srafan 2385166124Srafan To create a field type from scratch, you need to specify one or both 238676726Speter of the following things: 2387166124Srafan * A character-validation function, to check each character as it is 238876726Speter entered. 238976726Speter * A field-validation function to be applied on exit from the field. 2390166124Srafan 239176726Speter Here's how you do that: 239276726Spetertypedef int (*HOOK)(); /* pointer to function returning int */ 239376726Speter 239476726SpeterFIELDTYPE *new_fieldtype(HOOK f_validate, /* field validator */ 239576726Speter HOOK c_validate) /* character validator */ 239676726Speter 239776726Speter 239876726Speterint free_fieldtype(FIELDTYPE *ftype); /* type to free */ 239976726Speter 240076726Speter At least one of the arguments of new_fieldtype() must be non-NULL. The 2401166124Srafan forms driver will automatically call the new type's validation 240276726Speter functions at appropriate points in processing a field of the new type. 2403166124Srafan 2404166124Srafan The function free_fieldtype() deallocates the argument fieldtype, 240576726Speter freeing all storage associated with it. 2406166124Srafan 2407166124Srafan Normally, a field validator is called when the user attempts to leave 2408166124Srafan the field. Its first argument is a field pointer, from which it can 2409166124Srafan get to field buffer 0 and test it. If the function returns TRUE, the 2410166124Srafan operation succeeds; if it returns FALSE, the edit cursor stays in the 241176726Speter field. 2412166124Srafan 2413166124Srafan A character validator gets the character passed in as a first 2414166124Srafan argument. It too should return TRUE if the character is valid, FALSE 241576726Speter otherwise. 2416166124Srafan 241776726Speter Validation Function Arguments 2418166124Srafan 2419166124Srafan Your field- and character- validation functions will be passed a 2420166124Srafan second argument as well. This second argument is the address of a 2421166124Srafan structure (which we'll call a pile) built from any of the 2422166124Srafan field-type-specific arguments passed to set_field_type(). If no such 2423166124Srafan arguments are defined for the field type, this pile pointer argument 242476726Speter will be NULL. 2425166124Srafan 242676726Speter In order to arrange for such arguments to be passed to your validation 2427166124Srafan functions, you must associate a small set of storage-management 242876726Speter functions with the type. The forms driver will use these to synthesize 2429166124Srafan a pile from the trailing arguments of each set_field_type() argument, 243076726Speter and a pointer to the pile will be passed to the validation functions. 2431166124Srafan 243276726Speter Here is how you make the association: 243376726Spetertypedef char *(*PTRHOOK)(); /* pointer to function returning (char *) */ 243476726Spetertypedef void (*VOIDHOOK)(); /* pointer to function returning void */ 243576726Speter 243676726Speterint set_fieldtype_arg(FIELDTYPE *type, /* type to alter */ 243776726Speter PTRHOOK make_str, /* make structure from args */ 243876726Speter PTRHOOK copy_str, /* make copy of structure */ 243976726Speter VOIDHOOK free_str); /* free structure storage */ 244076726Speter 244176726Speter Here is how the storage-management hooks are used: 2442166124Srafan 244376726Speter make_str 2444166124Srafan This function is called by set_field_type(). It gets one 2445166124Srafan argument, a va_list of the type-specific arguments passed to 2446166124Srafan set_field_type(). It is expected to return a pile pointer to a 244776726Speter data structure that encapsulates those arguments. 2448166124Srafan 244976726Speter copy_str 245076726Speter This function is called by form library functions that allocate 2451166124Srafan new field instances. It is expected to take a pile pointer, 2452166124Srafan copy the pile to allocated storage, and return the address of 245376726Speter the pile copy. 2454166124Srafan 245576726Speter free_str 2456166124Srafan This function is called by field- and type-deallocation 2457166124Srafan routines in the library. It takes a pile pointer argument, and 245876726Speter is expected to free the storage of that pile. 2459166124Srafan 2460166124Srafan The make_str and copy_str functions may return NULL to signal 2461166124Srafan allocation failure. The library routines will that call them will 2462166124Srafan return error indication when this happens. Thus, your validation 2463166124Srafan functions should never see a NULL file pointer and need not check 246476726Speter specially for it. 2465166124Srafan 246676726Speter Order Functions For Custom Types 2467166124Srafan 2468166124Srafan Some custom field types are simply ordered in the same well-defined 2469166124Srafan way that TYPE_ENUM is. For such types, it is possible to define 247076726Speter successor and predecessor functions to support the REQ_NEXT_CHOICE and 247176726Speter REQ_PREV_CHOICE requests. Here's how: 247276726Spetertypedef int (*INTHOOK)(); /* pointer to function returning int */ 247376726Speter 247476726Speterint set_fieldtype_arg(FIELDTYPE *type, /* type to alter */ 247576726Speter INTHOOK succ, /* get successor value */ 247676726Speter INTHOOK pred); /* get predecessor value */ 247776726Speter 2478166124Srafan The successor and predecessor arguments will each be passed two 2479166124Srafan arguments; a field pointer, and a pile pointer (as for the validation 2480166124Srafan functions). They are expected to use the function field_buffer() to 2481166124Srafan read the current value, and set_field_buffer() on buffer 0 to set the 2482166124Srafan next or previous value. Either hook may return TRUE to indicate 2483166124Srafan success (a legal next or previous value was set) or FALSE to indicate 248476726Speter failure. 2485166124Srafan 248676726Speter Avoiding Problems 2487166124Srafan 2488166124Srafan The interface for defining custom types is complicated and tricky. 2489166124Srafan Rather than attempting to create a custom type entirely from scratch, 2490166124Srafan you should start by studying the library source code for whichever of 249176726Speter the pre-defined types seems to be closest to what you want. 2492166124Srafan 2493166124Srafan Use that code as a model, and evolve it towards what you really want. 2494166124Srafan You will avoid many problems and annoyances that way. The code in the 2495166124Srafan ncurses library has been specifically exempted from the package 249676726Speter copyright to support this. 2497166124Srafan 2498166124Srafan If your custom type defines order functions, have do something 2499166124Srafan intuitive with a blank field. A useful convention is to make the 2500166124Srafan successor of a blank field the types minimum value, and its 250176726Speter predecessor the maximum. 2502