ncurses 6.1 - patch 20180728
[ncurses.git] / man / form.3x
index c7c751cb7260dd6e4b6ad308e90f9104c751ac47..e9576b20b38315e4bddf1b628deb4dd7f218c6d4 100644 (file)
@@ -1,37 +1,85 @@
 '\" t
-.\" $Id: form.3x,v 0.8 1997/12/14 01:44:04 tom Exp $
+.\"***************************************************************************
+.\" Copyright (c) 1998-2017,2018 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.                                                           *
+.\"***************************************************************************
+.\"
+.\" $Id: form.3x,v 1.31 2018/07/28 21:34:56 tom Exp $
 .TH form 3X ""
+.ie \n(.g .ds `` \(lq
+.el       .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el       .ds '' ''
+.de bP
+.ie n  .IP \(bu 4
+.el    .IP \(bu 2
+..
 .SH NAME
-\fBform\fR - curses extension for programming forms
+\fBform\fR \- curses extension for programming forms
 .SH SYNOPSIS
 \fB#include <form.h>\fR
 .br
 .SH DESCRIPTION
 The \fBform\fR library provides terminal-independent facilities for composing
-form screens on character-cell terminals.  The library includes: field
+form screens on character-cell terminals.
+The library includes: field
 routines, which create and modify form fields; and form routines, which group
 fields into forms, display forms on the screen, and handle interaction with the
 user.
-
-The \fBform\fR library uses the \fBcurses\fR libraries, and a curses
-initialization routine such as \fBinitscr\fR must be called before using any of
-these functions.  To use the \fBform\fR library, link with the options
-\fB-lform -lcurses\fR.
-
+.PP
+The \fBform\fR library uses the \fBcurses\fR libraries.
+To use the \fBform\fR library, link with the options
+\fB\-lform \-lcurses\fR.
+.PP
+Your program should set up the locale, e.g.,
+.sp
+     \fBsetlocale(LC_ALL, "");\fP
+.sp
+so that input/output processing will work.
+.PP
+A curses initialization routine such as \fBinitscr\fR must be called
+before using any of these functions.
+.
 .SS Current Default Values for Field Attributes
-
-The \fBform\fR library maintains a default value for field attributes.  You
-can get or set this default by calling the appropriate \fBget_\fR or \fBset_\fR
-routine with a \fBNULL\fR field pointer.  Changing this default with a
+.
+The \fBform\fR library maintains a default value for field attributes.
+You
+can get or set this default by calling the appropriate \fBset_\fR
+or retrieval
+routine with a \fBNULL\fR field pointer.
+Changing this default with a
 \fBset_\fR function affects future field creations, but does not change the
 rendering of fields already created.
-
+.
 .SS Routine Name Index
-
+.
 The following table lists each \fBform\fR routine and the name of
 the manual page on which it is described.
-
-.TS 
+.
+.TS
 l l
 l l .
 \fBcurses\fR Routine Name      Manual Page Name
@@ -40,7 +88,7 @@ current_field \fBform_page\fR(3X)
 data_ahead     \fBform_data\fR(3X)
 data_behind    \fBform_data\fR(3X)
 dup_field      \fBform_field_new\fR(3X)
-dynamic_fieldinfo      \fBform_field_info\fR(3X)
+dynamic_field_info     \fBform_field_info\fR(3X)
 field_arg      \fBform_field_validation\fR(3X)
 field_back     \fBform_field_attributes\fR(3X)
 field_buffer   \fBform_field_buffer\fR(3X)
@@ -59,6 +107,7 @@ field_term   \fBform_hook\fR(3X)
 field_type     \fBform_field_validation\fR(3X)
 field_userptr  \fBform_field_userptr\fR(3X)
 form_driver    \fBform_driver\fR(3X)
+form_driver_w  \fBform_driver\fR(3X)*
 form_fields    \fBform_field\fR(3X)
 form_init      \fBform_hook\fR(3X)
 form_opts      \fBform_opts\fR(3X)
@@ -72,11 +121,13 @@ form_term  \fBform_hook\fR(3X)
 form_userptr   \fBform_userptr\fR(3X)
 form_win       \fBform_win\fR(3X)
 free_field     \fBform_field_new\fR(3X)
+free_fieldtype \fBform_fieldtype\fR(3X)
 free_form      \fBform_new\fR(3X)
 link_field     \fBform_field_new\fR(3X)
 link_fieldtype \fBform_fieldtype\fR(3X)
 move_field     \fBform_field\fR(3X)
 new_field      \fBform_field_new\fR(3X)
+new_fieldtype  \fBform_fieldtype\fR(3X)
 new_form       \fBform_new\fR(3X)
 new_page       \fBform_new_page\fR(3X)
 pos_form_cursor        \fBform_cursor\fR(3X)
@@ -106,66 +157,85 @@ set_form_userptr  \fBform_userptr\fR(3X)
 set_form_win   \fBform_win\fR(3X)
 set_max_field  \fBform_field_buffer\fR(3X)
 set_new_page   \fBform_new_page\fR(3X)
+unfocus_current_field  \fBform_page\fR(3X)
 unpost_form    \fBform_post\fR(3X)
 .TE
 .SH RETURN VALUE
-Routines that return pointers return \fBNULL\fR on error.  Routines that return
+Routines that return pointers return \fBNULL\fR on error,
+and set errno to the corresponding error-code returned by functions
+returning an integer.
+Routines that return
 an integer return one of the following error codes:
 .TP 5
-\fBE_OK\fR
+.B E_OK
 The routine succeeded.
 .TP 5
-\fBE_CONNECTED\fR
-The field is already connected to a form.
-.TP 5
-\fBE_SYSTEM_ERROR\fR
-System error occurred (see \fBerrno\fR).
-.TP 5
-\fBE_BAD_ARGUMENT\fR
+.B E_BAD_ARGUMENT
 Routine detected an incorrect or out-of-range argument.
 .TP 5
-\fBE_POSTED\fR
-The form is already posted.
-.TP 5
-\fBE_BAD_STATE\fR
+.B E_BAD_STATE
 Routine was called from an initialization or termination function.
 .TP 5
-\fBE_NO_ROOM\fR
-Form is too large for its window.
-.TP 5
-\fBE_NOT_POSTED\fR
-The form has not been posted.
-.TP 5
-\fBE_UNKNOWN_COMMAND\fR
-The form driver code saw an unknown request code.
+.B E_CONNECTED
+The field is already connected to a form.
 .TP 5
-\fBE_INVALID_FIELD\fR
+.B E_INVALID_FIELD
 Contents of a field are not valid.
 .TP 5
-\fBE_NOT_CONNECTED\fR
+.B E_NOT_CONNECTED
 No fields are connected to the form.
 .TP 5
-\fBE_REQUEST_DENIED\fR
+.B E_NOT_POSTED
+The form has not been posted.
+.TP 5
+.B E_NO_ROOM
+Form is too large for its window.
+.TP 5
+.B E_POSTED
+The form is already posted.
+.TP 5
+.B E_REQUEST_DENIED
 The form driver could not process the request.
-.SH SEE ALSO
-\fBcurses\fR(3X) and 3X pages whose names begin "form_" for detailed
-descriptions of the entry points.
+.TP 5
+.B E_SYSTEM_ERROR
+System error occurred (see \fBerrno\fR).
+.TP 5
+.B E_UNKNOWN_COMMAND
+The form driver code saw an unknown request code.
 .SH NOTES
 The header file \fB<form.h>\fR automatically includes the header files
 \fB<curses.h>\fR and \fB<eti.h>\fR.
-
+.PP
 In your library list, libform.a should be before libncurses.a; that is,
-you want to say `-lform -lncurses', not the other way around (which would
-give you a link error using GNU \fBld\fR(1) and many other linkers).
+you want to say \*(``\-lform \-lncurses\*('', not the other way around
+(which would give you a link error when using static libraries).
 .SH PORTABILITY
-These routines emulate the System V forms library.  They were not supported on
+These routines emulate the System V forms library.
+They were not supported on
 Version 7 or BSD versions.
+.PP
+The menu facility was documented in SVr4.2 in
+\fICharacter User Interface Programming (UNIX SVR4.2)\fP.
+.PP
+It is not part of X/Open Curses.
+.PP
+Aside from ncurses, there are few implementations:
+.bP
+systems based on SVr4 source code, e.g., Solaris.
+.bP
+NetBSD curses.
+.PP
+A few functions in this implementation are extensions added for ncurses,
+but not provided by other implementations, e.g.,
+\fBform_driver_w\fP,
+\fBunfocus_current_field\fP.
 .SH AUTHORS
-Juergen Pfeifer.  Manual pages and adaptation for ncurses by Eric
+Juergen Pfeifer.
+Manual pages and adaptation for ncurses by Eric
 S. Raymond.
-.\"#
-.\"# The following sets edit modes for GNU EMACS
-.\"# Local Variables:
-.\"# mode:nroff
-.\"# fill-column:79
-.\"# End:
+.SH SEE ALSO
+\fBcurses\fR(3X) and related pages whose names begin "form_" for detailed
+descriptions of the entry points.
+.PP
+This describes \fBncurses\fR
+version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).