ncurses 5.7 - patch 20101204

[ncurses.git] / man / form_fieldtype.3x

diff --git a/man/form_fieldtype.3x b/man/form_fieldtype.3x
index 217efa68bf03ec904474a8609cb697ef24799a1b..028e9b0befccfcb978bc238693c39e36c045596c 100644 (file)
--- a/man/form_fieldtype.3x
+++ b/man/form_fieldtype.3x
@@ -1,7 +1,36 @@
 '\" t
 '\" t

-.TH form_field 3X ""
+.\"***************************************************************************
+.\" Copyright (c) 1998-2006,2010 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_fieldtype.3x,v 1.16 2010/12/04 18:40:45 tom Exp $
+.TH form_fieldtype 3X ""

 .SH NAME
 .SH NAME

-\fBform_fieldtype\fR - define validation-field types
+\fBform_fieldtype\fR \- define validation-field types

 .SH SYNOPSIS
 \fB#include <form.h>\fR
 .br
 .SH SYNOPSIS
 \fB#include <form.h>\fR
 .br


@@ -18,68 +47,90 @@ int set_fieldtype_arg(
     void  (* const free_arg)(void *));
 .br
 int set_fieldtype_choice(
     void  (* const free_arg)(void *));
 .br
 int set_fieldtype_choice(

-    FIELDTYPE *fieldtype
+    FIELDTYPE *fieldtype,

     bool (* const next_choice)(FIELD *, const void *),
     bool (* const prev_choice)(FIELD *, const void *));
 .br
     bool (* const next_choice)(FIELD *, const void *),
     bool (* const prev_choice)(FIELD *, const void *));
 .br

-FIELDTYPE *link_fieldtype(FIELDTYPE *type1, 
+FIELDTYPE *link_fieldtype(FIELDTYPE *type1,

                           FIELDTYPE *type2);
                           FIELDTYPE *type2);

-.br 
+.br

 .SH DESCRIPTION
 The function \fBnew_fieldtype\fR creates a new field type usable for data
 validation.  You supply it with \fIfield_check\fR, a predicate to check the
 .SH DESCRIPTION
 The function \fBnew_fieldtype\fR creates a new field type usable for data
 validation.  You supply it with \fIfield_check\fR, a predicate to check the

-validity of an entered data string whenever the user attempt to leave a field.
+validity of an entered data string whenever the user attempts to leave a field.

 The (FIELD *) argument is passed in so the validation predicate can see the
 field's buffer, sizes and other attributes; the second argument is an
 argument-block structure, about which more below.
 The (FIELD *) argument is passed in so the validation predicate can see the
 field's buffer, sizes and other attributes; the second argument is an
 argument-block structure, about which more below.

-
+.PP

 You also supply \fBnew_fieldtype\fR with \fIchar_check\fR,
 a function to validate input characters as they are entered; it will be passed
 the character to be checked and a pointer to an argument-block structure.
 You also supply \fBnew_fieldtype\fR with \fIchar_check\fR,
 a function to validate input characters as they are entered; it will be passed
 the character to be checked and a pointer to an argument-block structure.

-
+.PP

 The function \fBfree_fieldtype\fR frees the space allocated for a given
 validation type.
 The function \fBfree_fieldtype\fR frees the space allocated for a given
 validation type.

-
-The function \fBset_fieldtype\fR associates three storage-management functions 
-with a field type.  The \fImak_arg\fR function is automatically applied to the
+.PP
+The function \fBset_fieldtype_arg\fR associates three storage-management functions
+with a field type.
+The \fImake_arg\fR function is automatically applied to the

 list of arguments you give \fBset_field_type\fR when attaching validation
 list of arguments you give \fBset_field_type\fR when attaching validation

-to a field; its job is to bundle these into an allocated argument-block 
-object which can later be passed to validation predicated.  The other two
-hook arguments should copy and free argument-block structures.  They will
-be used by the forms-driver code. You must supply the \fImak_arg\fR function,
-the other two are optional, you may supply NULL for them. In this case it
-is assumed, that \fImak_arg\fR doesn't allocate memory but simply loads the
+to a field; its job is to bundle these into an allocated argument-block
+object which can later be passed to validation predicated.
+The other two hook arguments should copy and free argument-block structures.
+They will be used by the forms-driver code.
+You must supply the \fImake_arg\fR function,
+the other two are optional, you may supply NULL for them.
+In this case it is assumed
+that \fImake_arg\fR does not allocate memory but simply loads the

 argument into a single scalar value.
 argument into a single scalar value.

-
+.PP
+The function \fBlink_fieldtype\fR creates
+a new field type from the two given types.
+They are connected by an logical 'OR'.
+.PP

 The form driver requests \fBREQ_NEXT_CHOICE\fR and \fBREQ_PREV_CHOICE\fR assume
 that the possible values of a field form an ordered set, and provide the forms
 The form driver requests \fBREQ_NEXT_CHOICE\fR and \fBREQ_PREV_CHOICE\fR assume
 that the possible values of a field form an ordered set, and provide the forms

-user with a way to move through the set.  The \fBset_fieldtype_choice\fR
+user with a way to move through the set.
+The \fBset_fieldtype_choice\fR

 function allows forms programmers to define successor and predecessor functions
 function allows forms programmers to define successor and predecessor functions

-for the field type.  These functions take the field pointer and an
+for the field type.
+These functions take the field pointer and an

 argument-block structure as arguments.
 .SH RETURN VALUE
 The pointer-valued routines return NULL on error.
 argument-block structure as arguments.
 .SH RETURN VALUE
 The pointer-valued routines return NULL on error.

-
+They set errno according to their success:
+.TP 5
+.B E_OK
+The routine succeeded.
+.TP 5
+.B E_BAD_ARGUMENT
+Routine detected an incorrect or out-of-range argument.
+.TP 5
+.B E_SYSTEM_ERROR
+System error occurred, e.g., malloc failure.
+.PP

 The integer-valued routines return one of the following codes on
 error:
 .TP 5
 The integer-valued routines return one of the following codes on
 error:
 .TP 5

-\fBE_OK\fR
+.B E_OK

 The routine succeeded.
 .TP 5
 The routine succeeded.
 .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
 Routine detected an incorrect or out-of-range argument.
 .TP 5

-\fBE_CONNECTED\fR
+.B E_CONNECTED

 The field is already connected to a form.
 The field is already connected to a form.

+.TP 5
+.B E_CURRENT
+The field is the current field.
+.TP 5
+.B E_SYSTEM_ERROR
+System error occurred (see \fBerrno\fR).

 .SH SEE ALSO
 \fBcurses\fR(3X), \fBform\fR(3X).
 .SH NOTES
 The header file \fB<form.h>\fR automatically includes the header file
 \fB<curses.h>\fR.
 .SH SEE ALSO
 \fBcurses\fR(3X), \fBform\fR(3X).
 .SH NOTES
 The header file \fB<form.h>\fR automatically includes the header file
 \fB<curses.h>\fR.

-
+.PP

 All of the \fB(char *)\fR arguments of these functions should actually be
 \fB(void *)\fR.  The type has been left uncorrected for strict compatibility
 with System V.
 All of the \fB(char *)\fR arguments of these functions should actually be
 \fB(void *)\fR.  The type has been left uncorrected for strict compatibility
 with System V.


@@ -89,9 +140,3 @@ Version 7 or BSD versions.
 .SH AUTHORS
 Juergen Pfeifer.  Manual pages and adaptation for new curses by Eric
 S. Raymond.
 .SH AUTHORS
 Juergen Pfeifer.  Manual pages and adaptation for new curses by Eric
 S. Raymond.

-.\"#
-.\"# The following sets edit modes for GNU EMACS
-.\"# Local Variables:
-.\"# mode:nroff
-.\"# fill-column:79
-.\"# End: