diff options
Diffstat (limited to 'doc/html/ncurses-intro.html')
| -rw-r--r-- | doc/html/ncurses-intro.html | 5394 |
1 files changed, 3058 insertions, 2336 deletions
diff --git a/doc/html/ncurses-intro.html b/doc/html/ncurses-intro.html index a6cd40c74ddb..cc1a041eeeaf 100644 --- a/doc/html/ncurses-intro.html +++ b/doc/html/ncurses-intro.html @@ -1,8 +1,7 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <!-- - $Id: ncurses-intro.html,v 1.46 2013/05/17 23:29:27 tom Exp $ + $Id: ncurses-intro.html,v 1.53 2019/07/28 16:53:26 tom Exp $ **************************************************************************** - * Copyright (c) 1998-2012,2013 Free Software Foundation, Inc. * + * Copyright (c) 1998-2017,2019 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * * copy of this software and associated documentation files (the * @@ -29,408 +28,623 @@ * authorization. * **************************************************************************** --> -<HTML> -<HEAD> -<TITLE>Writing Programs with NCURSES</TITLE> -<link rev="made" href="mailto:bugs-ncurses@gnu.org"> -<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> -</HEAD> -<BODY> - -<H1>Writing Programs with NCURSES</H1> - -<BLOCKQUOTE> -by Eric S. Raymond and Zeyd M. Ben-Halim<BR> -updates since release 1.9.9e by Thomas Dickey -</BLOCKQUOTE> - -<H1>Contents</H1> -<UL> -<LI><A HREF="#introduction">Introduction</A> -<UL> -<LI><A HREF="#history">A Brief History of Curses</A> -<LI><A HREF="#scope">Scope of This Document</A> -<LI><A HREF="#terminology">Terminology</A> -</UL> -<LI><A HREF="#curses">The Curses Library</A> -<UL> -<LI><A HREF="#overview">An Overview of Curses</A> -<UL> -<LI><A HREF="#compiling">Compiling Programs using Curses</A> -<LI><A HREF="#updating">Updating the Screen</A> -<LI><A HREF="#stdscr">Standard Windows and Function Naming Conventions</A> -<LI><A HREF="#variables">Variables</A> -</UL> -<LI><A HREF="#using">Using the Library</A> -<UL> -<LI><A HREF="#starting">Starting up</A> -<LI><A HREF="#output">Output</A> -<LI><A HREF="#input">Input</A> -<LI><A HREF="#formschars">Using Forms Characters</A> -<LI><A HREF="#attributes">Character Attributes and Color</A> -<LI><A HREF="#mouse">Mouse Interfacing</A> -<LI><A HREF="#finishing">Finishing Up</A> -</UL> -<LI><A HREF="#functions">Function Descriptions</A> -<UL> -<LI><A HREF="#init">Initialization and Wrapup</A> -<LI><A HREF="#flush">Causing Output to the Terminal</A> -<LI><A HREF="#lowlevel">Low-Level Capability Access</A> -<LI><A HREF="#debugging">Debugging</A> -</UL> -<LI><A HREF="#hints">Hints, Tips, and Tricks</A> -<UL> -<LI><A HREF="#caution">Some Notes of Caution</A> -<LI><A HREF="#leaving">Temporarily Leaving ncurses Mode</A> -<LI><A HREF="#xterm">Using <CODE>ncurses</CODE> under <CODE>xterm</CODE></A> -<LI><A HREF="#screens">Handling Multiple Terminal Screens</A> -<LI><A HREF="#testing">Testing for Terminal Capabilities</A> -<LI><A HREF="#tuning">Tuning for Speed</A> -<LI><A HREF="#special">Special Features of <CODE>ncurses</CODE></A> -</UL> -<LI><A HREF="#compat">Compatibility with Older Versions</A> -<UL> -<LI><A HREF="#refbug">Refresh of Overlapping Windows</A> -<LI><A HREF="#backbug">Background Erase</A> -</UL> -<LI><A HREF="#xsifuncs">XSI Curses Conformance</A> -</UL> -<LI><A HREF="#panels">The Panels Library</A> -<UL> -<LI><A HREF="#pcompile">Compiling With the Panels Library</A> -<LI><A HREF="#poverview">Overview of Panels</A> -<LI><A HREF="#pstdscr">Panels, Input, and the Standard Screen</A> -<LI><A HREF="#hiding">Hiding Panels</A> -<LI><A HREF="#pmisc">Miscellaneous Other Facilities</A> -</UL> -<LI><A HREF="#menu">The Menu Library</A> -<UL> -<LI><A HREF="#mcompile">Compiling with the menu Library</A> -<LI><A HREF="#moverview">Overview of Menus</A> -<LI><A HREF="#mselect">Selecting items</A> -<LI><A HREF="#mdisplay">Menu Display</A> -<LI><A HREF="#mwindows">Menu Windows</A> -<LI><A HREF="#minput">Processing Menu Input</A> -<LI><A HREF="#mmisc">Miscellaneous Other Features</A> -</UL> -<LI><A HREF="#form">The Forms Library</A> -<UL> -<LI><A HREF="#fcompile">Compiling with the forms Library</A> -<LI><A HREF="#foverview">Overview of Forms</A> -<LI><A HREF="#fcreate">Creating and Freeing Fields and Forms</A> -<LI><A HREF="#fattributes">Fetching and Changing Field Attributes</A> -<UL> -<LI><A HREF="#fsizes">Fetching Size and Location Data</A> -<LI><A HREF="#flocation">Changing the Field Location</A> -<LI><A HREF="#fjust">The Justification Attribute</A> -<LI><A HREF="#fdispatts">Field Display Attributes</A> -<LI><A HREF="#foptions">Field Option Bits</A> -<LI><A HREF="#fstatus">Field Status</A> -<LI><A HREF="#fuser">Field User Pointer</A> -</UL> -<LI><A HREF="#fdynamic">Variable-Sized Fields</A> -<LI><A HREF="#fvalidation">Field Validation</A> -<UL> -<LI><A HREF="#ftype_alpha">TYPE_ALPHA</A> -<LI><A HREF="#ftype_alnum">TYPE_ALNUM</A> -<LI><A HREF="#ftype_enum">TYPE_ENUM</A> -<LI><A HREF="#ftype_integer">TYPE_INTEGER</A> -<LI><A HREF="#ftype_numeric">TYPE_NUMERIC</A> -<LI><A HREF="#ftype_regexp">TYPE_REGEXP</A> -</UL> -<LI><A HREF="#fbuffer">Direct Field Buffer Manipulation</A> -<LI><A HREF="#formattrs">Attributes of Forms</A> -<LI><A HREF="#fdisplay">Control of Form Display</A> -<LI><A HREF="#fdriver">Input Processing in the Forms Driver</A> -<UL> -<LI><A HREF="#fpage">Page Navigation Requests</A> -<LI><A HREF="#ffield">Inter-Field Navigation Requests</A> -<LI><A HREF="#fifield">Intra-Field Navigation Requests</A> -<LI><A HREF="#fscroll">Scrolling Requests</A> -<LI><A HREF="#fedit">Field Editing Requests</A> -<LI><A HREF="#forder">Order Requests</A> -<LI><A HREF="#fappcmds">Application Commands</A> -</UL> -<LI><A HREF="#fhooks">Field Change Hooks</A> -<LI><A HREF="#ffocus">Field Change Commands</A> -<LI><A HREF="#frmoptions">Form Options</A> -<LI><A HREF="#fcustom">Custom Validation Types</A> -<UL> -<LI><A HREF="#flinktypes">Union Types</A> -<LI><A HREF="#fnewtypes">New Field Types</A> -<LI><A HREF="#fcheckargs">Validation Function Arguments</A> -<LI><A HREF="#fcustorder">Order Functions For Custom Types</A> -<LI><A HREF="#fcustprobs">Avoiding Problems</A> -</UL> -</UL> -</UL> - -<HR> -<H1><A NAME="introduction">Introduction</A></H1> - -This document is an introduction to programming with <CODE>curses</CODE>. It is -not an exhaustive reference for the curses Application Programming Interface -(API); that role is filled by the <CODE>curses</CODE> manual pages. Rather, it -is intended to help C programmers ease into using the package. <P> - -This document is aimed at C applications programmers not yet specifically -familiar with ncurses. If you are already an experienced <CODE>curses</CODE> -programmer, you should nevertheless read the sections on -<A HREF="#mouse">Mouse Interfacing</A>, <A HREF="#debugging">Debugging</A>, -<A HREF="#compat">Compatibility with Older Versions</A>, -and <A HREF="#hints">Hints, Tips, and Tricks</A>. These will bring you up -to speed on the special features and quirks of the <CODE>ncurses</CODE> -implementation. If you are not so experienced, keep reading. <P> - -The <CODE>curses</CODE> package is a subroutine library for -terminal-independent screen-painting and input-event handling which -presents a high level screen model to the programmer, hiding differences -between terminal types and doing automatic optimization of output to change -one screen full of text into another. <CODE>Curses</CODE> uses terminfo, which -is a database format that can describe the capabilities of thousands of -different terminals. <P> - -The <CODE>curses</CODE> API may seem something of an archaism on UNIX desktops -increasingly dominated by X, Motif, and Tcl/Tk. Nevertheless, UNIX still -supports tty lines and X supports <EM>xterm(1)</EM>; the <CODE>curses</CODE> -API has the advantage of (a) back-portability to character-cell terminals, -and (b) simplicity. For an application that does not require bit-mapped -graphics and multiple fonts, an interface implementation using <CODE>curses</CODE> -will typically be a great deal simpler and less expensive than one using an -X toolkit. - -<H2><A NAME="history">A Brief History of Curses</A></H2> - -Historically, the first ancestor of <CODE>curses</CODE> was the routines written to -provide screen-handling for the game <CODE>rogue</CODE>; these used the -already-existing <CODE>termcap</CODE> database facility for describing terminal -capabilities. These routines were abstracted into a documented library and -first released with the early BSD UNIX versions. <P> - -System III UNIX from Bell Labs featured a rewritten and much-improved -<CODE>curses</CODE> library. It introduced the terminfo format. Terminfo is based -on Berkeley's termcap database, but contains a number of improvements and -extensions. Parameterized capabilities strings were introduced, making it -possible to describe multiple video attributes, and colors and to handle far -more unusual terminals than possible with termcap. In the later AT&T -System V releases, <CODE>curses</CODE> evolved to use more facilities and offer -more capabilities, going far beyond BSD curses in power and flexibility. - -<H2><A NAME="scope">Scope of This Document</A></H2> - -This document describes <CODE>ncurses</CODE>, a free implementation of -the System V <CODE>curses</CODE> API with some clearly marked extensions. -It includes the following System V curses features: -<UL> -<LI>Support for multiple screen highlights (BSD curses could only -handle one `standout' highlight, usually reverse-video). -<LI>Support for line- and box-drawing using forms characters. -<LI>Recognition of function keys on input. -<LI>Color support. -<LI>Support for pads (windows of larger than screen size on which the -screen or a subwindow defines a viewport). -</UL> - -Also, this package makes use of the insert and delete line and character -features of terminals so equipped, and determines how to optimally use these -features with no help from the programmer. It allows arbitrary combinations of -video attributes to be displayed, even on terminals that leave ``magic -cookies'' on the screen to mark changes in attributes. <P> - -The <CODE>ncurses</CODE> package can also capture and use event reports from a -mouse in some environments (notably, xterm under the X window system). This -document includes tips for using the mouse. <P> - -The <CODE>ncurses</CODE> package was originated by Pavel Curtis. The original -maintainer of this package is -<A HREF="mailto:zmbenhal@netcom.com">Zeyd Ben-Halim</A> -<zmbenhal@netcom.com>. -<A HREF="mailto:esr@snark.thyrsus.com">Eric S. Raymond</A> -<esr@snark.thyrsus.com> -wrote many of the new features in versions after 1.8.1 -and wrote most of this introduction. -Jürgen Pfeifer -wrote all of the menu and forms code as well as the -<A HREF="http://www.adahome.com">Ada95</A> binding. -Ongoing work is being done by -<A HREF="mailto:dickey@invisible-island.net">Thomas Dickey</A> (maintainer). -Contact the current maintainers at -<A HREF="mailto:bug-ncurses@gnu.org">bug-ncurses@gnu.org</A>. -<P> - -This document also describes the <A HREF="#panels">panels</A> extension library, -similarly modeled on the SVr4 panels facility. This library allows you to -associate backing store with each of a stack or deck of overlapping windows, -and provides operations for moving windows around in the stack that change -their visibility in the natural way (handling window overlaps). <P> - -Finally, this document describes in detail the <A HREF="#menu">menus</A> and <A -HREF="#form">forms</A> extension libraries, also cloned from System V, -which support easy construction and sequences of menus and fill-in -forms. - - -<H2><A NAME="terminology">Terminology</A></H2> - -In this document, the following terminology is used with reasonable -consistency: - -<DL> -<DT> window -<DD> -A data structure describing a sub-rectangle of the screen (possibly the -entire screen). You can write to a window as though it were a miniature -screen, scrolling independently of other windows on the physical screen. -<DT> screens -<DD> -A subset of windows which are as large as the terminal screen, i.e., they start -at the upper left hand corner and encompass the lower right hand corner. One -of these, <CODE>stdscr</CODE>, is automatically provided for the programmer. -<DT> terminal screen -<DD> -The package's idea of what the terminal display currently looks like, i.e., -what the user sees now. This is a special screen. -</DL> - -<H1><A NAME="curses">The Curses Library</A></H1> - -<H2><A NAME="overview">An Overview of Curses</A></H2> - -<H3><A NAME="compiling">Compiling Programs using Curses</A></H3> - -In order to use the library, it is necessary to have certain types and -variables defined. Therefore, the programmer must have a line: - -<PRE> - #include <curses.h> -</PRE> - -at the top of the program source. The screen package uses the Standard I/O -library, so <CODE><curses.h></CODE> includes -<CODE><stdio.h></CODE>. <CODE><curses.h></CODE> also includes -<CODE><termios.h></CODE>, <CODE><termio.h></CODE>, or -<CODE><sgtty.h></CODE> depending on your system. It is redundant (but -harmless) for the programmer to do these includes, too. In linking with -<CODE>curses</CODE> you need to have <CODE>-lncurses</CODE> in your LDFLAGS or on the -command line. There is no need for any other libraries. - -<H3><A NAME="updating">Updating the Screen</A></H3> - -In order to update the screen optimally, it is necessary for the routines to -know what the screen currently looks like and what the programmer wants it to -look like next. For this purpose, a data type (structure) named WINDOW is -defined which describes a window image to the routines, including its starting -position on the screen (the (y, x) coordinates of the upper left hand corner) -and its size. One of these (called <CODE>curscr</CODE>, for current screen) is a -screen image of what the terminal currently looks like. Another screen (called -<CODE>stdscr</CODE>, for standard screen) is provided by default to make changes -on. <P> - -A window is a purely internal representation. It is used to build and store a -potential image of a portion of the terminal. It doesn't bear any necessary -relation to what is really on the terminal screen; it's more like a -scratchpad or write buffer. <P> - -To make the section of physical screen corresponding to a window reflect the -contents of the window structure, the routine <CODE>refresh()</CODE> (or -<CODE>wrefresh()</CODE> if the window is not <CODE>stdscr</CODE>) is called. <P> - -A given physical screen section may be within the scope of any number of -overlapping windows. Also, changes can be made to windows in any order, -without regard to motion efficiency. Then, at will, the programmer can -effectively say ``make it look like this,'' and let the package implementation -determine the most efficient way to repaint the screen. - -<H3><A NAME="stdscr">Standard Windows and Function Naming Conventions</A></H3> - -As hinted above, the routines can use several windows, but two are -automatically given: <CODE>curscr</CODE>, which knows what the terminal looks like, -and <CODE>stdscr</CODE>, which is what the programmer wants the terminal to look -like next. The user should never actually access <CODE>curscr</CODE> directly. -Changes should be made to through the API, and then the routine -<CODE>refresh()</CODE> (or <CODE>wrefresh()</CODE>) called. <P> - -Many functions are defined to use <CODE>stdscr</CODE> as a default screen. For -example, to add a character to <CODE>stdscr</CODE>, one calls <CODE>addch()</CODE> with -the desired character as argument. To write to a different window. use the -routine <CODE>waddch()</CODE> (for `w'indow-specific addch()) is provided. This -convention of prepending function names with a `w' when they are to be -applied to specific windows is consistent. The only routines which do not -follow it are those for which a window must always be specified. <P> - -In order to move the current (y, x) coordinates from one point to another, the -routines <CODE>move()</CODE> and <CODE>wmove()</CODE> are provided. However, it is -often desirable to first move and then perform some I/O operation. In order to -avoid clumsiness, most I/O routines can be preceded by the prefix 'mv' and -the desired (y, x) coordinates prepended to the arguments to the function. For -example, the calls - -<PRE> - move(y, x); - addch(ch); -</PRE> - -can be replaced by - -<PRE> - mvaddch(y, x, ch); -</PRE> - -and - -<PRE> - wmove(win, y, x); - waddch(win, ch); -</PRE> - -can be replaced by - -<PRE> - mvwaddch(win, y, x, ch); -</PRE> - -Note that the window description pointer (win) comes before the added (y, x) -coordinates. If a function requires a window pointer, it is always the first -parameter passed. - -<H3><A NAME="variables">Variables</A></H3> - -The <CODE>curses</CODE> library sets some variables describing the terminal -capabilities. - -<PRE> +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> + +<html> +<head> + <meta name="generator" content= + "HTML Tidy for HTML5 for Linux version 5.2.0"> + + <title>Writing Programs with NCURSES</title> + <link rel="author" href="mailto:bugs-ncurses@gnu.org"> + <meta http-equiv="Content-Type" content= + "text/html; charset=us-ascii"> +</head> + +<body> + <h1>Writing Programs with NCURSES</h1> + + <blockquote> + by Eric S. Raymond and Zeyd M. Ben-Halim<br> + updates since release 1.9.9e by Thomas Dickey + </blockquote> + + <h1>Contents</h1> + + <ul> + <li> + <a href="#introduction">Introduction</a> + + <ul> + <li><a href="#history">A Brief History of Curses</a></li> + + <li><a href="#scope">Scope of This Document</a></li> + + <li><a href="#terminology">Terminology</a></li> + </ul> + </li> + + <li> + <a href="#curses">The Curses Library</a> + + <ul> + <li> + <a href="#overview">An Overview of Curses</a> + + <ul> + <li><a href="#compiling">Compiling Programs using + Curses</a></li> + + <li><a href="#updating">Updating the Screen</a></li> + + <li><a href="#stdscr">Standard Windows and Function + Naming Conventions</a></li> + + <li><a href="#variables">Variables</a></li> + </ul> + </li> + + <li> + <a href="#using">Using the Library</a> + + <ul> + <li><a href="#starting">Starting up</a></li> + + <li><a href="#output">Output</a></li> + + <li><a href="#input">Input</a></li> + + <li><a href="#formschars">Using Forms Characters</a></li> + + <li><a href="#attributes">Character Attributes and + Color</a></li> + + <li><a href="#mouse">Mouse Interfacing</a></li> + + <li><a href="#finishing">Finishing Up</a></li> + </ul> + </li> + + <li> + <a href="#functions">Function Descriptions</a> + + <ul> + <li><a href="#init">Initialization and Wrapup</a></li> + + <li><a href="#flush">Causing Output to the Terminal</a></li> + + <li><a href="#lowlevel">Low-Level Capability Access</a></li> + + <li><a href="#debugging">Debugging</a></li> + </ul> + </li> + + <li> + <a href="#hints">Hints, Tips, and Tricks</a> + + <ul> + <li><a href="#caution">Some Notes of Caution</a></li> + + <li><a href="#leaving">Temporarily Leaving ncurses + Mode</a></li> + + <li><a href="#xterm">Using <code>ncurses</code> under + <code>xterm</code></a></li> + + <li><a href="#screens">Handling Multiple Terminal + Screens</a></li> + + <li><a href="#testing">Testing for Terminal + Capabilities</a></li> + + <li><a href="#tuning">Tuning for Speed</a></li> + + <li><a href="#special">Special Features of + <code>ncurses</code></a></li> + </ul> + </li> + + <li> + <a href="#compat">Compatibility with Older Versions</a> + + <ul> + <li><a href="#refbug">Refresh of Overlapping + Windows</a></li> + + <li><a href="#backbug">Background Erase</a></li> + </ul> + </li> + + <li><a href="#xsifuncs">XSI Curses Conformance</a></li> + </ul> + </li> + + <li> + <a href="#panels">The Panels Library</a> + + <ul> + <li><a href="#pcompile">Compiling With the Panels + Library</a></li> + + <li><a href="#poverview">Overview of Panels</a></li> + + <li><a href="#pstdscr">Panels, Input, and the Standard + Screen</a></li> + + <li><a href="#hiding">Hiding Panels</a></li> + + <li><a href="#pmisc">Miscellaneous Other Facilities</a></li> + </ul> + </li> + + <li> + <a href="#menu">The Menu Library</a> + + <ul> + <li><a href="#mcompile">Compiling with the menu Library</a></li> + + <li><a href="#moverview">Overview of Menus</a></li> + + <li><a href="#mselect">Selecting items</a></li> + + <li><a href="#mdisplay">Menu Display</a></li> + + <li><a href="#mwindows">Menu Windows</a></li> + + <li><a href="#minput">Processing Menu Input</a></li> + + <li><a href="#mmisc">Miscellaneous Other Features</a></li> + </ul> + </li> + + <li> + <a href="#form">The Forms Library</a> + + <ul> + <li><a href="#fcompile">Compiling with the forms + Library</a></li> + + <li><a href="#foverview">Overview of Forms</a></li> + + <li><a href="#fcreate">Creating and Freeing Fields and + Forms</a></li> + + <li> + <a href="#fattributes">Fetching and Changing Field + Attributes</a> + + <ul> + <li><a href="#fsizes">Fetching Size and Location + Data</a></li> + + <li><a href="#flocation">Changing the Field + Location</a></li> + + <li><a href="#fjust">The Justification Attribute</a></li> + + <li><a href="#fdispatts">Field Display Attributes</a></li> + + <li><a href="#foptions">Field Option Bits</a></li> + + <li><a href="#fstatus">Field Status</a></li> + + <li><a href="#fuser">Field User Pointer</a></li> + </ul> + </li> + + <li><a href="#fdynamic">Variable-Sized Fields</a></li> + + <li> + <a href="#fvalidation">Field Validation</a> + + <ul> + <li><a href="#ftype_alpha">TYPE_ALPHA</a></li> + + <li><a href="#ftype_alnum">TYPE_ALNUM</a></li> + + <li><a href="#ftype_enum">TYPE_ENUM</a></li> + + <li><a href="#ftype_integer">TYPE_INTEGER</a></li> + + <li><a href="#ftype_numeric">TYPE_NUMERIC</a></li> + + <li><a href="#ftype_regexp">TYPE_REGEXP</a></li> + </ul> + </li> + + <li><a href="#fbuffer">Direct Field Buffer Manipulation</a></li> + + <li><a href="#formattrs">Attributes of Forms</a></li> + + <li><a href="#fdisplay">Control of Form Display</a></li> + + <li> + <a href="#fdriver">Input Processing in the Forms + Driver</a> + + <ul> + <li><a href="#fpage">Page Navigation Requests</a></li> + + <li><a href="#ffield">Inter-Field Navigation + Requests</a></li> + + <li><a href="#fifield">Intra-Field Navigation + Requests</a></li> + + <li><a href="#fscroll">Scrolling Requests</a></li> + + <li><a href="#fedit">Field Editing Requests</a></li> + + <li><a href="#forder">Order Requests</a></li> + + <li><a href="#fappcmds">Application Commands</a></li> + </ul> + </li> + + <li><a href="#fhooks">Field Change Hooks</a></li> + + <li><a href="#ffocus">Field Change Commands</a></li> + + <li><a href="#frmoptions">Form Options</a></li> + + <li> + <a href="#fcustom">Custom Validation Types</a> + + <ul> + <li><a href="#flinktypes">Union Types</a></li> + + <li><a href="#fnewtypes">New Field Types</a></li> + + <li><a href="#fcheckargs">Validation Function + Arguments</a></li> + + <li><a href="#fcustorder">Order Functions For Custom + Types</a></li> + + <li><a href="#fcustprobs">Avoiding Problems</a></li> + </ul> + </li> + </ul> + </li> + </ul> + + <hr> + + <h1><a name="introduction" id="introduction">Introduction</a></h1> + + <p>This document is an introduction to programming with + <code>curses</code>. It is not an exhaustive reference for the + curses Application Programming Interface (API); that role is + filled by the <code>curses</code> manual pages. Rather, it is + intended to help C programmers ease into using the package.</p> + + <p>This document is aimed at C applications programmers not yet + specifically familiar with ncurses. If you are already an + experienced <code>curses</code> programmer, you should + nevertheless read the sections on <a href="#mouse">Mouse + Interfacing</a>, <a href="#debugging">Debugging</a>, <a href= + "#compat">Compatibility with Older Versions</a>, and <a href= + "#hints">Hints, Tips, and Tricks</a>. These will bring you up to + speed on the special features and quirks of the + <code>ncurses</code> implementation. If you are not so + experienced, keep reading.</p> + + <p>The <code>curses</code> package is a subroutine library for + terminal-independent screen-painting and input-event handling + which presents a high level screen model to the programmer, + hiding differences between terminal types and doing automatic + optimization of output to change one screen full of text into + another. <code>Curses</code> uses terminfo, which is a database + format that can describe the capabilities of thousands of + different terminals.</p> + + <p>The <code>curses</code> API may seem something of an archaism + on UNIX desktops increasingly dominated by X, Motif, and Tcl/Tk. + Nevertheless, UNIX still supports tty lines and X supports + <em>xterm(1)</em>; the <code>curses</code> API has the advantage + of (a) back-portability to character-cell terminals, and (b) + simplicity. For an application that does not require bit-mapped + graphics and multiple fonts, an interface implementation using + <code>curses</code> will typically be a great deal simpler and + less expensive than one using an X toolkit.</p> + + <h2><a name="history" id="history">A Brief History of Curses</a></h2> + + <p>Historically, the first ancestor of <code>curses</code> was + the routines written to provide screen-handling for the + <code>vi</code> editor; these used the <code>termcap</code> + database facility (both released in 3BSD) for describing terminal + capabilities. These routines were abstracted into a documented + library and first released with the early BSD UNIX versions. All + of this work was done by students at the University of California + (Berkeley campus). The curses library was first published in + 4.0BSD, a year after 3BSD (i.e., late 1980).</p> + + <p>After graduation, one of those students went to work at + AT&T Bell Labs, and made an improved <code>termcap</code> + library called <code>terminfo</code> (i.e., + “libterm”), and adapted the curses library to use + this. That was subsequently released in System V Release 2 (early + 1984). Thereafter, other developers added to the curses and + terminfo libraries. For instance, a student at Cornell University + wrote an improved terminfo library as well as a tool + (<code>tic</code>) to compile the terminal descriptions. As a + general rule, AT&T did not identify the developers in the + source-code or documentation; the <code>tic</code> and + <code>infocmp</code> programs are the exceptions.</p> + + <p>System V Release 3 (System III UNIX) from Bell Labs featured a + rewritten and much-improved <code>curses</code> library, along + with the <code>tic</code> program (late 1986).</p> + + <p>To recap, terminfo is based on Berkeley's termcap database, + but contains a number of improvements and extensions. + Parameterized capabilities strings were introduced, making it + possible to describe multiple video attributes, and colors and to + handle far more unusual terminals than possible with termcap. In + the later AT&T System V releases, <code>curses</code> evolved + to use more facilities and offer more capabilities, going far + beyond BSD curses in power and flexibility.</p> + + <h2><a name="scope" id="scope">Scope of This Document</a></h2> + + <p>This document describes <code>ncurses</code>, a free + implementation of the System V <code>curses</code> API with some + clearly marked extensions. It includes the following System V + curses features:</p> + + <ul> + <li>Support for multiple screen highlights (BSD curses could + only handle one “standout” highlight, usually + reverse-video).</li> + + <li>Support for line- and box-drawing using forms + characters.</li> + + <li>Recognition of function keys on input.</li> + + <li>Color support.</li> + + <li>Support for pads (windows of larger than screen size on + which the screen or a subwindow defines a viewport).</li> + </ul> + + <p>Also, this package makes use of the insert and delete line and + character features of terminals so equipped, and determines how + to optimally use these features with no help from the programmer. + It allows arbitrary combinations of video attributes to be + displayed, even on terminals that leave “magic + cookies” on the screen to mark changes in attributes.</p> + + <p>The <code>ncurses</code> package can also capture and use + event reports from a mouse in some environments (notably, xterm + under the X window system). This document includes tips for using + the mouse.</p> + + <p>The <code>ncurses</code> package was originated by Pavel + Curtis. The original maintainer of this package is <a href= + "mailto:zmbenhal@netcom.com">Zeyd Ben-Halim</a> + <zmbenhal@netcom.com>. <a href= + "mailto:esr@snark.thyrsus.com">Eric S. Raymond</a> + <esr@snark.thyrsus.com> wrote many of the new features in + versions after 1.8.1 and wrote most of this introduction. + Jürgen Pfeifer wrote all of the menu and forms code as well + as the <a href="http://www.adahome.com">Ada95</a> binding. + Ongoing work is being done by <a href= + "mailto:dickey@invisible-island.net">Thomas Dickey</a> + (maintainer). Contact the current maintainers at <a href= + "mailto:bug-ncurses@gnu.org">bug-ncurses@gnu.org</a>.</p> + + <p>This document also describes the <a href="#panels">panels</a> + extension library, similarly modeled on the SVr4 panels facility. + This library allows you to associate backing store with each of a + stack or deck of overlapping windows, and provides operations for + moving windows around in the stack that change their visibility + in the natural way (handling window overlaps).</p> + + <p>Finally, this document describes in detail the <a href= + "#menu">menus</a> and <a href="#form">forms</a> extension + libraries, also cloned from System V, which support easy + construction and sequences of menus and fill-in forms.</p> + + <h2><a name="terminology" id="terminology">Terminology</a></h2> + + <p>In this document, the following terminology is used with + reasonable consistency:</p> + + <dl> + <dt>window</dt> + + <dd>A data structure describing a sub-rectangle of the screen + (possibly the entire screen). You can write to a window as + though it were a miniature screen, scrolling independently of + other windows on the physical screen.</dd> + + <dt>screens</dt> + + <dd>A subset of windows which are as large as the terminal + screen, i.e., they start at the upper left hand corner and + encompass the lower right hand corner. One of these, + <code>stdscr</code>, is automatically provided for the + programmer.</dd> + + <dt>terminal screen</dt> + + <dd>The package's idea of what the terminal display currently + looks like, i.e., what the user sees now. This is a special + screen.</dd> + </dl> + + <h1><a name="curses" id="curses">The Curses Library</a></h1> + + <h2><a name="overview" id="overview">An Overview of Curses</a></h2> + + <h3><a name="compiling" id="compiling">Compiling Programs using + Curses</a></h3> + + <p>In order to use the library, it is necessary to have certain + types and variables defined. Therefore, the programmer must have + a line:</p> + + <pre> + #include <curses.h> +</pre> + + <p>at the top of the program source. The screen package uses the + Standard I/O library, so <code><curses.h></code> includes + <code><stdio.h></code>. <code><curses.h></code> also + includes <code><termios.h></code>, + <code><termio.h></code>, or <code><sgtty.h></code> + depending on your system. It is redundant (but harmless) for the + programmer to do these includes, too. In linking with + <code>curses</code> you need to have <code>-lncurses</code> in + your LDFLAGS or on the command line. There is no need for any + other libraries.</p> + + <h3><a name="updating" id="updating">Updating the Screen</a></h3> + + <p>In order to update the screen optimally, it is necessary for + the routines to know what the screen currently looks like and + what the programmer wants it to look like next. For this purpose, + a data type (structure) named WINDOW is defined which describes a + window image to the routines, including its starting position on + the screen (the (y, x) coordinates of the upper left hand corner) + and its size. One of these (called <code>curscr</code>, for + current screen) is a screen image of what the terminal currently + looks like. Another screen (called <code>stdscr</code>, for + standard screen) is provided by default to make changes on.</p> + + <p>A window is a purely internal representation. It is used to + build and store a potential image of a portion of the terminal. + It does not bear any necessary relation to what is really on the + terminal screen; it is more like a scratchpad or write + buffer.</p> + + <p>To make the section of physical screen corresponding to a + window reflect the contents of the window structure, the routine + <code>refresh()</code> (or <code>wrefresh()</code> if the window + is not <code>stdscr</code>) is called.</p> + + <p>A given physical screen section may be within the scope of any + number of overlapping windows. Also, changes can be made to + windows in any order, without regard to motion efficiency. Then, + at will, the programmer can effectively say “make it look + like this,” and let the package implementation determine + the most efficient way to repaint the screen.</p> + + <h3><a name="stdscr" id="stdscr">Standard Windows and Function + Naming Conventions</a></h3> + + <p>As hinted above, the routines can use several windows, but two + are automatically given: <code>curscr</code>, which knows what + the terminal looks like, and <code>stdscr</code>, which is what + the programmer wants the terminal to look like next. The user + should never actually access <code>curscr</code> directly. + Changes should be made to through the API, and then the routine + <code>refresh()</code> (or <code>wrefresh()</code>) called.</p> + + <p>Many functions are defined to use <code>stdscr</code> as a + default screen. For example, to add a character to + <code>stdscr</code>, one calls <code>addch()</code> with the + desired character as argument. To write to a different window. + use the routine <code>waddch()</code> (for + <strong>w</strong>indow-specific addch()) is provided. This + convention of prepending function names with a “w” + when they are to be applied to specific windows is consistent. + The only routines which do not follow it are those for which a + window must always be specified.</p> + + <p>In order to move the current (y, x) coordinates from one point + to another, the routines <code>move()</code> and + <code>wmove()</code> are provided. However, it is often desirable + to first move and then perform some I/O operation. In order to + avoid clumsiness, most I/O routines can be preceded by the prefix + “mv” and the desired (y, x) coordinates prepended to + the arguments to the function. For example, the calls</p> + + <pre> + move(y, x); + addch(ch); +</pre> + + <p>can be replaced by</p> + + <pre> + mvaddch(y, x, ch); +</pre> + + <p>and</p> + + <pre> + wmove(win, y, x); + waddch(win, ch); +</pre> + + <p>can be replaced by</p> + + <pre> + mvwaddch(win, y, x, ch); +</pre> + + <p>Note that the window description pointer (win) comes before + the added (y, x) coordinates. If a function requires a window + pointer, it is always the first parameter passed.</p> + + <h3><a name="variables" id="variables">Variables</a></h3> + + <p>The <code>curses</code> library sets some variables describing + the terminal capabilities.</p> + + <pre> type name description ------------------------------------------------------------------ int LINES number of lines on the terminal int COLS number of columns on the terminal -</PRE> - -The <CODE>curses.h</CODE> also introduces some <CODE>#define</CODE> constants and types -of general usefulness: - -<DL> -<DT> <CODE>bool</CODE> -<DD> boolean type, actually a `char' (e.g., <CODE>bool doneit;</CODE>) -<DT> <CODE>TRUE</CODE> -<DD> boolean `true' flag (1). -<DT> <CODE>FALSE</CODE> -<DD> boolean `false' flag (0). -<DT> <CODE>ERR</CODE> -<DD> error flag returned by routines on a failure (-1). -<DT> <CODE>OK</CODE> -<DD> error flag returned by routines when things go right. -</DL> - -<H2><A NAME="using">Using the Library</A></H2> - -Now we describe how to actually use the screen package. In it, we assume all -updating, reading, etc. is applied to <CODE>stdscr</CODE>. These instructions will -work on any window, providing you change the function names and parameters as -mentioned above. <P> - -Here is a sample program to motivate the discussion: - -<PRE> +</pre> + + <p>The <code>curses.h</code> also introduces some + <code>#define</code> constants and types of general + usefulness:</p> + + <dl> + <dt><code>bool</code> + </dt> + + <dd>boolean type, actually a “char” (e.g., + <code>bool doneit;</code>)</dd> + + <dt><code>TRUE</code> + </dt> + + <dd>boolean “true” flag (1).</dd> + + <dt><code>FALSE</code> + </dt> + + <dd>boolean “false” flag (0).</dd> + + <dt><code>ERR</code> + </dt> + + <dd>error flag returned by routines on a failure (-1).</dd> + + <dt><code>OK</code> + </dt> + + <dd>error flag returned by routines when things go right.</dd> + </dl> + + <h2><a name="using" id="using">Using the Library</a></h2> + + <p>Now we describe how to actually use the screen package. In it, + we assume all updating, reading, etc. is applied to + <code>stdscr</code>. These instructions will work on any window, + providing you change the function names and parameters as + mentioned above.</p> + + <p>Here is a sample program to motivate the discussion:</p> + + <pre> #include <stdlib.h> #include <curses.h> #include <signal.h> @@ -458,9 +672,9 @@ main(int argc, char *argv[]) /* * Simple color assignment, often all we need. Color pair 0 cannot - * be redefined. This example uses the same value for the color - * pair as for the foreground color, though of course that is not - * necessary: + * be redefined. This example uses the same value for the color + * pair as for the foreground color, though of course that is not + * necessary: */ init_pair(1, COLOR_RED, COLOR_BLACK); init_pair(2, COLOR_GREEN, COLOR_BLACK); @@ -474,13 +688,13 @@ main(int argc, char *argv[]) for (;;) { int c = getch(); /* refresh, accept single keystroke of input */ - attrset(COLOR_PAIR(num % 8)); - num++; + attrset(COLOR_PAIR(num % 8)); + num++; /* process the command keystroke */ } - finish(0); /* we're done */ + finish(0); /* we are done */ } static void finish(int sig) @@ -491,1165 +705,1377 @@ static void finish(int sig) exit(0); } -</PRE> - -<H3><A NAME="starting">Starting up</A></H3> - -In order to use the screen package, the routines must know about terminal -characteristics, and the space for <CODE>curscr</CODE> and <CODE>stdscr</CODE> must be -allocated. These function <CODE>initscr()</CODE> does both these things. Since it -must allocate space for the windows, it can overflow memory when attempting to -do so. On the rare occasions this happens, <CODE>initscr()</CODE> will terminate -the program with an error message. <CODE>initscr()</CODE> must always be called -before any of the routines which affect windows are used. If it is not, the -program will core dump as soon as either <CODE>curscr</CODE> or <CODE>stdscr</CODE> are -referenced. However, it is usually best to wait to call it until after you are -sure you will need it, like after checking for startup errors. Terminal status -changing routines like <CODE>nl()</CODE> and <CODE>cbreak()</CODE> should be called -after <CODE>initscr()</CODE>. <P> - -Once the screen windows have been allocated, you can set them up for -your program. If you want to, say, allow a screen to scroll, use -<CODE>scrollok()</CODE>. If you want the cursor to be left in place after -the last change, use <CODE>leaveok()</CODE>. If this isn't done, -<CODE>refresh()</CODE> will move the cursor to the window's current (y, x) -coordinates after updating it. <P> - -You can create new windows of your own using the functions <CODE>newwin()</CODE>, -<CODE>derwin()</CODE>, and <CODE>subwin()</CODE>. The routine <CODE>delwin()</CODE> will -allow you to get rid of old windows. All the options described above can be -applied to any window. - -<H3><A NAME="output">Output</A></H3> - -Now that we have set things up, we will want to actually update the terminal. -The basic functions used to change what will go on a window are -<CODE>addch()</CODE> and <CODE>move()</CODE>. <CODE>addch()</CODE> adds a character at the -current (y, x) coordinates. <CODE>move()</CODE> changes the current (y, x) -coordinates to whatever you want them to be. It returns <CODE>ERR</CODE> if you -try to move off the window. As mentioned above, you can combine the two into -<CODE>mvaddch()</CODE> to do both things at once. <P> - -The other output functions, such as <CODE>addstr()</CODE> and <CODE>printw()</CODE>, -all call <CODE>addch()</CODE> to add characters to the window. <P> - -After you have put on the window what you want there, when you want the portion -of the terminal covered by the window to be made to look like it, you must call -<CODE>refresh()</CODE>. In order to optimize finding changes, <CODE>refresh()</CODE> -assumes that any part of the window not changed since the last -<CODE>refresh()</CODE> of that window has not been changed on the terminal, i.e., -that you have not refreshed a portion of the terminal with an overlapping -window. If this is not the case, the routine <CODE>touchwin()</CODE> is provided -to make it look like the entire window has been changed, thus making -<CODE>refresh()</CODE> check the whole subsection of the terminal for changes. <P> - -If you call <CODE>wrefresh()</CODE> with <CODE>curscr</CODE> as its argument, it will -make the screen look like <CODE>curscr</CODE> thinks it looks like. This is useful -for implementing a command which would redraw the screen in case it get messed -up. - -<H3><A NAME="input">Input</A></H3> - -The complementary function to <CODE>addch()</CODE> is <CODE>getch()</CODE> which, if -echo is set, will call <CODE>addch()</CODE> to echo the character. Since the -screen package needs to know what is on the terminal at all times, if -characters are to be echoed, the tty must be in raw or cbreak mode. Since -initially the terminal has echoing enabled and is in ordinary ``cooked'' mode, -one or the other has to changed before calling <CODE>getch()</CODE>; otherwise, -the program's output will be unpredictable. <P> - -When you need to accept line-oriented input in a window, the functions -<CODE>wgetstr()</CODE> and friends are available. There is even a <CODE>wscanw()</CODE> -function that can do <CODE>scanf()</CODE>(3)-style multi-field parsing on window -input. These pseudo-line-oriented functions turn on echoing while they -execute. <P> - -The example code above uses the call <CODE>keypad(stdscr, TRUE)</CODE> to enable -support for function-key mapping. With this feature, the <CODE>getch()</CODE> code -watches the input stream for character sequences that correspond to arrow and -function keys. These sequences are returned as pseudo-character values. The -<CODE>#define</CODE> values returned are listed in the <CODE>curses.h</CODE> The -mapping from sequences to <CODE>#define</CODE> values is determined by -<CODE>key_</CODE> capabilities in the terminal's terminfo entry. - -<H3><A NAME="formschars">Using Forms Characters</A></H3> - -The <CODE>addch()</CODE> function (and some others, including <CODE>box()</CODE> and -<CODE>border()</CODE>) can accept some pseudo-character arguments which are specially -defined by <CODE>ncurses</CODE>. These are <CODE>#define</CODE> values set up in -the <CODE>curses.h</CODE> header; see there for a complete list (look for -the prefix <CODE>ACS_</CODE>). <P> - -The most useful of the ACS defines are the forms-drawing characters. You can -use these to draw boxes and simple graphs on the screen. If the terminal -does not have such characters, <CODE>curses.h</CODE> will map them to a -recognizable (though ugly) set of ASCII defaults. - -<H3><A NAME="attributes">Character Attributes and Color</A></H3> - -The <CODE>ncurses</CODE> package supports screen highlights including standout, -reverse-video, underline, and blink. It also supports color, which is treated -as another kind of highlight. <P> - -Highlights are encoded, internally, as high bits of the pseudo-character type -(<CODE>chtype</CODE>) that <CODE>curses.h</CODE> uses to represent the contents of a -screen cell. See the <CODE>curses.h</CODE> header file for a complete list of -highlight mask values (look for the prefix <CODE>A_</CODE>).<P> - -There are two ways to make highlights. One is to logical-or the value of the -highlights you want into the character argument of an <CODE>addch()</CODE> call, -or any other output call that takes a <CODE>chtype</CODE> argument. <P> - -The other is to set the current-highlight value. This is logical-or'ed with -any highlight you specify the first way. You do this with the functions -<CODE>attron()</CODE>, <CODE>attroff()</CODE>, and <CODE>attrset()</CODE>; see the manual -pages for details. - -Color is a special kind of highlight. The package actually thinks in terms -of color pairs, combinations of foreground and background colors. The sample -code above sets up eight color pairs, all of the guaranteed-available colors -on black. Note that each color pair is, in effect, given the name of its -foreground color. Any other range of eight non-conflicting values could -have been used as the first arguments of the <CODE>init_pair()</CODE> values. <P> - -Once you've done an <CODE>init_pair()</CODE> that creates color-pair N, you can -use <CODE>COLOR_PAIR(N)</CODE> as a highlight that invokes that particular -color combination. Note that <CODE>COLOR_PAIR(N)</CODE>, for constant N, -is itself a compile-time constant and can be used in initializers. - -<H3><A NAME="mouse">Mouse Interfacing</A></H3> - -The <CODE>ncurses</CODE> library also provides a mouse interface. -<!-- The 'note' tag is not portable enough --> -<blockquote> -<strong>NOTE:</strong> this facility is specific to <CODE>ncurses</CODE>, it is not part of either -the XSI Curses standard, nor of System V Release 4, nor BSD curses. -System V Release 4 curses contains code with similar interface definitions, -however it is not documented. Other than by disassembling the library, we -have no way to determine exactly how that mouse code works. -Thus, we recommend that you wrap mouse-related code in an #ifdef using the -feature macro NCURSES_MOUSE_VERSION so it will not be compiled and linked -on non-ncurses systems. -</blockquote> - -Presently, mouse event reporting works in the following environments: -<ul> -<li>xterm and similar programs such as rxvt. -<li>Linux console, when configured with <CODE>gpm</CODE>(1), Alessandro -Rubini's mouse server. -<li>FreeBSD sysmouse (console) -<li>OS/2 EMX -</ul> -<P> -The mouse interface is very simple. To activate it, you use the function -<CODE>mousemask()</CODE>, passing it as first argument a bit-mask that specifies -what kinds of events you want your program to be able to see. It will -return the bit-mask of events that actually become visible, which may differ -from the argument if the mouse device is not capable of reporting some of -the event types you specify. <P> - -Once the mouse is active, your application's command loop should watch -for a return value of <CODE>KEY_MOUSE</CODE> from <CODE>wgetch()</CODE>. When -you see this, a mouse event report has been queued. To pick it off -the queue, use the function <CODE>getmouse()</CODE> (you must do this before -the next <CODE>wgetch()</CODE>, otherwise another mouse event might come -in and make the first one inaccessible). <P> - -Each call to <CODE>getmouse()</CODE> fills a structure (the address of which you'll -pass it) with mouse event data. The event data includes zero-origin, -screen-relative character-cell coordinates of the mouse pointer. It also -includes an event mask. Bits in this mask will be set, corresponding -to the event type being reported. <P> - -The mouse structure contains two additional fields which may be -significant in the future as ncurses interfaces to new kinds of -pointing device. In addition to x and y coordinates, there is a slot -for a z coordinate; this might be useful with touch-screens that can -return a pressure or duration parameter. There is also a device ID -field, which could be used to distinguish between multiple pointing -devices. <P> - -The class of visible events may be changed at any time via <CODE>mousemask()</CODE>. -Events that can be reported include presses, releases, single-, double- and -triple-clicks (you can set the maximum button-down time for clicks). If -you don't make clicks visible, they will be reported as press-release -pairs. In some environments, the event mask may include bits reporting -the state of shift, alt, and ctrl keys on the keyboard during the event. <P> - -A function to check whether a mouse event fell within a given window is -also supplied. You can use this to see whether a given window should -consider a mouse event relevant to it. <P> - -Because mouse event reporting will not be available in all -environments, it would be unwise to build <CODE>ncurses</CODE> -applications that <EM>require</EM> the use of a mouse. Rather, you should -use the mouse as a shortcut for point-and-shoot commands your application -would normally accept from the keyboard. Two of the test games in the -<CODE>ncurses</CODE> distribution (<CODE>bs</CODE> and <CODE>knight</CODE>) contain -code that illustrates how this can be done. <P> - -See the manual page <CODE>curs_mouse(3X)</CODE> for full details of the -mouse-interface functions. - -<H3><A NAME="finishing">Finishing Up</A></H3> - -In order to clean up after the <CODE>ncurses</CODE> routines, the routine -<CODE>endwin()</CODE> is provided. It restores tty modes to what they were when -<CODE>initscr()</CODE> was first called, and moves the cursor down to the -lower-left corner. Thus, anytime after the call to initscr, <CODE>endwin()</CODE> -should be called before exiting. - -<H2><A NAME="functions">Function Descriptions</A></H2> - -We describe the detailed behavior of some important curses functions here, as a -supplement to the manual page descriptions. - -<H3><A NAME="init">Initialization and Wrapup</A></H3> - -<DL> -<DT> <CODE>initscr()</CODE> -<DD> The first function called should almost always be <CODE>initscr()</CODE>. -This will determine the terminal type and -initialize curses data structures. <CODE>initscr()</CODE> also arranges that -the first call to <CODE>refresh()</CODE> will clear the screen. If an error -occurs a message is written to standard error and the program -exits. Otherwise it returns a pointer to stdscr. A few functions may be -called before initscr (<CODE>slk_init()</CODE>, <CODE>filter()</CODE>, -<CODE>ripoffline()</CODE>, <CODE>use_env()</CODE>, and, if you are using multiple -terminals, <CODE>newterm()</CODE>.) -<DT> <CODE>endwin()</CODE> -<DD> Your program should always call <CODE>endwin()</CODE> before exiting or -shelling out of the program. This function will restore tty modes, -move the cursor to the lower left corner of the screen, reset the -terminal into the proper non-visual mode. Calling <CODE>refresh()</CODE> -or <CODE>doupdate()</CODE> after a temporary escape from the program will -restore the ncurses screen from before the escape. -<DT> <CODE>newterm(type, ofp, ifp)</CODE> -<DD> A program which outputs to more than one terminal should use -<CODE>newterm()</CODE> instead of <CODE>initscr()</CODE>. <CODE>newterm()</CODE> should -be called once for each terminal. It returns a variable of type -<CODE>SCREEN *</CODE> which should be saved as a reference to that -terminal. -(NOTE: a SCREEN variable is not a <em>screen</em> in the sense we -are describing in this introduction, but a collection of -parameters used to assist in optimizing the display.) -The arguments are the type of the terminal (a string) and -<CODE>FILE</CODE> pointers for the output and input of the terminal. If -type is NULL then the environment variable <CODE>$TERM</CODE> is used. -<CODE>endwin()</CODE> should called once at wrapup time for each terminal -opened using this function. -<DT> <CODE>set_term(new)</CODE> -<DD> This function is used to switch to a different terminal previously -opened by <CODE>newterm()</CODE>. The screen reference for the new terminal -is passed as the parameter. The previous terminal is returned by the -function. All other calls affect only the current terminal. -<DT> <CODE>delscreen(sp)</CODE> -<DD> The inverse of <CODE>newterm()</CODE>; deallocates the data structures -associated with a given <CODE>SCREEN</CODE> reference. -</DL> - -<H3><A NAME="flush">Causing Output to the Terminal</A></H3> - -<DL> -<DT> <CODE>refresh()</CODE> and <CODE>wrefresh(win)</CODE> -<DD> These functions must be called to actually get any output on -the terminal, as other routines merely manipulate data -structures. <CODE>wrefresh()</CODE> copies the named window to the physical -terminal screen, taking into account what is already -there in order to do optimizations. <CODE>refresh()</CODE> does a -refresh of <CODE>stdscr</CODE>. Unless <CODE>leaveok()</CODE> has been -enabled, the physical cursor of the terminal is left at the -location of the window's cursor. -<DT> <CODE>doupdate()</CODE> and <CODE>wnoutrefresh(win)</CODE> -<DD> These two functions allow multiple updates with more efficiency -than wrefresh. To use them, it is important to understand how curses -works. In addition to all the window structures, curses keeps two -data structures representing the terminal screen: a physical screen, -describing what is actually on the screen, and a virtual screen, -describing what the programmer wants to have on the screen. wrefresh -works by first copying the named window to the virtual screen -(<CODE>wnoutrefresh()</CODE>), and then calling the routine to update the -screen (<CODE>doupdate()</CODE>). If the programmer wishes to output -several windows at once, a series of calls to <CODE>wrefresh</CODE> will result -in alternating calls to <CODE>wnoutrefresh()</CODE> and <CODE>doupdate()</CODE>, -causing several bursts of output to the screen. By calling -<CODE>wnoutrefresh()</CODE> for each window, it is then possible to call -<CODE>doupdate()</CODE> once, resulting in only one burst of output, with -fewer total characters transmitted (this also avoids a visually annoying -flicker at each update). -</DL> - -<H3><A NAME="lowlevel">Low-Level Capability Access</A></H3> - -<DL> -<DT> <CODE>setupterm(term, filenum, errret)</CODE> -<DD> This routine is called to initialize a terminal's description, without setting -up the curses screen structures or changing the tty-driver mode bits. -<CODE>term</CODE> is the character string representing the name of the terminal -being used. <CODE>filenum</CODE> is the UNIX file descriptor of the terminal to -be used for output. <CODE>errret</CODE> is a pointer to an integer, in which a -success or failure indication is returned. The values returned can be 1 (all -is well), 0 (no such terminal), or -1 (some problem locating the terminfo -database). <P> - -The value of <CODE>term</CODE> can be given as NULL, which will cause the value of -<CODE>TERM</CODE> in the environment to be used. The <CODE>errret</CODE> pointer can -also be given as NULL, meaning no error code is wanted. If <CODE>errret</CODE> is -defaulted, and something goes wrong, <CODE>setupterm()</CODE> will print an -appropriate error message and exit, rather than returning. Thus, a simple -program can call setupterm(0, 1, 0) and not worry about initialization -errors. <P> - -After the call to <CODE>setupterm()</CODE>, the global variable <CODE>cur_term</CODE> is -set to point to the current structure of terminal capabilities. By calling -<CODE>setupterm()</CODE> for each terminal, and saving and restoring -<CODE>cur_term</CODE>, it is possible for a program to use two or more terminals at -once. <CODE>Setupterm()</CODE> also stores the names section of the terminal -description in the global character array <CODE>ttytype[]</CODE>. Subsequent calls -to <CODE>setupterm()</CODE> will overwrite this array, so you'll have to save it -yourself if need be. -</DL> - -<H3><A NAME="debugging">Debugging</A></H3> - -<!-- The 'note' tag is not portable enough --> -<blockquote> -<strong>NOTE:</strong> These functions are not part of the standard curses API! -</blockquote> - -<DL> -<DT> <CODE>trace()</CODE> -<DD> -This function can be used to explicitly set a trace level. If the -trace level is nonzero, execution of your program will generate a file -called `trace' in the current working directory containing a report on -the library's actions. Higher trace levels enable more detailed (and -verbose) reporting -- see comments attached to <CODE>TRACE_</CODE> defines -in the <CODE>curses.h</CODE> file for details. (It is also possible to set -a trace level by assigning a trace level value to the environment variable -<CODE>NCURSES_TRACE</CODE>). -<DT> <CODE>_tracef()</CODE> -<DD> -This function can be used to output your own debugging information. It is only -available only if you link with -lncurses_g. It can be used the same way as -<CODE>printf()</CODE>, only it outputs a newline after the end of arguments. -The output goes to a file called <CODE>trace</CODE> in the current directory. -</DL> - -Trace logs can be difficult to interpret due to the sheer volume of -data dumped in them. There is a script called <STRONG>tracemunch</STRONG> -included with the <CODE>ncurses</CODE> distribution that can alleviate -this problem somewhat; it compacts long sequences of similar operations into -more succinct single-line pseudo-operations. These pseudo-ops can be -distinguished by the fact that they are named in capital letters. - -<H2><A NAME="hints">Hints, Tips, and Tricks</A></H2> - -The <CODE>ncurses</CODE> manual pages are a complete reference for this library. -In the remainder of this document, we discuss various useful methods that -may not be obvious from the manual page descriptions. - -<H3><A NAME="caution">Some Notes of Caution</A></H3> - -If you find yourself thinking you need to use <CODE>noraw()</CODE> or -<CODE>nocbreak()</CODE>, think again and move carefully. It's probably -better design to use <CODE>getstr()</CODE> or one of its relatives to -simulate cooked mode. The <CODE>noraw()</CODE> and <CODE>nocbreak()</CODE> -functions try to restore cooked mode, but they may end up clobbering -some control bits set before you started your application. Also, they -have always been poorly documented, and are likely to hurt your -application's usability with other curses libraries. <P> - -Bear in mind that <CODE>refresh()</CODE> is a synonym for <CODE>wrefresh(stdscr)</CODE>. -Don't try to mix use of <CODE>stdscr</CODE> with use of windows declared -by <CODE>newwin()</CODE>; a <CODE>refresh()</CODE> call will blow them off the -screen. The right way to handle this is to use <CODE>subwin()</CODE>, or -not touch <CODE>stdscr</CODE> at all and tile your screen with declared -windows which you then <CODE>wnoutrefresh()</CODE> somewhere in your program -event loop, with a single <CODE>doupdate()</CODE> call to trigger actual -repainting. <P> - -You are much less likely to run into problems if you design your screen -layouts to use tiled rather than overlapping windows. Historically, -curses support for overlapping windows has been weak, fragile, and poorly -documented. The <CODE>ncurses</CODE> library is not yet an exception to this -rule. <P> - -There is a panels library included in the <CODE>ncurses</CODE> -distribution that does a pretty good job of strengthening the -overlapping-windows facilities. <P> - -Try to avoid using the global variables LINES and COLS. Use -<CODE>getmaxyx()</CODE> on the <CODE>stdscr</CODE> context instead. Reason: -your code may be ported to run in an environment with window resizes, -in which case several screens could be open with different sizes. - -<H3><A NAME="leaving">Temporarily Leaving NCURSES Mode</A></H3> - -Sometimes you will want to write a program that spends most of its time in -screen mode, but occasionally returns to ordinary `cooked' mode. A common -reason for this is to support shell-out. This behavior is simple to arrange -in <CODE>ncurses</CODE>. <P> - -To leave <CODE>ncurses</CODE> mode, call <CODE>endwin()</CODE> as you would if you -were intending to terminate the program. This will take the screen back to -cooked mode; you can do your shell-out. When you want to return to -<CODE>ncurses</CODE> mode, simply call <CODE>refresh()</CODE> or <CODE>doupdate()</CODE>. -This will repaint the screen. <P> - -There is a boolean function, <CODE>isendwin()</CODE>, which code can use to -test whether <CODE>ncurses</CODE> screen mode is active. It returns <CODE>TRUE</CODE> -in the interval between an <CODE>endwin()</CODE> call and the following -<CODE>refresh()</CODE>, <CODE>FALSE</CODE> otherwise. <P> - -Here is some sample code for shellout: - -<PRE> +</pre> + + <h3><a name="starting" id="starting">Starting up</a></h3> + + <p>In order to use the screen package, the routines must know + about terminal characteristics, and the space for + <code>curscr</code> and <code>stdscr</code> must be allocated. + These function <code>initscr()</code> does both these things. + Since it must allocate space for the windows, it can overflow + memory when attempting to do so. On the rare occasions this + happens, <code>initscr()</code> will terminate the program with + an error message. <code>initscr()</code> must always be called + before any of the routines which affect windows are used. If it + is not, the program will core dump as soon as either + <code>curscr</code> or <code>stdscr</code> are referenced. + However, it is usually best to wait to call it until after you + are sure you will need it, like after checking for startup + errors. Terminal status changing routines like <code>nl()</code> + and <code>cbreak()</code> should be called after + <code>initscr()</code>.</p> + + <p>Once the screen windows have been allocated, you can set them + up for your program. If you want to, say, allow a screen to + scroll, use <code>scrollok()</code>. If you want the cursor to be + left in place after the last change, use <code>leaveok()</code>. + If this is not done, <code>refresh()</code> will move the cursor + to the window's current (y, x) coordinates after updating it.</p> + + <p>You can create new windows of your own using the functions + <code>newwin()</code>, <code>derwin()</code>, and + <code>subwin()</code>. The routine <code>delwin()</code> will + allow you to get rid of old windows. All the options described + above can be applied to any window.</p> + + <h3><a name="output" id="output">Output</a></h3> + + <p>Now that we have set things up, we will want to actually + update the terminal. The basic functions used to change what will + go on a window are <code>addch()</code> and <code>move()</code>. + <code>addch()</code> adds a character at the current (y, x) + coordinates. <code>move()</code> changes the current (y, x) + coordinates to whatever you want them to be. It returns + <code>ERR</code> if you try to move off the window. As mentioned + above, you can combine the two into <code>mvaddch()</code> to do + both things at once.</p> + + <p>The other output functions, such as <code>addstr()</code> and + <code>printw()</code>, all call <code>addch()</code> to add + characters to the window.</p> + + <p>After you have put on the window what you want there, when you + want the portion of the terminal covered by the window to be made + to look like it, you must call <code>refresh()</code>. In order + to optimize finding changes, <code>refresh()</code> assumes that + any part of the window not changed since the last + <code>refresh()</code> of that window has not been changed on the + terminal, i.e., that you have not refreshed a portion of the + terminal with an overlapping window. If this is not the case, the + routine <code>touchwin()</code> is provided to make it look like + the entire window has been changed, thus making + <code>refresh()</code> check the whole subsection of the terminal + for changes.</p> + + <p>If you call <code>wrefresh()</code> with <code>curscr</code> + as its argument, it will make the screen look like + <code>curscr</code> thinks it looks like. This is useful for + implementing a command which would redraw the screen in case it + get messed up.</p> + + <h3><a name="input" id="input">Input</a></h3> + + <p>The complementary function to <code>addch()</code> is + <code>getch()</code> which, if echo is set, will call + <code>addch()</code> to echo the character. Since the screen + package needs to know what is on the terminal at all times, if + characters are to be echoed, the tty must be in raw or cbreak + mode. Since initially the terminal has echoing enabled and is in + ordinary “cooked” mode, one or the other has to + changed before calling <code>getch()</code>; otherwise, the + program's output will be unpredictable.</p> + + <p>When you need to accept line-oriented input in a window, the + functions <code>wgetstr()</code> and friends are available. There + is even a <code>wscanw()</code> function that can do + <code>scanf()</code>(3)-style multi-field parsing on window + input. These pseudo-line-oriented functions turn on echoing while + they execute.</p> + + <p>The example code above uses the call <code>keypad(stdscr, + TRUE)</code> to enable support for function-key mapping. With + this feature, the <code>getch()</code> code watches the input + stream for character sequences that correspond to arrow and + function keys. These sequences are returned as pseudo-character + values. The <code>#define</code> values returned are listed in + the <code>curses.h</code> The mapping from sequences to + <code>#define</code> values is determined by <code>key_</code> + capabilities in the terminal's terminfo entry.</p> + + <h3><a name="formschars" id="formschars">Using Forms + Characters</a></h3> + + <p>The <code>addch()</code> function (and some others, including + <code>box()</code> and <code>border()</code>) can accept some + pseudo-character arguments which are specially defined by + <code>ncurses</code>. These are <code>#define</code> values set + up in the <code>curses.h</code> header; see there for a complete + list (look for the prefix <code>ACS_</code>).</p> + + <p>The most useful of the ACS defines are the forms-drawing + characters. You can use these to draw boxes and simple graphs on + the screen. If the terminal does not have such characters, + <code>curses.h</code> will map them to a recognizable (though + ugly) set of ASCII defaults.</p> + + <h3><a name="attributes" id="attributes">Character Attributes and + Color</a></h3> + + <p>The <code>ncurses</code> package supports screen highlights + including standout, reverse-video, underline, and blink. It also + supports color, which is treated as another kind of + highlight.</p> + + <p>Highlights are encoded, internally, as high bits of the + pseudo-character type (<code>chtype</code>) that + <code>curses.h</code> uses to represent the contents of a screen + cell. See the <code>curses.h</code> header file for a complete + list of highlight mask values (look for the prefix + <code>A_</code>).</p> + + <p>There are two ways to make highlights. One is to logical-or + the value of the highlights you want into the character argument + of an <code>addch()</code> call, or any other output call that + takes a <code>chtype</code> argument.</p> + + <p>The other is to set the current-highlight value. This is + <em>logical-OR</em>ed with any highlight you specify the first + way. You do this with the functions <code>attron()</code>, + <code>attroff()</code>, and <code>attrset()</code>; see the + manual pages for details. Color is a special kind of highlight. + The package actually thinks in terms of color pairs, combinations + of foreground and background colors. The sample code above sets + up eight color pairs, all of the guaranteed-available colors on + black. Note that each color pair is, in effect, given the name of + its foreground color. Any other range of eight non-conflicting + values could have been used as the first arguments of the + <code>init_pair()</code> values.</p> + + <p>Once you have done an <code>init_pair()</code> that creates + color-pair N, you can use <code>COLOR_PAIR(N)</code> as a + highlight that invokes that particular color combination. Note + that <code>COLOR_PAIR(N)</code>, for constant N, is itself a + compile-time constant and can be used in initializers.</p> + + <h3><a name="mouse" id="mouse">Mouse Interfacing</a></h3> + + <p>The <code>ncurses</code> library also provides a mouse + interface.</p> + + <blockquote> + <strong>NOTE:</strong> this facility is specific to + <code>ncurses</code>, it is not part of either the XSI Curses + standard, nor of System V Release 4, nor BSD curses. System V + Release 4 curses contains code with similar interface + definitions, however it is not documented. Other than by + disassembling the library, we have no way to determine exactly + how that mouse code works. Thus, we recommend that you wrap + mouse-related code in an #ifdef using the feature macro + NCURSES_MOUSE_VERSION so it will not be compiled and linked on + non-ncurses systems. + </blockquote> + + <p>Presently, mouse event reporting works in the following + environments:</p> + + <ul> + <li>xterm and similar programs such as rxvt.</li> + + <li>Linux console, when configured with <code>gpm</code>(1), + Alessandro Rubini's mouse server.</li> + + <li>FreeBSD sysmouse (console)</li> + + <li>OS/2 EMX</li> + </ul> + + <p>The mouse interface is very simple. To activate it, you use + the function <code>mousemask()</code>, passing it as first + argument a bit-mask that specifies what kinds of events you want + your program to be able to see. It will return the bit-mask of + events that actually become visible, which may differ from the + argument if the mouse device is not capable of reporting some of + the event types you specify.</p> + + <p>Once the mouse is active, your application's command loop + should watch for a return value of <code>KEY_MOUSE</code> from + <code>wgetch()</code>. When you see this, a mouse event report + has been queued. To pick it off the queue, use the function + <code>getmouse()</code> (you must do this before the next + <code>wgetch()</code>, otherwise another mouse event might come + in and make the first one inaccessible).</p> + + <p>Each call to <code>getmouse()</code> fills a structure (the + address of which you will pass it) with mouse event data. The + event data includes zero-origin, screen-relative character-cell + coordinates of the mouse pointer. It also includes an event mask. + Bits in this mask will be set, corresponding to the event type + being reported.</p> + + <p>The mouse structure contains two additional fields which may + be significant in the future as ncurses interfaces to new kinds + of pointing device. In addition to x and y coordinates, there is + a slot for a z coordinate; this might be useful with + touch-screens that can return a pressure or duration parameter. + There is also a device ID field, which could be used to + distinguish between multiple pointing devices.</p> + + <p>The class of visible events may be changed at any time via + <code>mousemask()</code>. Events that can be reported include + presses, releases, single-, double- and triple-clicks (you can + set the maximum button-down time for clicks). If you do not make + clicks visible, they will be reported as press-release pairs. In + some environments, the event mask may include bits reporting the + state of shift, alt, and ctrl keys on the keyboard during the + event.</p> + + <p>A function to check whether a mouse event fell within a given + window is also supplied. You can use this to see whether a given + window should consider a mouse event relevant to it.</p> + + <p>Because mouse event reporting will not be available in all + environments, it would be unwise to build <code>ncurses</code> + applications that <em>require</em> the use of a mouse. Rather, + you should use the mouse as a shortcut for point-and-shoot + commands your application would normally accept from the + keyboard. Two of the test games in the <code>ncurses</code> + distribution (<code>bs</code> and <code>knight</code>) contain + code that illustrates how this can be done.</p> + + <p>See the manual page <code>curs_mouse(3X)</code> for full + details of the mouse-interface functions.</p> + + <h3><a name="finishing" id="finishing">Finishing Up</a></h3> + + <p>In order to clean up after the <code>ncurses</code> routines, + the routine <code>endwin()</code> is provided. It restores tty + modes to what they were when <code>initscr()</code> was first + called, and moves the cursor down to the lower-left corner. Thus, + anytime after the call to initscr, <code>endwin()</code> should + be called before exiting.</p> + + <h2><a name="functions" id="functions">Function Descriptions</a></h2> + + <p>We describe the detailed behavior of some important curses + functions here, as a supplement to the manual page + descriptions.</p> + + <h3><a name="init" id="init">Initialization and Wrapup</a></h3> + + <dl> + <dt><code>initscr()</code> + </dt> + + <dd>The first function called should almost always be + <code>initscr()</code>. This will determine the terminal type + and initialize curses data structures. <code>initscr()</code> + also arranges that the first call to <code>refresh()</code> + will clear the screen. If an error occurs a message is written + to standard error and the program exits. Otherwise it returns a + pointer to stdscr. A few functions may be called before initscr + (<code>slk_init()</code>, <code>filter()</code>, + <code>ripoffline()</code>, <code>use_env()</code>, and, if you + are using multiple terminals, <code>newterm()</code>.)</dd> + + <dt><code>endwin()</code> + </dt> + + <dd>Your program should always call <code>endwin()</code> + before exiting or shelling out of the program. This function + will restore tty modes, move the cursor to the lower left + corner of the screen, reset the terminal into the proper + non-visual mode. Calling <code>refresh()</code> or + <code>doupdate()</code> after a temporary escape from the + program will restore the ncurses screen from before the + escape.</dd> + + <dt><code>newterm(type, ofp, ifp)</code> + </dt> + + <dd>A program which outputs to more than one terminal should + use <code>newterm()</code> instead of <code>initscr()</code>. + <code>newterm()</code> should be called once for each terminal. + It returns a variable of type <code>SCREEN *</code> which + should be saved as a reference to that terminal. (NOTE: a + SCREEN variable is not a <em>screen</em> in the sense we are + describing in this introduction, but a collection of parameters + used to assist in optimizing the display.) The arguments are + the type of the terminal (a string) and <code>FILE</code> + pointers for the output and input of the terminal. If type is + NULL then the environment variable <code>$TERM</code> is used. + <code>endwin()</code> should called once at wrapup time for + each terminal opened using this function.</dd> + + <dt><code>set_term(new)</code> + </dt> + + <dd>This function is used to switch to a different terminal + previously opened by <code>newterm()</code>. The screen + reference for the new terminal is passed as the parameter. The + previous terminal is returned by the function. All other calls + affect only the current terminal.</dd> + + <dt><code>delscreen(sp)</code> + </dt> + + <dd>The inverse of <code>newterm()</code>; deallocates the data + structures associated with a given <code>SCREEN</code> + reference.</dd> + </dl> + + <h3><a name="flush" id="flush">Causing Output to the Terminal</a></h3> + + <dl> + <dt><code>refresh()</code> and <code>wrefresh(win)</code></dt> + + <dd>These functions must be called to actually get any output + on the terminal, as other routines merely manipulate data + structures. <code>wrefresh()</code> copies the named window to + the physical terminal screen, taking into account what is + already there in order to do optimizations. + <code>refresh()</code> does a refresh of <code>stdscr</code>. + Unless <code>leaveok()</code> has been enabled, the physical + cursor of the terminal is left at the location of the window's + cursor.</dd> + + <dt><code>doupdate()</code> and + <code>wnoutrefresh(win)</code></dt> + + <dd>These two functions allow multiple updates with more + efficiency than wrefresh. To use them, it is important to + understand how curses works. In addition to all the window + structures, curses keeps two data structures representing the + terminal screen: a physical screen, describing what is actually + on the screen, and a virtual screen, describing what the + programmer wants to have on the screen. wrefresh works by first + copying the named window to the virtual screen + (<code>wnoutrefresh()</code>), and then calling the routine to + update the screen (<code>doupdate()</code>). If the programmer + wishes to output several windows at once, a series of calls to + <code>wrefresh</code> will result in alternating calls to + <code>wnoutrefresh()</code> and <code>doupdate()</code>, + causing several bursts of output to the screen. By calling + <code>wnoutrefresh()</code> for each window, it is then + possible to call <code>doupdate()</code> once, resulting in + only one burst of output, with fewer total characters + transmitted (this also avoids a visually annoying flicker at + each update).</dd> + </dl> + + <h3><a name="lowlevel" id="lowlevel">Low-Level Capability + Access</a></h3> + + <dl> + <dt><code>setupterm(term, filenum, errret)</code> + </dt> + + <dd> + This routine is called to initialize a terminal's + description, without setting up the curses screen structures + or changing the tty-driver mode bits. <code>term</code> is + the character string representing the name of the terminal + being used. <code>filenum</code> is the UNIX file descriptor + of the terminal to be used for output. <code>errret</code> is + a pointer to an integer, in which a success or failure + indication is returned. The values returned can be 1 (all is + well), 0 (no such terminal), or -1 (some problem locating the + terminfo database). + + <p>The value of <code>term</code> can be given as NULL, which + will cause the value of <code>TERM</code> in the environment + to be used. The <code>errret</code> pointer can also be given + as NULL, meaning no error code is wanted. If + <code>errret</code> is defaulted, and something goes wrong, + <code>setupterm()</code> will print an appropriate error + message and exit, rather than returning. Thus, a simple + program can call setupterm(0, 1, 0) and not worry about + initialization errors.</p> + + <p>After the call to <code>setupterm()</code>, the global + variable <code>cur_term</code> is set to point to the current + structure of terminal capabilities. By calling + <code>setupterm()</code> for each terminal, and saving and + restoring <code>cur_term</code>, it is possible for a program + to use two or more terminals at once. + <code>Setupterm()</code> also stores the names section of the + terminal description in the global character array + <code>ttytype[]</code>. Subsequent calls to + <code>setupterm()</code> will overwrite this array, so you + will have to save it yourself if need be.</p> + </dd> + </dl> + + <h3><a name="debugging" id="debugging">Debugging</a></h3> + + <blockquote> + <strong>NOTE:</strong> These functions are not part of the + standard curses API! + </blockquote> + + <dl> + <dt><code>trace()</code> + </dt> + + <dd>This function can be used to explicitly set a trace level. + If the trace level is nonzero, execution of your program will + generate a file called “trace” in the current + working directory containing a report on the library's actions. + Higher trace levels enable more detailed (and verbose) + reporting -- see comments attached to <code>TRACE_</code> + defines in the <code>curses.h</code> file for details. (It is + also possible to set a trace level by assigning a trace level + value to the environment variable + <code>NCURSES_TRACE</code>).</dd> + + <dt><code>_tracef()</code> + </dt> + + <dd>This function can be used to output your own debugging + information. It is only available only if you link with + -lncurses_g. It can be used the same way as + <code>printf()</code>, only it outputs a newline after the end + of arguments. The output goes to a file called + <code>trace</code> in the current directory.</dd> + </dl> + + <p>Trace logs can be difficult to interpret due to the sheer + volume of data dumped in them. There is a script called + <strong>tracemunch</strong> included with the + <code>ncurses</code> distribution that can alleviate this problem + somewhat; it compacts long sequences of similar operations into + more succinct single-line pseudo-operations. These pseudo-ops can + be distinguished by the fact that they are named in capital + letters.</p> + + <h2><a name="hints" id="hints">Hints, Tips, and Tricks</a></h2> + + <p>The <code>ncurses</code> manual pages are a complete reference + for this library. In the remainder of this document, we discuss + various useful methods that may not be obvious from the manual + page descriptions.</p> + + <h3><a name="caution" id="caution">Some Notes of Caution</a></h3> + + <p>If you find yourself thinking you need to use + <code>noraw()</code> or <code>nocbreak()</code>, think again and + move carefully. It is probably better design to use + <code>getstr()</code> or one of its relatives to simulate cooked + mode. The <code>noraw()</code> and <code>nocbreak()</code> + functions try to restore cooked mode, but they may end up + clobbering some control bits set before you started your + application. Also, they have always been poorly documented, and + are likely to hurt your application's usability with other curses + libraries.</p> + + <p>Bear in mind that <code>refresh()</code> is a synonym for + <code>wrefresh(stdscr)</code>. Do not try to mix use of + <code>stdscr</code> with use of windows declared by + <code>newwin()</code>; a <code>refresh()</code> call will blow + them off the screen. The right way to handle this is to use + <code>subwin()</code>, or not touch <code>stdscr</code> at all + and tile your screen with declared windows which you then + <code>wnoutrefresh()</code> somewhere in your program event loop, + with a single <code>doupdate()</code> call to trigger actual + repainting.</p> + + <p>You are much less likely to run into problems if you design + your screen layouts to use tiled rather than overlapping windows. + Historically, curses support for overlapping windows has been + weak, fragile, and poorly documented. The <code>ncurses</code> + library is not yet an exception to this rule.</p> + + <p>There is a panels library included in the <code>ncurses</code> + distribution that does a pretty good job of strengthening the + overlapping-windows facilities.</p> + + <p>Try to avoid using the global variables LINES and COLS. Use + <code>getmaxyx()</code> on the <code>stdscr</code> context + instead. Reason: your code may be ported to run in an environment + with window resizes, in which case several screens could be open + with different sizes.</p> + + <h3><a name="leaving" id="leaving">Temporarily Leaving NCURSES + Mode</a></h3> + + <p>Sometimes you will want to write a program that spends most of + its time in screen mode, but occasionally returns to ordinary + “cooked” mode. A common reason for this is to support + shell-out. This behavior is simple to arrange in + <code>ncurses</code>.</p> + + <p>To leave <code>ncurses</code> mode, call <code>endwin()</code> + as you would if you were intending to terminate the program. This + will take the screen back to cooked mode; you can do your + shell-out. When you want to return to <code>ncurses</code> mode, + simply call <code>refresh()</code> or <code>doupdate()</code>. + This will repaint the screen.</p> + + <p>There is a boolean function, <code>isendwin()</code>, which + code can use to test whether <code>ncurses</code> screen mode is + active. It returns <code>TRUE</code> in the interval between an + <code>endwin()</code> call and the following + <code>refresh()</code>, <code>FALSE</code> otherwise.</p> + + <p>Here is some sample code for shellout:</p> + + <pre> addstr("Shelling out..."); def_prog_mode(); /* save current tty modes */ endwin(); /* restore original tty modes */ system("sh"); /* run shell */ addstr("returned.\n"); /* prepare return message */ refresh(); /* restore save modes, repaint screen */ -</PRE> - -<H3><A NAME="xterm">Using NCURSES under XTERM</A></H3> - -A resize operation in X sends <CODE>SIGWINCH</CODE> to the application running -under xterm. - -The easiest way to handle <CODE>SIGWINCH</CODE> -is to do an <CODE>endwin</CODE>, -followed by an <CODE>refresh</CODE> and a screen repaint you code -yourself. -The <CODE>refresh</CODE> will pick up the new screen size from the -xterm's environment. <P> - -That is the standard way, of course (it even works with some vendor's curses -implementations). -Its drawback is that it clears the screen to reinitialize the display, and does -not resize subwindows which must be shrunk. -<CODE>Ncurses</CODE> provides an extension which works better, the -<CODE>resizeterm</CODE> function. That function ensures that all windows -are limited to the new screen dimensions, and pads <CODE>stdscr</CODE> -with blanks if the screen is larger. <P> - -The <CODE>ncurses</CODE> library provides a SIGWINCH signal handler, -which pushes a <CODE>KEY_RESIZE</CODE> via the wgetch() calls. -When <CODE>ncurses</CODE> returns that code, -it calls <code>resizeterm</CODE> -to update the size of the standard screen's window, repainting that -(filling with blanks or truncating as needed). -It also resizes other windows, -but its effect may be less satisfactory because it cannot -know how you want the screen re-painted. -You will usually have to write special-purpose code to handle -<CODE>KEY_RESIZE</CODE> yourself. - -<H3><A NAME="screens">Handling Multiple Terminal Screens</A></H3> - -The <CODE>initscr()</CODE> function actually calls a function named -<CODE>newterm()</CODE> to do most of its work. If you are writing a program that -opens multiple terminals, use <CODE>newterm()</CODE> directly. <P> - -For each call, you will have to specify a terminal type and a pair of file -pointers; each call will return a screen reference, and <CODE>stdscr</CODE> will be -set to the last one allocated. You will switch between screens with the -<CODE>set_term</CODE> call. Note that you will also have to call -<CODE>def_shell_mode</CODE> and <CODE>def_prog_mode</CODE> on each tty yourself. - -<H3><A NAME="testing">Testing for Terminal Capabilities</A></H3> - -Sometimes you may want to write programs that test for the presence of various -capabilities before deciding whether to go into <CODE>ncurses</CODE> mode. An easy -way to do this is to call <CODE>setupterm()</CODE>, then use the functions -<CODE>tigetflag()</CODE>, <CODE>tigetnum()</CODE>, and <CODE>tigetstr()</CODE> to do your -testing. <P> - -A particularly useful case of this often comes up when you want to -test whether a given terminal type should be treated as `smart' -(cursor-addressable) or `stupid'. The right way to test this is to see -if the return value of <CODE>tigetstr("cup")</CODE> is non-NULL. Alternatively, -you can include the <CODE>term.h</CODE> file and test the value of the -macro <CODE>cursor_address</CODE>. - -<H3><A NAME="tuning">Tuning for Speed</A></H3> - -Use the <CODE>addchstr()</CODE> family of functions for fast -screen-painting of text when you know the text doesn't contain any -control characters. Try to make attribute changes infrequent on your -screens. Don't use the <CODE>immedok()</CODE> option! - -<H3><A NAME="special">Special Features of NCURSES</A></H3> - -The <CODE>wresize()</CODE> function allows you to resize a window in place. -The associated <CODE>resizeterm()</CODE> function simplifies the construction -of <a HREF="#xterm">SIGWINCH</a> handlers, for resizing all windows. <P> - -The <CODE>define_key()</CODE> function allows you -to define at runtime function-key control sequences which are not in the -terminal description. -The <CODE>keyok()</CODE> function allows you to temporarily -enable or disable interpretation of any function-key control sequence. <P> - -The <CODE>use_default_colors()</CODE> function allows you to construct -applications which can use the terminal's default foreground and -background colors as an additional "default" color. -Several terminal emulators support this feature, which is based on ISO 6429. <P> - -Ncurses supports up 16 colors, unlike SVr4 curses which defines only 8. -While most terminals which provide color allow only 8 colors, about -a quarter (including XFree86 xterm) support 16 colors. - -<H2><A NAME="compat">Compatibility with Older Versions</A></H2> - -Despite our best efforts, there are some differences between <CODE>ncurses</CODE> -and the (undocumented!) behavior of older curses implementations. These arise -from ambiguities or omissions in the documentation of the API. - -<H3><A NAME="refbug">Refresh of Overlapping Windows</A></H3> - -If you define two windows A and B that overlap, and then alternately scribble -on and refresh them, the changes made to the overlapping region under historic -<CODE>curses</CODE> versions were often not documented precisely. <P> - -To understand why this is a problem, remember that screen updates are -calculated between two representations of the <EM>entire</EM> display. The -documentation says that when you refresh a window, it is first copied to the -virtual screen, and then changes are calculated to update the physical screen -(and applied to the terminal). But "copied to" is not very specific, and -subtle differences in how copying works can produce different behaviors in the -case where two overlapping windows are each being refreshed at unpredictable -intervals. <P> - -What happens to the overlapping region depends on what <CODE>wnoutrefresh()</CODE> -does with its argument -- what portions of the argument window it copies to the -virtual screen. Some implementations do "change copy", copying down only -locations in the window that have changed (or been marked changed with -<CODE>wtouchln()</CODE> and friends). Some implementations do "entire copy", -copying <EM>all</EM> window locations to the virtual screen whether or not -they have changed. <P> - -The <CODE>ncurses</CODE> library itself has not always been consistent on this -score. Due to a bug, versions 1.8.7 to 1.9.8a did entire copy. Versions -1.8.6 and older, and versions 1.9.9 and newer, do change copy. <P> - -For most commercial curses implementations, it is not documented and not known -for sure (at least not to the <CODE>ncurses</CODE> maintainers) whether they do -change copy or entire copy. We know that System V release 3 curses has logic -in it that looks like an attempt to do change copy, but the surrounding logic -and data representations are sufficiently complex, and our knowledge -sufficiently indirect, that it's hard to know whether this is reliable. - -It is not clear what the SVr4 documentation and XSI standard intend. The XSI -Curses standard barely mentions wnoutrefresh(); the SVr4 documents seem to be -describing entire-copy, but it is possible with some effort and straining to -read them the other way. <P> - -It might therefore be unwise to rely on either behavior in programs that might -have to be linked with other curses implementations. Instead, you can do an -explicit <CODE>touchwin()</CODE> before the <CODE>wnoutrefresh()</CODE> call to -guarantee an entire-contents copy anywhere. <P> - -The really clean way to handle this is to use the panels library. If, -when you want a screen update, you do <CODE>update_panels()</CODE>, it will -do all the necessary <CODE>wnoutrefresh()</CODE> calls for whatever panel -stacking order you have defined. Then you can do one <CODE>doupdate()</CODE> -and there will be a <EM>single</EM> burst of physical I/O that will do -all your updates. - -<H3><A NAME="backbug">Background Erase</A></H3> - -If you have been using a very old versions of <CODE>ncurses</CODE> (1.8.7 or -older) you may be surprised by the behavior of the erase functions. In older -versions, erased areas of a window were filled with a blank modified by the -window's current attribute (as set by <STRONG>wattrset()</STRONG>, <STRONG>wattron()</STRONG>, -<STRONG>wattroff()</STRONG> and friends). <P> - -In newer versions, this is not so. Instead, the attribute of erased blanks -is normal unless and until it is modified by the functions <CODE>bkgdset()</CODE> -or <CODE>wbkgdset()</CODE>. <P> - -This change in behavior conforms <CODE>ncurses</CODE> to System V Release 4 and -the XSI Curses standard. - -<H2><A NAME="xsifuncs">XSI Curses Conformance</A></H2> - -The <CODE>ncurses</CODE> library is intended to be base-level conformant with the -XSI Curses standard from X/Open. Many extended-level features (in fact, almost -all features not directly concerned with wide characters and -internationalization) are also supported. <P> - -One effect of XSI conformance is the change in behavior described under -<A HREF="#backbug">"Background Erase -- Compatibility with Old Versions"</A>. <P> - -Also, <CODE>ncurses</CODE> meets the XSI requirement that every macro -entry point have a corresponding function which may be linked (and -will be prototype-checked) if the macro definition is disabled with -<CODE>#undef</CODE>. - -<H1><A NAME="panels">The Panels Library</A></H1> - -The <CODE>ncurses</CODE> library by itself provides good support for screen -displays in which the windows are tiled (non-overlapping). In the more -general case that windows may overlap, you have to use a series of -<CODE>wnoutrefresh()</CODE> calls followed by a <CODE>doupdate()</CODE>, and be -careful about the order you do the window refreshes in. It has to be -bottom-upwards, otherwise parts of windows that should be obscured will -show through. <P> - -When your interface design is such that windows may dive deeper into the -visibility stack or pop to the top at runtime, the resulting book-keeping -can be tedious and difficult to get right. Hence the panels library. <P> - -The <CODE>panel</CODE> library first appeared in AT&T System V. The -version documented here is the <CODE>panel</CODE> code distributed -with <CODE>ncurses</CODE>. - -<H2><A NAME="pcompile">Compiling With the Panels Library</A></H2> - -Your panels-using modules must import the panels library declarations with - -<PRE> - #include <panel.h> -</PRE> - -and must be linked explicitly with the panels library using an -<CODE>-lpanel</CODE> argument. Note that they must also link the -<CODE>ncurses</CODE> library with <CODE>-lncurses</CODE>. Many linkers -are two-pass and will accept either order, but it is still good practice -to put <CODE>-lpanel</CODE> first and <CODE>-lncurses</CODE> second. - -<H2><A NAME="poverview">Overview of Panels</A></H2> - -A panel object is a window that is implicitly treated as part of a -<DFN>deck</DFN> including all other panel objects. The deck has an implicit -bottom-to-top visibility order. The panels library includes an update -function (analogous to <CODE>refresh()</CODE>) that displays all panels in the -deck in the proper order to resolve overlaps. The standard window, -<CODE>stdscr</CODE>, is considered below all panels. <P> - -Details on the panels functions are available in the man pages. We'll just -hit the highlights here. <P> - -You create a panel from a window by calling <CODE>new_panel()</CODE> on a -window pointer. It then becomes the top of the deck. The panel's window -is available as the value of <CODE>panel_window()</CODE> called with the -panel pointer as argument.<P> - -You can delete a panel (removing it from the deck) with <CODE>del_panel</CODE>. -This will not deallocate the associated window; you have to do that yourself. +</pre> + + <h3><a name="xterm" id="xterm">Using NCURSES under XTERM</a></h3> + + <p>A resize operation in X sends <code>SIGWINCH</code> to the + application running under xterm. The easiest way to handle + <code>SIGWINCH</code> is to do an <code>endwin</code>, followed + by an <code>refresh</code> and a screen repaint you code + yourself. The <code>refresh</code> will pick up the new screen + size from the xterm's environment.</p> + + <p>That is the standard way, of course (it even works with some + vendor's curses implementations). Its drawback is that it clears + the screen to reinitialize the display, and does not resize + subwindows which must be shrunk. <code>Ncurses</code> provides an + extension which works better, the <code>resizeterm</code> + function. That function ensures that all windows are limited to + the new screen dimensions, and pads <code>stdscr</code> with + blanks if the screen is larger.</p> + + <p>The <code>ncurses</code> library provides a SIGWINCH signal + handler, which pushes a <code>KEY_RESIZE</code> via the wgetch() + calls. When <code>ncurses</code> returns that code, it calls + <code>resizeterm</code> to update the size of the standard + screen's window, repainting that (filling with blanks or + truncating as needed). It also resizes other windows, but its + effect may be less satisfactory because it cannot know how you + want the screen re-painted. You will usually have to write + special-purpose code to handle <code>KEY_RESIZE</code> + yourself.</p> + + <h3><a name="screens" id="screens">Handling Multiple Terminal + Screens</a></h3> + + <p>The <code>initscr()</code> function actually calls a function + named <code>newterm()</code> to do most of its work. If you are + writing a program that opens multiple terminals, use + <code>newterm()</code> directly.</p> + + <p>For each call, you will have to specify a terminal type and a + pair of file pointers; each call will return a screen reference, + and <code>stdscr</code> will be set to the last one allocated. + You will switch between screens with the <code>set_term</code> + call. Note that you will also have to call + <code>def_shell_mode</code> and <code>def_prog_mode</code> on + each tty yourself.</p> + + <h3><a name="testing" id="testing">Testing for Terminal + Capabilities</a></h3> + + <p>Sometimes you may want to write programs that test for the + presence of various capabilities before deciding whether to go + into <code>ncurses</code> mode. An easy way to do this is to call + <code>setupterm()</code>, then use the functions + <code>tigetflag()</code>, <code>tigetnum()</code>, and + <code>tigetstr()</code> to do your testing.</p> + + <p>A particularly useful case of this often comes up when you + want to test whether a given terminal type should be treated as + “smart” (cursor-addressable) or “stupid”. + The right way to test this is to see if the return value of + <code>tigetstr("cup")</code> is non-NULL. Alternatively, you can + include the <code>term.h</code> file and test the value of the + macro <code>cursor_address</code>.</p> + + <h3><a name="tuning" id="tuning">Tuning for Speed</a></h3> + + <p>Use the <code>addchstr()</code> family of functions for fast + screen-painting of text when you know the text does not contain + any control characters. Try to make attribute changes infrequent + on your screens. Do not use the <code>immedok()</code> + option!</p> + + <h3><a name="special" id="special">Special Features of + NCURSES</a></h3> + + <p>The <code>wresize()</code> function allows you to resize a + window in place. The associated <code>resizeterm()</code> + function simplifies the construction of <a href= + "#xterm">SIGWINCH</a> handlers, for resizing all windows.</p> + + <p>The <code>define_key()</code> function allows you to define at + runtime function-key control sequences which are not in the + terminal description. The <code>keyok()</code> function allows + you to temporarily enable or disable interpretation of any + function-key control sequence.</p> + + <p>The <code>use_default_colors()</code> function allows you to + construct applications which can use the terminal's default + foreground and background colors as an additional "default" + color. Several terminal emulators support this feature, which is + based on ISO 6429.</p> + + <p>Ncurses supports up 16 colors, unlike SVr4 curses which + defines only 8. While most terminals which provide color allow + only 8 colors, about a quarter (including XFree86 xterm) support + 16 colors.</p> + + <h2><a name="compat" id="compat">Compatibility with Older + Versions</a></h2> + + <p>Despite our best efforts, there are some differences between + <code>ncurses</code> and the (undocumented!) behavior of older + curses implementations. These arise from ambiguities or omissions + in the documentation of the API.</p> + + <h3><a name="refbug" id="refbug">Refresh of Overlapping + Windows</a></h3> + + <p>If you define two windows A and B that overlap, and then + alternately scribble on and refresh them, the changes made to the + overlapping region under historic <code>curses</code> versions + were often not documented precisely.</p> + + <p>To understand why this is a problem, remember that screen + updates are calculated between two representations of the + <em>entire</em> display. The documentation says that when you + refresh a window, it is first copied to the virtual screen, and + then changes are calculated to update the physical screen (and + applied to the terminal). But "copied to" is not very specific, + and subtle differences in how copying works can produce different + behaviors in the case where two overlapping windows are each + being refreshed at unpredictable intervals.</p> + + <p>What happens to the overlapping region depends on what + <code>wnoutrefresh()</code> does with its argument -- what + portions of the argument window it copies to the virtual screen. + Some implementations do "change copy", copying down only + locations in the window that have changed (or been marked changed + with <code>wtouchln()</code> and friends). Some implementations + do "entire copy", copying <em>all</em> window locations to the + virtual screen whether or not they have changed.</p> + + <p>The <code>ncurses</code> library itself has not always been + consistent on this score. Due to a bug, versions 1.8.7 to 1.9.8a + did entire copy. Versions 1.8.6 and older, and versions 1.9.9 and + newer, do change copy.</p> + + <p>For most commercial curses implementations, it is not + documented and not known for sure (at least not to the + <code>ncurses</code> maintainers) whether they do change copy or + entire copy. We know that System V release 3 curses has logic in + it that looks like an attempt to do change copy, but the + surrounding logic and data representations are sufficiently + complex, and our knowledge sufficiently indirect, that it is hard + to know whether this is reliable. It is not clear what the SVr4 + documentation and XSI standard intend. The XSI Curses standard + barely mentions wnoutrefresh(); the SVr4 documents seem to be + describing entire-copy, but it is possible with some effort and + straining to read them the other way.</p> + + <p>It might therefore be unwise to rely on either behavior in + programs that might have to be linked with other curses + implementations. Instead, you can do an explicit + <code>touchwin()</code> before the <code>wnoutrefresh()</code> + call to guarantee an entire-contents copy anywhere.</p> + + <p>The really clean way to handle this is to use the panels + library. If, when you want a screen update, you do + <code>update_panels()</code>, it will do all the necessary + <code>wnoutrefresh()</code> calls for whatever panel stacking + order you have defined. Then you can do one + <code>doupdate()</code> and there will be a <em>single</em> burst + of physical I/O that will do all your updates.</p> + + <h3><a name="backbug" id="backbug">Background Erase</a></h3> + + <p>If you have been using a very old versions of + <code>ncurses</code> (1.8.7 or older) you may be surprised by the + behavior of the erase functions. In older versions, erased areas + of a window were filled with a blank modified by the window's + current attribute (as set by <strong>wattrset()</strong>, + <strong>wattron()</strong>, <strong>wattroff()</strong> and + friends).</p> + + <p>In newer versions, this is not so. Instead, the attribute of + erased blanks is normal unless and until it is modified by the + functions <code>bkgdset()</code> or <code>wbkgdset()</code>.</p> + + <p>This change in behavior conforms <code>ncurses</code> to + System V Release 4 and the XSI Curses standard.</p> + + <h2><a name="xsifuncs" id="xsifuncs">XSI Curses Conformance</a></h2> + + <p>The <code>ncurses</code> library is intended to be base-level + conformant with the XSI Curses standard from X/Open. Many + extended-level features (in fact, almost all features not + directly concerned with wide characters and internationalization) + are also supported.</p> + + <p>One effect of XSI conformance is the change in behavior + described under <a href="#backbug">"Background Erase -- + Compatibility with Old Versions"</a>.</p> + + <p>Also, <code>ncurses</code> meets the XSI requirement that + every macro entry point have a corresponding function which may + be linked (and will be prototype-checked) if the macro definition + is disabled with <code>#undef</code>.</p> + + <h1><a name="panels" id="panels">The Panels Library</a></h1> + + <p>The <code>ncurses</code> library by itself provides good + support for screen displays in which the windows are tiled + (non-overlapping). In the more general case that windows may + overlap, you have to use a series of <code>wnoutrefresh()</code> + calls followed by a <code>doupdate()</code>, and be careful about + the order you do the window refreshes in. It has to be + bottom-upwards, otherwise parts of windows that should be + obscured will show through.</p> + + <p>When your interface design is such that windows may dive + deeper into the visibility stack or pop to the top at runtime, + the resulting book-keeping can be tedious and difficult to get + right. Hence the panels library.</p> + + <p>The <code>panel</code> library first appeared in AT&T + System V. The version documented here is the <code>panel</code> + code distributed with <code>ncurses</code>.</p> + + <h2><a name="pcompile" id="pcompile">Compiling With the Panels + Library</a></h2> + + <p>Your panels-using modules must import the panels library + declarations with</p> + + <pre> + #include <panel.h> +</pre> + + <p>and must be linked explicitly with the panels library using an + <code>-lpanel</code> argument. Note that they must also link the + <code>ncurses</code> library with <code>-lncurses</code>. Many + linkers are two-pass and will accept either order, but it is + still good practice to put <code>-lpanel</code> first and + <code>-lncurses</code> second.</p> + + <h2><a name="poverview" id="poverview">Overview of Panels</a></h2> + + <p>A panel object is a window that is implicitly treated as part + of a <dfn>deck</dfn> including all other panel objects. The deck + has an implicit bottom-to-top visibility order. The panels + library includes an update function (analogous to + <code>refresh()</code>) that displays all panels in the deck in + the proper order to resolve overlaps. The standard window, + <code>stdscr</code>, is considered below all panels.</p> + + <p>Details on the panels functions are available in the man + pages. We will just hit the highlights here.</p> + + <p>You create a panel from a window by calling + <code>new_panel()</code> on a window pointer. It then becomes the + top of the deck. The panel's window is available as the value of + <code>panel_window()</code> called with the panel pointer as + argument.</p> + + <p>You can delete a panel (removing it from the deck) with + <code>del_panel</code>. This will not deallocate the associated + window; you have to do that yourself. You can replace a panel's + window with a different window by calling + <code>replace_window</code>. The new window may be of different + size; the panel code will re-compute all overlaps. This operation + does not change the panel's position in the deck.</p> + + <p>To move a panel's window, use <code>move_panel()</code>. The + <code>mvwin()</code> function on the panel's window is not + sufficient because it does not update the panels library's + representation of where the windows are. This operation leaves + the panel's depth, contents, and size unchanged.</p> + + <p>Two functions (<code>top_panel()</code>, + <code>bottom_panel()</code>) are provided for rearranging the + deck. The first pops its argument window to the top of the deck; + the second sends it to the bottom. Either operation leaves the + panel's screen location, contents, and size unchanged.</p> + + <p>The function <code>update_panels()</code> does all the + <code>wnoutrefresh()</code> calls needed to prepare for + <code>doupdate()</code> (which you must call yourself, + afterwards).</p> + + <p>Typically, you will want to call <code>update_panels()</code> + and <code>doupdate()</code> just before accepting command input, + once in each cycle of interaction with the user. If you call + <code>update_panels()</code> after each and every panel write, + you will generate a lot of unnecessary refresh activity and + screen flicker.</p> + + <h2><a name="pstdscr" id="pstdscr">Panels, Input, and the + Standard Screen</a></h2> + + <p>You should not mix <code>wnoutrefresh()</code> or + <code>wrefresh()</code> operations with panels code; this will + work only if the argument window is either in the top panel or + unobscured by any other panels.</p> + + <p>The <code>stsdcr</code> window is a special case. It is + considered below all panels. Because changes to panels may + obscure parts of <code>stdscr</code>, though, you should call + <code>update_panels()</code> before <code>doupdate()</code> even + when you only change <code>stdscr</code>.</p> + + <p>Note that <code>wgetch</code> automatically calls + <code>wrefresh</code>. Therefore, before requesting input from a + panel window, you need to be sure that the panel is totally + unobscured.</p> + + <p>There is presently no way to display changes to one obscured + panel without repainting all panels.</p> -You can replace a panel's window with a different window by calling -<CODE>replace_window</CODE>. The new window may be of different size; -the panel code will re-compute all overlaps. This operation doesn't -change the panel's position in the deck. <P> + <h2><a name="hiding" id="hiding">Hiding Panels</a></h2> + + <p>It is possible to remove a panel from the deck temporarily; + use <code>hide_panel</code> for this. Use + <code>show_panel()</code> to render it visible again. The + predicate function <code>panel_hidden</code> tests whether or not + a panel is hidden.</p> + + <p>The <code>panel_update</code> code ignores hidden panels. You + cannot do <code>top_panel()</code> or <code>bottom_panel</code> + on a hidden panel(). Other panels operations are applicable.</p> + + <h2><a name="pmisc" id="pmisc">Miscellaneous Other Facilities</a></h2> + + <p>It is possible to navigate the deck using the functions + <code>panel_above()</code> and <code>panel_below</code>. Handed a + panel pointer, they return the panel above or below that panel. + Handed <code>NULL</code>, they return the bottom-most or top-most + panel.</p> + + <p>Every panel has an associated user pointer, not used by the + panel code, to which you can attach application data. See the man + page documentation of <code>set_panel_userptr()</code> and + <code>panel_userptr</code> for details.</p> + + <h1><a name="menu" id="menu">The Menu Library</a></h1> -To move a panel's window, use <CODE>move_panel()</CODE>. The -<CODE>mvwin()</CODE> function on the panel's window isn't sufficient because it -doesn't update the panels library's representation of where the windows are. -This operation leaves the panel's depth, contents, and size unchanged. <P> + <p>A menu is a screen display that assists the user to choose + some subset of a given set of items. The <code>menu</code> + library is a curses extension that supports easy programming of + menu hierarchies with a uniform but flexible interface.</p> -Two functions (<CODE>top_panel()</CODE>, <CODE>bottom_panel()</CODE>) are -provided for rearranging the deck. The first pops its argument window to the -top of the deck; the second sends it to the bottom. Either operation leaves -the panel's screen location, contents, and size unchanged. <P> + <p>The <code>menu</code> library first appeared in AT&T + System V. The version documented here is the <code>menu</code> + code distributed with <code>ncurses</code>.</p> -The function <CODE>update_panels()</CODE> does all the -<CODE>wnoutrefresh()</CODE> calls needed to prepare for -<CODE>doupdate()</CODE> (which you must call yourself, afterwards). <P> - -Typically, you will want to call <CODE>update_panels()</CODE> and -<CODE>doupdate()</CODE> just before accepting command input, once in each cycle -of interaction with the user. If you call <CODE>update_panels()</CODE> after -each and every panel write, you'll generate a lot of unnecessary refresh -activity and screen flicker. - -<H2><A NAME="pstdscr">Panels, Input, and the Standard Screen</A></H2> - -You shouldn't mix <CODE>wnoutrefresh()</CODE> or <CODE>wrefresh()</CODE> -operations with panels code; this will work only if the argument window -is either in the top panel or unobscured by any other panels. <P> - -The <CODE>stsdcr</CODE> window is a special case. It is considered below all -panels. Because changes to panels may obscure parts of <CODE>stdscr</CODE>, -though, you should call <CODE>update_panels()</CODE> before -<CODE>doupdate()</CODE> even when you only change <CODE>stdscr</CODE>. <P> - -Note that <CODE>wgetch</CODE> automatically calls <CODE>wrefresh</CODE>. -Therefore, before requesting input from a panel window, you need to be sure -that the panel is totally unobscured. <P> - -There is presently no way to display changes to one obscured panel without -repainting all panels. - -<H2><A NAME="hiding">Hiding Panels</A></H2> - -It's possible to remove a panel from the deck temporarily; use -<CODE>hide_panel</CODE> for this. Use <CODE>show_panel()</CODE> to render it -visible again. The predicate function <CODE>panel_hidden</CODE> -tests whether or not a panel is hidden. <P> - -The <CODE>panel_update</CODE> code ignores hidden panels. You cannot do -<CODE>top_panel()</CODE> or <CODE>bottom_panel</CODE> on a hidden panel(). -Other panels operations are applicable. - -<H2><A NAME="pmisc">Miscellaneous Other Facilities</A></H2> - -It's possible to navigate the deck using the functions -<CODE>panel_above()</CODE> and <CODE>panel_below</CODE>. Handed a panel -pointer, they return the panel above or below that panel. Handed -<CODE>NULL</CODE>, they return the bottom-most or top-most panel. <P> - -Every panel has an associated user pointer, not used by the panel code, to -which you can attach application data. See the man page documentation -of <CODE>set_panel_userptr()</CODE> and <CODE>panel_userptr</CODE> for -details. - -<H1><A NAME="menu">The Menu Library</A></H1> - -A menu is a screen display that assists the user to choose some subset -of a given set of items. The <CODE>menu</CODE> library is a curses -extension that supports easy programming of menu hierarchies with a -uniform but flexible interface. <P> - -The <CODE>menu</CODE> library first appeared in AT&T System V. The -version documented here is the <CODE>menu</CODE> code distributed -with <CODE>ncurses</CODE>. - -<H2><A NAME="mcompile">Compiling With the menu Library</A></H2> - -Your menu-using modules must import the menu library declarations with - -<PRE> - #include <menu.h> -</PRE> - -and must be linked explicitly with the menus library using an -<CODE>-lmenu</CODE> argument. Note that they must also link the -<CODE>ncurses</CODE> library with <CODE>-lncurses</CODE>. Many linkers -are two-pass and will accept either order, but it is still good practice -to put <CODE>-lmenu</CODE> first and <CODE>-lncurses</CODE> second. - -<H2><A NAME="moverview">Overview of Menus</A></H2> - -The menus created by this library consist of collections of -<DFN>items</DFN> including a name string part and a description string -part. To make menus, you create groups of these items and connect -them with menu frame objects. <P> - -The menu can then by <DFN>posted</DFN>, that is written to an -associated window. Actually, each menu has two associated windows; a -containing window in which the programmer can scribble titles or -borders, and a subwindow in which the menu items proper are displayed. -If this subwindow is too small to display all the items, it will be a -scrollable viewport on the collection of items. <P> - -A menu may also be <DFN>unposted</DFN> (that is, undisplayed), and finally -freed to make the storage associated with it and its items available for -re-use. <P> - -The general flow of control of a menu program looks like this: - -<OL> -<LI>Initialize <CODE>curses</CODE>. -<LI>Create the menu items, using <CODE>new_item()</CODE>. -<LI>Create the menu using <CODE>new_menu()</CODE>. -<LI>Post the menu using <CODE>post_menu()</CODE>. -<LI>Refresh the screen. -<LI>Process user requests via an input loop. -<LI>Unpost the menu using <CODE>unpost_menu()</CODE>. -<LI>Free the menu, using <CODE>free_menu()</CODE>. -<LI>Free the items using <CODE>free_item()</CODE>. -<LI>Terminate <CODE>curses</CODE>. -</OL> - -<H2><A NAME="mselect">Selecting items</A></H2> - -Menus may be multi-valued or (the default) single-valued (see the manual -page <CODE>menu_opts(3x)</CODE> to see how to change the default). -Both types always have a <DFN>current item</DFN>. <P> - -From a single-valued menu you can read the selected value simply by looking -at the current item. From a multi-valued menu, you get the selected set -by looping through the items applying the <CODE>item_value()</CODE> -predicate function. Your menu-processing code can use the function -<CODE>set_item_value()</CODE> to flag the items in the select set. <P> - -Menu items can be made unselectable using <CODE>set_item_opts()</CODE> -or <CODE>item_opts_off()</CODE> with the <CODE>O_SELECTABLE</CODE> -argument. This is the only option so far defined for menus, but it -is good practice to code as though other option bits might be on. - -<H2><A NAME="mdisplay">Menu Display</A></H2> - -The menu library calculates a minimum display size for your window, based -on the following variables: - -<UL> -<LI>The number and maximum length of the menu items -<LI>Whether the O_ROWMAJOR option is enabled -<LI>Whether display of descriptions is enabled -<LI>Whatever menu format may have been set by the programmer -<LI>The length of the menu mark string used for highlighting selected items -</UL> - -The function <CODE>set_menu_format()</CODE> allows you to set the -maximum size of the viewport or <DFN>menu page</DFN> that will be used -to display menu items. You can retrieve any format associated with a -menu with <CODE>menu_format()</CODE>. The default format is rows=16, -columns=1. <P> - -The actual menu page may be smaller than the format size. This depends -on the item number and size and whether O_ROWMAJOR is on. This option -(on by default) causes menu items to be displayed in a `raster-scan' -pattern, so that if more than one item will fit horizontally the first -couple of items are side-by-side in the top row. The alternative is -column-major display, which tries to put the first several items in -the first column. <P> - -As mentioned above, a menu format not large enough to allow all items to fit -on-screen will result in a menu display that is vertically scrollable. <P> -You can scroll it with requests to the menu driver, which will be described -in the section on <A HREF="#minput">menu input handling</A>. <P> - -Each menu has a <DFN>mark string</DFN> used to visually tag selected items; -see the <CODE>menu_mark(3x)</CODE> manual page for details. The mark -string length also influences the menu page size. <P> - -The function <CODE>scale_menu()</CODE> returns the minimum display size -that the menu code computes from all these factors. - -There are other menu display attributes including a select attribute, -an attribute for selectable items, an attribute for unselectable items, -and a pad character used to separate item name text from description -text. These have reasonable defaults which the library allows you to -change (see the <CODE>menu_attribs(3x)</CODE> manual page. - -<H2><A NAME="mwindows">Menu Windows</A></H2> - -Each menu has, as mentioned previously, a pair of associated windows. -Both these windows are painted when the menu is posted and erased when -the menu is unposted. <P> - -The outer or frame window is not otherwise touched by the menu -routines. It exists so the programmer can associate a title, a -border, or perhaps help text with the menu and have it properly -refreshed or erased at post/unpost time. The inner window or -<DFN>subwindow</DFN> is where the current menu page is displayed. <P> - -By default, both windows are <CODE>stdscr</CODE>. You can set them with the -functions in <CODE>menu_win(3x)</CODE>. <P> - -When you call <CODE>post_menu()</CODE>, you write the menu to its -subwindow. When you call <CODE>unpost_menu()</CODE>, you erase the -subwindow, However, neither of these actually modifies the screen. To -do that, call <CODE>wrefresh()</CODE> or some equivalent. - -<H2><A NAME="minput">Processing Menu Input</A></H2> - -The main loop of your menu-processing code should call -<CODE>menu_driver()</CODE> repeatedly. The first argument of this routine -is a menu pointer; the second is a menu command code. You should write an -input-fetching routine that maps input characters to menu command codes, and -pass its output to <CODE>menu_driver()</CODE>. The menu command codes are -fully documented in <CODE>menu_driver(3x)</CODE>. <P> - -The simplest group of command codes is <CODE>REQ_NEXT_ITEM</CODE>, -<CODE>REQ_PREV_ITEM</CODE>, <CODE>REQ_FIRST_ITEM</CODE>, -<CODE>REQ_LAST_ITEM</CODE>, <CODE>REQ_UP_ITEM</CODE>, -<CODE>REQ_DOWN_ITEM</CODE>, <CODE>REQ_LEFT_ITEM</CODE>, -<CODE>REQ_RIGHT_ITEM</CODE>. These change the currently selected -item. These requests may cause scrolling of the menu page if it only -partially displayed. <P> - -There are explicit requests for scrolling which also change the -current item (because the select location does not change, but the -item there does). These are <CODE>REQ_SCR_DLINE</CODE>, -<CODE>REQ_SCR_ULINE</CODE>, <CODE>REQ_SCR_DPAGE</CODE>, and -<CODE>REQ_SCR_UPAGE</CODE>. <P> - -The <CODE>REQ_TOGGLE_ITEM</CODE> selects or deselects the current item. -It is for use in multi-valued menus; if you use it with <CODE>O_ONEVALUE</CODE> -on, you'll get an error return (<CODE>E_REQUEST_DENIED</CODE>). <P> - -Each menu has an associated pattern buffer. The -<CODE>menu_driver()</CODE> logic tries to accumulate printable ASCII -characters passed in in that buffer; when it matches a prefix of an -item name, that item (or the next matching item) is selected. If -appending a character yields no new match, that character is deleted -from the pattern buffer, and <CODE>menu_driver()</CODE> returns -<CODE>E_NO_MATCH</CODE>. <P> - -Some requests change the pattern buffer directly: -<CODE>REQ_CLEAR_PATTERN</CODE>, <CODE>REQ_BACK_PATTERN</CODE>, -<CODE>REQ_NEXT_MATCH</CODE>, <CODE>REQ_PREV_MATCH</CODE>. The latter -two are useful when pattern buffer input matches more than one item -in a multi-valued menu. <P> - -Each successful scroll or item navigation request clears the pattern -buffer. It is also possible to set the pattern buffer explicitly -with <CODE>set_menu_pattern()</CODE>. <P> - -Finally, menu driver requests above the constant <CODE>MAX_COMMAND</CODE> -are considered application-specific commands. The <CODE>menu_driver()</CODE> -code ignores them and returns <CODE>E_UNKNOWN_COMMAND</CODE>. - -<H2><A NAME="mmisc">Miscellaneous Other Features</A></H2> - -Various menu options can affect the processing and visual appearance -and input processing of menus. See <CODE>menu_opts(3x) for -details.</CODE> <P> - -It is possible to change the current item from application code; this -is useful if you want to write your own navigation requests. It is -also possible to explicitly set the top row of the menu display. See -<CODE>mitem_current(3x)</CODE>. - -If your application needs to change the menu subwindow cursor for -any reason, <CODE>pos_menu_cursor()</CODE> will restore it to the -correct location for continuing menu driver processing. <P> - -It is possible to set hooks to be called at menu initialization and -wrapup time, and whenever the selected item changes. See -<CODE>menu_hook(3x)</CODE>. <P> - -Each item, and each menu, has an associated user pointer on which you -can hang application data. See <CODE>mitem_userptr(3x)</CODE> and -<CODE>menu_userptr(3x)</CODE>. - -<H1><A NAME="form">The Forms Library</A></H1> - -The <CODE>form</CODE> library is a curses extension that supports easy -programming of on-screen forms for data entry and program control. <P> - -The <CODE>form</CODE> library first appeared in AT&T System V. The -version documented here is the <CODE>form</CODE> code distributed -with <CODE>ncurses</CODE>. - -<H2><A NAME="fcompile">Compiling With the form Library</A></H2> - -Your form-using modules must import the form library declarations with - -<PRE> - #include <form.h> -</PRE> - -and must be linked explicitly with the forms library using an -<CODE>-lform</CODE> argument. Note that they must also link the -<CODE>ncurses</CODE> library with <CODE>-lncurses</CODE>. Many linkers -are two-pass and will accept either order, but it is still good practice -to put <CODE>-lform</CODE> first and <CODE>-lncurses</CODE> second. - -<H2><A NAME="foverview">Overview of Forms</A></H2> - -A form is a collection of fields; each field may be either a label -(explanatory text) or a data-entry location. Long forms may be -segmented into pages; each entry to a new page clears the screen. <P> -To make forms, you create groups of fields and connect them with form -frame objects; the form library makes this relatively simple. <P> - -Once defined, a form can be <DFN>posted</DFN>, that is written to an -associated window. Actually, each form has two associated windows; a -containing window in which the programmer can scribble titles or -borders, and a subwindow in which the form fields proper are displayed. <P> - -As the form user fills out the posted form, navigation and editing -keys support movement between fields, editing keys support modifying -field, and plain text adds to or changes data in a current field. The -form library allows you (the forms designer) to bind each navigation -and editing key to any keystroke accepted by <CODE>curses</CODE> - -Fields may have validation conditions on them, so that they check input -data for type and value. The form library supplies a rich set of -pre-defined field types, and makes it relatively easy to define new ones. <P> - -Once its transaction is completed (or aborted), a form may be -<DFN>unposted</DFN> (that is, undisplayed), and finally freed to make -the storage associated with it and its items available for re-use. <P> - -The general flow of control of a form program looks like this: - -<OL> -<LI>Initialize <CODE>curses</CODE>. -<LI>Create the form fields, using <CODE>new_field()</CODE>. -<LI>Create the form using <CODE>new_form()</CODE>. -<LI>Post the form using <CODE>post_form()</CODE>. -<LI>Refresh the screen. -<LI>Process user requests via an input loop. -<LI>Unpost the form using <CODE>unpost_form()</CODE>. -<LI>Free the form, using <CODE>free_form()</CODE>. -<LI>Free the fields using <CODE>free_field()</CODE>. -<LI>Terminate <CODE>curses</CODE>. -</OL> + <h2><a name="mcompile" id="mcompile">Compiling With the menu + Library</a></h2> -Note that this looks much like a menu program; the form library handles -tasks which are in many ways similar, and its interface was obviously -designed to resemble that of the <A HREF="#menu">menu library</A> -wherever possible. <P> + <p>Your menu-using modules must import the menu library + declarations with</p> -In forms programs, however, the `process user requests' is somewhat more -complicated than for menus. Besides menu-like navigation operations, -the menu driver loop has to support field editing and data validation. + <pre> + #include <menu.h> +</pre> -<H2><A NAME="fcreate">Creating and Freeing Fields and Forms</A></H2> + <p>and must be linked explicitly with the menus library using an + <code>-lmenu</code> argument. Note that they must also link the + <code>ncurses</code> library with <code>-lncurses</code>. Many + linkers are two-pass and will accept either order, but it is + still good practice to put <code>-lmenu</code> first and + <code>-lncurses</code> second.</p> -The basic function for creating fields is <CODE>new_field()</CODE>: + <h2><a name="moverview" id="moverview">Overview of Menus</a></h2> -<PRE> -FIELD *new_field(int height, int width, /* new field size */ - int top, int left, /* upper left corner */ - int offscreen, /* number of offscreen rows */ - int nbuf); /* number of working buffers */ -</PRE> - -Menu items always occupy a single row, but forms fields may have -multiple rows. So <CODE>new_field()</CODE> requires you to specify a -width and height (the first two arguments, which mist both be greater -than zero). <P> - -You must also specify the location of the field's upper left corner on -the screen (the third and fourth arguments, which must be zero or -greater). Note that these coordinates are relative to the form -subwindow, which will coincide with <CODE>stdscr</CODE> by default but -need not be <CODE>stdscr</CODE> if you've done an explicit -<CODE>set_form_win()</CODE> call. <P> - -The fifth argument allows you to specify a number of off-screen rows. If -this is zero, the entire field will always be displayed. If it is -nonzero, the form will be scrollable, with only one screen-full (initially -the top part) displayed at any given time. If you make a field dynamic -and grow it so it will no longer fit on the screen, the form will become -scrollable even if the <CODE>offscreen</CODE> argument was initially zero. <P> - -The forms library allocates one working buffer per field; the size of -each buffer is <CODE>((height + offscreen)*width + 1</CODE>, one character -for each position in the field plus a NUL terminator. The sixth -argument is the number of additional data buffers to allocate for the -field; your application can use them for its own purposes. - -<PRE> -FIELD *dup_field(FIELD *field, /* field to copy */ - int top, int left); /* location of new copy */ -</PRE> + <p>The menus created by this library consist of collections of + <dfn>items</dfn> including a name string part and a description + string part. To make menus, you create groups of these items and + connect them with menu frame objects.</p> -The function <CODE>dup_field()</CODE> duplicates an existing field at a -new location. Size and buffering information are copied; some -attribute flags and status bits are not (see the -<CODE>form_field_new(3X)</CODE> for details). + <p>The menu can then by <dfn>posted</dfn>, that is written to an + associated window. Actually, each menu has two associated + windows; a containing window in which the programmer can scribble + titles or borders, and a subwindow in which the menu items proper + are displayed. If this subwindow is too small to display all the + items, it will be a scrollable viewport on the collection of + items.</p> -<PRE> -FIELD *link_field(FIELD *field, /* field to copy */ - int top, int left); /* location of new copy */ -</PRE> + <p>A menu may also be <dfn>unposted</dfn> (that is, undisplayed), + and finally freed to make the storage associated with it and its + items available for re-use.</p> -The function <CODE>link_field()</CODE> also duplicates an existing field -at a new location. The difference from <CODE>dup_field()</CODE> is that -it arranges for the new field's buffer to be shared with the old one. <P> + <p>The general flow of control of a menu program looks like + this:</p> -Besides the obvious use in making a field editable from two different -form pages, linked fields give you a way to hack in dynamic labels. If -you declare several fields linked to an original, and then make them -inactive, changes from the original will still be propagated to the -linked fields. <P> + <ol> + <li>Initialize <code>curses</code>.</li> -As with duplicated fields, linked fields have attribute bits separate -from the original. <P> + <li>Create the menu items, using <code>new_item()</code>.</li> -As you might guess, all these field-allocations return <CODE>NULL</CODE> if -the field allocation is not possible due to an out-of-memory error or -out-of-bounds arguments. <P> + <li>Create the menu using <code>new_menu()</code>.</li> -To connect fields to a form, use + <li>Post the menu using <code>post_menu()</code>.</li> -<PRE> -FORM *new_form(FIELD **fields); -</PRE> + <li>Refresh the screen.</li> + + <li>Process user requests via an input loop.</li> + + <li>Unpost the menu using <code>unpost_menu()</code>.</li> + + <li>Free the menu, using <code>free_menu()</code>.</li> + + <li>Free the items using <code>free_item()</code>.</li> + + <li>Terminate <code>curses</code>.</li> + </ol> + + <h2><a name="mselect" id="mselect">Selecting items</a></h2> + + <p>Menus may be multi-valued or (the default) single-valued (see + the manual page <code>menu_opts(3x)</code> to see how to change + the default). Both types always have a <dfn>current + item</dfn>.</p> + + <p>From a single-valued menu you can read the selected value + simply by looking at the current item. From a multi-valued menu, + you get the selected set by looping through the items applying + the <code>item_value()</code> predicate function. Your + menu-processing code can use the function + <code>set_item_value()</code> to flag the items in the select + set.</p> + + <p>Menu items can be made unselectable using + <code>set_item_opts()</code> or <code>item_opts_off()</code> with + the <code>O_SELECTABLE</code> argument. This is the only option + so far defined for menus, but it is good practice to code as + though other option bits might be on.</p> + + <h2><a name="mdisplay" id="mdisplay">Menu Display</a></h2> + + <p>The menu library calculates a minimum display size for your + window, based on the following variables:</p> + + <ul> + <li>The number and maximum length of the menu items</li> + + <li>Whether the O_ROWMAJOR option is enabled</li> + + <li>Whether display of descriptions is enabled</li> + + <li>Whatever menu format may have been set by the + programmer</li> + + <li>The length of the menu mark string used for highlighting + selected items</li> + </ul> + + <p>The function <code>set_menu_format()</code> allows you to set + the maximum size of the viewport or <dfn>menu page</dfn> that + will be used to display menu items. You can retrieve any format + associated with a menu with <code>menu_format()</code>. The + default format is rows=16, columns=1.</p> + + <p>The actual menu page may be smaller than the format size. This + depends on the item number and size and whether O_ROWMAJOR is on. + This option (on by default) causes menu items to be displayed in + a “raster-scan” pattern, so that if more than one + item will fit horizontally the first couple of items are + side-by-side in the top row. The alternative is column-major + display, which tries to put the first several items in the first + column.</p> + + <p>As mentioned above, a menu format not large enough to allow + all items to fit on-screen will result in a menu display that is + vertically scrollable.</p> + + <p>You can scroll it with requests to the menu driver, which will + be described in the section on <a href="#minput">menu input + handling</a>.</p> + + <p>Each menu has a <dfn>mark string</dfn> used to visually tag + selected items; see the <code>menu_mark(3x)</code> manual page + for details. The mark string length also influences the menu page + size.</p> + + <p>The function <code>scale_menu()</code> returns the minimum + display size that the menu code computes from all these factors. + There are other menu display attributes including a select + attribute, an attribute for selectable items, an attribute for + unselectable items, and a pad character used to separate item + name text from description text. These have reasonable defaults + which the library allows you to change (see the + <code>menu_attribs(3x)</code> manual page.</p> + + <h2><a name="mwindows" id="mwindows">Menu Windows</a></h2> + + <p>Each menu has, as mentioned previously, a pair of associated + windows. Both these windows are painted when the menu is posted + and erased when the menu is unposted.</p> + + <p>The outer or frame window is not otherwise touched by the menu + routines. It exists so the programmer can associate a title, a + border, or perhaps help text with the menu and have it properly + refreshed or erased at post/unpost time. The inner window or + <dfn>subwindow</dfn> is where the current menu page is + displayed.</p> + + <p>By default, both windows are <code>stdscr</code>. You can set + them with the functions in <code>menu_win(3x)</code>.</p> + + <p>When you call <code>post_menu()</code>, you write the menu to + its subwindow. When you call <code>unpost_menu()</code>, you + erase the subwindow, However, neither of these actually modifies + the screen. To do that, call <code>wrefresh()</code> or some + equivalent.</p> + + <h2><a name="minput" id="minput">Processing Menu Input</a></h2> + + <p>The main loop of your menu-processing code should call + <code>menu_driver()</code> repeatedly. The first argument of this + routine is a menu pointer; the second is a menu command code. You + should write an input-fetching routine that maps input characters + to menu command codes, and pass its output to + <code>menu_driver()</code>. The menu command codes are fully + documented in <code>menu_driver(3x)</code>.</p> + + <p>The simplest group of command codes is + <code>REQ_NEXT_ITEM</code>, <code>REQ_PREV_ITEM</code>, + <code>REQ_FIRST_ITEM</code>, <code>REQ_LAST_ITEM</code>, + <code>REQ_UP_ITEM</code>, <code>REQ_DOWN_ITEM</code>, + <code>REQ_LEFT_ITEM</code>, <code>REQ_RIGHT_ITEM</code>. These + change the currently selected item. These requests may cause + scrolling of the menu page if it only partially displayed.</p> + + <p>There are explicit requests for scrolling which also change + the current item (because the select location does not change, + but the item there does). These are <code>REQ_SCR_DLINE</code>, + <code>REQ_SCR_ULINE</code>, <code>REQ_SCR_DPAGE</code>, and + <code>REQ_SCR_UPAGE</code>.</p> + + <p>The <code>REQ_TOGGLE_ITEM</code> selects or deselects the + current item. It is for use in multi-valued menus; if you use it + with <code>O_ONEVALUE</code> on, you will get an error return + (<code>E_REQUEST_DENIED</code>).</p> + + <p>Each menu has an associated pattern buffer. The + <code>menu_driver()</code> logic tries to accumulate printable + ASCII characters passed in in that buffer; when it matches a + prefix of an item name, that item (or the next matching item) is + selected. If appending a character yields no new match, that + character is deleted from the pattern buffer, and + <code>menu_driver()</code> returns <code>E_NO_MATCH</code>.</p> + + <p>Some requests change the pattern buffer directly: + <code>REQ_CLEAR_PATTERN</code>, <code>REQ_BACK_PATTERN</code>, + <code>REQ_NEXT_MATCH</code>, <code>REQ_PREV_MATCH</code>. The + latter two are useful when pattern buffer input matches more than + one item in a multi-valued menu.</p> + + <p>Each successful scroll or item navigation request clears the + pattern buffer. It is also possible to set the pattern buffer + explicitly with <code>set_menu_pattern()</code>.</p> + + <p>Finally, menu driver requests above the constant + <code>MAX_COMMAND</code> are considered application-specific + commands. The <code>menu_driver()</code> code ignores them and + returns <code>E_UNKNOWN_COMMAND</code>.</p> + + <h2><a name="mmisc" id="mmisc">Miscellaneous Other Features</a></h2> + + <p>Various menu options can affect the processing and visual + appearance and input processing of menus. See <code>menu_opts(3x) + for details.</code></p> + + <p>It is possible to change the current item from application + code; this is useful if you want to write your own navigation + requests. It is also possible to explicitly set the top row of + the menu display. See <code>mitem_current(3x)</code>. If your + application needs to change the menu subwindow cursor for any + reason, <code>pos_menu_cursor()</code> will restore it to the + correct location for continuing menu driver processing.</p> + + <p>It is possible to set hooks to be called at menu + initialization and wrapup time, and whenever the selected item + changes. See <code>menu_hook(3x)</code>.</p> + + <p>Each item, and each menu, has an associated user pointer on + which you can hang application data. See + <code>mitem_userptr(3x)</code> and + <code>menu_userptr(3x)</code>.</p> + + <h1><a name="form" id="form">The Forms Library</a></h1> + + <p>The <code>form</code> library is a curses extension that + supports easy programming of on-screen forms for data entry and + program control.</p> + + <p>The <code>form</code> library first appeared in AT&T + System V. The version documented here is the <code>form</code> + code distributed with <code>ncurses</code>.</p> + + <h2><a name="fcompile" id="fcompile">Compiling With the form + Library</a></h2> + + <p>Your form-using modules must import the form library + declarations with</p> + + <pre> + #include <form.h> +</pre> + + <p>and must be linked explicitly with the forms library using an + <code>-lform</code> argument. Note that they must also link the + <code>ncurses</code> library with <code>-lncurses</code>. Many + linkers are two-pass and will accept either order, but it is + still good practice to put <code>-lform</code> first and + <code>-lncurses</code> second.</p> + + <h2><a name="foverview" id="foverview">Overview of Forms</a></h2> + + <p>A form is a collection of fields; each field may be either a + label (explanatory text) or a data-entry location. Long forms may + be segmented into pages; each entry to a new page clears the + screen.</p> + + <p>To make forms, you create groups of fields and connect them + with form frame objects; the form library makes this relatively + simple.</p> + + <p>Once defined, a form can be <dfn>posted</dfn>, that is written + to an associated window. Actually, each form has two associated + windows; a containing window in which the programmer can scribble + titles or borders, and a subwindow in which the form fields + proper are displayed.</p> + + <p>As the form user fills out the posted form, navigation and + editing keys support movement between fields, editing keys + support modifying field, and plain text adds to or changes data + in a current field. The form library allows you (the forms + designer) to bind each navigation and editing key to any + keystroke accepted by <code>curses</code> Fields may have + validation conditions on them, so that they check input data for + type and value. The form library supplies a rich set of + pre-defined field types, and makes it relatively easy to define + new ones.</p> + + <p>Once its transaction is completed (or aborted), a form may be + <dfn>unposted</dfn> (that is, undisplayed), and finally freed to + make the storage associated with it and its items available for + re-use.</p> + + <p>The general flow of control of a form program looks like + this:</p> + + <ol> + <li>Initialize <code>curses</code>.</li> + + <li>Create the form fields, using + <code>new_field()</code>.</li> + + <li>Create the form using <code>new_form()</code>.</li> + + <li>Post the form using <code>post_form()</code>.</li> + + <li>Refresh the screen.</li> + + <li>Process user requests via an input loop.</li> -This function expects to see a NULL-terminated array of field pointers. -Said fields are connected to a newly-allocated form object; its address -is returned (or else NULL if the allocation fails). <P> + <li>Unpost the form using <code>unpost_form()</code>.</li> -Note that <CODE>new_field()</CODE> does <EM>not</EM> copy the pointer array -into private storage; if you modify the contents of the pointer array -during forms processing, all manner of bizarre things might happen. Also -note that any given field may only be connected to one form. <P> + <li>Free the form, using <code>free_form()</code>.</li> -The functions <CODE>free_field()</CODE> and <CODE>free_form</CODE> are available -to free field and form objects. It is an error to attempt to free a field -connected to a form, but not vice-versa; thus, you will generally free -your form objects first. + <li>Free the fields using <code>free_field()</code>.</li> -<H2><A NAME="fattributes">Fetching and Changing Field Attributes</A></H2> + <li>Terminate <code>curses</code>.</li> + </ol> -Each form field has a number of location and size attributes -associated with it. There are other field attributes used to control -display and editing of the field. Some (for example, the <CODE>O_STATIC</CODE> bit) -involve sufficient complications to be covered in sections of their own -later on. We cover the functions used to get and set several basic -attributes here. <P> + <p>Note that this looks much like a menu program; the form + library handles tasks which are in many ways similar, and its + interface was obviously designed to resemble that of the <a href= + "#menu">menu library</a> wherever possible.</p> -When a field is created, the attributes not specified by the -<CODE>new_field</CODE> function are copied from an invisible system -default field. In attribute-setting and -fetching functions, the -argument NULL is taken to mean this field. Changes to it persist -as defaults until your forms application terminates. + <p>In forms programs, however, the “process user + requests” is somewhat more complicated than for menus. + Besides menu-like navigation operations, the menu driver loop has + to support field editing and data validation.</p> -<H3><A NAME="fsizes">Fetching Size and Location Data</A></H3> + <h2><a name="fcreate" id="fcreate">Creating and Freeing Fields + and Forms</a></h2> -You can retrieve field sizes and locations through: + <p>The basic function for creating fields is + <code>new_field()</code>:</p> -<PRE> + <pre> +FIELD *new_field(int height, int width, /* new field size */ + int top, int left, /* upper left corner */ + int offscreen, /* number of offscreen rows */ + int nbuf); /* number of working buffers */ +</pre> + + <p>Menu items always occupy a single row, but forms fields may + have multiple rows. So <code>new_field()</code> requires you to + specify a width and height (the first two arguments, which mist + both be greater than zero).</p> + + <p>You must also specify the location of the field's upper left + corner on the screen (the third and fourth arguments, which must + be zero or greater). Note that these coordinates are relative to + the form subwindow, which will coincide with <code>stdscr</code> + by default but need not be <code>stdscr</code> if you have done + an explicit <code>set_form_win()</code> call.</p> + + <p>The fifth argument allows you to specify a number of + off-screen rows. If this is zero, the entire field will always be + displayed. If it is nonzero, the form will be scrollable, with + only one screen-full (initially the top part) displayed at any + given time. If you make a field dynamic and grow it so it will no + longer fit on the screen, the form will become scrollable even if + the <code>offscreen</code> argument was initially zero.</p> + + <p>The forms library allocates one working buffer per field; the + size of each buffer is <code>((height + offscreen)*width + + 1</code>, one character for each position in the field plus a NUL + terminator. The sixth argument is the number of additional data + buffers to allocate for the field; your application can use them + for its own purposes.</p> + + <pre> +FIELD *dup_field(FIELD *field, /* field to copy */ + int top, int left); /* location of new copy */ +</pre> + + <p>The function <code>dup_field()</code> duplicates an existing + field at a new location. Size and buffering information are + copied; some attribute flags and status bits are not (see the + <code>form_field_new(3X)</code> for details).</p> + + <pre> +FIELD *link_field(FIELD *field, /* field to copy */ + int top, int left); /* location of new copy */ +</pre> + + <p>The function <code>link_field()</code> also duplicates an + existing field at a new location. The difference from + <code>dup_field()</code> is that it arranges for the new field's + buffer to be shared with the old one.</p> + + <p>Besides the obvious use in making a field editable from two + different form pages, linked fields give you a way to hack in + dynamic labels. If you declare several fields linked to an + original, and then make them inactive, changes from the original + will still be propagated to the linked fields.</p> + + <p>As with duplicated fields, linked fields have attribute bits + separate from the original.</p> + + <p>As you might guess, all these field-allocations return + <code>NULL</code> if the field allocation is not possible due to + an out-of-memory error or out-of-bounds arguments.</p> + + <p>To connect fields to a form, use</p> + + <pre> +FORM *new_form(FIELD **fields); +</pre> + + <p>This function expects to see a NULL-terminated array of field + pointers. Said fields are connected to a newly-allocated form + object; its address is returned (or else NULL if the allocation + fails).</p> + + <p>Note that <code>new_field()</code> does <em>not</em> copy the + pointer array into private storage; if you modify the contents of + the pointer array during forms processing, all manner of bizarre + things might happen. Also note that any given field may only be + connected to one form.</p> + + <p>The functions <code>free_field()</code> and + <code>free_form</code> are available to free field and form + objects. It is an error to attempt to free a field connected to a + form, but not vice-versa; thus, you will generally free your form + objects first.</p> + + <h2><a name="fattributes" id="fattributes">Fetching and Changing + Field Attributes</a></h2> + + <p>Each form field has a number of location and size attributes + associated with it. There are other field attributes used to + control display and editing of the field. Some (for example, the + <code>O_STATIC</code> bit) involve sufficient complications to be + covered in sections of their own later on. We cover the functions + used to get and set several basic attributes here.</p> + + <p>When a field is created, the attributes not specified by the + <code>new_field</code> function are copied from an invisible + system default field. In attribute-setting and -fetching + functions, the argument NULL is taken to mean this field. Changes + to it persist as defaults until your forms application + terminates.</p> + + <h3><a name="fsizes" id="fsizes">Fetching Size and Location + Data</a></h3> + + <p>You can retrieve field sizes and locations through:</p> + + <pre> int field_info(FIELD *field, /* field from which to fetch */ int *height, *int width, /* field size */ int *top, int *left, /* upper left corner */ int *offscreen, /* number of offscreen rows */ int *nbuf); /* number of working buffers */ -</PRE> +</pre> -This function is a sort of inverse of <CODE>new_field()</CODE>; instead of -setting size and location attributes of a new field, it fetches them -from an existing one. + <p>This function is a sort of inverse of + <code>new_field()</code>; instead of setting size and location + attributes of a new field, it fetches them from an existing + one.</p> -<H3><A NAME="flocation">Changing the Field Location</A></H3> + <h3><a name="flocation" id="flocation">Changing the Field + Location</a></h3> -It is possible to move a field's location on the screen: + <p>It is possible to move a field's location on the screen:</p> -<PRE> + <pre> int move_field(FIELD *field, /* field to alter */ int top, int left); /* new upper-left corner */ -</PRE> +</pre> -You can, of course. query the current location through <CODE>field_info()</CODE>. + <p>You can, of course. query the current location through + <code>field_info()</code>.</p> -<H3><A NAME="fjust">The Justification Attribute</A></H3> + <h3><a name="fjust" id="fjust">The Justification Attribute</a></h3> -One-line fields may be unjustified, justified right, justified left, -or centered. Here is how you manipulate this attribute: + <p>One-line fields may be unjustified, justified right, justified + left, or centered. Here is how you manipulate this attribute:</p> -<PRE> + <pre> int set_field_just(FIELD *field, /* field to alter */ int justmode); /* mode to set */ int field_just(FIELD *field); /* fetch mode of field */ -</PRE> +</pre> -The mode values accepted and returned by this functions are -preprocessor macros <CODE>NO_JUSTIFICATION</CODE>, <CODE>JUSTIFY_RIGHT</CODE>, -<CODE>JUSTIFY_LEFT</CODE>, or <CODE>JUSTIFY_CENTER</CODE>. + <p>The mode values accepted and returned by this functions are + preprocessor macros <code>NO_JUSTIFICATION</code>, + <code>JUSTIFY_RIGHT</code>, <code>JUSTIFY_LEFT</code>, or + <code>JUSTIFY_CENTER</code>.</p> -<H3><A NAME="fdispatts">Field Display Attributes</A></H3> + <h3><a name="fdispatts" id="fdispatts">Field Display + Attributes</a></h3> -For each field, you can set a foreground attribute for entered -characters, a background attribute for the entire field, and a pad -character for the unfilled portion of the field. You can also -control pagination of the form. <P> + <p>For each field, you can set a foreground attribute for entered + characters, a background attribute for the entire field, and a + pad character for the unfilled portion of the field. You can also + control pagination of the form.</p> -This group of four field attributes controls the visual appearance -of the field on the screen, without affecting in any way the data -in the field buffer. + <p>This group of four field attributes controls the visual + appearance of the field on the screen, without affecting in any + way the data in the field buffer.</p> -<PRE> + <pre> int set_field_fore(FIELD *field, /* field to alter */ chtype attr); /* attribute to set */ @@ -1669,22 +2095,21 @@ int set_new_page(FIELD *field, /* field to alter */ int flag); /* TRUE to force new page */ chtype new_page(FIELD *field); /* field to query */ -</PRE> - -The attributes set and returned by the first four functions are normal -<CODE>curses(3x)</CODE> display attribute values (<CODE>A_STANDOUT</CODE>, -<CODE>A_BOLD</CODE>, <CODE>A_REVERSE</CODE> etc). +</pre> -The page bit of a field controls whether it is displayed at the start of -a new form screen. + <p>The attributes set and returned by the first four functions + are normal <code>curses(3x)</code> display attribute values + (<code>A_STANDOUT</code>, <code>A_BOLD</code>, + <code>A_REVERSE</code> etc). The page bit of a field controls + whether it is displayed at the start of a new form screen.</p> -<H3><A NAME="foptions">Field Option Bits</A></H3> + <h3><a name="foptions" id="foptions">Field Option Bits</a></h3> -There is also a large collection of field option bits you can set to control -various aspects of forms processing. You can manipulate them with these -functions: + <p>There is also a large collection of field option bits you can + set to control various aspects of forms processing. You can + manipulate them with these functions:</p> -<PRE> + <pre> int set_field_opts(FIELD *field, /* field to alter */ int attr); /* attribute to set */ @@ -1695,423 +2120,485 @@ int field_opts_off(FIELD *field, /* field to alter */ int attr); /* attributes to turn off */ int field_opts(FIELD *field); /* field to query */ -</PRE> - -By default, all options are on. Here are the available option bits: -<DL> -<DT> O_VISIBLE -<DD> Controls whether the field is visible on the screen. Can be used -during form processing to hide or pop up fields depending on the value -of parent fields. -<DT> O_ACTIVE -<DD> Controls whether the field is active during forms processing (i.e. -visited by form navigation keys). Can be used to make labels or derived -fields with buffer values alterable by the forms application, not the user. -<DT> O_PUBLIC -<DD> Controls whether data is displayed during field entry. If this option is -turned off on a field, the library will accept and edit data in that field, -but it will not be displayed and the visible field cursor will not move. -You can turn off the O_PUBLIC bit to define password fields. -<DT> O_EDIT -<DD> Controls whether the field's data can be modified. When this option is -off, all editing requests except <CODE>REQ_PREV_CHOICE</CODE> and -<CODE>REQ_NEXT_CHOICE</CODE> will fail. Such read-only fields may be useful for -help messages. -<DT> O_WRAP -<DD> Controls word-wrapping in multi-line fields. Normally, when any -character of a (blank-separated) word reaches the end of the current line, the -entire word is wrapped to the next line (assuming there is one). When this -option is off, the word will be split across the line break. -<DT> O_BLANK -<DD> Controls field blanking. When this option is on, entering a character at -the first field position erases the entire field (except for the just-entered -character). -<DT> O_AUTOSKIP -<DD> Controls automatic skip to next field when this one fills. Normally, -when the forms user tries to type more data into a field than will fit, -the editing location jumps to next field. When this option is off, the -user's cursor will hang at the end of the field. This option is ignored -in dynamic fields that have not reached their size limit. -<DT> O_NULLOK -<DD> Controls whether <A HREF="#fvalidation">validation</A> is applied to -blank fields. Normally, it is not; the user can leave a field blank -without invoking the usual validation check on exit. If this option is -off on a field, exit from it will invoke a validation check. -<DT> O_PASSOK -<DD> Controls whether validation occurs on every exit, or only after -the field is modified. Normally the latter is true. Setting O_PASSOK -may be useful if your field's validation function may change during -forms processing. -<DT> O_STATIC -<DD> Controls whether the field is fixed to its initial dimensions. If you -turn this off, the field becomes <A HREF="#fdynamic">dynamic</A> and will -stretch to fit entered data. -</DL> - -A field's options cannot be changed while the field is currently selected. -However, options may be changed on posted fields that are not current. <P> - -The option values are bit-masks and can be composed with logical-or in -the obvious way. - -<H2><A NAME="fstatus">Field Status</A></H2> - -Every field has a status flag, which is set to FALSE when the field is -created and TRUE when the value in field buffer 0 changes. This flag can -be queried and set directly: - -<PRE> -int set_field_status(FIELD *field, /* field to alter */ - int status); /* mode to set */ +</pre> -int field_status(FIELD *field); /* fetch mode of field */ -</PRE> + <p>By default, all options are on. Here are the available option + bits:</p> -Setting this flag under program control can be useful if you use the same -form repeatedly, looking for modified fields each time. <P> + <dl> + <dt>O_VISIBLE</dt> -Calling <CODE>field_status()</CODE> on a field not currently selected -for input will return a correct value. Calling <CODE>field_status()</CODE> on a -field that is currently selected for input may not necessarily give a -correct field status value, because entered data isn't necessarily copied to -buffer zero before the exit validation check. + <dd>Controls whether the field is visible on the screen. Can be + used during form processing to hide or pop up fields depending + on the value of parent fields.</dd> -To guarantee that the returned status value reflects reality, call -<CODE>field_status()</CODE> either (1) in the field's exit validation check -routine, (2) from the field's or form's initialization or termination -hooks, or (3) just after a <CODE>REQ_VALIDATION</CODE> request has been -processed by the forms driver. + <dt>O_ACTIVE</dt> -<H2><A NAME="fuser">Field User Pointer</A></H2> + <dd>Controls whether the field is active during forms + processing (i.e. visited by form navigation keys). Can be used + to make labels or derived fields with buffer values alterable + by the forms application, not the user.</dd> -Each field structure contains one character pointer slot that is not used -by the forms library. It is intended to be used by applications to store -private per-field data. You can manipulate it with: + <dt>O_PUBLIC</dt> -<PRE> -int set_field_userptr(FIELD *field, /* field to alter */ - char *userptr); /* mode to set */ + <dd>Controls whether data is displayed during field entry. If + this option is turned off on a field, the library will accept + and edit data in that field, but it will not be displayed and + the visible field cursor will not move. You can turn off the + O_PUBLIC bit to define password fields.</dd> -char *field_userptr(FIELD *field); /* fetch mode of field */ -</PRE> + <dt>O_EDIT</dt> -(Properly, this user pointer field ought to have <CODE>(void *)</CODE> type. -The <CODE>(char *)</CODE> type is retained for System V compatibility.) <P> + <dd>Controls whether the field's data can be modified. When + this option is off, all editing requests except + <code>REQ_PREV_CHOICE</code> and <code>REQ_NEXT_CHOICE</code> + will fail. Such read-only fields may be useful for help + messages.</dd> -It is valid to set the user pointer of the default field (with a -<CODE>set_field_userptr()</CODE> call passed a NULL field pointer.) -When a new field is created, the default-field user pointer is copied -to initialize the new field's user pointer. + <dt>O_WRAP</dt> -<H2><A NAME="fdynamic">Variable-Sized Fields</A></H2> + <dd>Controls word-wrapping in multi-line fields. Normally, when + any character of a (blank-separated) word reaches the end of + the current line, the entire word is wrapped to the next line + (assuming there is one). When this option is off, the word will + be split across the line break.</dd> -Normally, a field is fixed at the size specified for it at creation -time. If, however, you turn off its O_STATIC bit, it becomes -<DFN>dynamic</DFN> and will automatically resize itself to accommodate -data as it is entered. If the field has extra buffers associated with it, -they will grow right along with the main input buffer. <P> + <dt>O_BLANK</dt> -A one-line dynamic field will have a fixed height (1) but variable -width, scrolling horizontally to display data within the field area as -originally dimensioned and located. A multi-line dynamic field will -have a fixed width, but variable height (number of rows), scrolling -vertically to display data within the field area as originally -dimensioned and located. <P> + <dd>Controls field blanking. When this option is on, entering a + character at the first field position erases the entire field + (except for the just-entered character).</dd> -Normally, a dynamic field is allowed to grow without limit. But it is -possible to set an upper limit on the size of a dynamic field. You do -it with this function: + <dt>O_AUTOSKIP</dt> -<PRE> + <dd>Controls automatic skip to next field when this one fills. + Normally, when the forms user tries to type more data into a + field than will fit, the editing location jumps to next field. + When this option is off, the user's cursor will hang at the end + of the field. This option is ignored in dynamic fields that + have not reached their size limit.</dd> + + <dt>O_NULLOK</dt> + + <dd>Controls whether <a href="#fvalidation">validation</a> is + applied to blank fields. Normally, it is not; the user can + leave a field blank without invoking the usual validation check + on exit. If this option is off on a field, exit from it will + invoke a validation check.</dd> + + <dt>O_PASSOK</dt> + + <dd>Controls whether validation occurs on every exit, or only + after the field is modified. Normally the latter is true. + Setting O_PASSOK may be useful if your field's validation + function may change during forms processing.</dd> + + <dt>O_STATIC</dt> + + <dd>Controls whether the field is fixed to its initial + dimensions. If you turn this off, the field becomes <a href= + "#fdynamic">dynamic</a> and will stretch to fit entered + data.</dd> + </dl> + + <p>A field's options cannot be changed while the field is + currently selected. However, options may be changed on posted + fields that are not current.</p> + + <p>The option values are bit-masks and can be composed with + logical-or in the obvious way.</p> + + <h2><a name="fstatus" id="fstatus">Field Status</a></h2> + + <p>Every field has a status flag, which is set to FALSE when the + field is created and TRUE when the value in field buffer 0 + changes. This flag can be queried and set directly:</p> + + <pre> +int set_field_status(FIELD *field, /* field to alter */ + int status); /* mode to set */ + +int field_status(FIELD *field); /* fetch mode of field */ +</pre> + + <p>Setting this flag under program control can be useful if you + use the same form repeatedly, looking for modified fields each + time.</p> + + <p>Calling <code>field_status()</code> on a field not currently + selected for input will return a correct value. Calling + <code>field_status()</code> on a field that is currently selected + for input may not necessarily give a correct field status value, + because entered data is not necessarily copied to buffer zero + before the exit validation check. To guarantee that the returned + status value reflects reality, call <code>field_status()</code> + either (1) in the field's exit validation check routine, (2) from + the field's or form's initialization or termination hooks, or (3) + just after a <code>REQ_VALIDATION</code> request has been + processed by the forms driver.</p> + + <h2><a name="fuser" id="fuser">Field User Pointer</a></h2> + + <p>Each field structure contains one character pointer slot that + is not used by the forms library. It is intended to be used by + applications to store private per-field data. You can manipulate + it with:</p> + + <pre> +int set_field_userptr(FIELD *field, /* field to alter */ + char *userptr); /* mode to set */ + +char *field_userptr(FIELD *field); /* fetch mode of field */ +</pre>(Properly, this user pointer field ought to have <code>(void +*)</code> type. The <code>(char *)</code> type is retained for +System V compatibility.) + + <p>It is valid to set the user pointer of the default field (with + a <code>set_field_userptr()</code> call passed a NULL field + pointer.) When a new field is created, the default-field user + pointer is copied to initialize the new field's user pointer.</p> + + <h2><a name="fdynamic" id="fdynamic">Variable-Sized Fields</a></h2> + + <p>Normally, a field is fixed at the size specified for it at + creation time. If, however, you turn off its O_STATIC bit, it + becomes <dfn>dynamic</dfn> and will automatically resize itself + to accommodate data as it is entered. If the field has extra + buffers associated with it, they will grow right along with the + main input buffer.</p> + + <p>A one-line dynamic field will have a fixed height (1) but + variable width, scrolling horizontally to display data within the + field area as originally dimensioned and located. A multi-line + dynamic field will have a fixed width, but variable height + (number of rows), scrolling vertically to display data within the + field area as originally dimensioned and located.</p> + + <p>Normally, a dynamic field is allowed to grow without limit. + But it is possible to set an upper limit on the size of a dynamic + field. You do it with this function:</p> + + <pre> int set_max_field(FIELD *field, /* field to alter (may not be NULL) */ int max_size); /* upper limit on field size */ -</PRE> - -If the field is one-line, <CODE>max_size</CODE> is taken to be a column size -limit; if it is multi-line, it is taken to be a line size limit. To disable -any limit, use an argument of zero. The growth limit can be changed whether -or not the O_STATIC bit is on, but has no effect until it is. <P> - -The following properties of a field change when it becomes dynamic: - -<UL> -<LI>If there is no growth limit, there is no final position of the field; -therefore <CODE>O_AUTOSKIP</CODE> and <CODE>O_NL_OVERLOAD</CODE> are ignored. -<LI>Field justification will be ignored (though whatever justification is -set up will be retained internally and can be queried). -<LI>The <CODE>dup_field()</CODE> and <CODE>link_field()</CODE> calls copy -dynamic-buffer sizes. If the <CODE>O_STATIC</CODE> option is set on one of a -collection of links, buffer resizing will occur only when the field is -edited through that link. -<LI>The call <CODE>field_info()</CODE> will retrieve the original static size of -the field; use <CODE>dynamic_field_info()</CODE> to get the actual dynamic size. -</UL> - -<H2><A NAME="fvalidation">Field Validation</A></H2> - -By default, a field will accept any data that will fit in its input buffer. -However, it is possible to attach a validation type to a field. If you do -this, any attempt to leave the field while it contains data that doesn't -match the validation type will fail. Some validation types also have a -character-validity check for each time a character is entered in the field. <P> - -A field's validation check (if any) is not called when -<CODE>set_field_buffer()</CODE> modifies the input buffer, nor when that buffer -is changed through a linked field. <P> - -The <CODE>form</CODE> library provides a rich set of pre-defined validation -types, and gives you the capability to define custom ones of your own. You -can examine and change field validation attributes with the following -functions: - -<PRE> +</pre> + + <p>If the field is one-line, <code>max_size</code> is taken to be + a column size limit; if it is multi-line, it is taken to be a + line size limit. To disable any limit, use an argument of zero. + The growth limit can be changed whether or not the O_STATIC bit + is on, but has no effect until it is.</p> + + <p>The following properties of a field change when it becomes + dynamic:</p> + + <ul> + <li>If there is no growth limit, there is no final position of + the field; therefore <code>O_AUTOSKIP</code> and + <code>O_NL_OVERLOAD</code> are ignored.</li> + + <li>Field justification will be ignored (though whatever + justification is set up will be retained internally and can be + queried).</li> + + <li>The <code>dup_field()</code> and <code>link_field()</code> + calls copy dynamic-buffer sizes. If the <code>O_STATIC</code> + option is set on one of a collection of links, buffer resizing + will occur only when the field is edited through that + link.</li> + + <li>The call <code>field_info()</code> will retrieve the + original static size of the field; use + <code>dynamic_field_info()</code> to get the actual dynamic + size.</li> + </ul> + + <h2><a name="fvalidation" id="fvalidation">Field Validation</a></h2> + + <p>By default, a field will accept any data that will fit in its + input buffer. However, it is possible to attach a validation type + to a field. If you do this, any attempt to leave the field while + it contains data that does not match the validation type will + fail. Some validation types also have a character-validity check + for each time a character is entered in the field.</p> + + <p>A field's validation check (if any) is not called when + <code>set_field_buffer()</code> modifies the input buffer, nor + when that buffer is changed through a linked field.</p> + + <p>The <code>form</code> library provides a rich set of + pre-defined validation types, and gives you the capability to + define custom ones of your own. You can examine and change field + validation attributes with the following functions:</p> + + <pre> int set_field_type(FIELD *field, /* field to alter */ FIELDTYPE *ftype, /* type to associate */ ...); /* additional arguments*/ FIELDTYPE *field_type(FIELD *field); /* field to query */ -</PRE> +</pre> -The validation type of a field is considered an attribute of the field. As -with other field attributes, Also, doing <CODE>set_field_type()</CODE> with a -<CODE>NULL</CODE> field default will change the system default for validation of -newly-created fields. <P> + <p>The validation type of a field is considered an attribute of + the field. As with other field attributes, Also, doing + <code>set_field_type()</code> with a <code>NULL</code> field + default will change the system default for validation of + newly-created fields.</p> -Here are the pre-defined validation types: + <p>Here are the pre-defined validation types:</p> -<H3><A NAME="ftype_alpha">TYPE_ALPHA</A></H3> + <h3><a name="ftype_alpha" id="ftype_alpha">TYPE_ALPHA</a></h3> -This field type accepts alphabetic data; no blanks, no digits, no special -characters (this is checked at character-entry time). It is set up with: + <p>This field type accepts alphabetic data; no blanks, no digits, + no special characters (this is checked at character-entry time). + It is set up with:</p> -<PRE> + <pre> int set_field_type(FIELD *field, /* field to alter */ TYPE_ALPHA, /* type to associate */ int width); /* maximum width of field */ -</PRE> +</pre> -The <CODE>width</CODE> argument sets a minimum width of data. Typically -you'll want to set this to the field width; if it's greater than the -field width, the validation check will always fail. A minimum width -of zero makes field completion optional. + <p>The <code>width</code> argument sets a minimum width of data. + Typically you will want to set this to the field width; if it is + greater than the field width, the validation check will always + fail. A minimum width of zero makes field completion + optional.</p> -<H3><A NAME="ftype_alnum">TYPE_ALNUM</A></H3> + <h3><a name="ftype_alnum" id="ftype_alnum">TYPE_ALNUM</a></h3> -This field type accepts alphabetic data and digits; no blanks, no special -characters (this is checked at character-entry time). It is set up with: + <p>This field type accepts alphabetic data and digits; no blanks, + no special characters (this is checked at character-entry time). + It is set up with:</p> -<PRE> + <pre> int set_field_type(FIELD *field, /* field to alter */ TYPE_ALNUM, /* type to associate */ int width); /* maximum width of field */ -</PRE> +</pre> -The <CODE>width</CODE> argument sets a minimum width of data. As with -TYPE_ALPHA, typically you'll want to set this to the field width; if it's -greater than the field width, the validation check will always fail. A -minimum width of zero makes field completion optional. + <p>The <code>width</code> argument sets a minimum width of data. + As with TYPE_ALPHA, typically you will want to set this to the + field width; if it is greater than the field width, the + validation check will always fail. A minimum width of zero makes + field completion optional.</p> -<H3><A NAME="ftype_enum">TYPE_ENUM</A></H3> + <h3><a name="ftype_enum" id="ftype_enum">TYPE_ENUM</a></h3> -This type allows you to restrict a field's values to be among a specified -set of string values (for example, the two-letter postal codes for U.S. -states). It is set up with: + <p>This type allows you to restrict a field's values to be among + a specified set of string values (for example, the two-letter + postal codes for U.S. states). It is set up with:</p> -<PRE> + <pre> int set_field_type(FIELD *field, /* field to alter */ TYPE_ENUM, /* type to associate */ char **valuelist; /* list of possible values */ int checkcase; /* case-sensitive? */ int checkunique); /* must specify uniquely? */ -</PRE> +</pre> -The <CODE>valuelist</CODE> parameter must point at a NULL-terminated list of -valid strings. The <CODE>checkcase</CODE> argument, if true, makes comparison -with the string case-sensitive. <P> + <p>The <code>valuelist</code> parameter must point at a + NULL-terminated list of valid strings. The <code>checkcase</code> + argument, if true, makes comparison with the string + case-sensitive.</p> -When the user exits a TYPE_ENUM field, the validation procedure tries to -complete the data in the buffer to a valid entry. If a complete choice string -has been entered, it is of course valid. But it is also possible to enter a -prefix of a valid string and have it completed for you. <P> + <p>When the user exits a TYPE_ENUM field, the validation + procedure tries to complete the data in the buffer to a valid + entry. If a complete choice string has been entered, it is of + course valid. But it is also possible to enter a prefix of a + valid string and have it completed for you.</p> -By default, if you enter such a prefix and it matches more than one value -in the string list, the prefix will be completed to the first matching -value. But the <CODE>checkunique</CODE> argument, if true, requires prefix -matches to be unique in order to be valid. <P> + <p>By default, if you enter such a prefix and it matches more + than one value in the string list, the prefix will be completed + to the first matching value. But the <code>checkunique</code> + argument, if true, requires prefix matches to be unique in order + to be valid.</p> -The <CODE>REQ_NEXT_CHOICE</CODE> and <CODE>REQ_PREV_CHOICE</CODE> input requests -can be particularly useful with these fields. + <p>The <code>REQ_NEXT_CHOICE</code> and + <code>REQ_PREV_CHOICE</code> input requests can be particularly + useful with these fields.</p> -<H3><A NAME="ftype_integer">TYPE_INTEGER</A></H3> + <h3><a name="ftype_integer" id="ftype_integer">TYPE_INTEGER</a></h3> -This field type accepts an integer. It is set up as follows: + <p>This field type accepts an integer. It is set up as + follows:</p> -<PRE> + <pre> int set_field_type(FIELD *field, /* field to alter */ TYPE_INTEGER, /* type to associate */ int padding, /* # places to zero-pad to */ int vmin, int vmax); /* valid range */ -</PRE> +</pre> -Valid characters consist of an optional leading minus and digits. -The range check is performed on exit. If the range maximum is less -than or equal to the minimum, the range is ignored. <P> + <p>Valid characters consist of an optional leading minus and + digits. The range check is performed on exit. If the range + maximum is less than or equal to the minimum, the range is + ignored.</p> -If the value passes its range check, it is padded with as many leading -zero digits as necessary to meet the padding argument. <P> + <p>If the value passes its range check, it is padded with as many + leading zero digits as necessary to meet the padding + argument.</p> -A <CODE>TYPE_INTEGER</CODE> value buffer can conveniently be interpreted -with the C library function <CODE>atoi(3)</CODE>. + <p>A <code>TYPE_INTEGER</code> value buffer can conveniently be + interpreted with the C library function <code>atoi(3)</code>.</p> -<H3><A NAME="ftype_numeric">TYPE_NUMERIC</A></H3> + <h3><a name="ftype_numeric" id="ftype_numeric">TYPE_NUMERIC</a></h3> -This field type accepts a decimal number. It is set up as follows: + <p>This field type accepts a decimal number. It is set up as + follows:</p> -<PRE> + <pre> int set_field_type(FIELD *field, /* field to alter */ TYPE_NUMERIC, /* type to associate */ int padding, /* # places of precision */ double vmin, double vmax); /* valid range */ -</PRE> +</pre> -Valid characters consist of an optional leading minus and digits. possibly -including a decimal point. If your system supports locale's, the decimal point -character used must be the one defined by your locale. The range check is -performed on exit. If the range maximum is less than or equal to the minimum, -the range is ignored. <P> + <p>Valid characters consist of an optional leading minus and + digits. possibly including a decimal point. If your system + supports locale's, the decimal point character used must be the + one defined by your locale. The range check is performed on exit. + If the range maximum is less than or equal to the minimum, the + range is ignored.</p> -If the value passes its range check, it is padded with as many trailing -zero digits as necessary to meet the padding argument. <P> + <p>If the value passes its range check, it is padded with as many + trailing zero digits as necessary to meet the padding + argument.</p> -A <CODE>TYPE_NUMERIC</CODE> value buffer can conveniently be interpreted -with the C library function <CODE>atof(3)</CODE>. + <p>A <code>TYPE_NUMERIC</code> value buffer can conveniently be + interpreted with the C library function <code>atof(3)</code>.</p> -<H3><A NAME="ftype_regexp">TYPE_REGEXP</A></H3> + <h3><a name="ftype_regexp" id="ftype_regexp">TYPE_REGEXP</a></h3> -This field type accepts data matching a regular expression. It is set up -as follows: + <p>This field type accepts data matching a regular expression. It + is set up as follows:</p> -<PRE> + <pre> int set_field_type(FIELD *field, /* field to alter */ TYPE_REGEXP, /* type to associate */ char *regexp); /* expression to match */ -</PRE> +</pre> -The syntax for regular expressions is that of <CODE>regcomp(3)</CODE>. -The check for regular-expression match is performed on exit. + <p>The syntax for regular expressions is that of + <code>regcomp(3)</code>. The check for regular-expression match + is performed on exit.</p> -<H2><A NAME="fbuffer">Direct Field Buffer Manipulation</A></H2> + <h2><a name="fbuffer" id="fbuffer">Direct Field Buffer + Manipulation</a></h2> -The chief attribute of a field is its buffer contents. When a form has -been completed, your application usually needs to know the state of each -field buffer. You can find this out with: + <p>The chief attribute of a field is its buffer contents. When a + form has been completed, your application usually needs to know + the state of each field buffer. You can find this out with:</p> -<PRE> + <pre> char *field_buffer(FIELD *field, /* field to query */ int bufindex); /* number of buffer to query */ -</PRE> +</pre> -Normally, the state of the zero-numbered buffer for each field is set by -the user's editing actions on that field. It's sometimes useful to be able -to set the value of the zero-numbered (or some other) buffer from your -application: + <p>Normally, the state of the zero-numbered buffer for each field + is set by the user's editing actions on that field. It is + sometimes useful to be able to set the value of the zero-numbered + (or some other) buffer from your application:</p> -<PRE> + <pre> int set_field_buffer(FIELD *field, /* field to alter */ int bufindex, /* number of buffer to alter */ char *value); /* string value to set */ -</PRE> - -If the field is not large enough and cannot be resized to a sufficiently -large size to contain the specified value, the value will be truncated -to fit. <P> - -Calling <CODE>field_buffer()</CODE> with a null field pointer will raise an -error. Calling <CODE>field_buffer()</CODE> on a field not currently selected -for input will return a correct value. Calling <CODE>field_buffer()</CODE> on a -field that is currently selected for input may not necessarily give a -correct field buffer value, because entered data isn't necessarily copied to -buffer zero before the exit validation check. - -To guarantee that the returned buffer value reflects on-screen reality, -call <CODE>field_buffer()</CODE> either (1) in the field's exit validation -check routine, (2) from the field's or form's initialization or termination -hooks, or (3) just after a <CODE>REQ_VALIDATION</CODE> request has been processed -by the forms driver. - -<H2><A NAME="formattrs">Attributes of Forms</A></H2> - -As with field attributes, form attributes inherit a default from a -system default form structure. These defaults can be queried or set by -of these functions using a form-pointer argument of <CODE>NULL</CODE>. <P> - -The principal attribute of a form is its field list. You can query -and change this list with: - -<PRE> +</pre> + + <p>If the field is not large enough and cannot be resized to a + sufficiently large size to contain the specified value, the value + will be truncated to fit.</p> + + <p>Calling <code>field_buffer()</code> with a null field pointer + will raise an error. Calling <code>field_buffer()</code> on a + field not currently selected for input will return a correct + value. Calling <code>field_buffer()</code> on a field that is + currently selected for input may not necessarily give a correct + field buffer value, because entered data is not necessarily + copied to buffer zero before the exit validation check. To + guarantee that the returned buffer value reflects on-screen + reality, call <code>field_buffer()</code> either (1) in the + field's exit validation check routine, (2) from the field's or + form's initialization or termination hooks, or (3) just after a + <code>REQ_VALIDATION</code> request has been processed by the + forms driver.</p> + + <h2><a name="formattrs" id="formattrs">Attributes of Forms</a></h2> + + <p>As with field attributes, form attributes inherit a default + from a system default form structure. These defaults can be + queried or set by of these functions using a form-pointer + argument of <code>NULL</code>.</p> + + <p>The principal attribute of a form is its field list. You can + query and change this list with:</p> + + <pre> int set_form_fields(FORM *form, /* form to alter */ FIELD **fields); /* fields to connect */ char *form_fields(FORM *form); /* fetch fields of form */ int field_count(FORM *form); /* count connect fields */ -</PRE> - -The second argument of <CODE>set_form_fields()</CODE> may be a -NULL-terminated field pointer array like the one required by -<CODE>new_form()</CODE>. In that case, the old fields of the form are -disconnected but not freed (and eligible to be connected to other -forms), then the new fields are connected. <P> - -It may also be null, in which case the old fields are disconnected -(and not freed) but no new ones are connected. <P> - -The <CODE>field_count()</CODE> function simply counts the number of fields -connected to a given from. It returns -1 if the form-pointer argument -is NULL. - -<H2><A NAME="fdisplay">Control of Form Display</A></H2> - -In the overview section, you saw that to display a form you normally -start by defining its size (and fields), posting it, and refreshing -the screen. There is an hidden step before posting, which is the -association of the form with a frame window (actually, a pair of -windows) within which it will be displayed. By default, the forms -library associates every form with the full-screen window -<CODE>stdscr</CODE>. <P> - -By making this step explicit, you can associate a form with a declared -frame window on your screen display. This can be useful if you want to -adapt the form display to different screen sizes, dynamically tile -forms on the screen, or use a form as part of an interface layout -managed by <A HREF="#panels">panels</A>. <P> - -The two windows associated with each form have the same functions as -their analogues in the <A HREF="#menu">menu library</A>. Both these -windows are painted when the form is posted and erased when the form -is unposted. <P> - -The outer or frame window is not otherwise touched by the form -routines. It exists so the programmer can associate a title, a -border, or perhaps help text with the form and have it properly -refreshed or erased at post/unpost time. The inner window or subwindow -is where the current form page is actually displayed. <P> - -In order to declare your own frame window for a form, you'll need to -know the size of the form's bounding rectangle. You can get this -information with: - -<PRE> +</pre> + + <p>The second argument of <code>set_form_fields()</code> may be a + NULL-terminated field pointer array like the one required by + <code>new_form()</code>. In that case, the old fields of the form + are disconnected but not freed (and eligible to be connected to + other forms), then the new fields are connected.</p> + + <p>It may also be null, in which case the old fields are + disconnected (and not freed) but no new ones are connected.</p> + + <p>The <code>field_count()</code> function simply counts the + number of fields connected to a given from. It returns -1 if the + form-pointer argument is NULL.</p> + + <h2><a name="fdisplay" id="fdisplay">Control of Form Display</a></h2> + + <p>In the overview section, you saw that to display a form you + normally start by defining its size (and fields), posting it, and + refreshing the screen. There is an hidden step before posting, + which is the association of the form with a frame window + (actually, a pair of windows) within which it will be displayed. + By default, the forms library associates every form with the + full-screen window <code>stdscr</code>.</p> + + <p>By making this step explicit, you can associate a form with a + declared frame window on your screen display. This can be useful + if you want to adapt the form display to different screen sizes, + dynamically tile forms on the screen, or use a form as part of an + interface layout managed by <a href="#panels">panels</a>.</p> + + <p>The two windows associated with each form have the same + functions as their analogues in the <a href="#menu">menu + library</a>. Both these windows are painted when the form is + posted and erased when the form is unposted.</p> + + <p>The outer or frame window is not otherwise touched by the form + routines. It exists so the programmer can associate a title, a + border, or perhaps help text with the form and have it properly + refreshed or erased at post/unpost time. The inner window or + subwindow is where the current form page is actually + displayed.</p> + + <p>In order to declare your own frame window for a form, you will + need to know the size of the form's bounding rectangle. You can + get this information with:</p> + + <pre> int scale_form(FORM *form, /* form to query */ int *rows, /* form rows */ int *cols); /* form cols */ -</PRE> +</pre> -The form dimensions are passed back in the locations pointed to by -the arguments. Once you have this information, you can use it to -declare of windows, then use one of these functions: + <p>The form dimensions are passed back in the locations pointed + to by the arguments. Once you have this information, you can use + it to declare of windows, then use one of these functions:</p> -<PRE> + <pre> int set_form_win(FORM *form, /* form to alter */ WINDOW *win); /* frame window to connect */ @@ -2121,319 +2608,507 @@ int set_form_sub(FORM *form, /* form to alter */ WINDOW *win); /* form subwindow to connect */ WINDOW *form_sub(FORM *form); /* fetch form subwindow of form */ -</PRE> +</pre> -Note that curses operations, including <CODE>refresh()</CODE>, on the form, -should be done on the frame window, not the form subwindow. <P> + <p>Note that curses operations, including <code>refresh()</code>, + on the form, should be done on the frame window, not the form + subwindow.</p> -It is possible to check from your application whether all of a -scrollable field is actually displayed within the menu subwindow. Use -these functions: + <p>It is possible to check from your application whether all of a + scrollable field is actually displayed within the menu subwindow. + Use these functions:</p> -<PRE> + <pre> int data_ahead(FORM *form); /* form to be queried */ int data_behind(FORM *form); /* form to be queried */ -</PRE> +</pre> -The function <CODE>data_ahead()</CODE> returns TRUE if (a) the current -field is one-line and has undisplayed data off to the right, (b) the current -field is multi-line and there is data off-screen below it. <P> + <p>The function <code>data_ahead()</code> returns TRUE if (a) the + current field is one-line and has undisplayed data off to the + right, (b) the current field is multi-line and there is data + off-screen below it.</p> -The function <CODE>data_behind()</CODE> returns TRUE if the first (upper -left hand) character position is off-screen (not being displayed). <P> + <p>The function <code>data_behind()</code> returns TRUE if the + first (upper left hand) character position is off-screen (not + being displayed).</p> -Finally, there is a function to restore the form window's cursor to the -value expected by the forms driver: + <p>Finally, there is a function to restore the form window's + cursor to the value expected by the forms driver:</p> -<PRE> + <pre> int pos_form_cursor(FORM *) /* form to be queried */ -</PRE> +</pre> -If your application changes the form window cursor, call this function before -handing control back to the forms driver in order to re-synchronize it. + <p>If your application changes the form window cursor, call this + function before handing control back to the forms driver in order + to re-synchronize it.</p> -<H2><A NAME="fdriver">Input Processing in the Forms Driver</A></H2> + <h2><a name="fdriver" id="fdriver">Input Processing in the Forms + Driver</a></h2> -The function <CODE>form_driver()</CODE> handles virtualized input requests -for form navigation, editing, and validation requests, just as -<CODE>menu_driver</CODE> does for menus (see the section on <A -HREF="#minput">menu input handling</A>). + <p>The function <code>form_driver()</code> handles virtualized + input requests for form navigation, editing, and validation + requests, just as <code>menu_driver</code> does for menus (see + the section on <a href="#minput">menu input handling</a>).</p> -<PRE> + <pre> int form_driver(FORM *form, /* form to pass input to */ int request); /* form request code */ -</PRE> - -Your input virtualization function needs to take input and then convert it -to either an alphanumeric character (which is treated as data to be -entered in the currently-selected field), or a forms processing request. <P> - -The forms driver provides hooks (through input-validation and -field-termination functions) with which your application code can check -that the input taken by the driver matched what was expected. - -<H3><A NAME="fpage">Page Navigation Requests</A></H3> - -These requests cause page-level moves through the form, -triggering display of a new form screen. - -<DL> -<DT> <CODE>REQ_NEXT_PAGE</CODE> -<DD> Move to the next form page. -<DT> <CODE>REQ_PREV_PAGE</CODE> -<DD> Move to the previous form page. -<DT> <CODE>REQ_FIRST_PAGE</CODE> -<DD> Move to the first form page. -<DT> <CODE>REQ_LAST_PAGE</CODE> -<DD> Move to the last form page. -</DL> - -These requests treat the list as cyclic; that is, <CODE>REQ_NEXT_PAGE</CODE> -from the last page goes to the first, and <CODE>REQ_PREV_PAGE</CODE> from -the first page goes to the last. - -<H3><A NAME="ffield">Inter-Field Navigation Requests</A></H3> - -These requests handle navigation between fields on the same page. - -<DL> -<DT> <CODE>REQ_NEXT_FIELD</CODE> -<DD> Move to next field. -<DT> <CODE>REQ_PREV_FIELD</CODE> -<DD> Move to previous field. -<DT> <CODE>REQ_FIRST_FIELD</CODE> -<DD> Move to the first field. -<DT> <CODE>REQ_LAST_FIELD</CODE> -<DD> Move to the last field. -<DT> <CODE>REQ_SNEXT_FIELD</CODE> -<DD> Move to sorted next field. -<DT> <CODE>REQ_SPREV_FIELD</CODE> -<DD> Move to sorted previous field. -<DT> <CODE>REQ_SFIRST_FIELD</CODE> -<DD> Move to the sorted first field. -<DT> <CODE>REQ_SLAST_FIELD</CODE> -<DD> Move to the sorted last field. -<DT> <CODE>REQ_LEFT_FIELD</CODE> -<DD> Move left to field. -<DT> <CODE>REQ_RIGHT_FIELD</CODE> -<DD> Move right to field. -<DT> <CODE>REQ_UP_FIELD</CODE> -<DD> Move up to field. -<DT> <CODE>REQ_DOWN_FIELD</CODE> -<DD> Move down to field. -</DL> - -These requests treat the list of fields on a page as cyclic; that is, -<CODE>REQ_NEXT_FIELD</CODE> from the last field goes to the first, and -<CODE>REQ_PREV_FIELD</CODE> from the first field goes to the last. The -order of the fields for these (and the <CODE>REQ_FIRST_FIELD</CODE> and -<CODE>REQ_LAST_FIELD</CODE> requests) is simply the order of the field -pointers in the form array (as set up by <CODE>new_form()</CODE> or -<CODE>set_form_fields()</CODE> <P> - -It is also possible to traverse the fields as if they had been sorted in -screen-position order, so the sequence goes left-to-right and top-to-bottom. -To do this, use the second group of four sorted-movement requests. <P> - -Finally, it is possible to move between fields using visual directions up, -down, right, and left. To accomplish this, use the third group of four -requests. Note, however, that the position of a form for purposes of these -requests is its upper-left corner. <P> - -For example, suppose you have a multi-line field B, and two -single-line fields A and C on the same line with B, with A to the left -of B and C to the right of B. A <CODE>REQ_MOVE_RIGHT</CODE> from A will -go to B only if A, B, and C <EM>all</EM> share the same first line; -otherwise it will skip over B to C. - -<H3><A NAME="fifield">Intra-Field Navigation Requests</A></H3> - -These requests drive movement of the edit cursor within the currently -selected field. - -<DL> -<DT> <CODE>REQ_NEXT_CHAR</CODE> -<DD> Move to next character. -<DT> <CODE>REQ_PREV_CHAR</CODE> -<DD> Move to previous character. -<DT> <CODE>REQ_NEXT_LINE</CODE> -<DD> Move to next line. -<DT> <CODE>REQ_PREV_LINE</CODE> -<DD> Move to previous line. -<DT> <CODE>REQ_NEXT_WORD</CODE> -<DD> Move to next word. -<DT> <CODE>REQ_PREV_WORD</CODE> -<DD> Move to previous word. -<DT> <CODE>REQ_BEG_FIELD</CODE> -<DD> Move to beginning of field. -<DT> <CODE>REQ_END_FIELD</CODE> -<DD> Move to end of field. -<DT> <CODE>REQ_BEG_LINE</CODE> -<DD> Move to beginning of line. -<DT> <CODE>REQ_END_LINE</CODE> -<DD> Move to end of line. -<DT> <CODE>REQ_LEFT_CHAR</CODE> -<DD> Move left in field. -<DT> <CODE>REQ_RIGHT_CHAR</CODE> -<DD> Move right in field. -<DT> <CODE>REQ_UP_CHAR</CODE> -<DD> Move up in field. -<DT> <CODE>REQ_DOWN_CHAR</CODE> -<DD> Move down in field. -</DL> - -Each <EM>word</EM> is separated from the previous and next characters -by whitespace. The commands to move to beginning and end of line or field -look for the first or last non-pad character in their ranges. - -<H3><A NAME="fscroll">Scrolling Requests</A></H3> - -Fields that are dynamic and have grown and fields explicitly created -with offscreen rows are scrollable. One-line fields scroll horizontally; -multi-line fields scroll vertically. Most scrolling is triggered by -editing and intra-field movement (the library scrolls the field to keep the -cursor visible). It is possible to explicitly request scrolling with the -following requests: - -<DL> -<DT> <CODE>REQ_SCR_FLINE</CODE> -<DD> Scroll vertically forward a line. -<DT> <CODE>REQ_SCR_BLINE</CODE> -<DD> Scroll vertically backward a line. -<DT> <CODE>REQ_SCR_FPAGE</CODE> -<DD> Scroll vertically forward a page. -<DT> <CODE>REQ_SCR_BPAGE</CODE> -<DD> Scroll vertically backward a page. -<DT> <CODE>REQ_SCR_FHPAGE</CODE> -<DD> Scroll vertically forward half a page. -<DT> <CODE>REQ_SCR_BHPAGE</CODE> -<DD> Scroll vertically backward half a page. -<DT> <CODE>REQ_SCR_FCHAR</CODE> -<DD> Scroll horizontally forward a character. -<DT> <CODE>REQ_SCR_BCHAR</CODE> -<DD> Scroll horizontally backward a character. -<DT> <CODE>REQ_SCR_HFLINE</CODE> -<DD> Scroll horizontally one field width forward. -<DT> <CODE>REQ_SCR_HBLINE</CODE> -<DD> Scroll horizontally one field width backward. -<DT> <CODE>REQ_SCR_HFHALF</CODE> -<DD> Scroll horizontally one half field width forward. -<DT> <CODE>REQ_SCR_HBHALF</CODE> -<DD> Scroll horizontally one half field width backward. -</DL> - -For scrolling purposes, a <EM>page</EM> of a field is the height -of its visible part. - -<H3><A NAME="fedit">Editing Requests</A></H3> - -When you pass the forms driver an ASCII character, it is treated as a -request to add the character to the field's data buffer. Whether this -is an insertion or a replacement depends on the field's edit mode -(insertion is the default. <P> - -The following requests support editing the field and changing the edit -mode: - -<DL> -<DT> <CODE>REQ_INS_MODE</CODE> -<DD> Set insertion mode. -<DT> <CODE>REQ_OVL_MODE</CODE> -<DD> Set overlay mode. -<DT> <CODE>REQ_NEW_LINE</CODE> -<DD> New line request (see below for explanation). -<DT> <CODE>REQ_INS_CHAR</CODE> -<DD> Insert space at character location. -<DT> <CODE>REQ_INS_LINE</CODE> -<DD> Insert blank line at character location. -<DT> <CODE>REQ_DEL_CHAR</CODE> -<DD> Delete character at cursor. -<DT> <CODE>REQ_DEL_PREV</CODE> -<DD> Delete previous word at cursor. -<DT> <CODE>REQ_DEL_LINE</CODE> -<DD> Delete line at cursor. -<DT> <CODE>REQ_DEL_WORD</CODE> -<DD> Delete word at cursor. -<DT> <CODE>REQ_CLR_EOL</CODE> -<DD> Clear to end of line. -<DT> <CODE>REQ_CLR_EOF</CODE> -<DD> Clear to end of field. -<DT> <CODE>REQ_CLEAR_FIELD</CODE> -<DD> Clear entire field. -</DL> - -The behavior of the <CODE>REQ_NEW_LINE</CODE> and <CODE>REQ_DEL_PREV</CODE> requests -is complicated and partly controlled by a pair of forms options. -The special cases are triggered when the cursor is at the beginning of -a field, or on the last line of the field. <P> - -First, we consider <CODE>REQ_NEW_LINE</CODE>: <P> - -The normal behavior of <CODE>REQ_NEW_LINE</CODE> in insert mode is to break the -current line at the position of the edit cursor, inserting the portion of -the current line after the cursor as a new line following the current -and moving the cursor to the beginning of that new line (you may think -of this as inserting a newline in the field buffer). <P> - -The normal behavior of <CODE>REQ_NEW_LINE</CODE> in overlay mode is to clear the -current line from the position of the edit cursor to end of line. -The cursor is then moved to the beginning of the next line. <P> - -However, <CODE>REQ_NEW_LINE</CODE> at the beginning of a field, or on the -last line of a field, instead does a <CODE>REQ_NEXT_FIELD</CODE>. -<CODE>O_NL_OVERLOAD</CODE> option is off, this special action is -disabled. <P> - -Now, let us consider <CODE>REQ_DEL_PREV</CODE>: <P> - -The normal behavior of <CODE>REQ_DEL_PREV</CODE> is to delete the previous -character. If insert mode is on, and the cursor is at the start of a -line, and the text on that line will fit on the previous one, it -instead appends the contents of the current line to the previous one -and deletes the current line (you may think of this as deleting a -newline from the field buffer). <P> - -However, <CODE>REQ_DEL_PREV</CODE> at the beginning of a field is instead -treated as a <CODE>REQ_PREV_FIELD</CODE>. <P> If the -<CODE>O_BS_OVERLOAD</CODE> option is off, this special action is -disabled and the forms driver just returns <CODE>E_REQUEST_DENIED</CODE>. <P> - -See <A HREF="#frmoptions">Form Options</A> for discussion of how to set -and clear the overload options. - -<H3><A NAME="forder">Order Requests</A></H3> - -If the type of your field is ordered, and has associated functions -for getting the next and previous values of the type from a given value, -there are requests that can fetch that value into the field buffer: - -<DL> -<DT> <CODE>REQ_NEXT_CHOICE</CODE> -<DD> Place the successor value of the current value in the buffer. -<DT> <CODE>REQ_PREV_CHOICE</CODE> -<DD> Place the predecessor value of the current value in the buffer. -</DL> - -Of the built-in field types, only <CODE>TYPE_ENUM</CODE> has built-in successor -and predecessor functions. When you define a field type of your own -(see <A HREF="#fcustom">Custom Validation Types</A>), you can associate -our own ordering functions. - -<H3><A NAME="fappcmds">Application Commands</A></H3> - -Form requests are represented as integers above the <CODE>curses</CODE> value -greater than <CODE>KEY_MAX</CODE> and less than or equal to the constant -<CODE>MAX_COMMAND</CODE>. If your input-virtualization routine returns a -value above <CODE>MAX_COMMAND</CODE>, the forms driver will ignore it. - -<H2><A NAME="fhooks">Field Change Hooks</A></H2> - -It is possible to set function hooks to be executed whenever the -current field or form changes. Here are the functions that support this: - -<PRE> -typedef void (*HOOK)(); /* pointer to function returning void */ +</pre> + + <p>Your input virtualization function needs to take input and + then convert it to either an alphanumeric character (which is + treated as data to be entered in the currently-selected field), + or a forms processing request.</p> + + <p>The forms driver provides hooks (through input-validation and + field-termination functions) with which your application code can + check that the input taken by the driver matched what was + expected.</p> + + <h3><a name="fpage" id="fpage">Page Navigation Requests</a></h3> + + <p>These requests cause page-level moves through the form, + triggering display of a new form screen.</p> + + <dl> + <dt><code>REQ_NEXT_PAGE</code> + </dt> + + <dd>Move to the next form page.</dd> + + <dt><code>REQ_PREV_PAGE</code> + </dt> + + <dd>Move to the previous form page.</dd> + + <dt><code>REQ_FIRST_PAGE</code> + </dt> + + <dd>Move to the first form page.</dd> + + <dt><code>REQ_LAST_PAGE</code> + </dt> + + <dd>Move to the last form page.</dd> + </dl> + + <p>These requests treat the list as cyclic; that is, + <code>REQ_NEXT_PAGE</code> from the last page goes to the first, + and <code>REQ_PREV_PAGE</code> from the first page goes to the + last.</p> + + <h3><a name="ffield" id="ffield">Inter-Field Navigation + Requests</a></h3> + + <p>These requests handle navigation between fields on the same + page.</p> + + <dl> + <dt><code>REQ_NEXT_FIELD</code> + </dt> + + <dd>Move to next field.</dd> + + <dt><code>REQ_PREV_FIELD</code> + </dt> + + <dd>Move to previous field.</dd> + + <dt><code>REQ_FIRST_FIELD</code> + </dt> + + <dd>Move to the first field.</dd> + + <dt><code>REQ_LAST_FIELD</code> + </dt> + + <dd>Move to the last field.</dd> + + <dt><code>REQ_SNEXT_FIELD</code> + </dt> + + <dd>Move to sorted next field.</dd> + + <dt><code>REQ_SPREV_FIELD</code> + </dt> + + <dd>Move to sorted previous field.</dd> + + <dt><code>REQ_SFIRST_FIELD</code> + </dt> + + <dd>Move to the sorted first field.</dd> + + <dt><code>REQ_SLAST_FIELD</code> + </dt> + + <dd>Move to the sorted last field.</dd> + + <dt><code>REQ_LEFT_FIELD</code> + </dt> + + <dd>Move left to field.</dd> + + <dt><code>REQ_RIGHT_FIELD</code> + </dt> + + <dd>Move right to field.</dd> + + <dt><code>REQ_UP_FIELD</code> + </dt> + + <dd>Move up to field.</dd> + + <dt><code>REQ_DOWN_FIELD</code> + </dt> + + <dd>Move down to field.</dd> + </dl> + + <p>These requests treat the list of fields on a page as cyclic; + that is, <code>REQ_NEXT_FIELD</code> from the last field goes to + the first, and <code>REQ_PREV_FIELD</code> from the first field + goes to the last. The order of the fields for these (and the + <code>REQ_FIRST_FIELD</code> and <code>REQ_LAST_FIELD</code> + requests) is simply the order of the field pointers in the form + array (as set up by <code>new_form()</code> or + <code>set_form_fields()</code></p> + + <p>It is also possible to traverse the fields as if they had been + sorted in screen-position order, so the sequence goes + left-to-right and top-to-bottom. To do this, use the second group + of four sorted-movement requests.</p> + + <p>Finally, it is possible to move between fields using visual + directions up, down, right, and left. To accomplish this, use the + third group of four requests. Note, however, that the position of + a form for purposes of these requests is its upper-left + corner.</p> + + <p>For example, suppose you have a multi-line field B, and two + single-line fields A and C on the same line with B, with A to the + left of B and C to the right of B. A <code>REQ_MOVE_RIGHT</code> + from A will go to B only if A, B, and C <em>all</em> share the + same first line; otherwise it will skip over B to C.</p> + + <h3><a name="fifield" id="fifield">Intra-Field Navigation + Requests</a></h3> + + <p>These requests drive movement of the edit cursor within the + currently selected field.</p> + + <dl> + <dt><code>REQ_NEXT_CHAR</code> + </dt> + + <dd>Move to next character.</dd> + + <dt><code>REQ_PREV_CHAR</code> + </dt> + + <dd>Move to previous character.</dd> + + <dt><code>REQ_NEXT_LINE</code> + </dt> + + <dd>Move to next line.</dd> + + <dt><code>REQ_PREV_LINE</code> + </dt> + + <dd>Move to previous line.</dd> + + <dt><code>REQ_NEXT_WORD</code> + </dt> + + <dd>Move to next word.</dd> + + <dt><code>REQ_PREV_WORD</code> + </dt> + + <dd>Move to previous word.</dd> + + <dt><code>REQ_BEG_FIELD</code> + </dt> + + <dd>Move to beginning of field.</dd> + + <dt><code>REQ_END_FIELD</code> + </dt> + + <dd>Move to end of field.</dd> + + <dt><code>REQ_BEG_LINE</code> + </dt> + + <dd>Move to beginning of line.</dd> + + <dt><code>REQ_END_LINE</code> + </dt> + + <dd>Move to end of line.</dd> + + <dt><code>REQ_LEFT_CHAR</code> + </dt> + + <dd>Move left in field.</dd> + + <dt><code>REQ_RIGHT_CHAR</code> + </dt> + + <dd>Move right in field.</dd> + + <dt><code>REQ_UP_CHAR</code> + </dt> + + <dd>Move up in field.</dd> + + <dt><code>REQ_DOWN_CHAR</code> + </dt> + + <dd>Move down in field.</dd> + </dl> + + <p>Each <em>word</em> is separated from the previous and next + characters by whitespace. The commands to move to beginning and + end of line or field look for the first or last non-pad character + in their ranges.</p> + + <h3><a name="fscroll" id="fscroll">Scrolling Requests</a></h3> + + <p>Fields that are dynamic and have grown and fields explicitly + created with offscreen rows are scrollable. One-line fields + scroll horizontally; multi-line fields scroll vertically. Most + scrolling is triggered by editing and intra-field movement (the + library scrolls the field to keep the cursor visible). It is + possible to explicitly request scrolling with the following + requests:</p> + + <dl> + <dt><code>REQ_SCR_FLINE</code> + </dt> + + <dd>Scroll vertically forward a line.</dd> + + <dt><code>REQ_SCR_BLINE</code> + </dt> + + <dd>Scroll vertically backward a line.</dd> + + <dt><code>REQ_SCR_FPAGE</code> + </dt> + + <dd>Scroll vertically forward a page.</dd> + + <dt><code>REQ_SCR_BPAGE</code> + </dt> + + <dd>Scroll vertically backward a page.</dd> + + <dt><code>REQ_SCR_FHPAGE</code> + </dt> + + <dd>Scroll vertically forward half a page.</dd> + + <dt><code>REQ_SCR_BHPAGE</code> + </dt> + + <dd>Scroll vertically backward half a page.</dd> + + <dt><code>REQ_SCR_FCHAR</code> + </dt> + + <dd>Scroll horizontally forward a character.</dd> + + <dt><code>REQ_SCR_BCHAR</code> + </dt> + + <dd>Scroll horizontally backward a character.</dd> + + <dt><code>REQ_SCR_HFLINE</code> + </dt> + + <dd>Scroll horizontally one field width forward.</dd> + + <dt><code>REQ_SCR_HBLINE</code> + </dt> + + <dd>Scroll horizontally one field width backward.</dd> + + <dt><code>REQ_SCR_HFHALF</code> + </dt> + + <dd>Scroll horizontally one half field width forward.</dd> + + <dt><code>REQ_SCR_HBHALF</code> + </dt> + + <dd>Scroll horizontally one half field width backward.</dd> + </dl> + + <p>For scrolling purposes, a <em>page</em> of a field is the + height of its visible part.</p> + + <h3><a name="fedit" id="fedit">Editing Requests</a></h3> + + <p>When you pass the forms driver an ASCII character, it is + treated as a request to add the character to the field's data + buffer. Whether this is an insertion or a replacement depends on + the field's edit mode (insertion is the default.</p> + + <p>The following requests support editing the field and changing + the edit mode:</p> + + <dl> + <dt><code>REQ_INS_MODE</code> + </dt> + + <dd>Set insertion mode.</dd> + + <dt><code>REQ_OVL_MODE</code> + </dt> + + <dd>Set overlay mode.</dd> + + <dt><code>REQ_NEW_LINE</code> + </dt> + + <dd>New line request (see below for explanation).</dd> + + <dt><code>REQ_INS_CHAR</code> + </dt> + + <dd>Insert space at character location.</dd> + + <dt><code>REQ_INS_LINE</code> + </dt> + + <dd>Insert blank line at character location.</dd> + + <dt><code>REQ_DEL_CHAR</code> + </dt> + + <dd>Delete character at cursor.</dd> + + <dt><code>REQ_DEL_PREV</code> + </dt> + + <dd>Delete previous word at cursor.</dd> + + <dt><code>REQ_DEL_LINE</code> + </dt> + + <dd>Delete line at cursor.</dd> + + <dt><code>REQ_DEL_WORD</code> + </dt> + + <dd>Delete word at cursor.</dd> + + <dt><code>REQ_CLR_EOL</code> + </dt> + + <dd>Clear to end of line.</dd> + + <dt><code>REQ_CLR_EOF</code> + </dt> + + <dd>Clear to end of field.</dd> + + <dt><code>REQ_CLEAR_FIELD</code> + </dt> + + <dd>Clear entire field.</dd> + </dl> + + <p>The behavior of the <code>REQ_NEW_LINE</code> and + <code>REQ_DEL_PREV</code> requests is complicated and partly + controlled by a pair of forms options. The special cases are + triggered when the cursor is at the beginning of a field, or on + the last line of the field.</p> + + <p>First, we consider <code>REQ_NEW_LINE</code>:</p> + + <p>The normal behavior of <code>REQ_NEW_LINE</code> in insert + mode is to break the current line at the position of the edit + cursor, inserting the portion of the current line after the + cursor as a new line following the current and moving the cursor + to the beginning of that new line (you may think of this as + inserting a newline in the field buffer).</p> + + <p>The normal behavior of <code>REQ_NEW_LINE</code> in overlay + mode is to clear the current line from the position of the edit + cursor to end of line. The cursor is then moved to the beginning + of the next line.</p> + + <p>However, <code>REQ_NEW_LINE</code> at the beginning of a + field, or on the last line of a field, instead does a + <code>REQ_NEXT_FIELD</code>. <code>O_NL_OVERLOAD</code> option is + off, this special action is disabled.</p> + + <p>Now, let us consider <code>REQ_DEL_PREV</code>:</p> + + <p>The normal behavior of <code>REQ_DEL_PREV</code> is to delete + the previous character. If insert mode is on, and the cursor is + at the start of a line, and the text on that line will fit on the + previous one, it instead appends the contents of the current line + to the previous one and deletes the current line (you may think + of this as deleting a newline from the field buffer).</p> + + <p>However, <code>REQ_DEL_PREV</code> at the beginning of a field + is instead treated as a <code>REQ_PREV_FIELD</code>.</p> + + <p>If the <code>O_BS_OVERLOAD</code> option is off, this special + action is disabled and the forms driver just returns + <code>E_REQUEST_DENIED</code>.</p> + + <p>See <a href="#frmoptions">Form Options</a> for discussion of + how to set and clear the overload options.</p> + + <h3><a name="forder" id="forder">Order Requests</a></h3> + + <p>If the type of your field is ordered, and has associated + functions for getting the next and previous values of the type + from a given value, there are requests that can fetch that value + into the field buffer:</p> + + <dl> + <dt><code>REQ_NEXT_CHOICE</code> + </dt> + + <dd>Place the successor value of the current value in the + buffer.</dd> + + <dt><code>REQ_PREV_CHOICE</code> + </dt> + + <dd>Place the predecessor value of the current value in the + buffer.</dd> + </dl> + + <p>Of the built-in field types, only <code>TYPE_ENUM</code> has + built-in successor and predecessor functions. When you define a + field type of your own (see <a href="#fcustom">Custom Validation + Types</a>), you can associate our own ordering functions.</p> + + <h3><a name="fappcmds" id="fappcmds">Application Commands</a></h3> + + <p>Form requests are represented as integers above the + <code>curses</code> value greater than <code>KEY_MAX</code> and + less than or equal to the constant <code>MAX_COMMAND</code>. If + your input-virtualization routine returns a value above + <code>MAX_COMMAND</code>, the forms driver will ignore it.</p> + + <h2><a name="fhooks" id="fhooks">Field Change Hooks</a></h2> + + <p>It is possible to set function hooks to be executed whenever + the current field or form changes. Here are the functions that + support this:</p> + + <pre> +typedef void (*HOOK)(); /* pointer to function returning void */ int set_form_init(FORM *form, /* form to alter */ HOOK hook); /* initialization hook */ @@ -2454,53 +3129,67 @@ int set_field_term(FORM *form, /* form to alter */ HOOK hook); /* termination hook */ HOOK field_term(FORM *form); /* form to query */ -</PRE> - -These functions allow you to either set or query four different hooks. -In each of the set functions, the second argument should be the -address of a hook function. These functions differ only in the timing -of the hook call. - -<DL> -<DT> form_init -<DD> This hook is called when the form is posted; also, just after -each page change operation. -<DT> field_init -<DD> This hook is called when the form is posted; also, just after -each field change -<DT> field_term -<DD> This hook is called just after field validation; that is, just before -the field is altered. It is also called when the form is unposted. -<DT> form_term -<DD> This hook is called when the form is unposted; also, just before -each page change operation. -</DL> - -Calls to these hooks may be triggered -<OL> -<LI>When user editing requests are processed by the forms driver -<LI>When the current page is changed by <CODE>set_current_field()</CODE> call -<LI>When the current field is changed by a <CODE>set_form_page()</CODE> call -</OL> - -See <A NAME="ffocus">Field Change Commands</A> for discussion of the latter -two cases. <P> - -You can set a default hook for all fields by passing one of the set functions -a NULL first argument. <P> - -You can disable any of these hooks by (re)setting them to NULL, the default -value. - -<H2><A HREF="#ffocus">Field Change Commands</A></H2> - -Normally, navigation through the form will be driven by the user's -input requests. But sometimes it is useful to be able to move the -focus for editing and viewing under control of your application, or -ask which field it currently is in. The following functions help you -accomplish this: - -<PRE> +</pre> + + <p>These functions allow you to either set or query four + different hooks. In each of the set functions, the second + argument should be the address of a hook function. These + functions differ only in the timing of the hook call.</p> + + <dl> + <dt>form_init</dt> + + <dd>This hook is called when the form is posted; also, just + after each page change operation.</dd> + + <dt>field_init</dt> + + <dd>This hook is called when the form is posted; also, just + after each field change</dd> + + <dt>field_term</dt> + + <dd>This hook is called just after field validation; that is, + just before the field is altered. It is also called when the + form is unposted.</dd> + + <dt>form_term</dt> + + <dd>This hook is called when the form is unposted; also, just + before each page change operation.</dd> + </dl> + + <p>Calls to these hooks may be triggered</p> + + <ol> + <li>When user editing requests are processed by the forms + driver</li> + + <li>When the current page is changed by + <code>set_current_field()</code> call</li> + + <li>When the current field is changed by a + <code>set_form_page()</code> call</li> + </ol> + + <p>See <a name="ffocus" id="ffocus">Field Change Commands</a> for + discussion of the latter two cases.</p> + + <p>You can set a default hook for all fields by passing one of + the set functions a NULL first argument.</p> + + <p>You can disable any of these hooks by (re)setting them to + NULL, the default value.</p> + + <h2><a href="#ffocus">Field Change Commands</a></h2> + + <p>Normally, navigation through the form will be driven by the + user's input requests. But sometimes it is useful to be able to + move the focus for editing and viewing under control of your + application, or ask which field it currently is in. The following + functions help you accomplish this:</p> + + <pre> int set_current_field(FORM *form, /* form to alter */ FIELD *field); /* field to shift to */ @@ -2508,33 +3197,35 @@ FIELD *current_field(FORM *form); /* form to query */ int field_index(FORM *form, /* form to query */ FIELD *field); /* field to get index of */ -</PRE> +</pre> -The function <CODE>field_index()</CODE> returns the index of the given field -in the given form's field array (the array passed to <CODE>new_form()</CODE> or -<CODE>set_form_fields()</CODE>). <P> + <p>The function <code>field_index()</code> returns the index of + the given field in the given form's field array (the array passed + to <code>new_form()</code> or + <code>set_form_fields()</code>).</p> -The initial current field of a form is the first active field on the -first page. The function <CODE>set_form_fields()</CODE> resets this.<P> + <p>The initial current field of a form is the first active field + on the first page. The function <code>set_form_fields()</code> + resets this.</p> -It is also possible to move around by pages. + <p>It is also possible to move around by pages.</p> -<PRE> + <pre> int set_form_page(FORM *form, /* form to alter */ int page); /* page to go to (0-origin) */ int form_page(FORM *form); /* return form's current page */ -</PRE> +</pre> -The initial page of a newly-created form is 0. The function -<CODE>set_form_fields()</CODE> resets this. + <p>The initial page of a newly-created form is 0. The function + <code>set_form_fields()</code> resets this.</p> -<H2><A NAME="frmoptions">Form Options</A></H2> + <h2><a name="frmoptions" id="frmoptions">Form Options</a></h2> -Like fields, forms may have control option bits. They can be changed -or queried with these functions: + <p>Like fields, forms may have control option bits. They can be + changed or queried with these functions:</p> -<PRE> + <pre> int set_form_opts(FORM *form, /* form to alter */ int attr); /* attribute to set */ @@ -2545,179 +3236,210 @@ int form_opts_off(FORM *form, /* form to alter */ int attr); /* attributes to turn off */ int form_opts(FORM *form); /* form to query */ -</PRE> +</pre> + + <p>By default, all options are on. Here are the available option + bits:</p> + + <dl> + <dt>O_NL_OVERLOAD</dt> -By default, all options are on. Here are the available option bits: + <dd>Enable overloading of <code>REQ_NEW_LINE</code> as + described in <a href="#fedit">Editing Requests</a>. The value + of this option is ignored on dynamic fields that have not + reached their size limit; these have no last line, so the + circumstances for triggering a <code>REQ_NEXT_FIELD</code> + never arise.</dd> -<DL> -<DT> O_NL_OVERLOAD -<DD> Enable overloading of <CODE>REQ_NEW_LINE</CODE> as described in <A -href="#fedit">Editing Requests</A>. The value of this option is -ignored on dynamic fields that have not reached their size limit; -these have no last line, so the circumstances for triggering a -<CODE>REQ_NEXT_FIELD</CODE> never arise. -<DT> O_BS_OVERLOAD -<DD> Enable overloading of <CODE>REQ_DEL_PREV</CODE> as described in -<A href="#fedit">Editing Requests</A>. -</DL> + <dt>O_BS_OVERLOAD</dt> -The option values are bit-masks and can be composed with logical-or in -the obvious way. + <dd>Enable overloading of <code>REQ_DEL_PREV</code> as + described in <a href="#fedit">Editing Requests</a>.</dd> + </dl> -<H2><A NAME="fcustom">Custom Validation Types</A></H2> + <p>The option values are bit-masks and can be composed with + logical-or in the obvious way.</p> -The <CODE>form</CODE> library gives you the capability to define custom -validation types of your own. Further, the optional additional arguments -of <CODE>set_field_type</CODE> effectively allow you to parameterize validation -types. Most of the complications in the validation-type interface have to -do with the handling of the additional arguments within custom validation -functions. + <h2><a name="fcustom" id="fcustom">Custom Validation Types</a></h2> -<H3><A NAME="flinktypes">Union Types</A></H3> + <p>The <code>form</code> library gives you the capability to + define custom validation types of your own. Further, the optional + additional arguments of <code>set_field_type</code> effectively + allow you to parameterize validation types. Most of the + complications in the validation-type interface have to do with + the handling of the additional arguments within custom validation + functions.</p> -The simplest way to create a custom data type is to compose it from two -preexisting ones: + <h3><a name="flinktypes" id="flinktypes">Union Types</a></h3> -<PRE> + <p>The simplest way to create a custom data type is to compose it + from two preexisting ones:</p> + + <pre> FIELD *link_fieldtype(FIELDTYPE *type1, FIELDTYPE *type2); -</PRE> +</pre> + + <p>This function creates a field type that will accept any of the + values legal for either of its argument field types (which may be + either predefined or programmer-defined). If a + <code>set_field_type()</code> call later requires arguments, the + new composite type expects all arguments for the first type, than + all arguments for the second. Order functions (see <a href= + "#forder">Order Requests</a>) associated with the component types + will work on the composite; what it does is check the validation + function for the first type, then for the second, to figure what + type the buffer contents should be treated as.</p> -This function creates a field type that will accept any of the values -legal for either of its argument field types (which may be either -predefined or programmer-defined). + <h3><a name="fnewtypes" id="fnewtypes">New Field Types</a></h3> -If a <CODE>set_field_type()</CODE> call later requires arguments, the new -composite type expects all arguments for the first type, than all arguments -for the second. Order functions (see <A HREF="#forder">Order Requests</A>) -associated with the component types will work on the composite; what it does -is check the validation function for the first type, then for the second, to -figure what type the buffer contents should be treated as. + <p>To create a field type from scratch, you need to specify one + or both of the following things:</p> -<H3><A NAME="fnewtypes">New Field Types</A></H3> + <ul> + <li>A character-validation function, to check each character as + it is entered.</li> -To create a field type from scratch, you need to specify one or both of the -following things: + <li>A field-validation function to be applied on exit from the + field.</li> + </ul> -<UL> -<LI>A character-validation function, to check each character as it is entered. -<LI>A field-validation function to be applied on exit from the field. -</UL> + <p>Here is how you do that:</p> -Here's how you do that: -<PRE> -typedef int (*HOOK)(); /* pointer to function returning int */ + <pre> +typedef int (*HOOK)(); /* pointer to function returning int */ FIELDTYPE *new_fieldtype(HOOK f_validate, /* field validator */ HOOK c_validate) /* character validator */ - int free_fieldtype(FIELDTYPE *ftype); /* type to free */ -</PRE> +</pre> -At least one of the arguments of <CODE>new_fieldtype()</CODE> must be -non-NULL. The forms driver will automatically call the new type's -validation functions at appropriate points in processing a field of -the new type. <P> + <p>At least one of the arguments of <code>new_fieldtype()</code> + must be non-NULL. The forms driver will automatically call the + new type's validation functions at appropriate points in + processing a field of the new type.</p> -The function <CODE>free_fieldtype()</CODE> deallocates the argument -fieldtype, freeing all storage associated with it. <P> + <p>The function <code>free_fieldtype()</code> deallocates the + argument fieldtype, freeing all storage associated with it.</p> -Normally, a field validator is called when the user attempts to -leave the field. Its first argument is a field pointer, from which it -can get to field buffer 0 and test it. If the function returns TRUE, -the operation succeeds; if it returns FALSE, the edit cursor stays in -the field. <P> + <p>Normally, a field validator is called when the user attempts + to leave the field. Its first argument is a field pointer, from + which it can get to field buffer 0 and test it. If the function + returns TRUE, the operation succeeds; if it returns FALSE, the + edit cursor stays in the field.</p> -A character validator gets the character passed in as a first argument. -It too should return TRUE if the character is valid, FALSE otherwise. + <p>A character validator gets the character passed in as a first + argument. It too should return TRUE if the character is valid, + FALSE otherwise.</p> -<H3><A NAME="fcheckargs">Validation Function Arguments</A></H3> + <h3><a name="fcheckargs" id="fcheckargs">Validation Function + Arguments</a></h3> -Your field- and character- validation functions will be passed a -second argument as well. This second argument is the address of a -structure (which we'll call a <EM>pile</EM>) built from any of the -field-type-specific arguments passed to <CODE>set_field_type()</CODE>. If -no such arguments are defined for the field type, this pile pointer -argument will be NULL. <P> + <p>Your field- and character- validation functions will be passed + a second argument as well. This second argument is the address of + a structure (which we will call a <em>pile</em>) built from any + of the field-type-specific arguments passed to + <code>set_field_type()</code>. If no such arguments are defined + for the field type, this pile pointer argument will be NULL.</p> -In order to arrange for such arguments to be passed to your validation -functions, you must associate a small set of storage-management functions -with the type. The forms driver will use these to synthesize a pile -from the trailing arguments of each <CODE>set_field_type()</CODE> argument, and -a pointer to the pile will be passed to the validation functions. <P> + <p>In order to arrange for such arguments to be passed to your + validation functions, you must associate a small set of + storage-management functions with the type. The forms driver will + use these to synthesize a pile from the trailing arguments of + each <code>set_field_type()</code> argument, and a pointer to the + pile will be passed to the validation functions.</p> -Here is how you make the association: + <p>Here is how you make the association:</p> -<PRE> -typedef char *(*PTRHOOK)(); /* pointer to function returning (char *) */ -typedef void (*VOIDHOOK)(); /* pointer to function returning void */ + <pre> +typedef char *(*PTRHOOK)(); /* pointer to function returning (char *) */ +typedef void (*VOIDHOOK)(); /* pointer to function returning void */ int set_fieldtype_arg(FIELDTYPE *type, /* type to alter */ PTRHOOK make_str, /* make structure from args */ PTRHOOK copy_str, /* make copy of structure */ VOIDHOOK free_str); /* free structure storage */ -</PRE> - -Here is how the storage-management hooks are used: - -<DL> -<DT> <CODE>make_str</CODE> -<DD> This function is called by <CODE>set_field_type()</CODE>. It gets one -argument, a <CODE>va_list</CODE> of the type-specific arguments passed to -<CODE>set_field_type()</CODE>. It is expected to return a pile pointer to a data -structure that encapsulates those arguments. -<DT> <CODE>copy_str</CODE> -<DD> This function is called by form library functions that allocate new -field instances. It is expected to take a pile pointer, copy the pile -to allocated storage, and return the address of the pile copy. -<DT> <CODE>free_str</CODE> -<DD> This function is called by field- and type-deallocation routines in the -library. It takes a pile pointer argument, and is expected to free the -storage of that pile. -</DL> - -The <CODE>make_str</CODE> and <CODE>copy_str</CODE> functions may return NULL to -signal allocation failure. The library routines will that call them will -return error indication when this happens. Thus, your validation functions -should never see a NULL file pointer and need not check specially for it. - -<H3><A NAME="fcustorder">Order Functions For Custom Types</A></H3> - -Some custom field types are simply ordered in the same well-defined way -that <CODE>TYPE_ENUM</CODE> is. For such types, it is possible to define -successor and predecessor functions to support the <CODE>REQ_NEXT_CHOICE</CODE> -and <CODE>REQ_PREV_CHOICE</CODE> requests. Here's how: - -<PRE> -typedef int (*INTHOOK)(); /* pointer to function returning int */ +</pre> + + <p>Here is how the storage-management hooks are used:</p> + + <dl> + <dt><code>make_str</code> + </dt> + + <dd>This function is called by <code>set_field_type()</code>. + It gets one argument, a <code>va_list</code> of the + type-specific arguments passed to + <code>set_field_type()</code>. It is expected to return a pile + pointer to a data structure that encapsulates those + arguments.</dd> + + <dt><code>copy_str</code> + </dt> + + <dd>This function is called by form library functions that + allocate new field instances. It is expected to take a pile + pointer, copy the pile to allocated storage, and return the + address of the pile copy.</dd> + + <dt><code>free_str</code> + </dt> + + <dd>This function is called by field- and type-deallocation + routines in the library. It takes a pile pointer argument, and + is expected to free the storage of that pile.</dd> + </dl> + + <p>The <code>make_str</code> and <code>copy_str</code> functions + may return NULL to signal allocation failure. The library + routines will that call them will return error indication when + this happens. Thus, your validation functions should never see a + NULL file pointer and need not check specially for it.</p> + + <h3><a name="fcustorder" id="fcustorder">Order Functions For + Custom Types</a></h3> + + <p>Some custom field types are simply ordered in the same + well-defined way that <code>TYPE_ENUM</code> is. For such types, + it is possible to define successor and predecessor functions to + support the <code>REQ_NEXT_CHOICE</code> and + <code>REQ_PREV_CHOICE</code> requests. Here is how:</p> + + <pre> +typedef int (*INTHOOK)(); /* pointer to function returning int */ int set_fieldtype_arg(FIELDTYPE *type, /* type to alter */ INTHOOK succ, /* get successor value */ INTHOOK pred); /* get predecessor value */ -</PRE> - -The successor and predecessor arguments will each be passed two arguments; -a field pointer, and a pile pointer (as for the validation functions). They -are expected to use the function <CODE>field_buffer()</CODE> to read the -current value, and <CODE>set_field_buffer()</CODE> on buffer 0 to set the next -or previous value. Either hook may return TRUE to indicate success (a -legal next or previous value was set) or FALSE to indicate failure. - -<H3><A NAME="fcustprobs">Avoiding Problems</A></H3> - -The interface for defining custom types is complicated and tricky. -Rather than attempting to create a custom type entirely from scratch, -you should start by studying the library source code for whichever of -the pre-defined types seems to be closest to what you want. <P> - -Use that code as a model, and evolve it towards what you really want. -You will avoid many problems and annoyances that way. The code -in the <CODE>ncurses</CODE> library has been specifically exempted from -the package copyright to support this. <P> - -If your custom type defines order functions, have do something intuitive -with a blank field. A useful convention is to make the successor of a -blank field the types minimum value, and its predecessor the maximum. -</BODY> -</HTML> +</pre> + + <p>The successor and predecessor arguments will each be passed + two arguments; a field pointer, and a pile pointer (as for the + validation functions). They are expected to use the function + <code>field_buffer()</code> to read the current value, and + <code>set_field_buffer()</code> on buffer 0 to set the next or + previous value. Either hook may return TRUE to indicate success + (a legal next or previous value was set) or FALSE to indicate + failure.</p> + + <h3><a name="fcustprobs" id="fcustprobs">Avoiding Problems</a></h3> + + <p>The interface for defining custom types is complicated and + tricky. Rather than attempting to create a custom type entirely + from scratch, you should start by studying the library source + code for whichever of the pre-defined types seems to be closest + to what you want.</p> + + <p>Use that code as a model, and evolve it towards what you + really want. You will avoid many problems and annoyances that + way. The code in the <code>ncurses</code> library has been + specifically exempted from the package copyright to support + this.</p> + + <p>If your custom type defines order functions, have do something + intuitive with a blank field. A useful convention is to make the + successor of a blank field the types minimum value, and its + predecessor the maximum.</p> +</body> +</html> |