<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 3.0//EN">
<!--
- $Id: ncurses-intro.html,v 1.31 1999/05/16 17:02:31 juergen Exp $
+ $Id: ncurses-intro.html,v 1.34 2000/06/11 00:03:55 tom Exp $
-->
<HTML>
<HEAD>
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>
+X toolkit.
<H2><A NAME="history">A Brief History of Curses</A></H2>
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>
+more capabilities, going far beyond BSD curses in power and flexibility.
<H2><A NAME="scope">Scope of This Document</A></H2>
This document describes <CODE>ncurses</CODE>, a free implementation of
the System V <CODE>curses</CODE> API with some clearly marked extensions.
-It includes the following System V curses features: <P>
+It includes the following System V curses features:
<UL>
<LI>Support for multiple screen highlights (BSD curses could only
-handle one `standout' highlight, usually reverse-video). <P>
-<LI>Support for line- and box-drawing using forms characters. <P>
-<LI>Recognition of function keys on input. <P>
-<LI>Color support. <P>
+handle one `standout' highlight, usually reverse-video).
+<LI>Support for line- and box-drawing using forms characters.
+<LI>Recognition of function keys on input.
+<LI>Color support.
<LI>Support for pads (windows of larger than screen size on which the
screen or a subwindow defines a viewport).
</UL>
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@clark.net">Thomas Dickey</A>
+<A HREF="mailto:dickey@herndon4.his.com">Thomas Dickey</A>
and
<A HREF="mailto:juergen.pfeifer@gmx.net">Jürgen Pfeifer</A>.
<A HREF="mailto:florian@gnu.org">Florian La Roche</A>
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>
+forms.
<H2><A NAME="terminology">Terminology</A></H2>
<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. <P>
+screen, scrolling independently of other windows on the physical screen.
<DT> screens
<DD>
A subset of windows which are as large as the terminal screen, i.e., they start
at the upper left hand corner and encompass the lower right hand corner. One
-of these, <CODE>stdscr</CODE>, is automatically provided for the programmer. <P>
+of these, <CODE>stdscr</CODE>, is automatically provided for the programmer.
<DT> terminal screen
<DD>
The package's idea of what the terminal display currently looks like, i.e.,
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>
+determine the most efficient way to repaint the screen.
<H3><A NAME="stdscr">Standard Windows and Function Naming Conventions</A></H3>
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>
+parameter passed.
<H3><A NAME="variables">Variables</A></H3>
work on any window, providing you change the function names and parameters as
mentioned above. <P>
-Here is a sample program to motivate the discussion: <P>
+Here is a sample program to motivate the discussion:
<PRE>
#include <curses.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 */
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) noecho(); /* don't echo input */
+ (void) echo(); /* echo input - in color */
if (has_colors())
{
start_color();
/*
- * Simple color assignment, often all we need.
+ * 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(COLOR_BLACK, COLOR_BLACK, COLOR_BLACK);
- init_pair(COLOR_GREEN, COLOR_GREEN, COLOR_BLACK);
- init_pair(COLOR_RED, COLOR_RED, COLOR_BLACK);
- init_pair(COLOR_CYAN, COLOR_CYAN, COLOR_BLACK);
- init_pair(COLOR_WHITE, COLOR_WHITE, COLOR_BLACK);
- init_pair(COLOR_MAGENTA, COLOR_MAGENTA, COLOR_BLACK);
- init_pair(COLOR_BLUE, COLOR_BLUE, COLOR_BLACK);
- init_pair(COLOR_YELLOW, COLOR_YELLOW, COLOR_BLACK);
+ 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 */
}
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>
+applied to any window.
<H3><A NAME="output">Output</A></H3>
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>
+up.
<H3><A NAME="input">Input</A></H3>
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>
+<CODE>key_</CODE> capabilities in the terminal's terminfo entry.
<H3><A NAME="formschars">Using Forms Characters</A></H3>
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>
+recognizable (though ugly) set of ASCII defaults.
<H3><A NAME="attributes">Character Attributes and Color</A></H3>
Once you've done an <CODE>init_pair()</CODE> that creates color-pair N, you can
use <CODE>COLOR_PAIR(N)</CODE> as a highlight that invokes that particular
color combination. Note that <CODE>COLOR_PAIR(N)</CODE>, for constant N,
-is itself a compile-time constant and can be used in initializers. <P>
+is itself a compile-time constant and can be used in initializers.
<H3><A NAME="mouse">Mouse Interfacing</A></H3>
code that illustrates how this can be done. <P>
See the manual page <CODE>curs_mouse(3X)</CODE> for full details of the
-mouse-interface functions. <P>
+mouse-interface functions.
<H3><A NAME="finishing">Finishing Up</A></H3>
<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>
+should be called before exiting.
<H2><A NAME="functions">Function Descriptions</A></H2>
exits. Otherwise it returns a pointer to stdscr. A few functions may be
called before initscr (<CODE>slk_init()</CODE>, <CODE>filter()</CODE>,
<CODE>ripofflines()</CODE>, <CODE>use_env()</CODE>, and, if you are using multiple
-terminals, <CODE>newterm()</CODE>.) <P>
+terminals, <CODE>newterm()</CODE>.)
<DT> <CODE>endwin()</CODE>
<DD> Your program should always call <CODE>endwin()</CODE> before exiting or
shelling out of the program. This function will restore tty modes,
move the cursor to the lower left corner of the screen, reset the
terminal into the proper non-visual mode. Calling <CODE>refresh()</CODE>
or <CODE>doupdate()</CODE> after a temporary escape from the program will
-restore the ncurses screen from before the escape. <P>
+restore the ncurses screen from before the escape.
<DT> <CODE>newterm(type, ofp, ifp)</CODE>
<DD> A program which outputs to more than one terminal should use
<CODE>newterm()</CODE> instead of <CODE>initscr()</CODE>. <CODE>newterm()</CODE> should
<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. <P>
+opened using this function.
<DT> <CODE>set_term(new)</CODE>
<DD> This function is used to switch to a different terminal previously
opened by <CODE>newterm()</CODE>. The screen reference for the new terminal
is passed as the parameter. The previous terminal is returned by the
-function. All other calls affect only the current terminal. <P>
+function. All other calls affect only the current terminal.
<DT> <CODE>delscreen(sp)</CODE>
<DD> The inverse of <CODE>newterm()</CODE>; deallocates the data structures
associated with a given <CODE>SCREEN</CODE> reference.
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. <P>
+location of the window's cursor.
<DT> <CODE>doupdate()</CODE> and <CODE>wnoutrefresh(win)</CODE>
<DD> These two functions allow multiple updates with more efficiency
than wrefresh. To use them, it is important to understand how curses
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>
+distinguished by the fact that they are named in capital letters.
<H2><A NAME="hints">Hints, Tips, and Tricks</A></H2>
The <CODE>ncurses</CODE> manual pages are a complete reference for this library.
In the remainder of this document, we discuss various useful methods that
-may not be obvious from the manual page descriptions. <P>
+may not be obvious from the manual page descriptions.
<H3><A NAME="caution">Some Notes of Caution</A></H3>
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>
+in which case several screens could be open with different sizes.
<H3><A NAME="leaving">Temporarily Leaving NCURSES Mode</A></H3>
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>
+<CODE>def_shell_mode</CODE> and <CODE>def_prog_mode</CODE> on each tty yourself.
<H3><A NAME="testing">Testing for Terminal Capabilities</A></H3>
(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>
+macro <CODE>cursor_address</CODE>.
<H3><A NAME="tuning">Tuning for Speed</A></H3>
Use the <CODE>addchstr()</CODE> family of functions for fast
screen-painting of text when you know the text doesn't contain any
control characters. Try to make attribute changes infrequent on your
-screens. Don't use the <CODE>immedok()</CODE> option! <P>
+screens. Don't use the <CODE>immedok()</CODE> option!
<H3><A NAME="special">Special Features of NCURSES</A></H3>
do all the necessary <CODE>wnoutrfresh()</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>
+all your updates.
<H3><A NAME="backbug">Background Erase</A></H3>
or <CODE>wbkgdset()</CODE>. <P>
This change in behavior conforms <CODE>ncurses</CODE> to System V Release 4 and
-the XSI Curses standard. <P>
+the XSI Curses standard.
<H2><A NAME="xsifuncs">XSI Curses Conformance</A></H2>
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>
+<CODE>#undef</CODE>.
<H1><A NAME="panels">The Panels Library</A></H1>
<CODE>doupdate()</CODE> just before accepting command input, once in each cycle
of interaction with the user. If you call <CODE>update_panels()</CODE> after
each and every panel write, you'll generate a lot of unnecessary refresh
-activity and screen flicker. <P>
+activity and screen flicker.
<H2><A NAME="pstdscr">Panels, Input, and the Standard Screen</A></H2>
that the panel is totally unobscured. <P>
There is presently no way to display changes to one obscured panel without
-repainting all panels. <P>
+repainting all panels.
<H2><A NAME="hiding">Hiding Panels</A></H2>
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>
+Other panels operations are applicable.
<H2><A NAME="pmisc">Miscellaneous Other Facilities</A></H2>
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>
+details.
<H1><A NAME="menu">The Menu Library</A></H1>
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>
+with <CODE>ncurses</CODE>.
<H2><A NAME="mcompile">Compiling With the menu Library</A></H2>
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>
+is good practice to code as though other option bits might be on.
<H2><A NAME="mdisplay">Menu Display</A></H2>
The menu library calculates a minimum display size for your window, based
-on the following variables: <P>
+on the following variables:
<UL>
<LI>The number and maximum length of the menu items
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>
+change (see the <CODE>menu_attribs(3x)</CODE> manual page.
<H2><A NAME="mwindows">Menu Windows</A></H2>
When you call <CODE>menu_post()</CODE>, you write the menu to its
subwindow. When you call <CODE>menu_unpost()</CODE>, you erase the
subwindow, However, neither of these actually modifies the screen. To
-do that, call <CODE>wrefresh()</CODE> or some equivalent. <P>
+do that, call <CODE>wrefresh()</CODE> or some equivalent.
<H2><A NAME="minput">Processing Menu Input</A></H2>
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>
+<CODE>menu_userptr(3x)</CODE>.
<H1><A NAME="form">The Forms Library</A></H1>
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>
+with <CODE>ncurses</CODE>.
<H2><A NAME="fcompile">Compiling With the form Library</A></H2>
<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>
+to put <CODE>-lform</CODE> first and <CODE>-lncurses</CODE> second.
<H2><A NAME="foverview">Overview of Forms</A></H2>
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>
+the menu driver loop has to support field editing and data validation.
<H2><A NAME="fcreate">Creating and Freeing Fields and Forms</A></H2>
-The basic function for creating fields is <CODE>new_field()</CODE>: <P>
+The basic function for creating fields is <CODE>new_field()</CODE>:
<PRE>
FIELD *new_field(int height, int width, /* new field size */
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>
+field; your application can use them for its own purposes.
<PRE>
FIELD *dup_field(FIELD *field, /* field to copy */
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>
+<CODE>form_field_new(3X)</CODE> for details).
<PRE>
FIELD *link_field(FIELD *field, /* field to copy */
the field allocation is not possible due to an out-of-memory error or
out-of-bounds arguments. <P>
-To connect fields to a form, use <P>
+To connect fields to a form, use
<PRE>
FORM *new_form(FIELD **fields);
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>
+your form objects first.
<H2><A NAME="fattributes">Fetching and Changing Field Attributes</A></H2>
<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>
+as defaults until your forms application terminates.
<H3><A NAME="fsizes">Fetching Size and Location Data</A></H3>
-You can retrieve field sizes and locations through: <P>
+You can retrieve field sizes and locations through:
<PRE>
int field_info(FIELD *field, /* field from which to fetch */
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>
+from an existing one.
<H3><A NAME="flocation">Changing the Field Location</A></H3>
-It is possible to move a field's location on the screen: <P>
+It is possible to move a field's location on the screen:
<PRE>
int move_field(FIELD *field, /* field to alter */
<H3><A NAME="fjust">The Justification Attribute</A></H3>
One-line fields may be unjustified, justified right, justified left,
-or centered. Here is how you manipulate this attribute: <P>
+or centered. Here is how you manipulate this attribute:
<PRE>
int set_field_just(FIELD *field, /* field to alter */
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>
+<CODE>JUSTIFY_LEFT</CODE>, or <CODE>JUSTIFY_CENTER</CODE>.
<H3><A NAME="fdispatts">Field Display Attributes</A></H3>
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>
+in the field buffer.
<PRE>
int set_field_fore(FIELD *field, /* field to alter */
<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>
+a new form screen.
<H3><A NAME="foptions">Field Option Bits</A></H3>
However, options may be changed on posted fields that are not current. <P>
The option values are bit-masks and can be composed with logical-or in
-the obvious way. <P>
+the obvious way.
<H2><A NAME="fstatus">Field Status</A></H2>
Every field has a status flag, which is set to FALSE when the field is
created and TRUE when the value in field buffer 0 changes. This flag can
-be queried and set directly: <P>
+be queried and set directly:
<PRE>
int set_field_status(FIELD *field, /* field to alter */
<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>
+processed by the forms driver.
<H2><A NAME="fuser">Field User Pointer</A></H2>
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>
+to initialize the new field's user pointer.
<H2><A NAME="fdynamic">Variable-Sized Fields</A></H2>
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>
+it with this function:
<PRE>
int set_max_field(FIELD *field, /* field to alter (may not be NULL) */
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>
+functions:
<PRE>
int set_field_type(FIELD *field, /* field to alter */
<CODE>NULL</CODE> field default will change the system default for validation of
newly-created fields. <P>
-Here are the pre-defined validation types: <P>
+Here are the pre-defined validation types:
<H3><A NAME="ftype_alpha">TYPE_ALPHA</A></H3>
This field type accepts alphabetic data; no blanks, no digits, no special
-characters (this is checked at character-entry time). It is set up with: <P>
+characters (this is checked at character-entry time). It is set up with:
<PRE>
int set_field_type(FIELD *field, /* field to alter */
The <CODE>width</CODE> argument sets a minimum width of data. Typically
you'll want to set this to the field width; if it's greater than the
field width, the validation check will always fail. A minimum width
-of zero makes field completion optional. <P>
+of zero makes field completion optional.
<H3><A NAME="ftype_alnum">TYPE_ALNUM</A></H3>
This field type accepts alphabetic data and digits; no blanks, no special
-characters (this is checked at character-entry time). It is set up with: <P>
+characters (this is checked at character-entry time). It is set up with:
<PRE>
int set_field_type(FIELD *field, /* field to alter */
The <CODE>width</CODE> argument sets a minimum width of data. As with
TYPE_ALPHA, typically you'll want to set this to the field width; if it's
greater than the field width, the validation check will always fail. A
-minimum width of zero makes field completion optional. <P>
+minimum width of zero makes field completion optional.
<H3><A NAME="ftype_enum">TYPE_ENUM</A></H3>
This type allows you to restrict a field's values to be among a specified
set of string values (for example, the two-letter postal codes for U.S.
-states). It is set up with: <P>
+states). It is set up with:
<PRE>
int set_field_type(FIELD *field, /* field to alter */
matches to be unique in order to be valid. <P>
The <CODE>REQ_NEXT_CHOICE</CODE> and <CODE>REQ_PREV_CHOICE</CODE> input requests
-can be particularly useful with these fields. <P>
+can be particularly useful with these fields.
<H3><A NAME="ftype_integer">TYPE_INTEGER</A></H3>
-This field type accepts an integer. It is set up as follows: <P>
+This field type accepts an integer. It is set up as follows:
<PRE>
int set_field_type(FIELD *field, /* field to alter */
<H3><A NAME="ftype_numeric">TYPE_NUMERIC</A></H3>
-This field type accepts a decimal number. It is set up as follows: <P>
+This field type accepts a decimal number. It is set up as follows:
<PRE>
int set_field_type(FIELD *field, /* field to alter */
<H3><A NAME="ftype_regexp">TYPE_REGEXP</A></H3>
This field type accepts data matching a regular expression. It is set up
-as follows: <P>
+as follows:
<PRE>
int set_field_type(FIELD *field, /* field to alter */
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>
+field buffer. You can find this out with:
<PRE>
char *field_buffer(FIELD *field, /* field to query */
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>
+by the forms driver.
<H2><A NAME="formattrs">Attributes of Forms</A></H2>
of these functions using a form-pointer argument of <CODE>NULL</CODE>. <P>
The principal attribute of a form is its field list. You can query
-and change this list with: <P>
+and change this list with:
<PRE>
int set_form_fields(FORM *form, /* form to alter */
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>
+is NULL.
<H2><A NAME="fdisplay">Control of Form Display</A></H2>
In order to declare your own frame window for a form, you'll need to
know the size of the form's bounding rectangle. You can get this
-information with: <P>
+information with:
<PRE>
int scale_form(FORM *form, /* form to query */
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>
+these functions:
<PRE>
int data_ahead(FORM *form); /* form to be queried */
left hand) character position is off-screen (not being displayed). <P>
Finally, there is a function to restore the form window's cursor to the
-value expected by the forms driver: <P>
+value expected by the forms driver:
<PRE>
int pos_form_cursor(FORM *) /* form to be queried */
</PRE>
If your application changes the form window cursor, call this function before
-handing control back to the forms driver in order to re-synchronize it. <P>
+handing control back to the forms driver in order to re-synchronize it.
<H2><A NAME="fdriver">Input Processing in the Forms Driver</A></H2>
The function <CODE>form_driver()</CODE> handles virtualized input requests
for form navigation, editing, and validation requests, just as
<CODE>menu_driver</CODE> does for menus (see the section on <A
-HREF="#minput">menu input handling</A>). <P>
+HREF="#minput">menu input handling</A>).
<PRE>
int form_driver(FORM *form, /* form to pass input to */
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>
+that the input taken by the driver matched what was expected.
<H3><A NAME="fpage">Page Navigation Requests</A></H3>
These requests cause page-level moves through the form,
-triggering display of a new form screen. <P>
+triggering display of a new form screen.
<DL>
<DT> <CODE>REQ_NEXT_PAGE</CODE>
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>
+the first page goes to the last.
<H3><A NAME="#ffield">Inter-Field Navigation Requests</A></H3>
-These requests handle navigation between fields on the same page. <P>
+These requests handle navigation between fields on the same page.
<DL>
<DT> <CODE>REQ_NEXT_FIELD</CODE>
<DD> Move to the first field.
<DT> <CODE>REQ_LAST_FIELD</CODE>
<DD> Move to the last field.
-<P>
<DT> <CODE>REQ_SNEXT_FIELD</CODE>
<DD> Move to sorted next field.
<DT> <CODE>REQ_SPREV_FIELD</CODE>
<DD> Move to the sorted first field.
<DT> <CODE>REQ_SLAST_FIELD</CODE>
<DD> Move to the sorted last field.
-<P>
<DT> <CODE>REQ_LEFT_FIELD</CODE>
<DD> Move left to field.
<DT> <CODE>REQ_RIGHT_FIELD</CODE>
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>
+otherwise it will skip over B to C.
<H3><A NAME="#fifield">Intra-Field Navigation Requests</A></H3>
These requests drive movement of the edit cursor within the currently
-selected field. <P>
+selected field.
<DL>
<DT> <CODE>REQ_NEXT_CHAR</CODE>
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>
+look for the first or last non-pad character in their ranges.
<H3><A NAME="fscroll">Scrolling Requests</A></H3>
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>
</DL>
For scrolling purposes, a <EM>page</EM> of a field is the height
-of its visible part. <P>
+of its visible part.
<H3><A NAME="fedit">Editing Requests</A></H3>
(insertion is the default. <P>
The following requests support editing the field and changing the edit
-mode: <P>
+mode:
<DL>
<DT> <CODE>REQ_INS_MODE</CODE>
disabled and the forms driver just returns <CODE>E_REQUEST_DENIED</CODE>. <P>
See <A HREF="#frmoptions">Form Options</A> for discussion of how to set
-and clear the overload options. <P>
+and clear the overload options.
<H3><A NAME="forder">Order Requests</A></H3>
If the type of your field is ordered, and has associated functions
for getting the next and previous values of the type from a given value,
-there are requests that can fetch that value into the field buffer: <P>
+there are requests that can fetch that value into the field buffer:
<DL>
<DT> <CODE>REQ_NEXT_CHOICE</CODE>
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>
+our own ordering functions.
<H3><A NAME="fappcmds">Application Commands</A></H3>
Form requests are represented as integers above the <CODE>curses</CODE> value
greater than <CODE>KEY_MAX</CODE> and less than or equal to the constant
<CODE>MAX_COMMAND</CODE>. If your input-virtualization routine returns a
-value above <CODE>MAX_COMMAND</CODE>, the forms driver will ignore it. <P>
+value above <CODE>MAX_COMMAND</CODE>, the forms driver will ignore it.
<H2><A NAME="fhooks">Field Change Hooks</A></H2>
It is possible to set function hooks to be executed whenever the
-current field or form changes. Here are the functions that support this: <P>
+current field or form changes. Here are the functions that support this:
<PRE>
typedef void (*HOOK)(); /* pointer to function returning void */
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>
+of the hook call.
<DL>
<DT> form_init
each field change
<DT> field_term
<DD> This hook is called just after field validation; that is, just before
-the field is altered. It is also called when the form is unposted. <P>
+the field is altered. It is also called when the form is unposted.
<DT> form_term
<DD> This hook is called when the form is unposted; also, just before
each page change operation.
a NULL first argument. <P>
You can disable any of these hooks by (re)setting them to NULL, the default
-value. <P>
+value.
<H2><A HREF="#ffocus">Field Change Commands</A></H2>
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>
+accomplish this:
<PRE>
int set_current_field(FORM *form, /* form to alter */
The initial current field of a form is the first active field on the
first page. The function <CODE>set_form_fields()</CODE> resets this.<P>
-It is also possible to move around by pages. <P>
+It is also possible to move around by pages.
<PRE>
int set_form_page(FORM *form, /* form to alter */
</PRE>
The initial page of a newly-created form is 0. The function
-<CODE>set_form_fields()</CODE> resets this. <P>
+<CODE>set_form_fields()</CODE> resets this.
<H2><A NAME="frmoptions">Form Options</A></H2>
Like fields, forms may have control option bits. They can be changed
-or queried with these functions: <P>
+or queried with these functions:
<PRE>
int set_form_opts(FORM *form, /* form to alter */
</DL>
The option values are bit-masks and can be composed with logical-or in
-the obvious way. <P>
+the obvious way.
<H2><A NAME="fcustom">Custom Validation Types</A></H2>
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>
+functions.
<H3><A NAME="flinktypes">Union Types</A></H3>
The simplest way to create a custom data type is to compose it from two
-preexisting ones: <P>
+preexisting ones:
<PRE>
FIELD *link_fieldtype(FIELDTYPE *type1,
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>
+figure what type the buffer contents should be treated as.
<H3><A NAME="fnewtypes">New Field Types</A></H3>
To create a field type from scratch, you need to specify one or both of the
-following things: <P>
+following things:
<UL>
<LI>A character-validation function, to check each character as it is entered.
<LI>A field-validation function to be applied on exit from the field.
</UL>
-Here's how you do that: <P>
+Here's how you do that:
<PRE>
typedef int (*HOOK)(); /* pointer to function returning int */
the field. <P>
A character validator gets the character passed in as a first argument.
-It too should return TRUE if the character is valid, FALSE otherwise. <P>
+It too should return TRUE if the character is valid, FALSE otherwise.
<H3><A NAME="fcheckargs">Validation Function Arguments</A></H3>
from the trailing arguments of each <CODE>set_field_type()</CODE> argument, and
a pointer to the pile will be passed to the validation functions. <P>
-Here is how you make the association: <P>
+Here is how you make the association:
<PRE>
typedef char *(*PTRHOOK)(); /* pointer to function returning (char *) */
VOIDHOOK free_str); /* free structure storage */
</PRE>
-Here is how the storage-management hooks are used: <P>
+Here is how the storage-management hooks are used:
<DL>
<DT> <CODE>make_str</CODE>
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>
+should never see a NULL file pointer and need not check specially for it.
<H3><A NAME="fcustorder">Order Functions For Custom Types</A></H3>
Some custom field types are simply ordered in the same well-defined way
that <CODE>TYPE_ENUM</CODE> is. For such types, it is possible to define
successor and predecessor functions to support the <CODE>REQ_NEXT_CHOICE</CODE>
-and <CODE>REQ_PREV_CHOICE</CODE> requests. Here's how: <P>
+and <CODE>REQ_PREV_CHOICE</CODE> requests. Here's how:
<PRE>
typedef int (*INTHOOK)(); /* pointer to function returning int */
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>
+legal next or previous value was set) or FALSE to indicate failure.
<H3><A NAME="fcustprobs">Avoiding Problems</A></H3>
projects / ncurses.git / blobdiff