ncurses 6.5 - patch 20240622

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

diff --git a/man/form_fieldtype.3x b/man/form_fieldtype.3x
index d5b7cefa841d0849408097b22d67ceb13703319c..81a58b1d8e48f24beb1bbc38d700d6ffaec73e09 100644 (file)
--- a/man/form_fieldtype.3x
+++ b/man/form_fieldtype.3x
@@ -1,6 +1,5 @@
-'\" t

 .\"***************************************************************************
 .\"***************************************************************************

-.\" Copyright 2018-2019,2020 Thomas E. Dickey                                *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey                                *

 .\" Copyright 1998-2006,2010 Free Software Foundation, Inc.                  *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
 .\" Copyright 1998-2006,2010 Free Software Foundation, Inc.                  *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *


@@ -28,74 +27,99 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"

-.\" $Id: form_fieldtype.3x,v 1.23 2020/10/24 09:05:17 tom Exp $
-.TH form_fieldtype 3X ""
+.\" $Id: form_fieldtype.3x,v 1.46 2024/03/16 15:35:01 tom Exp $
+.TH form_fieldtype 3X 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.de bP
+.ie n  .IP \(bu 4
+.el    .IP \(bu 2
+..

 .SH NAME
 .SH NAME

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

 .SH SYNOPSIS
 .SH SYNOPSIS

-\fB#include <form.h>\fR
-.sp
-\fBFIELDTYPE *new_fieldtype(\fP
-    \fBbool (* const \fP\fIfield_check\fP\fB)(FIELD *, const void *),\fP
-    \fBbool (* const \fP\fIchar_check\fP\fB)(int, const void *));\fP
-.br
-\fBint free_fieldtype(FIELDTYPE *\fP\fIfieldtype\fP\fB);\fP
-.sp
+.nf
+\fB#include <form.h>
+.PP
+\fBFIELDTYPE *new_fieldtype(
+    \fBbool (* const \fIfield_check\fB)(FIELD *, const void *),\fR
+    \fBbool (* const \fIchar_check\fB)(int, const void *));\fR
+\fBint free_fieldtype(FIELDTYPE *\fIfieldtype\fB);\fR
+.PP

 \fBint set_fieldtype_arg(\fP
 \fBint set_fieldtype_arg(\fP

-    \fBFIELDTYPE *\fP\fIfieldtype\fP\fB,\fP
-    \fBvoid *(* const \fP\fImake_arg\fP\fB)(va_list *),\fP
-    \fBvoid *(* const \fP\fIcopy_arg\fP\fB)(const void *),\fP
-    \fBvoid  (* const \fP\fIfree_arg\fP\fB)(void *));\fP
-.br
+    \fBFIELDTYPE *\fIfieldtype\fB,\fR
+    \fBvoid *(* const \fImake_arg\fB)(va_list *),\fR
+    \fBvoid *(* const \fIcopy_arg\fB)(const void *),\fR
+    \fBvoid  (* const \fIfree_arg\fB)(void *));\fR

 \fBint set_fieldtype_choice(\fP
 \fBint set_fieldtype_choice(\fP

-    \fBFIELDTYPE *\fP\fIfieldtype\fP\fB,\fP
-    \fBbool (* const \fP\fInext_choice\fP\fB)(FIELD *, const void *),\fP
-    \fBbool (* const \fP\fIprev_choice\fP\fB)(FIELD *, const void *));\fP
-.sp
-\fBFIELDTYPE *link_fieldtype(FIELDTYPE *\fP\fItype1\fP\fB,\fP
-                          \fBFIELDTYPE *\fP\fItype2\fP\fB);\fP
+    \fBFIELDTYPE *\fIfieldtype\fB,\fR
+    \fBbool (* const \fInext_choice\fB)(FIELD *, const void *),\fR
+    \fBbool (* const \fIprev_choice\fB)(FIELD *, const void *));\fR
+.PP
+\fBFIELDTYPE *link_fieldtype(FIELDTYPE *\fItype1\fB,\fR
+                          \fBFIELDTYPE *\fItype2\fB);\fR
+.fi

 .SH DESCRIPTION
 .SH DESCRIPTION

-The function \fBnew_fieldtype\fR creates a new field type usable for data
+.SS new_fieldtype
+The function \fBnew_fieldtype\fP creates a new field type usable for data

 validation.
 validation.

-You supply it with \fIfield_check\fR, a predicate to check the
+Its parameters are function pointers:
+.TP 5
+\fIfield_check\fP
+This function checks the

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

+It has two arguments:
+.RS
+.bP

 The (FIELD *) argument is passed in so the validation predicate can see the
 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
+field's buffer, sizes and other attributes.
+.bP
+The second argument is an

 argument-block structure, about which more below.
 argument-block structure, about which more below.

+.RE
+.TP 5
+\fIchar_check\fP
+This function validates input characters as they are entered.
+The form library passes it the character to be checked
+and a pointer to an argument-block structure.
+.SS free_fieldtype
+The \fBfree_fieldtype\fP function
+frees the space allocated for a given validation type by \fBnew_fieldtype\fP.
+.SS set_fieldtype_arg
+The function \fBset_fieldtype_arg\fP associates
+three storage-management functions with a field type:
+.TP 5
+\fImake_arg\fP
+This function is automatically applied to the
+list of arguments you give \fBset_field_type\fP when attaching validation
+to a field.
+It stores the arguments in an allocated argument-block
+object which is used when validating input.
+.TP 5
+\fIcopy_arg\fP
+This function may be used by applications to copy argument-blocks.
+.TP 5
+\fIfree_arg\fP
+Frees an argument-block structure.

 .PP
 .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.
-.PP
-The function \fBfree_fieldtype\fR frees the space allocated for a given
-validation type.
-.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
-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
+You must supply the \fImake_arg\fP function.
+The other two are optional: you may supply NULL for them.
+In this case, the form library assumes
+that \fImake_arg\fP 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
+.SS set_fieldtype_choice
+The form driver requests \fBREQ_NEXT_CHOICE\fP and \fBREQ_PREV_CHOICE\fP 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.
 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
+.PP
+The \fBset_fieldtype_choice\fP

 function allows forms programmers to define successor and predecessor functions
 for the field type.
 These functions take the field pointer and an
 argument-block structure as arguments.
 function allows forms programmers to define successor and predecessor functions
 for the field type.
 These functions take the field pointer and an
 argument-block structure as arguments.

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

 .SH RETURN VALUE
 The pointer-valued routines return NULL on error.
 They set \fBerrno\fP according to their success:
 .SH RETURN VALUE
 The pointer-valued routines return NULL on error.
 They set \fBerrno\fP according to their success:


@@ -125,16 +149,7 @@ The field is already connected to a form.
 The field is the current field.
 .TP 5
 .B E_SYSTEM_ERROR
 The field is the current field.
 .TP 5
 .B E_SYSTEM_ERROR

-System error occurred (see \fBerrno\fR(3)).
-.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.
+System error occurred (see \fBerrno\fP(3)).

 .SH PORTABILITY
 These routines emulate the System V forms library.
 They were not supported on
 .SH PORTABILITY
 These routines emulate the System V forms library.
 They were not supported on


@@ -142,3 +157,7 @@ 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.

+.SH SEE ALSO
+\fB\%curses\fP(3X),
+\fB\%form\fP(3X),
+\fB\%form_field_validation\fP(3X)