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