doc/html/ncurses-intro.html

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