ncurses-intro.html revision 97049
1117632Sharti<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 3.0//EN"> 2117632Sharti<!-- 3117632Sharti $Id: ncurses-intro.html,v 1.35 2001/09/02 00:23:11 tom Exp $ 4117632Sharti--> 5117632Sharti<HTML> 6117632Sharti<HEAD> 7117632Sharti<TITLE>Writing Programs with NCURSES</TITLE> 8117632Sharti<link rev="made" href="mailto:bugs-ncurses@gnu.org"> 9117632Sharti</HEAD> 10117632Sharti<BODY> 11117632Sharti 12117632Sharti<H1>Writing Programs with NCURSES</H1> 13117632Sharti 14117632Sharti<BLOCKQUOTE> 15117632Shartiby Eric S. Raymond and Zeyd M. Ben-Halim<BR> 16117632Shartiupdates since release 1.9.9e by Thomas Dickey 17117632Sharti</BLOCKQUOTE> 18117632Sharti 19117632Sharti<H1>Contents</H1> 20117632Sharti<UL> 21117632Sharti<LI><A HREF="#introduction">Introduction</A> 22117632Sharti<UL> 23117632Sharti<LI><A HREF="#history">A Brief History of Curses</A> 24117632Sharti<LI><A HREF="#scope">Scope of This Document</A> 25117632Sharti<LI><A HREF="#terminology">Terminology</A> 26117632Sharti</UL> 27117632Sharti<LI><A HREF="#curses">The Curses Library</A> 28117632Sharti<UL> 29117632Sharti<LI><A HREF="#overview">An Overview of Curses</A> 30117632Sharti<UL> 31117632Sharti<LI><A HREF="#compiling">Compiling Programs using Curses</A> 32117632Sharti<LI><A HREF="#updating">Updating the Screen</A> 33117632Sharti<LI><A HREF="#stdscr">Standard Windows and Function Naming Conventions</A> 34117632Sharti<LI><A HREF="#variables">Variables</A> 35117632Sharti</UL> 36117632Sharti<LI><A HREF="#using">Using the Library</A> 37117632Sharti<UL> 38117632Sharti<LI><A HREF="#starting">Starting up</A> 39117632Sharti<LI><A HREF="#output">Output</A> 40117632Sharti<LI><A HREF="#input">Input</A> 41117632Sharti<LI><A HREF="#formschars">Using Forms Characters</A> 42117632Sharti<LI><A HREF="#attributes">Character Attributes and Color</A> 43117632Sharti<LI><A HREF="#mouse">Mouse Interfacing</A> 44117632Sharti<LI><A HREF="#finishing">Finishing Up</A> 45117632Sharti</UL> 46117632Sharti<LI><A HREF="#functions">Function Descriptions</A> 47117632Sharti<UL> 48117632Sharti<LI><A HREF="#init">Initialization and Wrapup</A> 49117632Sharti<LI><A HREF="#flush">Causing Output to the Terminal</A> 50117632Sharti<LI><A HREF="#lowlevel">Low-Level Capability Access</A> 51117632Sharti<LI><A HREF="#debugging">Debugging</A> 52117632Sharti</UL> 53117632Sharti<LI><A HREF="#hints">Hints, Tips, and Tricks</A> 54117632Sharti<UL> 55117632Sharti<LI><A HREF="#caution">Some Notes of Caution</A> 56117632Sharti<LI><A HREF="#leaving">Temporarily Leaving ncurses Mode</A> 57117632Sharti<LI><A HREF="#xterm">Using <CODE>ncurses</CODE> under <CODE>xterm</CODE></A> 58117632Sharti<LI><A HREF="#screens">Handling Multiple Terminal Screens</A> 59117632Sharti<LI><A HREF="#testing">Testing for Terminal Capabilities</A> 60117632Sharti<LI><A HREF="#tuning">Tuning for Speed</A> 61117632Sharti<LI><A HREF="#special">Special Features of <CODE>ncurses</CODE></A> 62117632Sharti</UL> 63117632Sharti<LI><A HREF="#compat">Compatibility with Older Versions</A> 64117632Sharti<UL> 65117632Sharti<LI><A HREF="#refbug">Refresh of Overlapping Windows</A> 66117632Sharti<LI><A HREF="#backbug">Background Erase</A> 67117632Sharti</UL> 68117632Sharti<LI><A HREF="#xsifuncs">XSI Curses Conformance</A> 69117632Sharti</UL> 70117632Sharti<LI><A HREF="#panels">The Panels Library</A> 71117632Sharti<UL> 72117632Sharti<LI><A HREF="#pcompile">Compiling With the Panels Library</A> 73117632Sharti<LI><A HREF="#poverview">Overview of Panels</A> 74117632Sharti<LI><A HREF="#pstdscr">Panels, Input, and the Standard Screen</A> 75117632Sharti<LI><A HREF="#hiding">Hiding Panels</A> 76117632Sharti<LI><A HREF="#pmisc">Miscellaneous Other Facilities</A> 77117632Sharti</UL> 78117632Sharti<LI><A HREF="#menu">The Menu Library</A> 79117632Sharti<UL> 80117632Sharti<LI><A HREF="#mcompile">Compiling with the menu Library</A> 81117632Sharti<LI><A HREF="#moverview">Overview of Menus</A> 82117632Sharti<LI><A HREF="#mselect">Selecting items</A> 83117632Sharti<LI><A HREF="#mdisplay">Menu Display</A> 84117632Sharti<LI><A HREF="#mwindows">Menu Windows</A> 85117632Sharti<LI><A HREF="#minput">Processing Menu Input</A> 86117632Sharti<LI><A HREF="#mmisc">Miscellaneous Other Features</A> 87117632Sharti</UL> 88117632Sharti<LI><A HREF="#form">The Forms Library</A> 89117632Sharti<UL> 90117632Sharti<LI><A HREF="#fcompile">Compiling with the forms Library</A> 91117632Sharti<LI><A HREF="#foverview">Overview of Forms</A> 92117632Sharti<LI><A HREF="#fcreate">Creating and Freeing Fields and Forms</A> 93117632Sharti<LI><A HREF="#fattributes">Fetching and Changing Field Attributes</A> 94117632Sharti<UL> 95117632Sharti<LI><A HREF="#fsizes">Fetching Size and Location Data</A> 96117632Sharti<LI><A HREF="#flocation">Changing the Field Location</A> 97117632Sharti<LI><A HREF="#fjust">The Justification Attribute</A> 98117632Sharti<LI><A HREF="#fdispatts">Field Display Attributes</A> 99117632Sharti<LI><A HREF="#foptions">Field Option Bits</A> 100117632Sharti<LI><A HREF="#fstatus">Field Status</A> 101117632Sharti<LI><A HREF="#fuser">Field User Pointer</A> 102117632Sharti</UL> 103117632Sharti<LI><A HREF="#fdynamic">Variable-Sized Fields</A> 104117632Sharti<LI><A HREF="#fvalidation">Field Validation</A> 105117632Sharti<UL> 106117632Sharti<LI><A HREF="#ftype_alpha">TYPE_ALPHA</A> 107117632Sharti<LI><A HREF="#ftype_alnum">TYPE_ALNUM</A> 108117632Sharti<LI><A HREF="#ftype_enum">TYPE_ENUM</A> 109117632Sharti<LI><A HREF="#ftype_integer">TYPE_INTEGER</A> 110117632Sharti<LI><A HREF="#ftype_numeric">TYPE_NUMERIC</A> 111117632Sharti<LI><A HREF="#ftype_regexp">TYPE_REGEXP</A> 112117632Sharti</UL> 113117632Sharti<LI><A HREF="#fbuffer">Direct Field Buffer Manipulation</A> 114117632Sharti<LI><A HREF="#formattrs">Attributes of Forms</A> 115117632Sharti<LI><A HREF="#fdisplay">Control of Form Display</A> 116117632Sharti<LI><A HREF="#fdriver">Input Processing in the Forms Driver</A> 117117632Sharti<UL> 118117632Sharti<LI><A HREF="#fpage">Page Navigation Requests</A> 119117632Sharti<LI><A HREF="#ffield">Inter-Field Navigation Requests</A> 120117632Sharti<LI><A HREF="#fifield">Intra-Field Navigation Requests</A> 121117632Sharti<LI><A HREF="#fscroll">Scrolling Requests</A> 122117632Sharti<LI><A HREF="#fedit">Field Editing Requests</A> 123117632Sharti<LI><A HREF="#forder">Order Requests</A> 124117632Sharti<LI><A HREF="#fappcmds">Application Commands</A> 125117632Sharti</UL> 126117632Sharti<LI><A HREF="#fhooks">Field Change Hooks</A> 127117632Sharti<LI><A HREF="#ffocus">Field Change Commands</A> 128117632Sharti<LI><A HREF="#frmoptions">Form Options</A> 129117632Sharti<LI><A HREF="#fcustom">Custom Validation Types</A> 130117632Sharti<UL> 131117632Sharti<LI><A HREF="#flinktypes">Union Types</A> 132117632Sharti<LI><A HREF="#fnewtypes">New Field Types</A> 133117632Sharti<LI><A HREF="#fcheckargs">Validation Function Arguments</A> 134117632Sharti<LI><A HREF="#fcustorder">Order Functions For Custom Types</A> 135117632Sharti<LI><A HREF="#fcustprobs">Avoiding Problems</A> 136117632Sharti</UL> 137117632Sharti</UL> 138117632Sharti</UL> 139117632Sharti 140117632Sharti<HR> 141117632Sharti<H1><A NAME="introduction">Introduction</A></H1> 142117632Sharti 143117632ShartiThis document is an introduction to programming with <CODE>curses</CODE>. It is 144117632Shartinot an exhaustive reference for the curses Application Programming Interface 145117632Sharti(API); that role is filled by the <CODE>curses</CODE> manual pages. Rather, it 146117632Shartiis intended to help C programmers ease into using the package. <P> 147117632Sharti 148117632ShartiThis document is aimed at C applications programmers not yet specifically 149117632Shartifamiliar with ncurses. If you are already an experienced <CODE>curses</CODE> 150117632Shartiprogrammer, you should nevertheless read the sections on 151117632Sharti<A HREF="#mouse">Mouse Interfacing</A>, <A HREF="#debugging">Debugging</A>, 152117632Sharti<A HREF="#compat">Compatibility with Older Versions</A>, 153117632Shartiand <A HREF="#hints">Hints, Tips, and Tricks</A>. These will bring you up 154117632Shartito speed on the special features and quirks of the <CODE>ncurses</CODE> 155117632Shartiimplementation. If you are not so experienced, keep reading. <P> 156117632Sharti 157117632ShartiThe <CODE>curses</CODE> package is a subroutine library for 158117632Shartiterminal-independent screen-painting and input-event handling which 159117632Shartipresents a high level screen model to the programmer, hiding differences 160117632Shartibetween terminal types and doing automatic optimization of output to change 161117632Shartione screen full of text into another. <CODE>Curses</CODE> uses terminfo, which 162117632Shartiis a database format that can describe the capabilities of thousands of 163117632Shartidifferent terminals. <P> 164117632Sharti 165117632ShartiThe <CODE>curses</CODE> API may seem something of an archaism on UNIX desktops 166117632Shartiincreasingly dominated by X, Motif, and Tcl/Tk. Nevertheless, UNIX still 167117632Shartisupports tty lines and X supports <EM>xterm(1)</EM>; the <CODE>curses</CODE> 168117632ShartiAPI has the advantage of (a) back-portability to character-cell terminals, 169117632Shartiand (b) simplicity. For an application that does not require bit-mapped 170117632Shartigraphics and multiple fonts, an interface implementation using <CODE>curses</CODE> 171117632Shartiwill typically be a great deal simpler and less expensive than one using an 172117632ShartiX toolkit. 173117632Sharti 174117632Sharti<H2><A NAME="history">A Brief History of Curses</A></H2> 175117632Sharti 176117632ShartiHistorically, the first ancestor of <CODE>curses</CODE> was the routines written to 177117632Shartiprovide screen-handling for the game <CODE>rogue</CODE>; these used the 178117632Shartialready-existing <CODE>termcap</CODE> database facility for describing terminal 179117632Sharticapabilities. These routines were abstracted into a documented library and 180117632Shartifirst released with the early BSD UNIX versions. <P> 181117632Sharti 182117632ShartiSystem III UNIX from Bell Labs featured a rewritten and much-improved 183117632Sharti<CODE>curses</CODE> library. It introduced the terminfo format. Terminfo is based 184117632Shartion Berkeley's termcap database, but contains a number of improvements and 185117632Shartiextensions. Parameterized capabilities strings were introduced, making it 186117632Shartipossible to describe multiple video attributes, and colors and to handle far 187117632Shartimore unusual terminals than possible with termcap. In the later AT&T 188117632ShartiSystem V releases, <CODE>curses</CODE> evolved to use more facilities and offer 189117632Shartimore capabilities, going far beyond BSD curses in power and flexibility. 190117632Sharti 191117632Sharti<H2><A NAME="scope">Scope of This Document</A></H2> 192117632Sharti 193117632ShartiThis document describes <CODE>ncurses</CODE>, a free implementation of 194117632Shartithe System V <CODE>curses</CODE> API with some clearly marked extensions. 195117632ShartiIt includes the following System V curses features: 196117632Sharti<UL> 197117632Sharti<LI>Support for multiple screen highlights (BSD curses could only 198117632Shartihandle one `standout' highlight, usually reverse-video). 199117632Sharti<LI>Support for line- and box-drawing using forms characters. 200117632Sharti<LI>Recognition of function keys on input. 201117632Sharti<LI>Color support. 202117632Sharti<LI>Support for pads (windows of larger than screen size on which the 203117632Shartiscreen or a subwindow defines a viewport). 204117632Sharti</UL> 205117632Sharti 206117632ShartiAlso, this package makes use of the insert and delete line and character 207117632Shartifeatures of terminals so equipped, and determines how to optimally use these 208117632Shartifeatures with no help from the programmer. It allows arbitrary combinations of 209117632Shartivideo attributes to be displayed, even on terminals that leave ``magic 210117632Sharticookies'' on the screen to mark changes in attributes. <P> 211117632Sharti 212117632ShartiThe <CODE>ncurses</CODE> package can also capture and use event reports from a 213117632Shartimouse in some environments (notably, xterm under the X window system). This 214117632Shartidocument includes tips for using the mouse. <P> 215117632Sharti 216117632ShartiThe <CODE>ncurses</CODE> package was originated by Pavel Curtis. The original 217117632Shartimaintainer of this package is 218117632Sharti<A HREF="mailto:zmbenhal@netcom.com">Zeyd Ben-Halim</A> 219117632Sharti<zmbenhal@netcom.com>. 220117632Sharti<A HREF="mailto:esr@snark.thyrsus.com">Eric S. Raymond</A> 221117632Sharti<esr@snark.thyrsus.com> 222117632Shartiwrote many of the new features in versions after 1.8.1 223117632Shartiand wrote most of this introduction. 224117632Sharti<A HREF="mailto:juergen.pfeifer@gmx.net">Jürgen Pfeifer</A> 225117632Shartiwrote all of the menu and forms code as well as the 226117632Sharti<A HREF="http://www.adahome.com">Ada95</A> binding. 227117632ShartiOngoing work is being done by 228117632Sharti<A HREF="mailto:dickey@herndon4.his.com">Thomas Dickey</A> 229117632Shartiand 230117632Sharti<A HREF="mailto:juergen.pfeifer@gmx.net">Jürgen Pfeifer</A>. 231117632Sharti<A HREF="mailto:florian@gnu.org">Florian La Roche</A> 232117632Shartiacts as the maintainer for the Free Software Foundation, which holds the 233117632Sharticopyright on ncurses. 234117632ShartiContact the current maintainers at 235117632Sharti<A HREF="mailto:bug-ncurses@gnu.org">bug-ncurses@gnu.org</A>. 236117632Sharti<P> 237117632Sharti 238117632ShartiThis document also describes the <A HREF="#panels">panels</A> extension library, 239117632Shartisimilarly modeled on the SVr4 panels facility. This library allows you to 240117632Shartiassociate backing store with each of a stack or deck of overlapping windows, 241117632Shartiand provides operations for moving windows around in the stack that change 242117632Shartitheir visibility in the natural way (handling window overlaps). <P> 243117632Sharti 244117632ShartiFinally, this document describes in detail the <A HREF="#menu">menus</A> and <A 245117632ShartiHREF="#form">forms</A> extension libraries, also cloned from System V, 246117632Shartiwhich support easy construction and sequences of menus and fill-in 247117632Shartiforms. 248117632Sharti 249117632Sharti 250117632Sharti<H2><A NAME="terminology">Terminology</A></H2> 251117632Sharti 252117632ShartiIn this document, the following terminology is used with reasonable 253117632Sharticonsistency: 254117632Sharti 255117632Sharti<DL> 256117632Sharti<DT> window 257117632Sharti<DD> 258117632ShartiA data structure describing a sub-rectangle of the screen (possibly the 259117632Shartientire screen). You can write to a window as though it were a miniature 260117632Shartiscreen, scrolling independently of other windows on the physical screen. 261117632Sharti<DT> screens 262117632Sharti<DD> 263117632ShartiA subset of windows which are as large as the terminal screen, i.e., they start 264117632Shartiat the upper left hand corner and encompass the lower right hand corner. One 265117632Shartiof these, <CODE>stdscr</CODE>, is automatically provided for the programmer. 266117632Sharti<DT> terminal screen 267117632Sharti<DD> 268117632ShartiThe package's idea of what the terminal display currently looks like, i.e., 269117632Shartiwhat the user sees now. This is a special screen. 270117632Sharti</DL> 271117632Sharti 272117632Sharti<H1><A NAME="curses">The Curses Library</A></H1> 273117632Sharti 274117632Sharti<H2><A NAME="overview">An Overview of Curses</A></H2> 275117632Sharti 276117632Sharti<H3><A NAME="compiling">Compiling Programs using Curses</A></H3> 277117632Sharti 278117632ShartiIn order to use the library, it is necessary to have certain types and 279117632Shartivariables defined. Therefore, the programmer must have a line: 280117632Sharti 281117632Sharti<PRE> 282117632Sharti #include <curses.h> 283117632Sharti</PRE> 284117632Sharti 285117632Shartiat the top of the program source. The screen package uses the Standard I/O 286117632Shartilibrary, so <CODE><curses.h></CODE> includes 287117632Sharti<CODE><stdio.h></CODE>. <CODE><curses.h></CODE> also includes 288117632Sharti<CODE><termios.h></CODE>, <CODE><termio.h></CODE>, or 289117632Sharti<CODE><sgtty.h></CODE> depending on your system. It is redundant (but 290117632Shartiharmless) for the programmer to do these includes, too. In linking with 291117632Sharti<CODE>curses</CODE> you need to have <CODE>-lncurses</CODE> in your LDFLAGS or on the 292117632Sharticommand line. There is no need for any other libraries. 293117632Sharti 294117632Sharti<H3><A NAME="updating">Updating the Screen</A></H3> 295117632Sharti 296117632ShartiIn order to update the screen optimally, it is necessary for the routines to 297117632Shartiknow what the screen currently looks like and what the programmer wants it to 298117632Shartilook like next. For this purpose, a data type (structure) named WINDOW is 299117632Shartidefined which describes a window image to the routines, including its starting 300117632Shartiposition on the screen (the (y, x) coordinates of the upper left hand corner) 301117632Shartiand its size. One of these (called <CODE>curscr</CODE>, for current screen) is a 302117632Shartiscreen image of what the terminal currently looks like. Another screen (called 303117632Sharti<CODE>stdscr</CODE>, for standard screen) is provided by default to make changes 304117632Shartion. <P> 305117632Sharti 306117632ShartiA window is a purely internal representation. It is used to build and store a 307117632Shartipotential image of a portion of the terminal. It doesn't bear any necessary 308117632Shartirelation to what is really on the terminal screen; it's more like a 309117632Shartiscratchpad or write buffer. <P> 310117632Sharti 311117632ShartiTo make the section of physical screen corresponding to a window reflect the 312117632Sharticontents of the window structure, the routine <CODE>refresh()</CODE> (or 313117632Sharti<CODE>wrefresh()</CODE> if the window is not <CODE>stdscr</CODE>) is called. <P> 314117632Sharti 315117632ShartiA given physical screen section may be within the scope of any number of 316117632Shartioverlapping windows. Also, changes can be made to windows in any order, 317117632Shartiwithout regard to motion efficiency. Then, at will, the programmer can 318117632Shartieffectively say ``make it look like this,'' and let the package implementation 319117632Shartidetermine the most efficient way to repaint the screen. 320117632Sharti 321117632Sharti<H3><A NAME="stdscr">Standard Windows and Function Naming Conventions</A></H3> 322117632Sharti 323117632ShartiAs hinted above, the routines can use several windows, but two are 324117632Shartiautomatically given: <CODE>curscr</CODE>, which knows what the terminal looks like, 325117632Shartiand <CODE>stdscr</CODE>, which is what the programmer wants the terminal to look 326117632Shartilike next. The user should never actually access <CODE>curscr</CODE> directly. 327117632ShartiChanges should be made to through the API, and then the routine 328117632Sharti<CODE>refresh()</CODE> (or <CODE>wrefresh()</CODE>) called. <P> 329117632Sharti 330117632ShartiMany functions are defined to use <CODE>stdscr</CODE> as a default screen. For 331117632Shartiexample, to add a character to <CODE>stdscr</CODE>, one calls <CODE>addch()</CODE> with 332117632Shartithe desired character as argument. To write to a different window. use the 333117632Shartiroutine <CODE>waddch()</CODE> (for `w'indow-specific addch()) is provided. This 334117632Sharticonvention of prepending function names with a `w' when they are to be 335117632Shartiapplied to specific windows is consistent. The only routines which do not 336117632Shartifollow it are those for which a window must always be specified. <P> 337117632Sharti 338117632ShartiIn order to move the current (y, x) coordinates from one point to another, the 339117632Shartiroutines <CODE>move()</CODE> and <CODE>wmove()</CODE> are provided. However, it is 340117632Shartioften desirable to first move and then perform some I/O operation. In order to 341117632Shartiavoid clumsiness, most I/O routines can be preceded by the prefix 'mv' and 342117632Shartithe desired (y, x) coordinates prepended to the arguments to the function. For 343117632Shartiexample, the calls 344117632Sharti 345117632Sharti<PRE> 346117632Sharti move(y, x); 347117632Sharti addch(ch); 348117632Sharti</PRE> 349117632Sharti 350117632Shartican be replaced by 351117632Sharti 352117632Sharti<PRE> 353117632Sharti mvaddch(y, x, ch); 354117632Sharti</PRE> 355117632Sharti 356117632Shartiand 357117632Sharti 358117632Sharti<PRE> 359117632Sharti wmove(win, y, x); 360117632Sharti waddch(win, ch); 361117632Sharti</PRE> 362117632Sharti 363117632Shartican be replaced by 364117632Sharti 365117632Sharti<PRE> 366117632Sharti mvwaddch(win, y, x, ch); 367117632Sharti</PRE> 368117632Sharti 369117632ShartiNote that the window description pointer (win) comes before the added (y, x) 370117632Sharticoordinates. If a function requires a window pointer, it is always the first 371117632Shartiparameter passed. 372117632Sharti 373117632Sharti<H3><A NAME="variables">Variables</A></H3> 374117632Sharti 375117632ShartiThe <CODE>curses</CODE> library sets some variables describing the terminal 376117632Sharticapabilities. 377117632Sharti 378117632Sharti<PRE> 379117632Sharti type name description 380117632Sharti ------------------------------------------------------------------ 381117632Sharti int LINES number of lines on the terminal 382117632Sharti int COLS number of columns on the terminal 383117632Sharti</PRE> 384117632Sharti 385117632ShartiThe <CODE>curses.h</CODE> also introduces some <CODE>#define</CODE> constants and types 386117632Shartiof general usefulness: 387117632Sharti 388117632Sharti<DL> 389117632Sharti<DT> <CODE>bool</CODE> 390117632Sharti<DD> boolean type, actually a `char' (e.g., <CODE>bool doneit;</CODE>) 391117632Sharti<DT> <CODE>TRUE</CODE> 392117632Sharti<DD> boolean `true' flag (1). 393117632Sharti<DT> <CODE>FALSE</CODE> 394117632Sharti<DD> boolean `false' flag (0). 395117632Sharti<DT> <CODE>ERR</CODE> 396117632Sharti<DD> error flag returned by routines on a failure (-1). 397117632Sharti<DT> <CODE>OK</CODE> 398117632Sharti<DD> error flag returned by routines when things go right. 399117632Sharti</DL> 400117632Sharti 401117632Sharti<H2><A NAME="using">Using the Library</A></H2> 402117632Sharti 403117632ShartiNow we describe how to actually use the screen package. In it, we assume all 404117632Shartiupdating, reading, etc. is applied to <CODE>stdscr</CODE>. These instructions will 405117632Shartiwork on any window, providing you change the function names and parameters as 406117632Shartimentioned above. <P> 407117632Sharti 408117632ShartiHere is a sample program to motivate the discussion: 409117632Sharti 410117632Sharti<PRE> 411117632Sharti#include <curses.h> 412117632Sharti#include <signal.h> 413117632Sharti 414117632Shartistatic void finish(int sig); 415117632Sharti 416117632Shartiint 417117632Shartimain(int argc, char *argv[]) 418117632Sharti{ 419117632Sharti int num = 0; 420117632Sharti 421117632Sharti /* initialize your non-curses data structures here */ 422117632Sharti 423117632Sharti (void) signal(SIGINT, finish); /* arrange interrupts to terminate */ 424117632Sharti 425117632Sharti (void) initscr(); /* initialize the curses library */ 426117632Sharti keypad(stdscr, TRUE); /* enable keyboard mapping */ 427117632Sharti (void) nonl(); /* tell curses not to do NL->CR/NL on output */ 428117632Sharti (void) cbreak(); /* take input chars one at a time, no wait for \n */ 429117632Sharti (void) echo(); /* echo input - in color */ 430117632Sharti 431117632Sharti if (has_colors()) 432117632Sharti { 433117632Sharti start_color(); 434117632Sharti 435117632Sharti /* 436117632Sharti * Simple color assignment, often all we need. Color pair 0 cannot 437117632Sharti * be redefined. This example uses the same value for the color 438117632Sharti * pair as for the foreground color, though of course that is not 439117632Sharti * necessary: 440117632Sharti */ 441117632Sharti init_pair(1, COLOR_RED, COLOR_BLACK); 442117632Sharti init_pair(2, COLOR_GREEN, COLOR_BLACK); 443117632Sharti init_pair(3, COLOR_YELLOW, COLOR_BLACK); 444117632Sharti init_pair(4, COLOR_BLUE, COLOR_BLACK); 445117632Sharti init_pair(5, COLOR_CYAN, COLOR_BLACK); 446117632Sharti init_pair(6, COLOR_MAGENTA, COLOR_BLACK); 447117632Sharti init_pair(7, COLOR_WHITE, COLOR_BLACK); 448117632Sharti } 449117632Sharti 450117632Sharti for (;;) 451117632Sharti { 452117632Sharti int c = getch(); /* refresh, accept single keystroke of input */ 453117632Sharti attrset(COLOR_PAIR(num % 8)); 454117632Sharti num++; 455117632Sharti 456117632Sharti /* process the command keystroke */ 457117632Sharti } 458117632Sharti 459117632Sharti finish(0); /* we're done */ 460117632Sharti} 461117632Sharti 462117632Shartistatic void finish(int sig) 463117632Sharti{ 464117632Sharti endwin(); 465117632Sharti 466117632Sharti /* do your non-curses wrapup here */ 467117632Sharti 468117632Sharti exit(0); 469117632Sharti} 470117632Sharti</PRE> 471117632Sharti 472117632Sharti<H3><A NAME="starting">Starting up</A></H3> 473117632Sharti 474117632ShartiIn order to use the screen package, the routines must know about terminal 475117632Sharticharacteristics, and the space for <CODE>curscr</CODE> and <CODE>stdscr</CODE> must be 476117632Shartiallocated. These function <CODE>initscr()</CODE> does both these things. Since it 477117632Shartimust allocate space for the windows, it can overflow memory when attempting to 478117632Shartido so. On the rare occasions this happens, <CODE>initscr()</CODE> will terminate 479117632Shartithe program with an error message. <CODE>initscr()</CODE> must always be called 480117632Shartibefore any of the routines which affect windows are used. If it is not, the 481117632Shartiprogram will core dump as soon as either <CODE>curscr</CODE> or <CODE>stdscr</CODE> are 482117632Shartireferenced. However, it is usually best to wait to call it until after you are 483117632Shartisure you will need it, like after checking for startup errors. Terminal status 484117632Shartichanging routines like <CODE>nl()</CODE> and <CODE>cbreak()</CODE> should be called 485117632Shartiafter <CODE>initscr()</CODE>. <P> 486117632Sharti 487117632ShartiOnce the screen windows have been allocated, you can set them up for 488117632Shartiyour program. If you want to, say, allow a screen to scroll, use 489117632Sharti<CODE>scrollok()</CODE>. If you want the cursor to be left in place after 490117632Shartithe last change, use <CODE>leaveok()</CODE>. If this isn't done, 491117632Sharti<CODE>refresh()</CODE> will move the cursor to the window's current (y, x) 492117632Sharticoordinates after updating it. <P> 493117632Sharti 494117632ShartiYou can create new windows of your own using the functions <CODE>newwin()</CODE>, 495117632Sharti<CODE>derwin()</CODE>, and <CODE>subwin()</CODE>. The routine <CODE>delwin()</CODE> will 496117632Shartiallow you to get rid of old windows. All the options described above can be 497117632Shartiapplied to any window. 498117632Sharti 499117632Sharti<H3><A NAME="output">Output</A></H3> 500117632Sharti 501117632ShartiNow that we have set things up, we will want to actually update the terminal. 502117632ShartiThe basic functions used to change what will go on a window are 503117632Sharti<CODE>addch()</CODE> and <CODE>move()</CODE>. <CODE>addch()</CODE> adds a character at the 504117632Sharticurrent (y, x) coordinates. <CODE>move()</CODE> changes the current (y, x) 505117632Sharticoordinates to whatever you want them to be. It returns <CODE>ERR</CODE> if you 506117632Shartitry to move off the window. As mentioned above, you can combine the two into 507117632Sharti<CODE>mvaddch()</CODE> to do both things at once. <P> 508117632Sharti 509117632ShartiThe other output functions, such as <CODE>addstr()</CODE> and <CODE>printw()</CODE>, 510117632Shartiall call <CODE>addch()</CODE> to add characters to the window. <P> 511117632Sharti 512117632ShartiAfter you have put on the window what you want there, when you want the portion 513117632Shartiof the terminal covered by the window to be made to look like it, you must call 514117632Sharti<CODE>refresh()</CODE>. In order to optimize finding changes, <CODE>refresh()</CODE> 515117632Shartiassumes that any part of the window not changed since the last 516117632Sharti<CODE>refresh()</CODE> of that window has not been changed on the terminal, i.e., 517117632Shartithat you have not refreshed a portion of the terminal with an overlapping 518117632Shartiwindow. If this is not the case, the routine <CODE>touchwin()</CODE> is provided 519117632Shartito make it look like the entire window has been changed, thus making 520117632Sharti<CODE>refresh()</CODE> check the whole subsection of the terminal for changes. <P> 521117632Sharti 522117632ShartiIf you call <CODE>wrefresh()</CODE> with <CODE>curscr</CODE> as its argument, it will 523117632Shartimake the screen look like <CODE>curscr</CODE> thinks it looks like. This is useful 524117632Shartifor implementing a command which would redraw the screen in case it get messed 525117632Shartiup. 526117632Sharti 527117632Sharti<H3><A NAME="input">Input</A></H3> 528117632Sharti 529117632ShartiThe complementary function to <CODE>addch()</CODE> is <CODE>getch()</CODE> which, if 530117632Shartiecho is set, will call <CODE>addch()</CODE> to echo the character. Since the 531117632Shartiscreen package needs to know what is on the terminal at all times, if 532117632Sharticharacters are to be echoed, the tty must be in raw or cbreak mode. Since 533117632Shartiinitially the terminal has echoing enabled and is in ordinary ``cooked'' mode, 534117632Shartione or the other has to changed before calling <CODE>getch()</CODE>; otherwise, 535117632Shartithe program's output will be unpredictable. <P> 536117632Sharti 537117632ShartiWhen you need to accept line-oriented input in a window, the functions 538117632Sharti<CODE>wgetstr()</CODE> and friends are available. There is even a <CODE>wscanw()</CODE> 539117632Shartifunction that can do <CODE>scanf()</CODE>(3)-style multi-field parsing on window 540117632Shartiinput. These pseudo-line-oriented functions turn on echoing while they 541117632Shartiexecute. <P> 542117632Sharti 543117632ShartiThe example code above uses the call <CODE>keypad(stdscr, TRUE)</CODE> to enable 544117632Shartisupport for function-key mapping. With this feature, the <CODE>getch()</CODE> code 545117632Shartiwatches the input stream for character sequences that correspond to arrow and 546117632Shartifunction keys. These sequences are returned as pseudo-character values. The 547117632Sharti<CODE>#define</CODE> values returned are listed in the <CODE>curses.h</CODE> The 548117632Shartimapping from sequences to <CODE>#define</CODE> values is determined by 549117632Sharti<CODE>key_</CODE> capabilities in the terminal's terminfo entry. 550117632Sharti 551117632Sharti<H3><A NAME="formschars">Using Forms Characters</A></H3> 552117632Sharti 553117632ShartiThe <CODE>addch()</CODE> function (and some others, including <CODE>box()</CODE> and 554117632Sharti<CODE>border()</CODE>) can accept some pseudo-character arguments which are specially 555117632Shartidefined by <CODE>ncurses</CODE>. These are <CODE>#define</CODE> values set up in 556117632Shartithe <CODE>curses.h</CODE> header; see there for a complete list (look for 557117632Shartithe prefix <CODE>ACS_</CODE>). <P> 558117632Sharti 559117632ShartiThe most useful of the ACS defines are the forms-drawing characters. You can 560117632Shartiuse these to draw boxes and simple graphs on the screen. If the terminal 561117632Shartidoes not have such characters, <CODE>curses.h</CODE> will map them to a 562117632Shartirecognizable (though ugly) set of ASCII defaults. 563117632Sharti 564117632Sharti<H3><A NAME="attributes">Character Attributes and Color</A></H3> 565117632Sharti 566117632ShartiThe <CODE>ncurses</CODE> package supports screen highlights including standout, 567117632Shartireverse-video, underline, and blink. It also supports color, which is treated 568117632Shartias another kind of highlight. <P> 569117632Sharti 570117632ShartiHighlights are encoded, internally, as high bits of the pseudo-character type 571117632Sharti(<CODE>chtype</CODE>) that <CODE>curses.h</CODE> uses to represent the contents of a 572117632Shartiscreen cell. See the <CODE>curses.h</CODE> header file for a complete list of 573117632Shartihighlight mask values (look for the prefix <CODE>A_</CODE>).<P> 574117632Sharti 575117632ShartiThere are two ways to make highlights. One is to logical-or the value of the 576117632Shartihighlights you want into the character argument of an <CODE>addch()</CODE> call, 577117632Shartior any other output call that takes a <CODE>chtype</CODE> argument. <P> 578117632Sharti 579117632ShartiThe other is to set the current-highlight value. This is logical-or'ed with 580117632Shartiany highlight you specify the first way. You do this with the functions 581117632Sharti<CODE>attron()</CODE>, <CODE>attroff()</CODE>, and <CODE>attrset()</CODE>; see the manual 582117632Shartipages for details. 583117632Sharti 584117632ShartiColor is a special kind of highlight. The package actually thinks in terms 585117632Shartiof color pairs, combinations of foreground and background colors. The sample 586117632Sharticode above sets up eight color pairs, all of the guaranteed-available colors 587117632Shartion black. Note that each color pair is, in effect, given the name of its 588117632Shartiforeground color. Any other range of eight non-conflicting values could 589117632Shartihave been used as the first arguments of the <CODE>init_pair()</CODE> values. <P> 590117632Sharti 591117632ShartiOnce you've done an <CODE>init_pair()</CODE> that creates color-pair N, you can 592117632Shartiuse <CODE>COLOR_PAIR(N)</CODE> as a highlight that invokes that particular 593117632Sharticolor combination. Note that <CODE>COLOR_PAIR(N)</CODE>, for constant N, 594117632Shartiis itself a compile-time constant and can be used in initializers. 595117632Sharti 596117632Sharti<H3><A NAME="mouse">Mouse Interfacing</A></H3> 597117632Sharti 598117632ShartiThe <CODE>ncurses</CODE> library also provides a mouse interface. 599117632Sharti<!-- The 'note' tag is not portable enough --> 600117632Sharti<blockquote> 601117632Sharti<strong>NOTE:</strong> this facility is specific to <CODE>ncurses</CODE>, it is not part of either 602117632Shartithe XSI Curses standard, nor of System V Release 4, nor BSD curses. 603117632ShartiSystem V Release 4 curses contains code with similar interface definitions, 604117632Shartihowever it is not documented. Other than by disassembling the library, we 605117632Shartihave no way to determine exactly how that mouse code works. 606117632ShartiThus, we recommend that you wrap mouse-related code in an #ifdef using the 607117632Shartifeature macro NCURSES_MOUSE_VERSION so it will not be compiled and linked 608117632Shartion non-ncurses systems. 609117632Sharti</blockquote> 610117632Sharti 611117632ShartiPresently, mouse event reporting works in the following environments: 612117632Sharti<ul> 613117632Sharti<li>xterm and similar programs such as rxvt. 614117632Sharti<li>Linux console, when configured with <CODE>gpm</CODE>(1), Alessandro 615117632ShartiRubini's mouse server. 616117632Sharti<li>OS/2 EMX 617117632Sharti</ul> 618117632Sharti<P> 619117632ShartiThe mouse interface is very simple. To activate it, you use the function 620117632Sharti<CODE>mousemask()</CODE>, passing it as first argument a bit-mask that specifies 621117632Shartiwhat kinds of events you want your program to be able to see. It will 622117632Shartireturn the bit-mask of events that actually become visible, which may differ 623117632Shartifrom the argument if the mouse device is not capable of reporting some of 624117632Shartithe event types you specify. <P> 625117632Sharti 626117632ShartiOnce the mouse is active, your application's command loop should watch 627117632Shartifor a return value of <CODE>KEY_MOUSE</CODE> from <CODE>wgetch()</CODE>. When 628117632Shartiyou see this, a mouse event report has been queued. To pick it off 629117632Shartithe queue, use the function <CODE>getmouse()</CODE> (you must do this before 630117632Shartithe next <CODE>wgetch()</CODE>, otherwise another mouse event might come 631117632Shartiin and make the first one inaccessible). <P> 632117632Sharti 633117632ShartiEach call to <CODE>getmouse()</CODE> fills a structure (the address of which you'll 634117632Shartipass it) with mouse event data. The event data includes zero-origin, 635117632Shartiscreen-relative character-cell coordinates of the mouse pointer. It also 636117632Shartiincludes an event mask. Bits in this mask will be set, corresponding 637117632Shartito the event type being reported. <P> 638117632Sharti 639117632ShartiThe mouse structure contains two additional fields which may be 640117632Shartisignificant in the future as ncurses interfaces to new kinds of 641117632Shartipointing device. In addition to x and y coordinates, there is a slot 642117632Shartifor a z coordinate; this might be useful with touch-screens that can 643117632Shartireturn a pressure or duration parameter. There is also a device ID 644117632Shartifield, which could be used to distinguish between multiple pointing 645117632Shartidevices. <P> 646117632Sharti 647117632ShartiThe class of visible events may be changed at any time via <CODE>mousemask()</CODE>. 648117632ShartiEvents that can be reported include presses, releases, single-, double- and 649117632Shartitriple-clicks (you can set the maximum button-down time for clicks). If 650117632Shartiyou don't make clicks visible, they will be reported as press-release 651117632Shartipairs. In some environments, the event mask may include bits reporting 652117632Shartithe state of shift, alt, and ctrl keys on the keyboard during the event. <P> 653117632Sharti 654117632ShartiA function to check whether a mouse event fell within a given window is 655117632Shartialso supplied. You can use this to see whether a given window should 656117632Sharticonsider a mouse event relevant to it. <P> 657117632Sharti 658117632ShartiBecause mouse event reporting will not be available in all 659117632Shartienvironments, it would be unwise to build <CODE>ncurses</CODE> 660117632Shartiapplications that <EM>require</EM> the use of a mouse. Rather, you should 661117632Shartiuse the mouse as a shortcut for point-and-shoot commands your application 662117632Shartiwould normally accept from the keyboard. Two of the test games in the 663117632Sharti<CODE>ncurses</CODE> distribution (<CODE>bs</CODE> and <CODE>knight</CODE>) contain 664117632Sharticode that illustrates how this can be done. <P> 665117632Sharti 666117632ShartiSee the manual page <CODE>curs_mouse(3X)</CODE> for full details of the 667117632Shartimouse-interface functions. 668117632Sharti 669117632Sharti<H3><A NAME="finishing">Finishing Up</A></H3> 670117632Sharti 671117632ShartiIn order to clean up after the <CODE>ncurses</CODE> routines, the routine 672117632Sharti<CODE>endwin()</CODE> is provided. It restores tty modes to what they were when 673117632Sharti<CODE>initscr()</CODE> was first called, and moves the cursor down to the 674117632Shartilower-left corner. Thus, anytime after the call to initscr, <CODE>endwin()</CODE> 675117632Shartishould be called before exiting. 676117632Sharti 677117632Sharti<H2><A NAME="functions">Function Descriptions</A></H2> 678117632Sharti 679117632ShartiWe describe the detailed behavior of some important curses functions here, as a 680117632Shartisupplement to the manual page descriptions. 681117632Sharti 682117632Sharti<H3><A NAME="init">Initialization and Wrapup</A></H3> 683117632Sharti 684117632Sharti<DL> 685117632Sharti<DT> <CODE>initscr()</CODE> 686117632Sharti<DD> The first function called should almost always be <CODE>initscr()</CODE>. 687117632ShartiThis will determine the terminal type and 688117632Shartiinitialize curses data structures. <CODE>initscr()</CODE> also arranges that 689117632Shartithe first call to <CODE>refresh()</CODE> will clear the screen. If an error 690117632Shartioccurs a message is written to standard error and the program 691117632Shartiexits. Otherwise it returns a pointer to stdscr. A few functions may be 692117632Sharticalled before initscr (<CODE>slk_init()</CODE>, <CODE>filter()</CODE>, 693117632Sharti<CODE>ripofflines()</CODE>, <CODE>use_env()</CODE>, and, if you are using multiple 694117632Shartiterminals, <CODE>newterm()</CODE>.) 695117632Sharti<DT> <CODE>endwin()</CODE> 696117632Sharti<DD> Your program should always call <CODE>endwin()</CODE> before exiting or 697117632Shartishelling out of the program. This function will restore tty modes, 698117632Shartimove the cursor to the lower left corner of the screen, reset the 699117632Shartiterminal into the proper non-visual mode. Calling <CODE>refresh()</CODE> 700117632Shartior <CODE>doupdate()</CODE> after a temporary escape from the program will 701117632Shartirestore the ncurses screen from before the escape. 702117632Sharti<DT> <CODE>newterm(type, ofp, ifp)</CODE> 703117632Sharti<DD> A program which outputs to more than one terminal should use 704117632Sharti<CODE>newterm()</CODE> instead of <CODE>initscr()</CODE>. <CODE>newterm()</CODE> should 705117632Shartibe called once for each terminal. It returns a variable of type 706117632Sharti<CODE>SCREEN *</CODE> which should be saved as a reference to that 707117632Shartiterminal. 708117632Sharti(NOTE: a SCREEN variable is not a <em>screen</em> in the sense we 709117632Shartiare describing in this introduction, but a collection of 710117632Shartiparameters used to assist in optimizing the display.) 711117632ShartiThe arguments are the type of the terminal (a string) and 712117632Sharti<CODE>FILE</CODE> pointers for the output and input of the terminal. If 713117632Shartitype is NULL then the environment variable <CODE>$TERM</CODE> is used. 714117632Sharti<CODE>endwin()</CODE> should called once at wrapup time for each terminal 715117632Shartiopened using this function. 716117632Sharti<DT> <CODE>set_term(new)</CODE> 717117632Sharti<DD> This function is used to switch to a different terminal previously 718117632Shartiopened by <CODE>newterm()</CODE>. The screen reference for the new terminal 719117632Shartiis passed as the parameter. The previous terminal is returned by the 720117632Shartifunction. All other calls affect only the current terminal. 721117632Sharti<DT> <CODE>delscreen(sp)</CODE> 722117632Sharti<DD> The inverse of <CODE>newterm()</CODE>; deallocates the data structures 723117632Shartiassociated with a given <CODE>SCREEN</CODE> reference. 724117632Sharti</DL> 725117632Sharti 726117632Sharti<H3><A NAME="flush">Causing Output to the Terminal</A></H3> 727117632Sharti 728117632Sharti<DL> 729117632Sharti<DT> <CODE>refresh()</CODE> and <CODE>wrefresh(win)</CODE> 730117632Sharti<DD> These functions must be called to actually get any output on 731117632Shartithe terminal, as other routines merely manipulate data 732117632Shartistructures. <CODE>wrefresh()</CODE> copies the named window to the physical 733117632Shartiterminal screen, taking into account what is already 734117632Shartithere in order to do optimizations. <CODE>refresh()</CODE> does a 735117632Shartirefresh of <CODE>stdscr()</CODE>. Unless <CODE>leaveok()</CODE> has been 736117632Shartienabled, the physical cursor of the terminal is left at the 737117632Shartilocation of the window's cursor. 738117632Sharti<DT> <CODE>doupdate()</CODE> and <CODE>wnoutrefresh(win)</CODE> 739117632Sharti<DD> These two functions allow multiple updates with more efficiency 740117632Shartithan wrefresh. To use them, it is important to understand how curses 741117632Shartiworks. In addition to all the window structures, curses keeps two 742117632Shartidata structures representing the terminal screen: a physical screen, 743117632Shartidescribing what is actually on the screen, and a virtual screen, 744117632Shartidescribing what the programmer wants to have on the screen. wrefresh 745117632Shartiworks by first copying the named window to the virtual screen 746117632Sharti(<CODE>wnoutrefresh()</CODE>), and then calling the routine to update the 747117632Shartiscreen (<CODE>doupdate()</CODE>). If the programmer wishes to output 748117632Shartiseveral windows at once, a series of calls to <CODE>wrefresh</CODE> will result 749117632Shartiin alternating calls to <CODE>wnoutrefresh()</CODE> and <CODE>doupdate()</CODE>, 750117632Sharticausing several bursts of output to the screen. By calling 751117632Sharti<CODE>wnoutrefresh()</CODE> for each window, it is then possible to call 752117632Sharti<CODE>doupdate()</CODE> once, resulting in only one burst of output, with 753117632Shartifewer total characters transmitted (this also avoids a visually annoying 754117632Shartiflicker at each update). 755117632Sharti</DL> 756117632Sharti 757117632Sharti<H3><A NAME="lowlevel">Low-Level Capability Access</A></H3> 758117632Sharti 759117632Sharti<DL> 760117632Sharti<DT> <CODE>setupterm(term, filenum, errret)</CODE> 761117632Sharti<DD> This routine is called to initialize a terminal's description, without setting 762117632Shartiup the curses screen structures or changing the tty-driver mode bits. 763117632Sharti<CODE>term</CODE> is the character string representing the name of the terminal 764117632Shartibeing used. <CODE>filenum</CODE> is the UNIX file descriptor of the terminal to 765117632Shartibe used for output. <CODE>errret</CODE> is a pointer to an integer, in which a 766117632Shartisuccess or failure indication is returned. The values returned can be 1 (all 767117632Shartiis well), 0 (no such terminal), or -1 (some problem locating the terminfo 768117632Shartidatabase). <P> 769117632Sharti 770117632ShartiThe value of <CODE>term</CODE> can be given as NULL, which will cause the value of 771117632Sharti<CODE>TERM</CODE> in the environment to be used. The <CODE>errret</CODE> pointer can 772117632Shartialso be given as NULL, meaning no error code is wanted. If <CODE>errret</CODE> is 773117632Shartidefaulted, and something goes wrong, <CODE>setupterm()</CODE> will print an 774117632Shartiappropriate error message and exit, rather than returning. Thus, a simple 775117632Shartiprogram can call setupterm(0, 1, 0) and not worry about initialization 776117632Shartierrors. <P> 777117632Sharti 778117632ShartiAfter the call to <CODE>setupterm()</CODE>, the global variable <CODE>cur_term</CODE> is 779117632Shartiset to point to the current structure of terminal capabilities. By calling 780117632Sharti<CODE>setupterm()</CODE> for each terminal, and saving and restoring 781117632Sharti<CODE>cur_term</CODE>, it is possible for a program to use two or more terminals at 782117632Shartionce. <CODE>Setupterm()</CODE> also stores the names section of the terminal 783117632Shartidescription in the global character array <CODE>ttytype[]</CODE>. Subsequent calls 784117632Shartito <CODE>setupterm()</CODE> will overwrite this array, so you'll have to save it 785117632Shartiyourself if need be. 786117632Sharti</DL> 787117632Sharti 788117632Sharti<H3><A NAME="debugging">Debugging</A></H3> 789117632Sharti 790117632Sharti<!-- The 'note' tag is not portable enough --> 791117632Sharti<blockquote> 792117632Sharti<strong>NOTE:</strong> These functions are not part of the standard curses API! 793117632Sharti</blockquote> 794117632Sharti 795117632Sharti<DL> 796117632Sharti<DT> <CODE>trace()</CODE> 797117632Sharti<DD> 798117632ShartiThis function can be used to explicitly set a trace level. If the 799117632Shartitrace level is nonzero, execution of your program will generate a file 800117632Sharticalled `trace' in the current working directory containing a report on 801117632Shartithe library's actions. Higher trace levels enable more detailed (and 802117632Shartiverbose) reporting -- see comments attached to <CODE>TRACE_</CODE> defines 803117632Shartiin the <CODE>curses.h</CODE> file for details. (It is also possible to set 804117632Shartia trace level by assigning a trace level value to the environment variable 805117632Sharti<CODE>NCURSES_TRACE</CODE>). 806117632Sharti<DT> <CODE>_tracef()</CODE> 807117632Sharti<DD> 808117632ShartiThis function can be used to output your own debugging information. It is only 809117632Shartiavailable only if you link with -lncurses_g. It can be used the same way as 810117632Sharti<CODE>printf()</CODE>, only it outputs a newline after the end of arguments. 811117632ShartiThe output goes to a file called <CODE>trace</CODE> in the current directory. 812117632Sharti</DL> 813117632Sharti 814117632ShartiTrace logs can be difficult to interpret due to the sheer volume of 815117632Shartidata dumped in them. There is a script called <STRONG>tracemunch</STRONG> 816117632Shartiincluded with the <CODE>ncurses</CODE> distribution that can alleviate 817117632Shartithis problem somewhat; it compacts long sequences of similar operations into 818117632Shartimore succinct single-line pseudo-operations. These pseudo-ops can be 819117632Shartidistinguished by the fact that they are named in capital letters. 820117632Sharti 821117632Sharti<H2><A NAME="hints">Hints, Tips, and Tricks</A></H2> 822117632Sharti 823117632ShartiThe <CODE>ncurses</CODE> manual pages are a complete reference for this library. 824117632ShartiIn the remainder of this document, we discuss various useful methods that 825117632Shartimay not be obvious from the manual page descriptions. 826117632Sharti 827117632Sharti<H3><A NAME="caution">Some Notes of Caution</A></H3> 828117632Sharti 829117632ShartiIf you find yourself thinking you need to use <CODE>noraw()</CODE> or 830117632Sharti<CODE>nocbreak()</CODE>, think again and move carefully. It's probably 831117632Shartibetter design to use <CODE>getstr()</CODE> or one of its relatives to 832117632Shartisimulate cooked mode. The <CODE>noraw()</CODE> and <CODE>nocbreak()</CODE> 833117632Shartifunctions try to restore cooked mode, but they may end up clobbering 834117632Shartisome control bits set before you started your application. Also, they 835117632Shartihave always been poorly documented, and are likely to hurt your 836117632Shartiapplication's usability with other curses libraries. <P> 837117632Sharti 838117632ShartiBear in mind that <CODE>refresh()</CODE> is a synonym for <CODE>wrefresh(stdscr)</CODE>. 839117632ShartiDon't try to mix use of <CODE>stdscr</CODE> with use of windows declared 840117632Shartiby <CODE>newwin()</CODE>; a <CODE>refresh()</CODE> call will blow them off the 841117632Shartiscreen. The right way to handle this is to use <CODE>subwin()</CODE>, or 842117632Shartinot touch <CODE>stdscr</CODE> at all and tile your screen with declared 843117632Shartiwindows which you then <CODE>wnoutrefresh()</CODE> somewhere in your program 844117632Shartievent loop, with a single <CODE>doupdate()</CODE> call to trigger actual 845117632Shartirepainting. <P> 846117632Sharti 847117632ShartiYou are much less likely to run into problems if you design your screen 848117632Shartilayouts to use tiled rather than overlapping windows. Historically, 849117632Sharticurses support for overlapping windows has been weak, fragile, and poorly 850117632Shartidocumented. The <CODE>ncurses</CODE> library is not yet an exception to this 851117632Shartirule. <P> 852117632Sharti 853117632ShartiThere is a panels library included in the <CODE>ncurses</CODE> 854117632Shartidistribution that does a pretty good job of strengthening the 855117632Shartioverlapping-windows facilities. <P> 856117632Sharti 857117632ShartiTry to avoid using the global variables LINES and COLS. Use 858117632Sharti<CODE>getmaxyx()</CODE> on the <CODE>stdscr</CODE> context instead. Reason: 859117632Shartiyour code may be ported to run in an environment with window resizes, 860117632Shartiin which case several screens could be open with different sizes. 861117632Sharti 862117632Sharti<H3><A NAME="leaving">Temporarily Leaving NCURSES Mode</A></H3> 863117632Sharti 864117632ShartiSometimes you will want to write a program that spends most of its time in 865117632Shartiscreen mode, but occasionally returns to ordinary `cooked' mode. A common 866117632Shartireason for this is to support shell-out. This behavior is simple to arrange 867117632Shartiin <CODE>ncurses</CODE>. <P> 868117632Sharti 869117632ShartiTo leave <CODE>ncurses</CODE> mode, call <CODE>endwin()</CODE> as you would if you 870117632Shartiwere intending to terminate the program. This will take the screen back to 871117632Sharticooked mode; you can do your shell-out. When you want to return to 872117632Sharti<CODE>ncurses</CODE> mode, simply call <CODE>refresh()</CODE> or <CODE>doupdate()</CODE>. 873117632ShartiThis will repaint the screen. <P> 874117632Sharti 875117632ShartiThere is a boolean function, <CODE>isendwin()</CODE>, which code can use to 876117632Shartitest whether <CODE>ncurses</CODE> screen mode is active. It returns <CODE>TRUE</CODE> 877117632Shartiin the interval between an <CODE>endwin()</CODE> call and the following 878117632Sharti<CODE>refresh()</CODE>, <CODE>FALSE</CODE> otherwise. <P> 879117632Sharti 880117632ShartiHere is some sample code for shellout: 881117632Sharti 882117632Sharti<PRE> 883117632Sharti addstr("Shelling out..."); 884117632Sharti def_prog_mode(); /* save current tty modes */ 885117632Sharti endwin(); /* restore original tty modes */ 886117632Sharti system("sh"); /* run shell */ 887117632Sharti addstr("returned.\n"); /* prepare return message */ 888117632Sharti refresh(); /* restore save modes, repaint screen */ 889117632Sharti</PRE> 890117632Sharti 891117632Sharti<H3><A NAME="xterm">Using NCURSES under XTERM</A></H3> 892117632Sharti 893117632ShartiA resize operation in X sends SIGWINCH to the application running under xterm. 894117632ShartiThe <CODE>ncurses</CODE> library provides an experimental signal 895117632Shartihandler, but in general does not catch this signal, because it cannot 896117632Shartiknow how you want the screen re-painted. You will usually have to write the 897117632ShartiSIGWINCH handler yourself. Ncurses can give you some help. <P> 898117632Sharti 899117632ShartiThe easiest way to code your SIGWINCH handler is to have it do an 900117632Sharti<CODE>endwin</CODE>, followed by an <CODE>refresh</CODE> and a screen repaint you code 901117632Shartiyourself. The <CODE>refresh</CODE> will pick up the new screen size from the 902117632Shartixterm's environment. <P> 903117632Sharti 904117632ShartiThat is the standard way, of course (it even works with some vendor's curses 905117632Shartiimplementations). 906117632ShartiIts drawback is that it clears the screen to reinitialize the display, and does 907117632Shartinot resize subwindows which must be shrunk. 908117632Sharti<CODE>Ncurses</CODE> provides an extension which works better, the 909117632Sharti<CODE>resizeterm</CODE> function. That function ensures that all windows 910117632Shartiare limited to the new screen dimensions, and pads <CODE>stdscr</CODE> 911117632Shartiwith blanks if the screen is larger. <P> 912117632Sharti 913117632ShartiFinally, ncurses can be configured to provide its own SIGWINCH handler, 914117632Shartibased on <CODE>resizeterm</CODE>. 915117632Sharti 916117632Sharti<H3><A NAME="screens">Handling Multiple Terminal Screens</A></H3> 917117632Sharti 918117632ShartiThe <CODE>initscr()</CODE> function actually calls a function named 919117632Sharti<CODE>newterm()</CODE> to do most of its work. If you are writing a program that 920117632Shartiopens multiple terminals, use <CODE>newterm()</CODE> directly. <P> 921117632Sharti 922117632ShartiFor each call, you will have to specify a terminal type and a pair of file 923117632Shartipointers; each call will return a screen reference, and <CODE>stdscr</CODE> will be 924117632Shartiset to the last one allocated. You will switch between screens with the 925117632Sharti<CODE>set_term</CODE> call. Note that you will also have to call 926117632Sharti<CODE>def_shell_mode</CODE> and <CODE>def_prog_mode</CODE> on each tty yourself. 927117632Sharti 928117632Sharti<H3><A NAME="testing">Testing for Terminal Capabilities</A></H3> 929117632Sharti 930117632ShartiSometimes you may want to write programs that test for the presence of various 931117632Sharticapabilities before deciding whether to go into <CODE>ncurses</CODE> mode. An easy 932117632Shartiway to do this is to call <CODE>setupterm()</CODE>, then use the functions 933117632Sharti<CODE>tigetflag()</CODE>, <CODE>tigetnum()</CODE>, and <CODE>tigetstr()</CODE> to do your 934117632Shartitesting. <P> 935117632Sharti 936117632ShartiA particularly useful case of this often comes up when you want to 937117632Shartitest whether a given terminal type should be treated as `smart' 938117632Sharti(cursor-addressable) or `stupid'. The right way to test this is to see 939117632Shartiif the return value of <CODE>tigetstr("cup")</CODE> is non-NULL. Alternatively, 940117632Shartiyou can include the <CODE>term.h</CODE> file and test the value of the 941117632Shartimacro <CODE>cursor_address</CODE>. 942117632Sharti 943117632Sharti<H3><A NAME="tuning">Tuning for Speed</A></H3> 944117632Sharti 945117632ShartiUse the <CODE>addchstr()</CODE> family of functions for fast 946117632Shartiscreen-painting of text when you know the text doesn't contain any 947117632Sharticontrol characters. Try to make attribute changes infrequent on your 948117632Shartiscreens. Don't use the <CODE>immedok()</CODE> option! 949117632Sharti 950117632Sharti<H3><A NAME="special">Special Features of NCURSES</A></H3> 951117632Sharti 952117632ShartiThe <CODE>wresize()</CODE> function allows you to resize a window in place. 953117632ShartiThe associated <CODE>resizeterm()</CODE> function simplifies the construction 954117632Shartiof <a HREF="#xterm">SIGWINCH</a> handlers, for resizing all windows. <P> 955117632Sharti 956117632ShartiThe <CODE>define_key()</CODE> function allows you 957117632Shartito define at runtime function-key control sequences which are not in the 958117632Shartiterminal description. 959117632ShartiThe <CODE>keyok()</CODE> function allows you to temporarily 960117632Shartienable or disable interpretation of any function-key control sequence. <P> 961117632Sharti 962117632ShartiThe <CODE>use_default_colors()</CODE> function allows you to construct 963117632Shartiapplications which can use the terminal's default foreground and 964117632Shartibackground colors as an additional "default" color. 965117632ShartiSeveral terminal emulators support this feature, which is based on ISO 6429. <P> 966117632Sharti 967117632ShartiNcurses supports up 16 colors, unlike SVr4 curses which defines only 8. 968117632ShartiWhile most terminals which provide color allow only 8 colors, about 969117632Shartia quarter (including XFree86 xterm) support 16 colors. 970117632Sharti 971117632Sharti<H2><A NAME="compat">Compatibility with Older Versions</A></H2> 972117632Sharti 973117632ShartiDespite our best efforts, there are some differences between <CODE>ncurses</CODE> 974117632Shartiand the (undocumented!) behavior of older curses implementations. These arise 975117632Shartifrom ambiguities or omissions in the documentation of the API. 976117632Sharti 977117632Sharti<H3><A NAME="refbug">Refresh of Overlapping Windows</A></H3> 978117632Sharti 979117632ShartiIf you define two windows A and B that overlap, and then alternately scribble 980117632Shartion and refresh them, the changes made to the overlapping region under historic 981117632Sharti<CODE>curses</CODE> versions were often not documented precisely. <P> 982117632Sharti 983117632ShartiTo understand why this is a problem, remember that screen updates are 984117632Sharticalculated between two representations of the <EM>entire</EM> display. The 985117632Shartidocumentation says that when you refresh a window, it is first copied to to the 986117632Shartivirtual screen, and then changes are calculated to update the physical screen 987117632Sharti(and applied to the terminal). But "copied to" is not very specific, and 988117632Shartisubtle differences in how copying works can produce different behaviors in the 989117632Sharticase where two overlapping windows are each being refreshed at unpredictable 990117632Shartiintervals. <P> 991117632Sharti 992117632ShartiWhat happens to the overlapping region depends on what <CODE>wnoutrefresh()</CODE> 993117632Shartidoes with its argument -- what portions of the argument window it copies to the 994117632Shartivirtual screen. Some implementations do "change copy", copying down only 995117632Shartilocations in the window that have changed (or been marked changed with 996117632Sharti<CODE>wtouchln()</CODE> and friends). Some implementations do "entire copy", 997117632Sharticopying <EM>all</EM> window locations to the virtual screen whether or not 998117632Shartithey have changed. <P> 999117632Sharti 1000117632ShartiThe <CODE>ncurses</CODE> library itself has not always been consistent on this 1001117632Shartiscore. Due to a bug, versions 1.8.7 to 1.9.8a did entire copy. Versions 1002117632Sharti1.8.6 and older, and versions 1.9.9 and newer, do change copy. <P> 1003117632Sharti 1004117632ShartiFor most commercial curses implementations, it is not documented and not known 1005117632Shartifor sure (at least not to the <CODE>ncurses</CODE> maintainers) whether they do 1006117632Shartichange copy or entire copy. We know that System V release 3 curses has logic 1007117632Shartiin it that looks like an attempt to do change copy, but the surrounding logic 1008117632Shartiand data representations are sufficiently complex, and our knowledge 1009117632Shartisufficiently indirect, that it's hard to know whether this is reliable. 1010117632Sharti 1011117632ShartiIt is not clear what the SVr4 documentation and XSI standard intend. The XSI 1012117632ShartiCurses standard barely mentions wnoutrefresh(); the SVr4 documents seem to be 1013117632Shartidescribing entire-copy, but it is possible with some effort and straining to 1014117632Shartiread them the other way. <P> 1015117632Sharti 1016117632ShartiIt might therefore be unwise to rely on either behavior in programs that might 1017117632Shartihave to be linked with other curses implementations. Instead, you can do an 1018117632Shartiexplicit <CODE>touchwin()</CODE> before the <CODE>wnoutrefresh()</CODE> call to 1019117632Shartiguarantee an entire-contents copy anywhere. <P> 1020117632Sharti 1021117632ShartiThe really clean way to handle this is to use the panels library. If, 1022117632Shartiwhen you want a screen update, you do <CODE>update_panels()</CODE>, it will 1023117632Shartido all the necessary <CODE>wnoutrfresh()</CODE> calls for whatever panel 1024117632Shartistacking order you have defined. Then you can do one <CODE>doupdate()</CODE> 1025117632Shartiand there will be a <EM>single</EM> burst of physical I/O that will do 1026117632Shartiall your updates. 1027117632Sharti 1028117632Sharti<H3><A NAME="backbug">Background Erase</A></H3> 1029117632Sharti 1030117632ShartiIf you have been using a very old versions of <CODE>ncurses</CODE> (1.8.7 or 1031117632Shartiolder) you may be surprised by the behavior of the erase functions. In older 1032117632Shartiversions, erased areas of a window were filled with a blank modified by the 1033117632Shartiwindow's current attribute (as set by <STRONG>wattrset()</STRONG>, <STRONG>wattron()</STRONG>, 1034117632Sharti<STRONG>wattroff()</STRONG> and friends). <P> 1035117632Sharti 1036117632ShartiIn newer versions, this is not so. Instead, the attribute of erased blanks 1037117632Shartiis normal unless and until it is modified by the functions <CODE>bkgdset()</CODE> 1038117632Shartior <CODE>wbkgdset()</CODE>. <P> 1039117632Sharti 1040117632ShartiThis change in behavior conforms <CODE>ncurses</CODE> to System V Release 4 and 1041117632Shartithe XSI Curses standard. 1042117632Sharti 1043117632Sharti<H2><A NAME="xsifuncs">XSI Curses Conformance</A></H2> 1044117632Sharti 1045117632ShartiThe <CODE>ncurses</CODE> library is intended to be base-level conformant with the 1046117632ShartiXSI Curses standard from X/Open. Many extended-level features (in fact, almost 1047117632Shartiall features not directly concerned with wide characters and 1048117632Shartiinternationalization) are also supported. <P> 1049117632Sharti 1050117632ShartiOne effect of XSI conformance is the change in behavior described under 1051117632Sharti<A HREF="#backbug">"Background Erase -- Compatibility with Old Versions"</A>. <P> 1052117632Sharti 1053117632ShartiAlso, <CODE>ncurses</CODE> meets the XSI requirement that every macro 1054117632Shartientry point have a corresponding function which may be linked (and 1055117632Shartiwill be prototype-checked) if the macro definition is disabled with 1056117632Sharti<CODE>#undef</CODE>. 1057117632Sharti 1058117632Sharti<H1><A NAME="panels">The Panels Library</A></H1> 1059117632Sharti 1060117632ShartiThe <CODE>ncurses</CODE> library by itself provides good support for screen 1061117632Shartidisplays in which the windows are tiled (non-overlapping). In the more 1062117632Shartigeneral case that windows may overlap, you have to use a series of 1063117632Sharti<CODE>wnoutrefresh()</CODE> calls followed by a <CODE>doupdate()</CODE>, and be 1064117632Sharticareful about the order you do the window refreshes in. It has to be 1065117632Shartibottom-upwards, otherwise parts of windows that should be obscured will 1066117632Shartishow through. <P> 1067117632Sharti 1068117632ShartiWhen your interface design is such that windows may dive deeper into the 1069117632Shartivisibility stack or pop to the top at runtime, the resulting book-keeping 1070117632Shartican be tedious and difficult to get right. Hence the panels library. <P> 1071117632Sharti 1072117632ShartiThe <CODE>panel</CODE> library first appeared in AT&T System V. The 1073117632Shartiversion documented here is the <CODE>panel</CODE> code distributed 1074117632Shartiwith <CODE>ncurses</CODE>. 1075117632Sharti 1076117632Sharti<H2><A NAME="pcompile">Compiling With the Panels Library</A></H2> 1077117632Sharti 1078117632ShartiYour panels-using modules must import the panels library declarations with 1079117632Sharti 1080117632Sharti<PRE> 1081117632Sharti #include <panel.h> 1082117632Sharti</PRE> 1083117632Sharti 1084117632Shartiand must be linked explicitly with the panels library using an 1085117632Sharti<CODE>-lpanel</CODE> argument. Note that they must also link the 1086117632Sharti<CODE>ncurses</CODE> library with <CODE>-lncurses</CODE>. Many linkers 1087117632Shartiare two-pass and will accept either order, but it is still good practice 1088117632Shartito put <CODE>-lpanel</CODE> first and <CODE>-lncurses</CODE> second. 1089117632Sharti 1090117632Sharti<H2><A NAME="poverview">Overview of Panels</A></H2> 1091117632Sharti 1092117632ShartiA panel object is a window that is implicitly treated as part of a 1093117632Sharti<DFN>deck</DFN> including all other panel objects. The deck has an implicit 1094117632Shartibottom-to-top visibility order. The panels library includes an update 1095117632Shartifunction (analogous to <CODE>refresh()</CODE>) that displays all panels in the 1096117632Shartideck in the proper order to resolve overlaps. The standard window, 1097117632Sharti<CODE>stdscr</CODE>, is considered below all panels. <P> 1098117632Sharti 1099117632ShartiDetails on the panels functions are available in the man pages. We'll just 1100117632Shartihit the highlights here. <P> 1101117632Sharti 1102117632ShartiYou create a panel from a window by calling <CODE>new_panel()</CODE> on a 1103117632Shartiwindow pointer. It then becomes the top of the deck. The panel's window 1104117632Shartiis available as the value of <CODE>panel_window()</CODE> called with the 1105117632Shartipanel pointer as argument.<P> 1106117632Sharti 1107117632ShartiYou can delete a panel (removing it from the deck) with <CODE>del_panel</CODE>. 1108117632ShartiThis will not deallocate the associated window; you have to do that yourself. 1109117632Sharti 1110117632ShartiYou can replace a panel's window with a different window by calling 1111117632Sharti<CODE>replace_window</CODE>. The new window may be of different size; 1112117632Shartithe panel code will re-compute all overlaps. This operation doesn't 1113117632Shartichange the panel's position in the deck. <P> 1114117632Sharti 1115117632ShartiTo move a panel's window, use <CODE>move_panel()</CODE>. The 1116117632Sharti<CODE>mvwin()</CODE> function on the panel's window isn't sufficient because it 1117117632Shartidoesn't update the panels library's representation of where the windows are. 1118117632ShartiThis operation leaves the panel's depth, contents, and size unchanged. <P> 1119117632Sharti 1120117632ShartiTwo functions (<CODE>top_panel()</CODE>, <CODE>bottom_panel()</CODE>) are 1121117632Shartiprovided for rearranging the deck. The first pops its argument window to the 1122117632Shartitop of the deck; the second sends it to the bottom. Either operation leaves 1123117632Shartithe panel's screen location, contents, and size unchanged. <P> 1124117632Sharti 1125117632ShartiThe function <CODE>update_panels()</CODE> does all the 1126117632Sharti<CODE>wnoutrefresh()</CODE> calls needed to prepare for 1127117632Sharti<CODE>doupdate()</CODE> (which you must call yourself, afterwards). <P> 1128117632Sharti 1129117632ShartiTypically, you will want to call <CODE>update_panels()</CODE> and 1130117632Sharti<CODE>doupdate()</CODE> just before accepting command input, once in each cycle 1131117632Shartiof interaction with the user. If you call <CODE>update_panels()</CODE> after 1132117632Shartieach and every panel write, you'll generate a lot of unnecessary refresh 1133117632Shartiactivity and screen flicker. 1134117632Sharti 1135117632Sharti<H2><A NAME="pstdscr">Panels, Input, and the Standard Screen</A></H2> 1136117632Sharti 1137117632ShartiYou shouldn't mix <CODE>wnoutrefresh()</CODE> or <CODE>wrefresh()</CODE> 1138117632Shartioperations with panels code; this will work only if the argument window 1139117632Shartiis either in the top panel or unobscured by any other panels. <P> 1140117632Sharti 1141117632ShartiThe <CODE>stsdcr</CODE> window is a special case. It is considered below all 1142117632Shartipanels. Because changes to panels may obscure parts of <CODE>stdscr</CODE>, 1143117632Shartithough, you should call <CODE>update_panels()</CODE> before 1144117632Sharti<CODE>doupdate()</CODE> even when you only change <CODE>stdscr</CODE>. <P> 1145117632Sharti 1146117632ShartiNote that <CODE>wgetch</CODE> automatically calls <CODE>wrefresh</CODE>. 1147117632ShartiTherefore, before requesting input from a panel window, you need to be sure 1148117632Shartithat the panel is totally unobscured. <P> 1149117632Sharti 1150117632ShartiThere is presently no way to display changes to one obscured panel without 1151117632Shartirepainting all panels. 1152117632Sharti 1153117632Sharti<H2><A NAME="hiding">Hiding Panels</A></H2> 1154117632Sharti 1155117632ShartiIt's possible to remove a panel from the deck temporarily; use 1156117632Sharti<CODE>hide_panel</CODE> for this. Use <CODE>show_panel()</CODE> to render it 1157117632Shartivisible again. The predicate function <CODE>panel_hidden</CODE> 1158117632Shartitests whether or not a panel is hidden. <P> 1159117632Sharti 1160117632ShartiThe <CODE>panel_update</CODE> code ignores hidden panels. You cannot do 1161117632Sharti<CODE>top_panel()</CODE> or <CODE>bottom_panel</CODE> on a hidden panel(). 1162117632ShartiOther panels operations are applicable. 1163117632Sharti 1164117632Sharti<H2><A NAME="pmisc">Miscellaneous Other Facilities</A></H2> 1165117632Sharti 1166117632ShartiIt's possible to navigate the deck using the functions 1167117632Sharti<CODE>panel_above()</CODE> and <CODE>panel_below</CODE>. Handed a panel 1168117632Shartipointer, they return the panel above or below that panel. Handed 1169117632Sharti<CODE>NULL</CODE>, they return the bottom-most or top-most panel. <P> 1170117632Sharti 1171117632ShartiEvery panel has an associated user pointer, not used by the panel code, to 1172117632Shartiwhich you can attach application data. See the man page documentation 1173117632Shartiof <CODE>set_panel_userptr()</CODE> and <CODE>panel_userptr</CODE> for 1174117632Shartidetails. 1175117632Sharti 1176117632Sharti<H1><A NAME="menu">The Menu Library</A></H1> 1177117632Sharti 1178117632ShartiA menu is a screen display that assists the user to choose some subset 1179117632Shartiof a given set of items. The <CODE>menu</CODE> library is a curses 1180117632Shartiextension that supports easy programming of menu hierarchies with a 1181117632Shartiuniform but flexible interface. <P> 1182117632Sharti 1183117632ShartiThe <CODE>menu</CODE> library first appeared in AT&T System V. The 1184117632Shartiversion documented here is the <CODE>menu</CODE> code distributed 1185117632Shartiwith <CODE>ncurses</CODE>. 1186117632Sharti 1187117632Sharti<H2><A NAME="mcompile">Compiling With the menu Library</A></H2> 1188117632Sharti 1189117632ShartiYour menu-using modules must import the menu library declarations with 1190117632Sharti 1191117632Sharti<PRE> 1192117632Sharti #include <menu.h> 1193117632Sharti</PRE> 1194117632Sharti 1195117632Shartiand must be linked explicitly with the menus library using an 1196117632Sharti<CODE>-lmenu</CODE> argument. Note that they must also link the 1197117632Sharti<CODE>ncurses</CODE> library with <CODE>-lncurses</CODE>. Many linkers 1198117632Shartiare two-pass and will accept either order, but it is still good practice 1199117632Shartito put <CODE>-lmenu</CODE> first and <CODE>-lncurses</CODE> second. 1200117632Sharti 1201117632Sharti<H2><A NAME="moverview">Overview of Menus</A></H2> 1202117632Sharti 1203117632ShartiThe menus created by this library consist of collections of 1204117632Sharti<DFN>items</DFN> including a name string part and a description string 1205117632Shartipart. To make menus, you create groups of these items and connect 1206117632Shartithem with menu frame objects. <P> 1207117632Sharti 1208117632ShartiThe menu can then by <DFN>posted</DFN>, that is written to an 1209117632Shartiassociated window. Actually, each menu has two associated windows; a 1210117632Sharticontaining window in which the programmer can scribble titles or 1211117632Shartiborders, and a subwindow in which the menu items proper are displayed. 1212117632ShartiIf this subwindow is too small to display all the items, it will be a 1213117632Shartiscrollable viewport on the collection of items. <P> 1214117632Sharti 1215117632ShartiA menu may also be <DFN>unposted</DFN> (that is, undisplayed), and finally 1216117632Shartifreed to make the storage associated with it and its items available for 1217117632Shartire-use. <P> 1218117632Sharti 1219117632ShartiThe general flow of control of a menu program looks like this: 1220117632Sharti 1221117632Sharti<OL> 1222117632Sharti<LI>Initialize <CODE>curses</CODE>. 1223117632Sharti<LI>Create the menu items, using <CODE>new_item()</CODE>. 1224117632Sharti<LI>Create the menu using <CODE>new_menu()</CODE>. 1225117632Sharti<LI>Post the menu using <CODE>menu_post()</CODE>. 1226117632Sharti<LI>Refresh the screen. 1227117632Sharti<LI>Process user requests via an input loop. 1228117632Sharti<LI>Unpost the menu using <CODE>menu_unpost()</CODE>. 1229117632Sharti<LI>Free the menu, using <CODE>free_menu()</CODE>. 1230117632Sharti<LI>Free the items using <CODE>free_item()</CODE>. 1231117632Sharti<LI>Terminate <CODE>curses</CODE>. 1232117632Sharti</OL> 1233117632Sharti 1234117632Sharti<H2><A NAME="mselect">Selecting items</A></H2> 1235117632Sharti 1236117632ShartiMenus may be multi-valued or (the default) single-valued (see the manual 1237117632Shartipage <CODE>menu_opts(3x)</CODE> to see how to change the default). 1238117632ShartiBoth types always have a <DFN>current item</DFN>. <P> 1239117632Sharti 1240117632ShartiFrom a single-valued menu you can read the selected value simply by looking 1241117632Shartiat the current item. From a multi-valued menu, you get the selected set 1242117632Shartiby looping through the items applying the <CODE>item_value()</CODE> 1243117632Shartipredicate function. Your menu-processing code can use the function 1244117632Sharti<CODE>set_item_value()</CODE> to flag the items in the select set. <P> 1245117632Sharti 1246117632ShartiMenu items can be made unselectable using <CODE>set_item_opts()</CODE> 1247117632Shartior <CODE>item_opts_off()</CODE> with the <CODE>O_SELECTABLE</CODE> 1248117632Shartiargument. This is the only option so far defined for menus, but it 1249117632Shartiis good practice to code as though other option bits might be on. 1250117632Sharti 1251117632Sharti<H2><A NAME="mdisplay">Menu Display</A></H2> 1252117632Sharti 1253117632ShartiThe menu library calculates a minimum display size for your window, based 1254117632Shartion the following variables: 1255117632Sharti 1256117632Sharti<UL> 1257117632Sharti<LI>The number and maximum length of the menu items 1258117632Sharti<LI>Whether the O_ROWMAJOR option is enabled 1259117632Sharti<LI>Whether display of descriptions is enabled 1260117632Sharti<LI>Whatever menu format may have been set by the programmer 1261117632Sharti<LI>The length of the menu mark string used for highlighting selected items 1262117632Sharti</UL> 1263117632Sharti 1264117632ShartiThe function <CODE>set_menu_format()</CODE> allows you to set the 1265117632Shartimaximum size of the viewport or <DFN>menu page</DFN> that will be used 1266117632Shartito display menu items. You can retrieve any format associated with a 1267117632Shartimenu with <CODE>menu_format()</CODE>. The default format is rows=16, 1268117632Sharticolumns=1. <P> 1269117632Sharti 1270117632ShartiThe actual menu page may be smaller than the format size. This depends 1271117632Shartion the item number and size and whether O_ROWMAJOR is on. This option 1272117632Sharti(on by default) causes menu items to be displayed in a `raster-scan' 1273117632Shartipattern, so that if more than one item will fit horizontally the first 1274117632Sharticouple of items are side-by-side in the top row. The alternative is 1275117632Sharticolumn-major display, which tries to put the first several items in 1276117632Shartithe first column. <P> 1277117632Sharti 1278117632ShartiAs mentioned above, a menu format not large enough to allow all items to fit 1279117632Shartion-screen will result in a menu display that is vertically scrollable. <P> 1280117632ShartiYou can scroll it with requests to the menu driver, which will be described 1281117632Shartiin the section on <A HREF="#minput">menu input handling</A>. <P> 1282117632Sharti 1283117632ShartiEach menu has a <DFN>mark string</DFN> used to visually tag selected items; 1284117632Shartisee the <CODE>menu_mark(3x)</CODE> manual page for details. The mark 1285117632Shartistring length also influences the menu page size. <P> 1286117632Sharti 1287117632ShartiThe function <CODE>scale_menu()</CODE> returns the minimum display size 1288117632Shartithat the menu code computes from all these factors. 1289117632Sharti 1290117632ShartiThere are other menu display attributes including a select attribute, 1291117632Shartian attribute for selectable items, an attribute for unselectable items, 1292117632Shartiand a pad character used to separate item name text from description 1293117632Shartitext. These have reasonable defaults which the library allows you to 1294117632Shartichange (see the <CODE>menu_attribs(3x)</CODE> manual page. 1295117632Sharti 1296117632Sharti<H2><A NAME="mwindows">Menu Windows</A></H2> 1297117632Sharti 1298117632ShartiEach menu has, as mentioned previously, a pair of associated windows. 1299117632ShartiBoth these windows are painted when the menu is posted and erased when 1300117632Shartithe menu is unposted. <P> 1301117632Sharti 1302117632ShartiThe outer or frame window is not otherwise touched by the menu 1303117632Shartiroutines. It exists so the programmer can associate a title, a 1304117632Shartiborder, or perhaps help text with the menu and have it properly 1305117632Shartirefreshed or erased at post/unpost time. The inner window or 1306117632Sharti<DFN>subwindow</DFN> is where the current menu page is displayed. <P> 1307117632Sharti 1308117632ShartiBy default, both windows are <CODE>stdscr</CODE>. You can set them with the 1309117632Shartifunctions in <CODE>menu_win(3x)</CODE>. <P> 1310117632Sharti 1311117632ShartiWhen you call <CODE>menu_post()</CODE>, you write the menu to its 1312117632Shartisubwindow. When you call <CODE>menu_unpost()</CODE>, you erase the 1313117632Shartisubwindow, However, neither of these actually modifies the screen. To 1314117632Shartido that, call <CODE>wrefresh()</CODE> or some equivalent. 1315117632Sharti 1316117632Sharti<H2><A NAME="minput">Processing Menu Input</A></H2> 1317117632Sharti 1318117632ShartiThe main loop of your menu-processing code should call 1319117632Sharti<CODE>menu_driver()</CODE> repeatedly. The first argument of this routine 1320117632Shartiis a menu pointer; the second is a menu command code. You should write an 1321117632Shartiinput-fetching routine that maps input characters to menu command codes, and 1322117632Shartipass its output to <CODE>menu_driver()</CODE>. The menu command codes are 1323117632Shartifully documented in <CODE>menu_driver(3x)</CODE>. <P> 1324117632Sharti 1325117632ShartiThe simplest group of command codes is <CODE>REQ_NEXT_ITEM</CODE>, 1326117632Sharti<CODE>REQ_PREV_ITEM</CODE>, <CODE>REQ_FIRST_ITEM</CODE>, 1327117632Sharti<CODE>REQ_LAST_ITEM</CODE>, <CODE>REQ_UP_ITEM</CODE>, 1328117632Sharti<CODE>REQ_DOWN_ITEM</CODE>, <CODE>REQ_LEFT_ITEM</CODE>, 1329117632Sharti<CODE>REQ_RIGHT_ITEM</CODE>. These change the currently selected 1330117632Shartiitem. These requests may cause scrolling of the menu page if it only 1331117632Shartipartially displayed. <P> 1332117632Sharti 1333117632ShartiThere are explicit requests for scrolling which also change the 1334117632Sharticurrent item (because the select location does not change, but the 1335117632Shartiitem there does). These are <CODE>REQ_SCR_DLINE</CODE>, 1336117632Sharti<CODE>REQ_SCR_ULINE</CODE>, <CODE>REQ_SCR_DPAGE</CODE>, and 1337117632Sharti<CODE>REQ_SCR_UPAGE</CODE>. <P> 1338117632Sharti 1339117632ShartiThe <CODE>REQ_TOGGLE_ITEM</CODE> selects or deselects the current item. 1340117632ShartiIt is for use in multi-valued menus; if you use it with <CODE>O_ONEVALUE</CODE> 1341117632Shartion, you'll get an error return (<CODE>E_REQUEST_DENIED</CODE>). <P> 1342117632Sharti 1343117632ShartiEach menu has an associated pattern buffer. The 1344117632Sharti<CODE>menu_driver()</CODE> logic tries to accumulate printable ASCII 1345117632Sharticharacters passed in in that buffer; when it matches a prefix of an 1346117632Shartiitem name, that item (or the next matching item) is selected. If 1347117632Shartiappending a character yields no new match, that character is deleted 1348117632Shartifrom the pattern buffer, and <CODE>menu_driver()</CODE> returns 1349117632Sharti<CODE>E_NO_MATCH</CODE>. <P> 1350117632Sharti 1351117632ShartiSome requests change the pattern buffer directly: 1352117632Sharti<CODE>REQ_CLEAR_PATTERN</CODE>, <CODE>REQ_BACK_PATTERN</CODE>, 1353117632Sharti<CODE>REQ_NEXT_MATCH</CODE>, <CODE>REQ_PREV_MATCH</CODE>. The latter 1354117632Shartitwo are useful when pattern buffer input matches more than one item 1355117632Shartiin a multi-valued menu. <P> 1356117632Sharti 1357117632ShartiEach successful scroll or item navigation request clears the pattern 1358117632Shartibuffer. It is also possible to set the pattern buffer explicitly 1359117632Shartiwith <CODE>set_menu_pattern()</CODE>. <P> 1360117632Sharti 1361117632ShartiFinally, menu driver requests above the constant <CODE>MAX_COMMAND</CODE> 1362117632Shartiare considered application-specific commands. The <CODE>menu_driver()</CODE> 1363117632Sharticode ignores them and returns <CODE>E_UNKNOWN_COMMAND</CODE>. 1364117632Sharti 1365117632Sharti<H2><A NAME="mmisc">Miscellaneous Other Features</A></H2> 1366117632Sharti 1367117632ShartiVarious menu options can affect the processing and visual appearance 1368117632Shartiand input processing of menus. See <CODE>menu_opts(3x) for 1369117632Shartidetails.</CODE> <P> 1370117632Sharti 1371117632ShartiIt is possible to change the current item from application code; this 1372117632Shartiis useful if you want to write your own navigation requests. It is 1373117632Shartialso possible to explicitly set the top row of the menu display. See 1374117632Sharti<CODE>mitem_current(3x)</CODE>. 1375117632Sharti 1376117632ShartiIf your application needs to change the menu subwindow cursor for 1377117632Shartiany reason, <CODE>pos_menu_cursor()</CODE> will restore it to the 1378117632Sharticorrect location for continuing menu driver processing. <P> 1379117632Sharti 1380117632ShartiIt is possible to set hooks to be called at menu initialization and 1381117632Shartiwrapup time, and whenever the selected item changes. See 1382117632Sharti<CODE>menu_hook(3x)</CODE>. <P> 1383117632Sharti 1384117632ShartiEach item, and each menu, has an associated user pointer on which you 1385117632Shartican hang application data. See <CODE>mitem_userptr(3x)</CODE> and 1386117632Sharti<CODE>menu_userptr(3x)</CODE>. 1387117632Sharti 1388117632Sharti<H1><A NAME="form">The Forms Library</A></H1> 1389117632Sharti 1390117632ShartiThe <CODE>form</CODE> library is a curses extension that supports easy 1391117632Shartiprogramming of on-screen forms for data entry and program control. <P> 1392117632Sharti 1393117632ShartiThe <CODE>form</CODE> library first appeared in AT&T System V. The 1394117632Shartiversion documented here is the <CODE>form</CODE> code distributed 1395117632Shartiwith <CODE>ncurses</CODE>. 1396117632Sharti 1397117632Sharti<H2><A NAME="fcompile">Compiling With the form Library</A></H2> 1398117632Sharti 1399117632ShartiYour form-using modules must import the form library declarations with 1400117632Sharti 1401117632Sharti<PRE> 1402117632Sharti #include <form.h> 1403117632Sharti</PRE> 1404117632Sharti 1405117632Shartiand must be linked explicitly with the forms library using an 1406117632Sharti<CODE>-lform</CODE> argument. Note that they must also link the 1407117632Sharti<CODE>ncurses</CODE> library with <CODE>-lncurses</CODE>. Many linkers 1408117632Shartiare two-pass and will accept either order, but it is still good practice 1409117632Shartito put <CODE>-lform</CODE> first and <CODE>-lncurses</CODE> second. 1410117632Sharti 1411117632Sharti<H2><A NAME="foverview">Overview of Forms</A></H2> 1412117632Sharti 1413117632ShartiA form is a collection of fields; each field may be either a label 1414117632Sharti(explanatory text) or a data-entry location. Long forms may be 1415117632Shartisegmented into pages; each entry to a new page clears the screen. <P> 1416117632ShartiTo make forms, you create groups of fields and connect them with form 1417117632Shartiframe objects; the form library makes this relatively simple. <P> 1418117632Sharti 1419117632ShartiOnce defined, a form can be <DFN>posted</DFN>, that is written to an 1420117632Shartiassociated window. Actually, each form has two associated windows; a 1421117632Sharticontaining window in which the programmer can scribble titles or 1422117632Shartiborders, and a subwindow in which the form fields proper are displayed. <P> 1423117632Sharti 1424117632ShartiAs the form user fills out the posted form, navigation and editing 1425117632Shartikeys support movement between fields, editing keys support modifying 1426117632Shartifield, and plain text adds to or changes data in a current field. The 1427117632Shartiform library allows you (the forms designer) to bind each navigation 1428117632Shartiand editing key to any keystroke accepted by <CODE>curses</CODE> 1429117632Sharti 1430117632ShartiFields may have validation conditions on them, so that they check input 1431117632Shartidata for type and value. The form library supplies a rich set of 1432117632Shartipre-defined field types, and makes it relatively easy to define new ones. <P> 1433117632Sharti 1434117632ShartiOnce its transaction is completed (or aborted), a form may be 1435117632Sharti<DFN>unposted</DFN> (that is, undisplayed), and finally freed to make 1436117632Shartithe storage associated with it and its items available for re-use. <P> 1437117632Sharti 1438117632ShartiThe general flow of control of a form program looks like this: 1439117632Sharti 1440117632Sharti<OL> 1441117632Sharti<LI>Initialize <CODE>curses</CODE>. 1442117632Sharti<LI>Create the form fields, using <CODE>new_field()</CODE>. 1443117632Sharti<LI>Create the form using <CODE>new_form()</CODE>. 1444117632Sharti<LI>Post the form using <CODE>form_post()</CODE>. 1445117632Sharti<LI>Refresh the screen. 1446117632Sharti<LI>Process user requests via an input loop. 1447117632Sharti<LI>Unpost the form using <CODE>form_unpost()</CODE>. 1448117632Sharti<LI>Free the form, using <CODE>free_form()</CODE>. 1449117632Sharti<LI>Free the fields using <CODE>free_field()</CODE>. 1450117632Sharti<LI>Terminate <CODE>curses</CODE>. 1451117632Sharti</OL> 1452117632Sharti 1453117632ShartiNote that this looks much like a menu program; the form library handles 1454117632Shartitasks which are in many ways similar, and its interface was obviously 1455117632Shartidesigned to resemble that of the <A HREF="#menu">menu library</A> 1456117632Shartiwherever possible. <P> 1457117632Sharti 1458117632ShartiIn forms programs, however, the `process user requests' is somewhat more 1459117632Sharticomplicated than for menus. Besides menu-like navigation operations, 1460117632Shartithe menu driver loop has to support field editing and data validation. 1461117632Sharti 1462117632Sharti<H2><A NAME="fcreate">Creating and Freeing Fields and Forms</A></H2> 1463117632Sharti 1464117632ShartiThe basic function for creating fields is <CODE>new_field()</CODE>: 1465117632Sharti 1466117632Sharti<PRE> 1467117632ShartiFIELD *new_field(int height, int width, /* new field size */ 1468117632Sharti int top, int left, /* upper left corner */ 1469117632Sharti int offscreen, /* number of offscreen rows */ 1470117632Sharti int nbuf); /* number of working buffers */ 1471117632Sharti</PRE> 1472117632Sharti 1473117632ShartiMenu items always occupy a single row, but forms fields may have 1474117632Shartimultiple rows. So <CODE>new_field()</CODE> requires you to specify a 1475117632Shartiwidth and height (the first two arguments, which mist both be greater 1476117632Shartithan zero). <P> 1477117632Sharti 1478117632ShartiYou must also specify the location of the field's upper left corner on 1479117632Shartithe screen (the third and fourth arguments, which must be zero or 1480117632Shartigreater). Note that these coordinates are relative to the form 1481117632Shartisubwindow, which will coincide with <CODE>stdscr</CODE> by default but 1482117632Shartineed not be <CODE>stdscr</CODE> if you've done an explicit 1483117632Sharti<CODE>set_form_window()</CODE> call. <P> 1484117632Sharti 1485117632ShartiThe fifth argument allows you to specify a number of off-screen rows. If 1486117632Shartithis is zero, the entire field will always be displayed. If it is 1487117632Shartinonzero, the form will be scrollable, with only one screen-full (initially 1488117632Shartithe top part) displayed at any given time. If you make a field dynamic 1489117632Shartiand grow it so it will no longer fit on the screen, the form will become 1490117632Shartiscrollable even if the <CODE>offscreen</CODE> argument was initially zero. <P> 1491117632Sharti 1492117632ShartiThe forms library allocates one working buffer per field; the size of 1493117632Shartieach buffer is <CODE>((height + offscreen)*width + 1</CODE>, one character 1494117632Shartifor each position in the field plus a NUL terminator. The sixth 1495117632Shartiargument is the number of additional data buffers to allocate for the 1496117632Shartifield; your application can use them for its own purposes. 1497117632Sharti 1498117632Sharti<PRE> 1499117632ShartiFIELD *dup_field(FIELD *field, /* field to copy */ 1500117632Sharti int top, int left); /* location of new copy */ 1501117632Sharti</PRE> 1502117632Sharti 1503117632ShartiThe function <CODE>dup_field()</CODE> duplicates an existing field at a 1504117632Shartinew location. Size and buffering information are copied; some 1505117632Shartiattribute flags and status bits are not (see the 1506117632Sharti<CODE>form_field_new(3X)</CODE> for details). 1507117632Sharti 1508117632Sharti<PRE> 1509117632ShartiFIELD *link_field(FIELD *field, /* field to copy */ 1510117632Sharti int top, int left); /* location of new copy */ 1511117632Sharti</PRE> 1512117632Sharti 1513117632ShartiThe function <CODE>link_field()</CODE> also duplicates an existing field 1514117632Shartiat a new location. The difference from <CODE>dup_field()</CODE> is that 1515117632Shartiit arranges for the new field's buffer to be shared with the old one. <P> 1516117632Sharti 1517117632ShartiBesides the obvious use in making a field editable from two different 1518117632Shartiform pages, linked fields give you a way to hack in dynamic labels. If 1519117632Shartiyou declare several fields linked to an original, and then make them 1520117632Shartiinactive, changes from the original will still be propagated to the 1521117632Shartilinked fields. <P> 1522117632Sharti 1523117632ShartiAs with duplicated fields, linked fields have attribute bits separate 1524117632Shartifrom the original. <P> 1525117632Sharti 1526117632ShartiAs you might guess, all these field-allocations return <CODE>NULL</CODE> if 1527117632Shartithe field allocation is not possible due to an out-of-memory error or 1528117632Shartiout-of-bounds arguments. <P> 1529117632Sharti 1530117632ShartiTo connect fields to a form, use 1531117632Sharti 1532117632Sharti<PRE> 1533117632ShartiFORM *new_form(FIELD **fields); 1534117632Sharti</PRE> 1535117632Sharti 1536117632ShartiThis function expects to see a NULL-terminated array of field pointers. 1537117632ShartiSaid fields are connected to a newly-allocated form object; its address 1538117632Shartiis returned (or else NULL if the allocation fails). <P> 1539117632Sharti 1540117632ShartiNote that <CODE>new_field()</CODE> does <EM>not</EM> copy the pointer array 1541117632Shartiinto private storage; if you modify the contents of the pointer array 1542117632Shartiduring forms processing, all manner of bizarre things might happen. Also 1543117632Shartinote that any given field may only be connected to one form. <P> 1544117632Sharti 1545117632ShartiThe functions <CODE>free_field()</CODE> and <CODE>free_form</CODE> are available 1546117632Shartito free field and form objects. It is an error to attempt to free a field 1547117632Sharticonnected to a form, but not vice-versa; thus, you will generally free 1548117632Shartiyour form objects first. 1549117632Sharti 1550117632Sharti<H2><A NAME="fattributes">Fetching and Changing Field Attributes</A></H2> 1551117632Sharti 1552117632ShartiEach form field has a number of location and size attributes 1553117632Shartiassociated with it. There are other field attributes used to control 1554117632Shartidisplay and editing of the field. Some (for example, the <CODE>O_STATIC</CODE> bit) 1555117632Shartiinvolve sufficient complications to be covered in sections of their own 1556117632Shartilater on. We cover the functions used to get and set several basic 1557117632Shartiattributes here. <P> 1558117632Sharti 1559117632ShartiWhen a field is created, the attributes not specified by the 1560117632Sharti<CODE>new_field</CODE> function are copied from an invisible system 1561117632Shartidefault field. In attribute-setting and -fetching functions, the 1562117632Shartiargument NULL is taken to mean this field. Changes to it persist 1563117632Shartias defaults until your forms application terminates. 1564117632Sharti 1565117632Sharti<H3><A NAME="fsizes">Fetching Size and Location Data</A></H3> 1566117632Sharti 1567117632ShartiYou can retrieve field sizes and locations through: 1568117632Sharti 1569117632Sharti<PRE> 1570117632Shartiint field_info(FIELD *field, /* field from which to fetch */ 1571117632Sharti int *height, *int width, /* field size */ 1572117632Sharti int *top, int *left, /* upper left corner */ 1573117632Sharti int *offscreen, /* number of offscreen rows */ 1574117632Sharti int *nbuf); /* number of working buffers */ 1575117632Sharti</PRE> 1576117632Sharti 1577117632ShartiThis function is a sort of inverse of <CODE>new_field()</CODE>; instead of 1578117632Shartisetting size and location attributes of a new field, it fetches them 1579117632Shartifrom an existing one. 1580117632Sharti 1581117632Sharti<H3><A NAME="flocation">Changing the Field Location</A></H3> 1582117632Sharti 1583117632ShartiIt is possible to move a field's location on the screen: 1584117632Sharti 1585117632Sharti<PRE> 1586117632Shartiint move_field(FIELD *field, /* field to alter */ 1587117632Sharti int top, int left); /* new upper-left corner */ 1588117632Sharti</PRE> 1589117632Sharti 1590117632ShartiYou can, of course. query the current location through <CODE>field_info()</CODE>. 1591117632Sharti 1592117632Sharti<H3><A NAME="fjust">The Justification Attribute</A></H3> 1593117632Sharti 1594117632ShartiOne-line fields may be unjustified, justified right, justified left, 1595117632Shartior centered. Here is how you manipulate this attribute: 1596117632Sharti 1597117632Sharti<PRE> 1598117632Shartiint set_field_just(FIELD *field, /* field to alter */ 1599117632Sharti int justmode); /* mode to set */ 1600117632Sharti 1601117632Shartiint field_just(FIELD *field); /* fetch mode of field */ 1602117632Sharti</PRE> 1603117632Sharti 1604117632ShartiThe mode values accepted and returned by this functions are 1605117632Shartipreprocessor macros <CODE>NO_JUSTIFICATION</CODE>, <CODE>JUSTIFY_RIGHT</CODE>, 1606117632Sharti<CODE>JUSTIFY_LEFT</CODE>, or <CODE>JUSTIFY_CENTER</CODE>. 1607117632Sharti 1608117632Sharti<H3><A NAME="fdispatts">Field Display Attributes</A></H3> 1609117632Sharti 1610117632ShartiFor each field, you can set a foreground attribute for entered 1611117632Sharticharacters, a background attribute for the entire field, and a pad 1612117632Sharticharacter for the unfilled portion of the field. You can also 1613117632Sharticontrol pagination of the form. <P> 1614117632Sharti 1615117632ShartiThis group of four field attributes controls the visual appearance 1616117632Shartiof the field on the screen, without affecting in any way the data 1617117632Shartiin the field buffer. 1618117632Sharti 1619117632Sharti<PRE> 1620117632Shartiint set_field_fore(FIELD *field, /* field to alter */ 1621117632Sharti chtype attr); /* attribute to set */ 1622117632Sharti 1623117632Shartichtype field_fore(FIELD *field); /* field to query */ 1624117632Sharti 1625117632Shartiint set_field_back(FIELD *field, /* field to alter */ 1626117632Sharti chtype attr); /* attribute to set */ 1627117632Sharti 1628117632Shartichtype field_back(FIELD *field); /* field to query */ 1629117632Sharti 1630117632Shartiint set_field_pad(FIELD *field, /* field to alter */ 1631117632Sharti int pad); /* pad character to set */ 1632117632Sharti 1633117632Shartichtype field_pad(FIELD *field); 1634117632Sharti 1635117632Shartiint set_new_page(FIELD *field, /* field to alter */ 1636117632Sharti int flag); /* TRUE to force new page */ 1637117632Sharti 1638117632Shartichtype new_page(FIELD *field); /* field to query */ 1639117632Sharti</PRE> 1640117632Sharti 1641117632ShartiThe attributes set and returned by the first four functions are normal 1642117632Sharti<CODE>curses(3x)</CODE> display attribute values (<CODE>A_STANDOUT</CODE>, 1643117632Sharti<CODE>A_BOLD</CODE>, <CODE>A_REVERSE</CODE> etc). 1644117632Sharti 1645117632ShartiThe page bit of a field controls whether it is displayed at the start of 1646117632Shartia new form screen. 1647117632Sharti 1648117632Sharti<H3><A NAME="foptions">Field Option Bits</A></H3> 1649117632Sharti 1650117632ShartiThere is also a large collection of field option bits you can set to control 1651117632Shartivarious aspects of forms processing. You can manipulate them with these 1652117632Shartifunctions: 1653117632Sharti 1654117632Sharti<PRE> 1655117632Shartiint set_field_opts(FIELD *field, /* field to alter */ 1656117632Sharti int attr); /* attribute to set */ 1657117632Sharti 1658117632Shartiint field_opts_on(FIELD *field, /* field to alter */ 1659117632Sharti int attr); /* attributes to turn on */ 1660117632Sharti 1661117632Shartiint field_opts_off(FIELD *field, /* field to alter */ 1662117632Sharti int attr); /* attributes to turn off */ 1663117632Sharti 1664117632Shartiint field_opts(FIELD *field); /* field to query */ 1665117632Sharti</PRE> 1666117632Sharti 1667117632ShartiBy default, all options are on. Here are the available option bits: 1668117632Sharti<DL> 1669117632Sharti<DT> O_VISIBLE 1670117632Sharti<DD> Controls whether the field is visible on the screen. Can be used 1671117632Shartiduring form processing to hide or pop up fields depending on the value 1672117632Shartiof parent fields. 1673117632Sharti<DT> O_ACTIVE 1674117632Sharti<DD> Controls whether the field is active during forms processing (i.e. 1675117632Shartivisited by form navigation keys). Can be used to make labels or derived 1676117632Shartifields with buffer values alterable by the forms application, not the user. 1677117632Sharti<DT> O_PUBLIC 1678117632Sharti<DD> Controls whether data is displayed during field entry. If this option is 1679117632Shartiturned off on a field, the library will accept and edit data in that field, 1680117632Shartibut it will not be displayed and the visible field cursor will not move. 1681117632ShartiYou can turn off the O_PUBLIC bit to define password fields. 1682117632Sharti<DT> O_EDIT 1683117632Sharti<DD> Controls whether the field's data can be modified. When this option is 1684117632Shartioff, all editing requests except <CODE>REQ_PREV_CHOICE</CODE> and 1685117632Sharti<CODE>REQ_NEXT_CHOICE</CODE> will fail. Such read-only fields may be useful for 1686117632Shartihelp messages. 1687117632Sharti<DT> O_WRAP 1688117632Sharti<DD> Controls word-wrapping in multi-line fields. Normally, when any 1689117632Sharticharacter of a (blank-separated) word reaches the end of the current line, the 1690117632Shartientire word is wrapped to the next line (assuming there is one). When this 1691117632Shartioption is off, the word will be split across the line break. 1692117632Sharti<DT> O_BLANK 1693117632Sharti<DD> Controls field blanking. When this option is on, entering a character at 1694117632Shartithe first field position erases the entire field (except for the just-entered 1695117632Sharticharacter). 1696117632Sharti<DT> O_AUTOSKIP 1697117632Sharti<DD> Controls automatic skip to next field when this one fills. Normally, 1698117632Shartiwhen the forms user tries to type more data into a field than will fit, 1699117632Shartithe editing location jumps to next field. When this option is off, the 1700117632Shartiuser's cursor will hang at the end of the field. This option is ignored 1701117632Shartiin dynamic fields that have not reached their size limit. 1702117632Sharti<DT> O_NULLOK 1703117632Sharti<DD> Controls whether <A HREF="#fvalidation">validation</A> is applied to 1704117632Shartiblank fields. Normally, it is not; the user can leave a field blank 1705117632Shartiwithout invoking the usual validation check on exit. If this option is 1706117632Shartioff on a field, exit from it will invoke a validation check. 1707117632Sharti<DT> O_PASSOK 1708117632Sharti<DD> Controls whether validation occurs on every exit, or only after 1709117632Shartithe field is modified. Normally the latter is true. Setting O_PASSOK 1710117632Shartimay be useful if your field's validation function may change during 1711117632Shartiforms processing. 1712117632Sharti<DT> O_STATIC 1713117632Sharti<DD> Controls whether the field is fixed to its initial dimensions. If you 1714117632Shartiturn this off, the field becomes <A HREF="#fdynamic">dynamic</A> and will 1715117632Shartistretch to fit entered data. 1716117632Sharti</DL> 1717117632Sharti 1718117632ShartiA field's options cannot be changed while the field is currently selected. 1719117632ShartiHowever, options may be changed on posted fields that are not current. <P> 1720117632Sharti 1721117632ShartiThe option values are bit-masks and can be composed with logical-or in 1722117632Shartithe obvious way. 1723117632Sharti 1724117632Sharti<H2><A NAME="fstatus">Field Status</A></H2> 1725117632Sharti 1726117632ShartiEvery field has a status flag, which is set to FALSE when the field is 1727117632Sharticreated and TRUE when the value in field buffer 0 changes. This flag can 1728117632Shartibe queried and set directly: 1729117632Sharti 1730117632Sharti<PRE> 1731117632Shartiint set_field_status(FIELD *field, /* field to alter */ 1732117632Sharti int status); /* mode to set */ 1733117632Sharti 1734117632Shartiint field_status(FIELD *field); /* fetch mode of field */ 1735117632Sharti</PRE> 1736117632Sharti 1737117632ShartiSetting this flag under program control can be useful if you use the same 1738117632Shartiform repeatedly, looking for modified fields each time. <P> 1739117632Sharti 1740117632ShartiCalling <CODE>field_status()</CODE> on a field not currently selected 1741117632Shartifor input will return a correct value. Calling <CODE>field_status()</CODE> on a 1742117632Shartifield that is currently selected for input may not necessarily give a 1743117632Sharticorrect field status value, because entered data isn't necessarily copied to 1744117632Shartibuffer zero before the exit validation check. 1745117632Sharti 1746117632ShartiTo guarantee that the returned status value reflects reality, call 1747117632Sharti<CODE>field_status()</CODE> either (1) in the field's exit validation check 1748117632Shartiroutine, (2) from the field's or form's initialization or termination 1749117632Shartihooks, or (3) just after a <CODE>REQ_VALIDATION</CODE> request has been 1750117632Shartiprocessed by the forms driver. 1751117632Sharti 1752117632Sharti<H2><A NAME="fuser">Field User Pointer</A></H2> 1753117632Sharti 1754117632ShartiEach field structure contains one character pointer slot that is not used 1755117632Shartiby the forms library. It is intended to be used by applications to store 1756117632Shartiprivate per-field data. You can manipulate it with: 1757117632Sharti 1758117632Sharti<PRE> 1759117632Shartiint set_field_userptr(FIELD *field, /* field to alter */ 1760117632Sharti char *userptr); /* mode to set */ 1761117632Sharti 1762117632Shartichar *field_userptr(FIELD *field); /* fetch mode of field */ 1763117632Sharti</PRE> 1764117632Sharti 1765117632Sharti(Properly, this user pointer field ought to have <CODE>(void *)</CODE> type. 1766117632ShartiThe <CODE>(char *)</CODE> type is retained for System V compatibility.) <P> 1767117632Sharti 1768117632ShartiIt is valid to set the user pointer of the default field (with a 1769117632Sharti<CODE>set_field_userptr()</CODE> call passed a NULL field pointer.) 1770117632ShartiWhen a new field is created, the default-field user pointer is copied 1771117632Shartito initialize the new field's user pointer. 1772117632Sharti 1773117632Sharti<H2><A NAME="fdynamic">Variable-Sized Fields</A></H2> 1774117632Sharti 1775117632ShartiNormally, a field is fixed at the size specified for it at creation 1776117632Shartitime. If, however, you turn off its O_STATIC bit, it becomes 1777117632Sharti<DFN>dynamic</DFN> and will automatically resize itself to accommodate 1778117632Shartidata as it is entered. If the field has extra buffers associated with it, 1779117632Shartithey will grow right along with the main input buffer. <P> 1780117632Sharti 1781117632ShartiA one-line dynamic field will have a fixed height (1) but variable 1782117632Shartiwidth, scrolling horizontally to display data within the field area as 1783117632Shartioriginally dimensioned and located. A multi-line dynamic field will 1784117632Shartihave a fixed width, but variable height (number of rows), scrolling 1785117632Shartivertically to display data within the field area as originally 1786117632Shartidimensioned and located. <P> 1787117632Sharti 1788117632ShartiNormally, a dynamic field is allowed to grow without limit. But it is 1789117632Shartipossible to set an upper limit on the size of a dynamic field. You do 1790117632Shartiit with this function: 1791117632Sharti 1792117632Sharti<PRE> 1793117632Shartiint set_max_field(FIELD *field, /* field to alter (may not be NULL) */ 1794117632Sharti int max_size); /* upper limit on field size */ 1795117632Sharti</PRE> 1796117632Sharti 1797117632ShartiIf the field is one-line, <CODE>max_size</CODE> is taken to be a column size 1798117632Shartilimit; if it is multi-line, it is taken to be a line size limit. To disable 1799117632Shartiany limit, use an argument of zero. The growth limit can be changed whether 1800117632Shartior not the O_STATIC bit is on, but has no effect until it is. <P> 1801117632Sharti 1802117632ShartiThe following properties of a field change when it becomes dynamic: 1803117632Sharti 1804117632Sharti<UL> 1805117632Sharti<LI>If there is no growth limit, there is no final position of the field; 1806117632Shartitherefore <CODE>O_AUTOSKIP</CODE> and <CODE>O_NL_OVERLOAD</CODE> are ignored. 1807117632Sharti<LI>Field justification will be ignored (though whatever justification is 1808117632Shartiset up will be retained internally and can be queried). 1809117632Sharti<LI>The <CODE>dup_field()</CODE> and <CODE>link_field()</CODE> calls copy 1810117632Shartidynamic-buffer sizes. If the <CODE>O_STATIC</CODE> option is set on one of a 1811117632Sharticollection of links, buffer resizing will occur only when the field is 1812117632Shartiedited through that link. 1813117632Sharti<LI>The call <CODE>field_info()</CODE> will retrieve the original static size of 1814117632Shartithe field; use <CODE>dynamic_field_info()</CODE> to get the actual dynamic size. 1815117632Sharti</UL> 1816117632Sharti 1817117632Sharti<H2><A NAME="fvalidation">Field Validation</A></H2> 1818117632Sharti 1819117632ShartiBy default, a field will accept any data that will fit in its input buffer. 1820117632ShartiHowever, it is possible to attach a validation type to a field. If you do 1821117632Shartithis, any attempt to leave the field while it contains data that doesn't 1822117632Shartimatch the validation type will fail. Some validation types also have a 1823117632Sharticharacter-validity check for each time a character is entered in the field. <P> 1824117632Sharti 1825117632ShartiA field's validation check (if any) is not called when 1826117632Sharti<CODE>set_field_buffer()</CODE> modifies the input buffer, nor when that buffer 1827117632Shartiis changed through a linked field. <P> 1828117632Sharti 1829117632ShartiThe <CODE>form</CODE> library provides a rich set of pre-defined validation 1830117632Shartitypes, and gives you the capability to define custom ones of your own. You 1831117632Shartican examine and change field validation attributes with the following 1832117632Shartifunctions: 1833117632Sharti 1834117632Sharti<PRE> 1835117632Shartiint set_field_type(FIELD *field, /* field to alter */ 1836117632Sharti FIELDTYPE *ftype, /* type to associate */ 1837117632Sharti ...); /* additional arguments*/ 1838117632Sharti 1839117632ShartiFIELDTYPE *field_type(FIELD *field); /* field to query */ 1840117632Sharti</PRE> 1841117632Sharti 1842117632ShartiThe validation type of a field is considered an attribute of the field. As 1843117632Shartiwith other field attributes, Also, doing <CODE>set_field_type()</CODE> with a 1844117632Sharti<CODE>NULL</CODE> field default will change the system default for validation of 1845117632Shartinewly-created fields. <P> 1846117632Sharti 1847117632ShartiHere are the pre-defined validation types: 1848117632Sharti 1849117632Sharti<H3><A NAME="ftype_alpha">TYPE_ALPHA</A></H3> 1850117632Sharti 1851117632ShartiThis field type accepts alphabetic data; no blanks, no digits, no special 1852117632Sharticharacters (this is checked at character-entry time). It is set up with: 1853117632Sharti 1854117632Sharti<PRE> 1855117632Shartiint set_field_type(FIELD *field, /* field to alter */ 1856117632Sharti TYPE_ALPHA, /* type to associate */ 1857117632Sharti int width); /* maximum width of field */ 1858117632Sharti</PRE> 1859117632Sharti 1860117632ShartiThe <CODE>width</CODE> argument sets a minimum width of data. Typically 1861117632Shartiyou'll want to set this to the field width; if it's greater than the 1862117632Shartifield width, the validation check will always fail. A minimum width 1863117632Shartiof zero makes field completion optional. 1864117632Sharti 1865117632Sharti<H3><A NAME="ftype_alnum">TYPE_ALNUM</A></H3> 1866117632Sharti 1867117632ShartiThis field type accepts alphabetic data and digits; no blanks, no special 1868117632Sharticharacters (this is checked at character-entry time). It is set up with: 1869117632Sharti 1870117632Sharti<PRE> 1871117632Shartiint set_field_type(FIELD *field, /* field to alter */ 1872117632Sharti TYPE_ALNUM, /* type to associate */ 1873117632Sharti int width); /* maximum width of field */ 1874117632Sharti</PRE> 1875117632Sharti 1876117632ShartiThe <CODE>width</CODE> argument sets a minimum width of data. As with 1877117632ShartiTYPE_ALPHA, typically you'll want to set this to the field width; if it's 1878117632Shartigreater than the field width, the validation check will always fail. A 1879117632Shartiminimum width of zero makes field completion optional. 1880117632Sharti 1881117632Sharti<H3><A NAME="ftype_enum">TYPE_ENUM</A></H3> 1882117632Sharti 1883117632ShartiThis type allows you to restrict a field's values to be among a specified 1884117632Shartiset of string values (for example, the two-letter postal codes for U.S. 1885117632Shartistates). It is set up with: 1886117632Sharti 1887117632Sharti<PRE> 1888117632Shartiint set_field_type(FIELD *field, /* field to alter */ 1889117632Sharti TYPE_ENUM, /* type to associate */ 1890117632Sharti char **valuelist; /* list of possible values */ 1891117632Sharti int checkcase; /* case-sensitive? */ 1892117632Sharti int checkunique); /* must specify uniquely? */ 1893117632Sharti</PRE> 1894117632Sharti 1895117632ShartiThe <CODE>valuelist</CODE> parameter must point at a NULL-terminated list of 1896117632Shartivalid strings. The <CODE>checkcase</CODE> argument, if true, makes comparison 1897117632Shartiwith the string case-sensitive. <P> 1898117632Sharti 1899117632ShartiWhen the user exits a TYPE_ENUM field, the validation procedure tries to 1900117632Sharticomplete the data in the buffer to a valid entry. If a complete choice string 1901117632Shartihas been entered, it is of course valid. But it is also possible to enter a 1902117632Shartiprefix of a valid string and have it completed for you. <P> 1903117632Sharti 1904117632ShartiBy default, if you enter such a prefix and it matches more than one value 1905117632Shartiin the string list, the prefix will be completed to the first matching 1906117632Shartivalue. But the <CODE>checkunique</CODE> argument, if true, requires prefix 1907117632Shartimatches to be unique in order to be valid. <P> 1908117632Sharti 1909117632ShartiThe <CODE>REQ_NEXT_CHOICE</CODE> and <CODE>REQ_PREV_CHOICE</CODE> input requests 1910117632Shartican be particularly useful with these fields. 1911117632Sharti 1912117632Sharti<H3><A NAME="ftype_integer">TYPE_INTEGER</A></H3> 1913117632Sharti 1914117632ShartiThis field type accepts an integer. It is set up as follows: 1915117632Sharti 1916117632Sharti<PRE> 1917117632Shartiint set_field_type(FIELD *field, /* field to alter */ 1918117632Sharti TYPE_INTEGER, /* type to associate */ 1919117632Sharti int padding, /* # places to zero-pad to */ 1920117632Sharti int vmin, int vmax); /* valid range */ 1921117632Sharti</PRE> 1922117632Sharti 1923117632ShartiValid characters consist of an optional leading minus and digits. 1924117632ShartiThe range check is performed on exit. If the range maximum is less 1925117632Shartithan or equal to the minimum, the range is ignored. <P> 1926117632Sharti 1927117632ShartiIf the value passes its range check, it is padded with as many leading 1928117632Shartizero digits as necessary to meet the padding argument. <P> 1929117632Sharti 1930117632ShartiA <CODE>TYPE_INTEGER</CODE> value buffer can conveniently be interpreted 1931117632Shartiwith the C library function <CODE>atoi(3)</CODE>. 1932117632Sharti 1933117632Sharti<H3><A NAME="ftype_numeric">TYPE_NUMERIC</A></H3> 1934117632Sharti 1935117632ShartiThis field type accepts a decimal number. It is set up as follows: 1936117632Sharti 1937117632Sharti<PRE> 1938117632Shartiint set_field_type(FIELD *field, /* field to alter */ 1939117632Sharti TYPE_NUMERIC, /* type to associate */ 1940117632Sharti int padding, /* # places of precision */ 1941117632Sharti double vmin, double vmax); /* valid range */ 1942117632Sharti</PRE> 1943117632Sharti 1944117632ShartiValid characters consist of an optional leading minus and digits. possibly 1945117632Shartiincluding a decimal point. If your system supports locale's, the decimal point 1946117632Sharticharacter used must be the one defined by your locale. The range check is 1947117632Shartiperformed on exit. If the range maximum is less than or equal to the minimum, 1948117632Shartithe range is ignored. <P> 1949117632Sharti 1950117632ShartiIf the value passes its range check, it is padded with as many trailing 1951117632Shartizero digits as necessary to meet the padding argument. <P> 1952117632Sharti 1953117632ShartiA <CODE>TYPE_NUMERIC</CODE> value buffer can conveniently be interpreted 1954117632Shartiwith the C library function <CODE>atof(3)</CODE>. 1955117632Sharti 1956117632Sharti<H3><A NAME="ftype_regexp">TYPE_REGEXP</A></H3> 1957117632Sharti 1958117632ShartiThis field type accepts data matching a regular expression. It is set up 1959117632Shartias follows: 1960117632Sharti 1961117632Sharti<PRE> 1962117632Shartiint set_field_type(FIELD *field, /* field to alter */ 1963117632Sharti TYPE_REGEXP, /* type to associate */ 1964117632Sharti char *regexp); /* expression to match */ 1965117632Sharti</PRE> 1966117632Sharti 1967117632ShartiThe syntax for regular expressions is that of <CODE>regcomp(3)</CODE>. 1968117632ShartiThe check for regular-expression match is performed on exit. 1969117632Sharti 1970117632Sharti<H2><A NAME="fbuffer">Direct Field Buffer Manipulation</A></H2> 1971117632Sharti 1972117632ShartiThe chief attribute of a field is its buffer contents. When a form has 1973117632Shartibeen completed, your application usually needs to know the state of each 1974117632Shartifield buffer. You can find this out with: 1975117632Sharti 1976117632Sharti<PRE> 1977117632Shartichar *field_buffer(FIELD *field, /* field to query */ 1978117632Sharti int bufindex); /* number of buffer to query */ 1979117632Sharti</PRE> 1980117632Sharti 1981117632ShartiNormally, the state of the zero-numbered buffer for each field is set by 1982117632Shartithe user's editing actions on that field. It's sometimes useful to be able 1983117632Shartito set the value of the zero-numbered (or some other) buffer from your 1984117632Shartiapplication: 1985117632Sharti 1986117632Sharti<PRE> 1987117632Shartiint set_field_buffer(FIELD *field, /* field to alter */ 1988117632Sharti int bufindex, /* number of buffer to alter */ 1989117632Sharti char *value); /* string value to set */ 1990117632Sharti</PRE> 1991117632Sharti 1992117632ShartiIf the field is not large enough and cannot be resized to a sufficiently 1993117632Shartilarge size to contain the specified value, the value will be truncated 1994117632Shartito fit. <P> 1995117632Sharti 1996117632ShartiCalling <CODE>field_buffer()</CODE> with a null field pointer will raise an 1997117632Shartierror. Calling <CODE>field_buffer()</CODE> on a field not currently selected 1998117632Shartifor input will return a correct value. Calling <CODE>field_buffer()</CODE> on a 1999117632Shartifield that is currently selected for input may not necessarily give a 2000117632Sharticorrect field buffer value, because entered data isn't necessarily copied to 2001117632Shartibuffer zero before the exit validation check. 2002117632Sharti 2003117632ShartiTo guarantee that the returned buffer value reflects on-screen reality, 2004117632Sharticall <CODE>field_buffer()</CODE> either (1) in the field's exit validation 2005117632Sharticheck routine, (2) from the field's or form's initialization or termination 2006117632Shartihooks, or (3) just after a <CODE>REQ_VALIDATION</CODE> request has been processed 2007117632Shartiby the forms driver. 2008117632Sharti 2009117632Sharti<H2><A NAME="formattrs">Attributes of Forms</A></H2> 2010117632Sharti 2011117632ShartiAs with field attributes, form attributes inherit a default from a 2012117632Shartisystem default form structure. These defaults can be queried or set by 2013117632Shartiof these functions using a form-pointer argument of <CODE>NULL</CODE>. <P> 2014117632Sharti 2015117632ShartiThe principal attribute of a form is its field list. You can query 2016117632Shartiand change this list with: 2017117632Sharti 2018117632Sharti<PRE> 2019117632Shartiint set_form_fields(FORM *form, /* form to alter */ 2020117632Sharti FIELD **fields); /* fields to connect */ 2021117632Sharti 2022117632Shartichar *form_fields(FORM *form); /* fetch fields of form */ 2023117632Sharti 2024117632Shartiint field_count(FORM *form); /* count connect fields */ 2025117632Sharti</PRE> 2026117632Sharti 2027117632ShartiThe second argument of <CODE>set_form_fields()</CODE> may be a 2028117632ShartiNULL-terminated field pointer array like the one required by 2029117632Sharti<CODE>new_form()</CODE>. In that case, the old fields of the form are 2030117632Shartidisconnected but not freed (and eligible to be connected to other 2031117632Shartiforms), then the new fields are connected. <P> 2032117632Sharti 2033117632ShartiIt may also be null, in which case the old fields are disconnected 2034117632Sharti(and not freed) but no new ones are connected. <P> 2035117632Sharti 2036117632ShartiThe <CODE>field_count()</CODE> function simply counts the number of fields 2037117632Sharticonnected to a given from. It returns -1 if the form-pointer argument 2038117632Shartiis NULL. 2039117632Sharti 2040117632Sharti<H2><A NAME="fdisplay">Control of Form Display</A></H2> 2041117632Sharti 2042117632ShartiIn the overview section, you saw that to display a form you normally 2043117632Shartistart by defining its size (and fields), posting it, and refreshing 2044117632Shartithe screen. There is an hidden step before posting, which is the 2045117632Shartiassociation of the form with a frame window (actually, a pair of 2046117632Shartiwindows) within which it will be displayed. By default, the forms 2047117632Shartilibrary associates every form with the full-screen window 2048117632Sharti<CODE>stdscr</CODE>. <P> 2049117632Sharti 2050117632ShartiBy making this step explicit, you can associate a form with a declared 2051117632Shartiframe window on your screen display. This can be useful if you want to 2052117632Shartiadapt the form display to different screen sizes, dynamically tile 2053117632Shartiforms on the screen, or use a form as part of an interface layout 2054117632Shartimanaged by <A HREF="#panels">panels</A>. <P> 2055117632Sharti 2056117632ShartiThe two windows associated with each form have the same functions as 2057117632Shartitheir analogues in the <A HREF="#menu">menu library</A>. Both these 2058117632Shartiwindows are painted when the form is posted and erased when the form 2059117632Shartiis unposted. <P> 2060117632Sharti 2061117632ShartiThe outer or frame window is not otherwise touched by the form 2062117632Shartiroutines. It exists so the programmer can associate a title, a 2063117632Shartiborder, or perhaps help text with the form and have it properly 2064117632Shartirefreshed or erased at post/unpost time. The inner window or subwindow 2065117632Shartiis where the current form page is actually displayed. <P> 2066117632Sharti 2067117632ShartiIn order to declare your own frame window for a form, you'll need to 2068117632Shartiknow the size of the form's bounding rectangle. You can get this 2069117632Shartiinformation with: 2070117632Sharti 2071117632Sharti<PRE> 2072117632Shartiint scale_form(FORM *form, /* form to query */ 2073117632Sharti int *rows, /* form rows */ 2074117632Sharti int *cols); /* form cols */ 2075117632Sharti</PRE> 2076117632Sharti 2077117632ShartiThe form dimensions are passed back in the locations pointed to by 2078117632Shartithe arguments. Once you have this information, you can use it to 2079117632Shartideclare of windows, then use one of these functions: 2080117632Sharti 2081117632Sharti<PRE> 2082117632Shartiint set_form_win(FORM *form, /* form to alter */ 2083117632Sharti WINDOW *win); /* frame window to connect */ 2084117632Sharti 2085117632ShartiWINDOW *form_win(FORM *form); /* fetch frame window of form */ 2086117632Sharti 2087117632Shartiint set_form_sub(FORM *form, /* form to alter */ 2088117632Sharti WINDOW *win); /* form subwindow to connect */ 2089117632Sharti 2090117632ShartiWINDOW *form_sub(FORM *form); /* fetch form subwindow of form */ 2091117632Sharti</PRE> 2092117632Sharti 2093117632ShartiNote that curses operations, including <CODE>refresh()</CODE>, on the form, 2094117632Shartishould be done on the frame window, not the form subwindow. <P> 2095117632Sharti 2096117632ShartiIt is possible to check from your application whether all of a 2097117632Shartiscrollable field is actually displayed within the menu subwindow. Use 2098117632Shartithese functions: 2099117632Sharti 2100117632Sharti<PRE> 2101117632Shartiint data_ahead(FORM *form); /* form to be queried */ 2102117632Sharti 2103117632Shartiint data_behind(FORM *form); /* form to be queried */ 2104117632Sharti</PRE> 2105117632Sharti 2106117632ShartiThe function <CODE>data_ahead()</CODE> returns TRUE if (a) the current 2107117632Shartifield is one-line and has undisplayed data off to the right, (b) the current 2108117632Shartifield is multi-line and there is data off-screen below it. <P> 2109117632Sharti 2110117632ShartiThe function <CODE>data_behind()</CODE> returns TRUE if the first (upper 2111117632Shartileft hand) character position is off-screen (not being displayed). <P> 2112117632Sharti 2113117632ShartiFinally, there is a function to restore the form window's cursor to the 2114117632Shartivalue expected by the forms driver: 2115117632Sharti 2116117632Sharti<PRE> 2117117632Shartiint pos_form_cursor(FORM *) /* form to be queried */ 2118117632Sharti</PRE> 2119117632Sharti 2120117632ShartiIf your application changes the form window cursor, call this function before 2121117632Shartihanding control back to the forms driver in order to re-synchronize it. 2122117632Sharti 2123117632Sharti<H2><A NAME="fdriver">Input Processing in the Forms Driver</A></H2> 2124117632Sharti 2125117632ShartiThe function <CODE>form_driver()</CODE> handles virtualized input requests 2126117632Shartifor form navigation, editing, and validation requests, just as 2127117632Sharti<CODE>menu_driver</CODE> does for menus (see the section on <A 2128117632ShartiHREF="#minput">menu input handling</A>). 2129117632Sharti 2130117632Sharti<PRE> 2131117632Shartiint form_driver(FORM *form, /* form to pass input to */ 2132117632Sharti int request); /* form request code */ 2133117632Sharti</PRE> 2134117632Sharti 2135117632ShartiYour input virtualization function needs to take input and then convert it 2136117632Shartito either an alphanumeric character (which is treated as data to be 2137117632Shartientered in the currently-selected field), or a forms processing request. <P> 2138117632Sharti 2139117632ShartiThe forms driver provides hooks (through input-validation and 2140117632Shartifield-termination functions) with which your application code can check 2141117632Shartithat the input taken by the driver matched what was expected. 2142117632Sharti 2143117632Sharti<H3><A NAME="fpage">Page Navigation Requests</A></H3> 2144117632Sharti 2145117632ShartiThese requests cause page-level moves through the form, 2146117632Shartitriggering display of a new form screen. 2147117632Sharti 2148117632Sharti<DL> 2149117632Sharti<DT> <CODE>REQ_NEXT_PAGE</CODE> 2150117632Sharti<DD> Move to the next form page. 2151117632Sharti<DT> <CODE>REQ_PREV_PAGE</CODE> 2152117632Sharti<DD> Move to the previous form page. 2153117632Sharti<DT> <CODE>REQ_FIRST_PAGE</CODE> 2154117632Sharti<DD> Move to the first form page. 2155117632Sharti<DT> <CODE>REQ_LAST_PAGE</CODE> 2156117632Sharti<DD> Move to the last form page. 2157117632Sharti</DL> 2158117632Sharti 2159117632ShartiThese requests treat the list as cyclic; that is, <CODE>REQ_NEXT_PAGE</CODE> 2160117632Shartifrom the last page goes to the first, and <CODE>REQ_PREV_PAGE</CODE> from 2161117632Shartithe first page goes to the last. 2162117632Sharti 2163117632Sharti<H3><A NAME="#ffield">Inter-Field Navigation Requests</A></H3> 2164117632Sharti 2165117632ShartiThese requests handle navigation between fields on the same page. 2166117632Sharti 2167117632Sharti<DL> 2168117632Sharti<DT> <CODE>REQ_NEXT_FIELD</CODE> 2169117632Sharti<DD> Move to next field. 2170117632Sharti<DT> <CODE>REQ_PREV_FIELD</CODE> 2171117632Sharti<DD> Move to previous field. 2172117632Sharti<DT> <CODE>REQ_FIRST_FIELD</CODE> 2173117632Sharti<DD> Move to the first field. 2174117632Sharti<DT> <CODE>REQ_LAST_FIELD</CODE> 2175117632Sharti<DD> Move to the last field. 2176117632Sharti<DT> <CODE>REQ_SNEXT_FIELD</CODE> 2177117632Sharti<DD> Move to sorted next field. 2178117632Sharti<DT> <CODE>REQ_SPREV_FIELD</CODE> 2179117632Sharti<DD> Move to sorted previous field. 2180117632Sharti<DT> <CODE>REQ_SFIRST_FIELD</CODE> 2181117632Sharti<DD> Move to the sorted first field. 2182117632Sharti<DT> <CODE>REQ_SLAST_FIELD</CODE> 2183117632Sharti<DD> Move to the sorted last field. 2184117632Sharti<DT> <CODE>REQ_LEFT_FIELD</CODE> 2185117632Sharti<DD> Move left to field. 2186117632Sharti<DT> <CODE>REQ_RIGHT_FIELD</CODE> 2187117632Sharti<DD> Move right to field. 2188117632Sharti<DT> <CODE>REQ_UP_FIELD</CODE> 2189117632Sharti<DD> Move up to field. 2190117632Sharti<DT> <CODE>REQ_DOWN_FIELD</CODE> 2191117632Sharti<DD> Move down to field. 2192117632Sharti</DL> 2193117632Sharti 2194117632ShartiThese requests treat the list of fields on a page as cyclic; that is, 2195117632Sharti<CODE>REQ_NEXT_FIELD</CODE> from the last field goes to the first, and 2196117632Sharti<CODE>REQ_PREV_FIELD</CODE> from the first field goes to the last. The 2197117632Shartiorder of the fields for these (and the <CODE>REQ_FIRST_FIELD</CODE> and 2198117632Sharti<CODE>REQ_LAST_FIELD</CODE> requests) is simply the order of the field 2199117632Shartipointers in the form array (as set up by <CODE>new_form()</CODE> or 2200117632Sharti<CODE>set_form_fields()</CODE> <P> 2201117632Sharti 2202117632ShartiIt is also possible to traverse the fields as if they had been sorted in 2203117632Shartiscreen-position order, so the sequence goes left-to-right and top-to-bottom. 2204117632ShartiTo do this, use the second group of four sorted-movement requests. <P> 2205117632Sharti 2206117632ShartiFinally, it is possible to move between fields using visual directions up, 2207117632Shartidown, right, and left. To accomplish this, use the third group of four 2208117632Shartirequests. Note, however, that the position of a form for purposes of these 2209117632Shartirequests is its upper-left corner. <P> 2210117632Sharti 2211117632ShartiFor example, suppose you have a multi-line field B, and two 2212117632Shartisingle-line fields A and C on the same line with B, with A to the left 2213117632Shartiof B and C to the right of B. A <CODE>REQ_MOVE_RIGHT</CODE> from A will 2214117632Shartigo to B only if A, B, and C <EM>all</EM> share the same first line; 2215117632Shartiotherwise it will skip over B to C. 2216117632Sharti 2217117632Sharti<H3><A NAME="#fifield">Intra-Field Navigation Requests</A></H3> 2218117632Sharti 2219117632ShartiThese requests drive movement of the edit cursor within the currently 2220117632Shartiselected field. 2221117632Sharti 2222117632Sharti<DL> 2223117632Sharti<DT> <CODE>REQ_NEXT_CHAR</CODE> 2224117632Sharti<DD> Move to next character. 2225117632Sharti<DT> <CODE>REQ_PREV_CHAR</CODE> 2226117632Sharti<DD> Move to previous character. 2227117632Sharti<DT> <CODE>REQ_NEXT_LINE</CODE> 2228117632Sharti<DD> Move to next line. 2229117632Sharti<DT> <CODE>REQ_PREV_LINE</CODE> 2230117632Sharti<DD> Move to previous line. 2231117632Sharti<DT> <CODE>REQ_NEXT_WORD</CODE> 2232117632Sharti<DD> Move to next word. 2233117632Sharti<DT> <CODE>REQ_PREV_WORD</CODE> 2234117632Sharti<DD> Move to previous word. 2235117632Sharti<DT> <CODE>REQ_BEG_FIELD</CODE> 2236117632Sharti<DD> Move to beginning of field. 2237117632Sharti<DT> <CODE>REQ_END_FIELD</CODE> 2238117632Sharti<DD> Move to end of field. 2239117632Sharti<DT> <CODE>REQ_BEG_LINE</CODE> 2240117632Sharti<DD> Move to beginning of line. 2241117632Sharti<DT> <CODE>REQ_END_LINE</CODE> 2242117632Sharti<DD> Move to end of line. 2243117632Sharti<DT> <CODE>REQ_LEFT_CHAR</CODE> 2244117632Sharti<DD> Move left in field. 2245117632Sharti<DT> <CODE>REQ_RIGHT_CHAR</CODE> 2246117632Sharti<DD> Move right in field. 2247117632Sharti<DT> <CODE>REQ_UP_CHAR</CODE> 2248117632Sharti<DD> Move up in field. 2249117632Sharti<DT> <CODE>REQ_DOWN_CHAR</CODE> 2250117632Sharti<DD> Move down in field. 2251117632Sharti</DL> 2252117632Sharti 2253117632ShartiEach <EM>word</EM> is separated from the previous and next characters 2254117632Shartiby whitespace. The commands to move to beginning and end of line or field 2255117632Shartilook for the first or last non-pad character in their ranges. 2256117632Sharti 2257117632Sharti<H3><A NAME="fscroll">Scrolling Requests</A></H3> 2258117632Sharti 2259117632ShartiFields that are dynamic and have grown and fields explicitly created 2260117632Shartiwith offscreen rows are scrollable. One-line fields scroll horizontally; 2261117632Shartimulti-line fields scroll vertically. Most scrolling is triggered by 2262117632Shartiediting and intra-field movement (the library scrolls the field to keep the 2263117632Sharticursor visible). It is possible to explicitly request scrolling with the 2264117632Shartifollowing requests: 2265117632Sharti 2266117632Sharti<DL> 2267117632Sharti<DT> <CODE>REQ_SCR_FLINE</CODE> 2268117632Sharti<DD> Scroll vertically forward a line. 2269117632Sharti<DT> <CODE>REQ_SCR_BLINE</CODE> 2270117632Sharti<DD> Scroll vertically backward a line. 2271117632Sharti<DT> <CODE>REQ_SCR_FPAGE</CODE> 2272117632Sharti<DD> Scroll vertically forward a page. 2273117632Sharti<DT> <CODE>REQ_SCR_BPAGE</CODE> 2274117632Sharti<DD> Scroll vertically backward a page. 2275117632Sharti<DT> <CODE>REQ_SCR_FHPAGE</CODE> 2276117632Sharti<DD> Scroll vertically forward half a page. 2277117632Sharti<DT> <CODE>REQ_SCR_BHPAGE</CODE> 2278117632Sharti<DD> Scroll vertically backward half a page. 2279117632Sharti<DT> <CODE>REQ_SCR_FCHAR</CODE> 2280117632Sharti<DD> Scroll horizontally forward a character. 2281117632Sharti<DT> <CODE>REQ_SCR_BCHAR</CODE> 2282117632Sharti<DD> Scroll horizontally backward a character. 2283117632Sharti<DT> <CODE>REQ_SCR_HFLINE</CODE> 2284117632Sharti<DD> Scroll horizontally one field width forward. 2285117632Sharti<DT> <CODE>REQ_SCR_HBLINE</CODE> 2286117632Sharti<DD> Scroll horizontally one field width backward. 2287117632Sharti<DT> <CODE>REQ_SCR_HFHALF</CODE> 2288117632Sharti<DD> Scroll horizontally one half field width forward. 2289117632Sharti<DT> <CODE>REQ_SCR_HBHALF</CODE> 2290117632Sharti<DD> Scroll horizontally one half field width backward. 2291117632Sharti</DL> 2292117632Sharti 2293117632ShartiFor scrolling purposes, a <EM>page</EM> of a field is the height 2294117632Shartiof its visible part. 2295117632Sharti 2296117632Sharti<H3><A NAME="fedit">Editing Requests</A></H3> 2297117632Sharti 2298117632ShartiWhen you pass the forms driver an ASCII character, it is treated as a 2299117632Shartirequest to add the character to the field's data buffer. Whether this 2300117632Shartiis an insertion or a replacement depends on the field's edit mode 2301117632Sharti(insertion is the default. <P> 2302117632Sharti 2303117632ShartiThe following requests support editing the field and changing the edit 2304117632Shartimode: 2305117632Sharti 2306117632Sharti<DL> 2307117632Sharti<DT> <CODE>REQ_INS_MODE</CODE> 2308117632Sharti<DD> Set insertion mode. 2309117632Sharti<DT> <CODE>REQ_OVL_MODE</CODE> 2310117632Sharti<DD> Set overlay mode. 2311117632Sharti<DT> <CODE>REQ_NEW_LINE</CODE> 2312117632Sharti<DD> New line request (see below for explanation). 2313117632Sharti<DT> <CODE>REQ_INS_CHAR</CODE> 2314117632Sharti<DD> Insert space at character location. 2315117632Sharti<DT> <CODE>REQ_INS_LINE</CODE> 2316117632Sharti<DD> Insert blank line at character location. 2317117632Sharti<DT> <CODE>REQ_DEL_CHAR</CODE> 2318117632Sharti<DD> Delete character at cursor. 2319117632Sharti<DT> <CODE>REQ_DEL_PREV</CODE> 2320117632Sharti<DD> Delete previous word at cursor. 2321117632Sharti<DT> <CODE>REQ_DEL_LINE</CODE> 2322117632Sharti<DD> Delete line at cursor. 2323117632Sharti<DT> <CODE>REQ_DEL_WORD</CODE> 2324117632Sharti<DD> Delete word at cursor. 2325117632Sharti<DT> <CODE>REQ_CLR_EOL</CODE> 2326117632Sharti<DD> Clear to end of line. 2327117632Sharti<DT> <CODE>REQ_CLR_EOF</CODE> 2328117632Sharti<DD> Clear to end of field. 2329117632Sharti<DT> <CODE>REQ_CLEAR_FIELD</CODE> 2330117632Sharti<DD> Clear entire field. 2331117632Sharti</DL> 2332117632Sharti 2333117632ShartiThe behavior of the <CODE>REQ_NEW_LINE</CODE> and <CODE>REQ_DEL_PREV</CODE> requests 2334117632Shartiis complicated and partly controlled by a pair of forms options. 2335117632ShartiThe special cases are triggered when the cursor is at the beginning of 2336117632Shartia field, or on the last line of the field. <P> 2337117632Sharti 2338117632ShartiFirst, we consider <CODE>REQ_NEW_LINE</CODE>: <P> 2339117632Sharti 2340117632ShartiThe normal behavior of <CODE>REQ_NEW_LINE</CODE> in insert mode is to break the 2341117632Sharticurrent line at the position of the edit cursor, inserting the portion of 2342117632Shartithe current line after the cursor as a new line following the current 2343117632Shartiand moving the cursor to the beginning of that new line (you may think 2344117632Shartiof this as inserting a newline in the field buffer). <P> 2345117632Sharti 2346117632ShartiThe normal behavior of <CODE>REQ_NEW_LINE</CODE> in overlay mode is to clear the 2347117632Sharticurrent line from the position of the edit cursor to end of line. 2348117632ShartiThe cursor is then moved to the beginning of the next line. <P> 2349117632Sharti 2350117632ShartiHowever, <CODE>REQ_NEW_LINE</CODE> at the beginning of a field, or on the 2351117632Shartilast line of a field, instead does a <CODE>REQ_NEXT_FIELD</CODE>. 2352117632Sharti<CODE>O_NL_OVERLOAD</CODE> option is off, this special action is 2353117632Shartidisabled. <P> 2354117632Sharti 2355117632ShartiNow, let us consider <CODE>REQ_DEL_PREV</CODE>: <P> 2356117632Sharti 2357117632ShartiThe normal behavior of <CODE>REQ_DEL_PREV</CODE> is to delete the previous 2358117632Sharticharacter. If insert mode is on, and the cursor is at the start of a 2359117632Shartiline, and the text on that line will fit on the previous one, it 2360117632Shartiinstead appends the contents of the current line to the previous one 2361117632Shartiand deletes the current line (you may think of this as deleting a 2362117632Shartinewline from the field buffer). <P> 2363117632Sharti 2364117632ShartiHowever, <CODE>REQ_DEL_PREV</CODE> at the beginning of a field is instead 2365117632Shartitreated as a <CODE>REQ_PREV_FIELD</CODE>. <P> If the 2366117632Sharti<CODE>O_BS_OVERLOAD</CODE> option is off, this special action is 2367117632Shartidisabled and the forms driver just returns <CODE>E_REQUEST_DENIED</CODE>. <P> 2368117632Sharti 2369117632ShartiSee <A HREF="#frmoptions">Form Options</A> for discussion of how to set 2370117632Shartiand clear the overload options. 2371117632Sharti 2372117632Sharti<H3><A NAME="forder">Order Requests</A></H3> 2373117632Sharti 2374117632ShartiIf the type of your field is ordered, and has associated functions 2375117632Shartifor getting the next and previous values of the type from a given value, 2376117632Shartithere are requests that can fetch that value into the field buffer: 2377117632Sharti 2378117632Sharti<DL> 2379117632Sharti<DT> <CODE>REQ_NEXT_CHOICE</CODE> 2380117632Sharti<DD> Place the successor value of the current value in the buffer. 2381117632Sharti<DT> <CODE>REQ_PREV_CHOICE</CODE> 2382117632Sharti<DD> Place the predecessor value of the current value in the buffer. 2383117632Sharti</DL> 2384117632Sharti 2385117632ShartiOf the built-in field types, only <CODE>TYPE_ENUM</CODE> has built-in successor 2386117632Shartiand predecessor functions. When you define a field type of your own 2387117632Sharti(see <A HREF="#fcustom">Custom Validation Types</A>), you can associate 2388117632Shartiour own ordering functions. 2389117632Sharti 2390117632Sharti<H3><A NAME="fappcmds">Application Commands</A></H3> 2391117632Sharti 2392117632ShartiForm requests are represented as integers above the <CODE>curses</CODE> value 2393117632Shartigreater than <CODE>KEY_MAX</CODE> and less than or equal to the constant 2394117632Sharti<CODE>MAX_COMMAND</CODE>. If your input-virtualization routine returns a 2395117632Shartivalue above <CODE>MAX_COMMAND</CODE>, the forms driver will ignore it. 2396117632Sharti 2397117632Sharti<H2><A NAME="fhooks">Field Change Hooks</A></H2> 2398117632Sharti 2399117632ShartiIt is possible to set function hooks to be executed whenever the 2400117632Sharticurrent field or form changes. Here are the functions that support this: 2401117632Sharti 2402117632Sharti<PRE> 2403117632Shartitypedef void (*HOOK)(); /* pointer to function returning void */ 2404117632Sharti 2405117632Shartiint set_form_init(FORM *form, /* form to alter */ 2406117632Sharti HOOK hook); /* initialization hook */ 2407117632Sharti 2408117632ShartiHOOK form_init(FORM *form); /* form to query */ 2409117632Sharti 2410117632Shartiint set_form_term(FORM *form, /* form to alter */ 2411117632Sharti HOOK hook); /* termination hook */ 2412117632Sharti 2413117632ShartiHOOK form_term(FORM *form); /* form to query */ 2414117632Sharti 2415117632Shartiint set_field_init(FORM *form, /* form to alter */ 2416117632Sharti HOOK hook); /* initialization hook */ 2417117632Sharti 2418117632ShartiHOOK field_init(FORM *form); /* form to query */ 2419117632Sharti 2420117632Shartiint set_field_term(FORM *form, /* form to alter */ 2421117632Sharti HOOK hook); /* termination hook */ 2422117632Sharti 2423117632ShartiHOOK field_term(FORM *form); /* form to query */ 2424117632Sharti</PRE> 2425117632Sharti 2426117632ShartiThese functions allow you to either set or query four different hooks. 2427117632ShartiIn each of the set functions, the second argument should be the 2428117632Shartiaddress of a hook function. These functions differ only in the timing 2429117632Shartiof the hook call. 2430117632Sharti 2431117632Sharti<DL> 2432117632Sharti<DT> form_init 2433117632Sharti<DD> This hook is called when the form is posted; also, just after 2434117632Shartieach page change operation. 2435117632Sharti<DT> field_init 2436117632Sharti<DD> This hook is called when the form is posted; also, just after 2437117632Shartieach field change 2438117632Sharti<DT> field_term 2439117632Sharti<DD> This hook is called just after field validation; that is, just before 2440117632Shartithe field is altered. It is also called when the form is unposted. 2441117632Sharti<DT> form_term 2442117632Sharti<DD> This hook is called when the form is unposted; also, just before 2443117632Shartieach page change operation. 2444117632Sharti</DL> 2445117632Sharti 2446117632ShartiCalls to these hooks may be triggered 2447117632Sharti<OL> 2448117632Sharti<LI>When user editing requests are processed by the forms driver 2449117632Sharti<LI>When the current page is changed by <CODE>set_current_field()</CODE> call 2450117632Sharti<LI>When the current field is changed by a <CODE>set_form_page()</CODE> call 2451117632Sharti</OL> 2452117632Sharti 2453117632ShartiSee <A NAME="ffocus">Field Change Commands</A> for discussion of the latter 2454117632Shartitwo cases. <P> 2455117632Sharti 2456117632ShartiYou can set a default hook for all fields by passing one of the set functions 2457117632Shartia NULL first argument. <P> 2458117632Sharti 2459117632ShartiYou can disable any of these hooks by (re)setting them to NULL, the default 2460117632Shartivalue. 2461117632Sharti 2462117632Sharti<H2><A HREF="#ffocus">Field Change Commands</A></H2> 2463117632Sharti 2464117632ShartiNormally, navigation through the form will be driven by the user's 2465117632Shartiinput requests. But sometimes it is useful to be able to move the 2466117632Shartifocus for editing and viewing under control of your application, or 2467117632Shartiask which field it currently is in. The following functions help you 2468117632Shartiaccomplish this: 2469117632Sharti 2470117632Sharti<PRE> 2471117632Shartiint set_current_field(FORM *form, /* form to alter */ 2472117632Sharti FIELD *field); /* field to shift to */ 2473117632Sharti 2474117632ShartiFIELD *current_field(FORM *form); /* form to query */ 2475117632Sharti 2476117632Shartiint field_index(FORM *form, /* form to query */ 2477117632Sharti FIELD *field); /* field to get index of */ 2478117632Sharti</PRE> 2479117632Sharti 2480117632ShartiThe function <CODE>field_index()</CODE> returns the index of the given field 2481117632Shartiin the given form's field array (the array passed to <CODE>new_form()</CODE> or 2482117632Sharti<CODE>set_form_fields()</CODE>). <P> 2483117632Sharti 2484117632ShartiThe initial current field of a form is the first active field on the 2485117632Shartifirst page. The function <CODE>set_form_fields()</CODE> resets this.<P> 2486117632Sharti 2487117632ShartiIt is also possible to move around by pages. 2488117632Sharti 2489117632Sharti<PRE> 2490117632Shartiint set_form_page(FORM *form, /* form to alter */ 2491117632Sharti int page); /* page to go to (0-origin) */ 2492117632Sharti 2493117632Shartiint form_page(FORM *form); /* return form's current page */ 2494117632Sharti</PRE> 2495117632Sharti 2496117632ShartiThe initial page of a newly-created form is 0. The function 2497117632Sharti<CODE>set_form_fields()</CODE> resets this. 2498117632Sharti 2499117632Sharti<H2><A NAME="frmoptions">Form Options</A></H2> 2500117632Sharti 2501117632ShartiLike fields, forms may have control option bits. They can be changed 2502117632Shartior queried with these functions: 2503117632Sharti 2504117632Sharti<PRE> 2505117632Shartiint set_form_opts(FORM *form, /* form to alter */ 2506117632Sharti int attr); /* attribute to set */ 2507117632Sharti 2508117632Shartiint form_opts_on(FORM *form, /* form to alter */ 2509117632Sharti int attr); /* attributes to turn on */ 2510117632Sharti 2511117632Shartiint form_opts_off(FORM *form, /* form to alter */ 2512117632Sharti int attr); /* attributes to turn off */ 2513117632Sharti 2514117632Shartiint form_opts(FORM *form); /* form to query */ 2515117632Sharti</PRE> 2516117632Sharti 2517117632ShartiBy default, all options are on. Here are the available option bits: 2518117632Sharti 2519117632Sharti<DL> 2520117632Sharti<DT> O_NL_OVERLOAD 2521117632Sharti<DD> Enable overloading of <CODE>REQ_NEW_LINE</CODE> as described in <A 2522117632ShartiNAME="fedit">Editing Requests</A>. The value of this option is 2523117632Shartiignored on dynamic fields that have not reached their size limit; 2524117632Shartithese have no last line, so the circumstances for triggering a 2525117632Sharti<CODE>REQ_NEXT_FIELD</CODE> never arise. 2526117632Sharti<DT> O_BS_OVERLOAD 2527117632Sharti<DD> Enable overloading of <CODE>REQ_DEL_PREV</CODE> as described in 2528117632Sharti<A NAME="fedit">Editing Requests</A>. 2529117632Sharti</DL> 2530117632Sharti 2531117632ShartiThe option values are bit-masks and can be composed with logical-or in 2532117632Shartithe obvious way. 2533117632Sharti 2534117632Sharti<H2><A NAME="fcustom">Custom Validation Types</A></H2> 2535117632Sharti 2536117632ShartiThe <CODE>form</CODE> library gives you the capability to define custom 2537117632Shartivalidation types of your own. Further, the optional additional arguments 2538117632Shartiof <CODE>set_field_type</CODE> effectively allow you to parameterize validation 2539117632Shartitypes. Most of the complications in the validation-type interface have to 2540117632Shartido with the handling of the additional arguments within custom validation 2541117632Shartifunctions. 2542117632Sharti 2543117632Sharti<H3><A NAME="flinktypes">Union Types</A></H3> 2544117632Sharti 2545117632ShartiThe simplest way to create a custom data type is to compose it from two 2546117632Shartipreexisting ones: 2547117632Sharti 2548117632Sharti<PRE> 2549117632ShartiFIELD *link_fieldtype(FIELDTYPE *type1, 2550117632Sharti FIELDTYPE *type2); 2551117632Sharti</PRE> 2552117632Sharti 2553117632ShartiThis function creates a field type that will accept any of the values 2554117632Shartilegal for either of its argument field types (which may be either 2555117632Shartipredefined or programmer-defined). 2556117632Sharti 2557117632ShartiIf a <CODE>set_field_type()</CODE> call later requires arguments, the new 2558117632Sharticomposite type expects all arguments for the first type, than all arguments 2559117632Shartifor the second. Order functions (see <A HREF="#forder">Order Requests</A>) 2560117632Shartiassociated with the component types will work on the composite; what it does 2561117632Shartiis check the validation function for the first type, then for the second, to 2562117632Shartifigure what type the buffer contents should be treated as. 2563117632Sharti 2564117632Sharti<H3><A NAME="fnewtypes">New Field Types</A></H3> 2565117632Sharti 2566117632ShartiTo create a field type from scratch, you need to specify one or both of the 2567117632Shartifollowing things: 2568117632Sharti 2569117632Sharti<UL> 2570117632Sharti<LI>A character-validation function, to check each character as it is entered. 2571117632Sharti<LI>A field-validation function to be applied on exit from the field. 2572117632Sharti</UL> 2573117632Sharti 2574117632ShartiHere's how you do that: 2575117632Sharti<PRE> 2576117632Shartitypedef int (*HOOK)(); /* pointer to function returning int */ 2577117632Sharti 2578117632ShartiFIELDTYPE *new_fieldtype(HOOK f_validate, /* field validator */ 2579117632Sharti HOOK c_validate) /* character validator */ 2580117632Sharti 2581117632Sharti 2582117632Shartiint free_fieldtype(FIELDTYPE *ftype); /* type to free */ 2583117632Sharti</PRE> 2584117632Sharti 2585117632ShartiAt least one of the arguments of <CODE>new_fieldtype()</CODE> must be 2586117632Shartinon-NULL. The forms driver will automatically call the new type's 2587117632Shartivalidation functions at appropriate points in processing a field of 2588117632Shartithe new type. <P> 2589117632Sharti 2590117632ShartiThe function <CODE>free_fieldtype()</CODE> deallocates the argument 2591117632Shartifieldtype, freeing all storage associated with it. <P> 2592117632Sharti 2593117632ShartiNormally, a field validator is called when the user attempts to 2594117632Shartileave the field. Its first argument is a field pointer, from which it 2595117632Shartican get to field buffer 0 and test it. If the function returns TRUE, 2596117632Shartithe operation succeeds; if it returns FALSE, the edit cursor stays in 2597117632Shartithe field. <P> 2598117632Sharti 2599117632ShartiA character validator gets the character passed in as a first argument. 2600117632ShartiIt too should return TRUE if the character is valid, FALSE otherwise. 2601117632Sharti 2602117632Sharti<H3><A NAME="fcheckargs">Validation Function Arguments</A></H3> 2603117632Sharti 2604117632ShartiYour field- and character- validation functions will be passed a 2605117632Shartisecond argument as well. This second argument is the address of a 2606117632Shartistructure (which we'll call a <EM>pile</EM>) built from any of the 2607117632Shartifield-type-specific arguments passed to <CODE>set_field_type()</CODE>. If 2608117632Shartino such arguments are defined for the field type, this pile pointer 2609117632Shartiargument will be NULL. <P> 2610117632Sharti 2611117632ShartiIn order to arrange for such arguments to be passed to your validation 2612117632Shartifunctions, you must associate a small set of storage-management functions 2613117632Shartiwith the type. The forms driver will use these to synthesize a pile 2614117632Shartifrom the trailing arguments of each <CODE>set_field_type()</CODE> argument, and 2615117632Shartia pointer to the pile will be passed to the validation functions. <P> 2616117632Sharti 2617117632ShartiHere is how you make the association: 2618117632Sharti 2619117632Sharti<PRE> 2620117632Shartitypedef char *(*PTRHOOK)(); /* pointer to function returning (char *) */ 2621117632Shartitypedef void (*VOIDHOOK)(); /* pointer to function returning void */ 2622117632Sharti 2623117632Shartiint set_fieldtype_arg(FIELDTYPE *type, /* type to alter */ 2624117632Sharti PTRHOOK make_str, /* make structure from args */ 2625117632Sharti PTRHOOK copy_str, /* make copy of structure */ 2626117632Sharti VOIDHOOK free_str); /* free structure storage */ 2627117632Sharti</PRE> 2628117632Sharti 2629117632ShartiHere is how the storage-management hooks are used: 2630117632Sharti 2631117632Sharti<DL> 2632117632Sharti<DT> <CODE>make_str</CODE> 2633117632Sharti<DD> This function is called by <CODE>set_field_type()</CODE>. It gets one 2634117632Shartiargument, a <CODE>va_list</CODE> of the type-specific arguments passed to 2635117632Sharti<CODE>set_field_type()</CODE>. It is expected to return a pile pointer to a data 2636117632Shartistructure that encapsulates those arguments. 2637117632Sharti<DT> <CODE>copy_str</CODE> 2638117632Sharti<DD> This function is called by form library functions that allocate new 2639117632Shartifield instances. It is expected to take a pile pointer, copy the pile 2640117632Shartito allocated storage, and return the address of the pile copy. 2641117632Sharti<DT> <CODE>free_str</CODE> 2642117632Sharti<DD> This function is called by field- and type-deallocation routines in the 2643117632Shartilibrary. It takes a pile pointer argument, and is expected to free the 2644117632Shartistorage of that pile. 2645117632Sharti</DL> 2646117632Sharti 2647117632ShartiThe <CODE>make_str</CODE> and <CODE>copy_str</CODE> functions may return NULL to 2648117632Shartisignal allocation failure. The library routines will that call them will 2649117632Shartireturn error indication when this happens. Thus, your validation functions 2650117632Shartishould never see a NULL file pointer and need not check specially for it. 2651117632Sharti 2652117632Sharti<H3><A NAME="fcustorder">Order Functions For Custom Types</A></H3> 2653117632Sharti 2654117632ShartiSome custom field types are simply ordered in the same well-defined way 2655117632Shartithat <CODE>TYPE_ENUM</CODE> is. For such types, it is possible to define 2656117632Shartisuccessor and predecessor functions to support the <CODE>REQ_NEXT_CHOICE</CODE> 2657117632Shartiand <CODE>REQ_PREV_CHOICE</CODE> requests. Here's how: 2658117632Sharti 2659117632Sharti<PRE> 2660117632Shartitypedef int (*INTHOOK)(); /* pointer to function returning int */ 2661117632Sharti 2662117632Shartiint set_fieldtype_arg(FIELDTYPE *type, /* type to alter */ 2663117632Sharti INTHOOK succ, /* get successor value */ 2664117632Sharti INTHOOK pred); /* get predecessor value */ 2665117632Sharti</PRE> 2666117632Sharti 2667117632ShartiThe successor and predecessor arguments will each be passed two arguments; 2668117632Shartia field pointer, and a pile pointer (as for the validation functions). They 2669117632Shartiare expected to use the function <CODE>field_buffer()</CODE> to read the 2670117632Sharticurrent value, and <CODE>set_field_buffer()</CODE> on buffer 0 to set the next 2671117632Shartior previous value. Either hook may return TRUE to indicate success (a 2672117632Shartilegal next or previous value was set) or FALSE to indicate failure. 2673117632Sharti 2674117632Sharti<H3><A NAME="fcustprobs">Avoiding Problems</A></H3> 2675117632Sharti 2676117632ShartiThe interface for defining custom types is complicated and tricky. 2677117632ShartiRather than attempting to create a custom type entirely from scratch, 2678117632Shartiyou should start by studying the library source code for whichever of 2679117632Shartithe pre-defined types seems to be closest to what you want. <P> 2680117632Sharti 2681117632ShartiUse that code as a model, and evolve it towards what you really want. 2682117632ShartiYou will avoid many problems and annoyances that way. The code 2683117632Shartiin the <CODE>ncurses</CODE> library has been specifically exempted from 2684117632Shartithe package copyright to support this. <P> 2685117632Sharti 2686117632ShartiIf your custom type defines order functions, have do something intuitive 2687117632Shartiwith a blank field. A useful convention is to make the successor of a 2688117632Shartiblank field the types minimum value, and its predecessor the maximum. 2689117632Sharti</BODY> 2690117632Sharti</HTML> 2691117632Sharti