mirror of
https://git.hardenedbsd.org/hardenedbsd/HardenedBSD.git
synced 2024-11-15 06:42:51 +01:00
e18651243e
While I didn't plan another upgrade, This version incorporate fixes from kevans@ so let's upgrade to it
3447 lines
131 KiB
HTML
3447 lines
131 KiB
HTML
<!--
|
|
$Id: ncurses-intro.html,v 1.54 2020/02/02 23:34:34 tom Exp $
|
|
****************************************************************************
|
|
* Copyright 2019,2020 Thomas E. Dickey *
|
|
* Copyright 2000-2013,2017 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 *
|
|
* "Software"), to deal in the Software without restriction, including *
|
|
* without limitation the rights to use, copy, modify, merge, publish, *
|
|
* distribute, distribute with modifications, sublicense, and/or sell *
|
|
* copies of the Software, and to permit persons to whom the Software is *
|
|
* furnished to do so, subject to the following conditions: *
|
|
* *
|
|
* The above copyright notice and this permission notice shall be included *
|
|
* in all copies or substantial portions of the Software. *
|
|
* *
|
|
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
|
|
* OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
|
|
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
|
|
* IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
|
|
* DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
|
|
* OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
|
|
* THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
|
|
* *
|
|
* Except as contained in this notice, the name(s) of the above copyright *
|
|
* holders shall not be used in advertising or otherwise to promote the *
|
|
* sale, use or other dealings in this Software without prior written *
|
|
* authorization. *
|
|
****************************************************************************
|
|
-->
|
|
<!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>
|
|
|
|
<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>
|
|
|
|
static void finish(int sig);
|
|
|
|
int
|
|
main(int argc, char *argv[])
|
|
{
|
|
int num = 0;
|
|
|
|
/* initialize your non-curses data structures here */
|
|
|
|
(void) signal(SIGINT, finish); /* arrange interrupts to terminate */
|
|
|
|
(void) initscr(); /* initialize the curses library */
|
|
keypad(stdscr, TRUE); /* enable keyboard mapping */
|
|
(void) nonl(); /* tell curses not to do NL->CR/NL on output */
|
|
(void) cbreak(); /* take input chars one at a time, no wait for \n */
|
|
(void) echo(); /* echo input - in color */
|
|
|
|
if (has_colors())
|
|
{
|
|
start_color();
|
|
|
|
/*
|
|
* 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:
|
|
*/
|
|
init_pair(1, COLOR_RED, COLOR_BLACK);
|
|
init_pair(2, COLOR_GREEN, COLOR_BLACK);
|
|
init_pair(3, COLOR_YELLOW, COLOR_BLACK);
|
|
init_pair(4, COLOR_BLUE, COLOR_BLACK);
|
|
init_pair(5, COLOR_CYAN, COLOR_BLACK);
|
|
init_pair(6, COLOR_MAGENTA, COLOR_BLACK);
|
|
init_pair(7, COLOR_WHITE, COLOR_BLACK);
|
|
}
|
|
|
|
for (;;)
|
|
{
|
|
int c = getch(); /* refresh, accept single keystroke of input */
|
|
attrset(COLOR_PAIR(num % 8));
|
|
num++;
|
|
|
|
/* process the command keystroke */
|
|
}
|
|
|
|
finish(0); /* we are done */
|
|
}
|
|
|
|
static void finish(int sig)
|
|
{
|
|
endwin();
|
|
|
|
/* do your non-curses wrapup here */
|
|
|
|
exit(0);
|
|
}
|
|
</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" 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>
|
|
|
|
<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>
|
|
|
|
<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>
|
|
|
|
<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>
|
|
|
|
<h2><a name="mcompile" id="mcompile">Compiling With the menu
|
|
Library</a></h2>
|
|
|
|
<p>Your menu-using modules must import the menu library
|
|
declarations with</p>
|
|
|
|
<pre>
|
|
#include <menu.h>
|
|
</pre>
|
|
|
|
<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>
|
|
|
|
<h2><a name="moverview" id="moverview">Overview of Menus</a></h2>
|
|
|
|
<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>
|
|
|
|
<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>
|
|
|
|
<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>
|
|
|
|
<p>The general flow of control of a menu program looks like
|
|
this:</p>
|
|
|
|
<ol>
|
|
<li>Initialize <code>curses</code>.</li>
|
|
|
|
<li>Create the menu items, using <code>new_item()</code>.</li>
|
|
|
|
<li>Create the menu using <code>new_menu()</code>.</li>
|
|
|
|
<li>Post the menu using <code>post_menu()</code>.</li>
|
|
|
|
<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>
|
|
|
|
<li>Unpost the form using <code>unpost_form()</code>.</li>
|
|
|
|
<li>Free the form, using <code>free_form()</code>.</li>
|
|
|
|
<li>Free the fields using <code>free_field()</code>.</li>
|
|
|
|
<li>Terminate <code>curses</code>.</li>
|
|
</ol>
|
|
|
|
<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>
|
|
|
|
<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>
|
|
|
|
<h2><a name="fcreate" id="fcreate">Creating and Freeing Fields
|
|
and Forms</a></h2>
|
|
|
|
<p>The basic function for creating fields is
|
|
<code>new_field()</code>:</p>
|
|
|
|
<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>
|
|
|
|
<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" id="flocation">Changing the Field
|
|
Location</a></h3>
|
|
|
|
<p>It is possible to move a field's location on the screen:</p>
|
|
|
|
<pre>
|
|
int move_field(FIELD *field, /* field to alter */
|
|
int top, int left); /* new upper-left corner */
|
|
</pre>
|
|
|
|
<p>You can, of course. query the current location through
|
|
<code>field_info()</code>.</p>
|
|
|
|
<h3><a name="fjust" id="fjust">The Justification Attribute</a></h3>
|
|
|
|
<p>One-line fields may be unjustified, justified right, justified
|
|
left, or centered. Here is how you manipulate this attribute:</p>
|
|
|
|
<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>
|
|
|
|
<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" id="fdispatts">Field Display
|
|
Attributes</a></h3>
|
|
|
|
<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>
|
|
|
|
<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>
|
|
int set_field_fore(FIELD *field, /* field to alter */
|
|
chtype attr); /* attribute to set */
|
|
|
|
chtype field_fore(FIELD *field); /* field to query */
|
|
|
|
int set_field_back(FIELD *field, /* field to alter */
|
|
chtype attr); /* attribute to set */
|
|
|
|
chtype field_back(FIELD *field); /* field to query */
|
|
|
|
int set_field_pad(FIELD *field, /* field to alter */
|
|
int pad); /* pad character to set */
|
|
|
|
chtype field_pad(FIELD *field);
|
|
|
|
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>
|
|
|
|
<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" id="foptions">Field Option Bits</a></h3>
|
|
|
|
<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>
|
|
int set_field_opts(FIELD *field, /* field to alter */
|
|
int attr); /* attribute to set */
|
|
|
|
int field_opts_on(FIELD *field, /* field to alter */
|
|
int attr); /* attributes to turn on */
|
|
|
|
int field_opts_off(FIELD *field, /* field to alter */
|
|
int attr); /* attributes to turn off */
|
|
|
|
int field_opts(FIELD *field); /* field to query */
|
|
</pre>
|
|
|
|
<p>By default, all options are on. Here are the available option
|
|
bits:</p>
|
|
|
|
<dl>
|
|
<dt>O_VISIBLE</dt>
|
|
|
|
<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>
|
|
|
|
<dt>O_ACTIVE</dt>
|
|
|
|
<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>
|
|
|
|
<dt>O_PUBLIC</dt>
|
|
|
|
<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>
|
|
|
|
<dt>O_EDIT</dt>
|
|
|
|
<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>
|
|
|
|
<dt>O_WRAP</dt>
|
|
|
|
<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>
|
|
|
|
<dt>O_BLANK</dt>
|
|
|
|
<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>
|
|
|
|
<dt>O_AUTOSKIP</dt>
|
|
|
|
<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>
|
|
|
|
<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>
|
|
|
|
<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>
|
|
|
|
<p>Here are the pre-defined validation types:</p>
|
|
|
|
<h3><a name="ftype_alpha" id="ftype_alpha">TYPE_ALPHA</a></h3>
|
|
|
|
<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>
|
|
int set_field_type(FIELD *field, /* field to alter */
|
|
TYPE_ALPHA, /* type to associate */
|
|
int width); /* maximum width of field */
|
|
</pre>
|
|
|
|
<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" id="ftype_alnum">TYPE_ALNUM</a></h3>
|
|
|
|
<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>
|
|
int set_field_type(FIELD *field, /* field to alter */
|
|
TYPE_ALNUM, /* type to associate */
|
|
int width); /* maximum width of field */
|
|
</pre>
|
|
|
|
<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" id="ftype_enum">TYPE_ENUM</a></h3>
|
|
|
|
<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>
|
|
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>
|
|
|
|
<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>
|
|
|
|
<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>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>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" id="ftype_integer">TYPE_INTEGER</a></h3>
|
|
|
|
<p>This field type accepts an integer. It is set up as
|
|
follows:</p>
|
|
|
|
<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>
|
|
|
|
<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>
|
|
|
|
<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>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" id="ftype_numeric">TYPE_NUMERIC</a></h3>
|
|
|
|
<p>This field type accepts a decimal number. It is set up as
|
|
follows:</p>
|
|
|
|
<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>
|
|
|
|
<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>
|
|
|
|
<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>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" id="ftype_regexp">TYPE_REGEXP</a></h3>
|
|
|
|
<p>This field type accepts data matching a regular expression. It
|
|
is set up as follows:</p>
|
|
|
|
<pre>
|
|
int set_field_type(FIELD *field, /* field to alter */
|
|
TYPE_REGEXP, /* type to associate */
|
|
char *regexp); /* expression to match */
|
|
</pre>
|
|
|
|
<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" id="fbuffer">Direct Field Buffer
|
|
Manipulation</a></h2>
|
|
|
|
<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>
|
|
char *field_buffer(FIELD *field, /* field to query */
|
|
int bufindex); /* number of buffer to query */
|
|
</pre>
|
|
|
|
<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>
|
|
int set_field_buffer(FIELD *field, /* field to alter */
|
|
int bufindex, /* number of buffer to alter */
|
|
char *value); /* string value to set */
|
|
</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>
|
|
|
|
<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>
|
|
|
|
<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>
|
|
int set_form_win(FORM *form, /* form to alter */
|
|
WINDOW *win); /* frame window to connect */
|
|
|
|
WINDOW *form_win(FORM *form); /* fetch frame window of form */
|
|
|
|
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>
|
|
|
|
<p>Note that curses operations, including <code>refresh()</code>,
|
|
on the form, should be done on the frame window, not the form
|
|
subwindow.</p>
|
|
|
|
<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>
|
|
int data_ahead(FORM *form); /* form to be queried */
|
|
|
|
int data_behind(FORM *form); /* form to be queried */
|
|
</pre>
|
|
|
|
<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>
|
|
|
|
<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>Finally, there is a function to restore the form window's
|
|
cursor to the value expected by the forms driver:</p>
|
|
|
|
<pre>
|
|
int pos_form_cursor(FORM *) /* form to be queried */
|
|
</pre>
|
|
|
|
<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" id="fdriver">Input Processing in the Forms
|
|
Driver</a></h2>
|
|
|
|
<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>
|
|
int form_driver(FORM *form, /* form to pass input to */
|
|
int request); /* form request code */
|
|
</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 */
|
|
|
|
HOOK form_init(FORM *form); /* form to query */
|
|
|
|
int set_form_term(FORM *form, /* form to alter */
|
|
HOOK hook); /* termination hook */
|
|
|
|
HOOK form_term(FORM *form); /* form to query */
|
|
|
|
int set_field_init(FORM *form, /* form to alter */
|
|
HOOK hook); /* initialization hook */
|
|
|
|
HOOK field_init(FORM *form); /* form to query */
|
|
|
|
int set_field_term(FORM *form, /* form to alter */
|
|
HOOK hook); /* termination hook */
|
|
|
|
HOOK field_term(FORM *form); /* form to query */
|
|
</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 */
|
|
|
|
FIELD *current_field(FORM *form); /* form to query */
|
|
|
|
int field_index(FORM *form, /* form to query */
|
|
FIELD *field); /* field to get index of */
|
|
</pre>
|
|
|
|
<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>
|
|
|
|
<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>It is also possible to move around by pages.</p>
|
|
|
|
<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>
|
|
|
|
<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" id="frmoptions">Form Options</a></h2>
|
|
|
|
<p>Like fields, forms may have control option bits. They can be
|
|
changed or queried with these functions:</p>
|
|
|
|
<pre>
|
|
int set_form_opts(FORM *form, /* form to alter */
|
|
int attr); /* attribute to set */
|
|
|
|
int form_opts_on(FORM *form, /* form to alter */
|
|
int attr); /* attributes to turn on */
|
|
|
|
int form_opts_off(FORM *form, /* form to alter */
|
|
int attr); /* attributes to turn off */
|
|
|
|
int form_opts(FORM *form); /* form to query */
|
|
</pre>
|
|
|
|
<p>By default, all options are on. Here are the available option
|
|
bits:</p>
|
|
|
|
<dl>
|
|
<dt>O_NL_OVERLOAD</dt>
|
|
|
|
<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>
|
|
|
|
<dt>O_BS_OVERLOAD</dt>
|
|
|
|
<dd>Enable overloading of <code>REQ_DEL_PREV</code> as
|
|
described in <a href="#fedit">Editing Requests</a>.</dd>
|
|
</dl>
|
|
|
|
<p>The option values are bit-masks and can be composed with
|
|
logical-or in the obvious way.</p>
|
|
|
|
<h2><a name="fcustom" id="fcustom">Custom Validation Types</a></h2>
|
|
|
|
<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>
|
|
|
|
<h3><a name="flinktypes" id="flinktypes">Union Types</a></h3>
|
|
|
|
<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>
|
|
|
|
<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>
|
|
|
|
<h3><a name="fnewtypes" id="fnewtypes">New Field Types</a></h3>
|
|
|
|
<p>To create a field type from scratch, you need to specify one
|
|
or both of the following things:</p>
|
|
|
|
<ul>
|
|
<li>A character-validation function, to check each character as
|
|
it is entered.</li>
|
|
|
|
<li>A field-validation function to be applied on exit from the
|
|
field.</li>
|
|
</ul>
|
|
|
|
<p>Here is how you do that:</p>
|
|
|
|
<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>
|
|
|
|
<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>
|
|
|
|
<p>The function <code>free_fieldtype()</code> deallocates the
|
|
argument fieldtype, freeing all storage associated with it.</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>
|
|
|
|
<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" id="fcheckargs">Validation Function
|
|
Arguments</a></h3>
|
|
|
|
<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>
|
|
|
|
<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>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 */
|
|
|
|
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>
|
|
|
|
<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>
|
|
|
|
<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>
|