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