misc/ncurses-intro.html

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