1.\" $NetBSD: form_fieldtype.3,v 1.4 2002/02/20 11:30:58 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. The 72function 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. The 81.Fa char_check 82validates the character input into the field, this function will be 83called for each character entered, if the character can be entered 84into the field then 85.Fa char_check 86must return TRUE. Neither 87.Fa field_check 88nor 89.Fa char_check 90may be NULL. The functions for handling the field type arguments can 91be defined by using the 92.Fn set_fieldtype_arg 93function, the 94.Fa make_args 95function is used to create new arguments for the fieldtype, the 96.Fa copy_args 97is used to copy the fieldtype arguments to a new arguments structure 98and 99.Fa free_args 100is used to destroy the fieldtype arguments and release any associated 101storage, none of these function pointers may be NULL. The field type 102choice functions can be set by calling 103.Fn set_fieldtype_choice , 104the 105.Fa next_choice 106and 107.Fa prev_choice 108specify the next and previous choice functions for the field type. 109These functions must perform the necessary actions to select the next 110or previous choice for the field, updating the field buffer if 111necessary. The choice functions must return TRUE if the function 112succeeded and FALSE otherwise. 113.Sh RETURN VALUES 114Functions returning pointers will return NULL if an error is detected. 115The functions that return an int will return one of the following error 116values: 117.Pp 118.Bl -tag -width E_UNKNOWN_COMMAND -compact 119.It Er E_OK 120The function was successful. 121.It Er E_BAD_ARGUMENT 122The function was passed a bad argument. 123.It Er E_CONNECTED 124The field is connected to a form. 125.El 126.Sh SEE ALSO 127.Xr curses 3 , 128.Xr forms 3 129.Sh NOTES 130The header 131.Pa \*[Lt]form.h\*[Gt] 132automatically includes both 133.Pa \*[Lt]curses.h\*[Gt] 134and 135.Pa \*[Lt]eti.h\*[Gt] . 136