1.\" $NetBSD: form_fieldtype.3,v 1.6 2002/10/01 19:15:16 wiz Exp $ 2.\" 3.\" Copyright (c) 2001 4.\" Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au 5.\" 6.\" This code is donated to The NetBSD Foundation by the author. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 3. The name of the Author may not be used to endorse or promote 17.\" products derived from this software without specific prior written 18.\" permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.Dd January 1, 2001 33.Dt FORMS 3 34.Os 35.Sh NAME 36.Nm free_fieldtype , 37.Nm link_fieldtype , 38.Nm new_fieldtype , 39.Nm set_fieldtype_arg , 40.Nm set_fieldtype_choice 41.Nd form library 42.Sh LIBRARY 43.Lb libform 44.Sh SYNOPSIS 45.Fd #include \*[Lt]form.h\*[Gt] 46.Ft int 47.Fn free_fieldtype "FIELDTYPE *fieldtype" 48.Ft FIELDTYPE * 49.Fn link_fieldtype "FIELDTYPE *type1" "FIELDTYPE *type2" 50.Ft FIELDTYPE * 51.Fo new_fieldtype 52.Fa "int (*field_check)(FIELD *, char *)" 53.Fa "int (*char_check)(int, char *)" 54.Fc 55.Ft int 56.Fo "set_fieldtype_arg" 57.Fa "FIELDTYPE *fieldtype" 58.Fa "char * (*make_args)(va_list *)" 59.Fa "char * (*copy_args)(char *)" 60.Fa "void (*free_args)(char *)" 61.Fc 62.Ft int 63.Fo set_fieldtype_choice 64.Fa "FIELDTYPE *fieldtype" 65.Fa "int (*next_choice)(FIELD *, char *)" 66.Fa "int (*prev_choice)(FIELD *, char *)" 67.Fc 68.Sh DESCRIPTION 69The function 70.Fn free_fieldtype 71frees the storage associated with the field type and destroys it. 72The function 73.Fn link_fieldtype 74links together the two given field types to produce a new field type. 75A new field type can be created by calling 76.Fn new_fieldtype 77which requires pointers to two functions which perform validation, the 78.Fa field_check 79function must validate the field contents and return TRUE if they are 80acceptable and FALSE if they are not. 81The 82.Fa char_check 83validates the character input into the field, this function will be 84called for each character entered, if the character can be entered 85into the field then 86.Fa char_check 87must return TRUE. 88Neither 89.Fa field_check 90nor 91.Fa char_check 92may be NULL. 93The functions for handling the field type arguments can 94be defined by using the 95.Fn set_fieldtype_arg 96function, the 97.Fa make_args 98function is used to create new arguments for the fieldtype, the 99.Fa copy_args 100is used to copy the fieldtype arguments to a new arguments structure 101and 102.Fa free_args 103is used to destroy the fieldtype arguments and release any associated 104storage, none of these function pointers may be NULL. 105The field type choice functions can be set by calling 106.Fn set_fieldtype_choice , 107the 108.Fa next_choice 109and 110.Fa prev_choice 111specify the next and previous choice functions for the field type. 112These functions must perform the necessary actions to select the next 113or previous choice for the field, updating the field buffer if 114necessary. 115The choice functions must return TRUE if the function 116succeeded and FALSE otherwise. 117.Sh RETURN VALUES 118Functions returning pointers will return NULL if an error is detected. 119The functions that return an int will return one of the following error 120values: 121.Pp 122.Bl -tag -width E_UNKNOWN_COMMAND -compact 123.It Er E_OK 124The function was successful. 125.It Er E_BAD_ARGUMENT 126The function was passed a bad argument. 127.It Er E_CONNECTED 128The field is connected to a form. 129.El 130.Sh SEE ALSO 131.Xr curses 3 , 132.Xr forms 3 133.Sh NOTES 134The header 135.Pa \*[Lt]form.h\*[Gt] 136automatically includes both 137.Pa \*[Lt]curses.h\*[Gt] 138and 139.Pa \*[Lt]eti.h\*[Gt] . 140