| '\" t |
| .\"*************************************************************************** |
| .\" Copyright 2018-2019,2020 Thomas E. Dickey * |
| .\" Copyright 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.28 2020/12/12 17:11:21 tom Exp $ |
| .de bP |
| .ie n .IP \(bu 4 |
| .el .IP \(bu 2 |
| .. |
| .TH form_fieldtype 3X "" |
| .SH NAME |
| \fBform_fieldtype\fR \- define validation-field types |
| .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 |
| \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 |
| \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 |
| .SH DESCRIPTION |
| .SS new_fieldtype |
| The function \fBnew_fieldtype\fR creates a new field type usable for data |
| validation. |
| Its parameters are function pointers: |
| .TP 5 |
| \fIfield_check\fR |
| This function checks the |
| 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 |
| field's buffer, sizes and other attributes. |
| .bP |
| The second argument is an |
| argument-block structure, about which more below. |
| .RE |
| .TP 5 |
| \fIchar_check\fR |
| 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 |
| .PP |
| The \fBfree_fieldtype\fR function |
| frees the space allocated for a given validation type by \fBnew_fieldtype\fP. |
| .SS set_fieldtype_arg |
| .PP |
| The function \fBset_fieldtype_arg\fR associates |
| three storage-management functions with a field type: |
| .TP 5 |
| \fImake_arg\fR |
| This function is automatically applied to the |
| list of arguments you give \fBset_field_type\fR 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\fR |
| This function may be used by applications to copy argument-blocks. |
| .TP 5 |
| \fIfree_arg\fR |
| Frees an argument-block structure. |
| .PP |
| You must supply the \fImake_arg\fR function. |
| The other two are optional: you may supply NULL for them. |
| In this case, the form library assumes |
| that \fImake_arg\fR does not allocate memory but simply loads the |
| argument into a single scalar value. |
| .SS set_fieldtype_choice |
| .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 |
| user with a way to move through the set. |
| .PP |
| The \fBset_fieldtype_choice\fR |
| 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 |
| .PP |
| The function \fBlink_fieldtype\fR 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: |
| .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 |
| .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_CONNECTED |
| 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(3)). |
| .SH SEE ALSO |
| \fBcurses\fR(3X), |
| \fBform\fR(3X), |
| \fBform_field_validation\fR(3X). |
| .SH NOTES |
| The header file \fB<form.h>\fR automatically includes the header file |
| \fB<curses.h>\fR. |
| .SH PORTABILITY |
| These routines emulate the System V forms library. |
| They were not supported on |
| Version 7 or BSD versions. |
| .SH AUTHORS |
| Juergen Pfeifer. |
| Manual pages and adaptation for new curses by Eric S. Raymond. |