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