1.\" $NetBSD: form_driver.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 form_driver 37.Nd form library 38.Sh LIBRARY 39.Lb libform 40.Sh SYNOPSIS 41.In form.h 42.Ft int 43.Fn form_driver "FORM *form" "int request" 44.Sh DESCRIPTION 45The 46.Fn form_driver 47is the heart of the forms library, it takes commands in the 48.Fa request 49parameter that is either a request to the driver to perform some 50action or is a character to be inserted into the current field. 51The form driver will attempt to insert any printable character passed to 52it into the current field. 53This may or may not succeed depending on the state of the current field. 54If the character passed is not 55printable then the driver attempts to process it as a driver request. 56If the character passed is not a valid request then the driver will 57return an unknown command error. 58.Sh PARAMETERS 59The forms driver recognizes the following requests: 60.Pp 61.Bl -tag -width REQ_SFIRST_FIELD -compact 62.It REQ_NEXT_PAGE 63Change to the next page in the form. 64.It REQ_PREV_PAGE 65Change to the previous page in the form. 66.It REQ_FIRST_PAGE 67Select the first page in the form. 68.It REQ_LAST_PAGE 69Go to the last page in the form. 70.It REQ_NEXT_FIELD 71Move to the next field in the form field array. 72.It REQ_PREV_FIELD 73Move to the previous field in the form field array. 74.It REQ_FIRST_FIELD 75Go to the first field in the form field array. 76.It REQ_LAST_FIELD 77Go to the last field in the form field array. 78.It REQ_SNEXT_FIELD 79Move to the next sorted field on the form. 80.It REQ_SPREV_FIELD 81Move to the previous sorted field on the form. 82.It REQ_SFIRST_FIELD 83Go to the first field in the sorted list. 84.It REQ_SLAST_FIELD 85Move to the last field in the sorted list. 86.It REQ_LEFT_FIELD 87Go one field to the left on the form page. 88.It REQ_RIGHT_FIELD 89Go one field to the right on the form page. 90.It REQ_UP_FIELD 91Go up one field on the form page. 92.It REQ_DOWN_FIELD 93Go down one field on the form page. 94.It REQ_NEXT_CHAR 95Move one char to the right within the field 96.It REQ_PREV_CHAR 97Move one char to the left within the current field. 98.It REQ_NEXT_LINE 99Go down one line in the current field. 100.It REQ_PREV_LINE 101Go up one line in the current field. 102.It REQ_NEXT_WORD 103Go forward one word in the current field 104.It REQ_PREV_WORD 105Go backward one word in the current field. 106.It REQ_BEG_FIELD 107Move the cursor to the beginning of the current field. 108.It REQ_END_FIELD 109Move the cursor to the end of the current field. 110.It REQ_BEG_LINE 111Move the cursor to the beginning of the line in the current field. 112.It REQ_END_LINE 113Move the cursor to the end of the line. 114.It REQ_LEFT_CHAR 115Move the cursor left one character 116.It REQ_RIGHT_CHAR 117Move the cursor right one character 118.It REQ_UP_CHAR 119Move the cursor up one line. 120.It REQ_DOWN_CHAR 121Move the cursor down one line. 122.It REQ_NEW_LINE 123Insert a new line at the current cursor position. 124.It REQ_INS_CHAR 125Insert a blank character at the current cursor position 126.It REQ_INS_LINE 127Open a blank line at the current cursor position. 128.It REQ_DEL_CHAR 129Delete the character at the current cursor position. 130.It REQ_DEL_PREV 131Delete the character to the left of the current cursor position. 132.It REQ_DEL_LINE 133Delete the current line. 134.It REQ_DEL_WORD 135Delete the word at the current cursor position. 136.It REQ_CLR_EOL 137Clear the field from the current cursor position to the end of the 138current line. 139.It REQ_CLR_EOF 140Clear the field from the current cursor position to the end of the field. 141.It REQ_CLR_FIELD 142Clear the field. 143.It REQ_OVL_MODE 144Enter overlay mode, characters added to the field will replace the 145ones already there. 146.It REQ_INS_MODE 147Enter insert mode, characters will be inserted at the current cursor 148position. 149Any characters to the right of the cursor will be moved 150right to accommodate the new characters. 151.It REQ_SCR_FLINE 152Scroll the field forward one line. 153.It REQ_SCR_BLINE 154Scroll the field backward one line. 155.It REQ_SCR_FPAGE 156Scroll the field forward one field page. 157.It REQ_SCR_BPAGE 158Scroll the field backward one field page. 159.It REQ_SCR_FHPAGE 160Scroll the field forward half one field page. 161.It REQ_SCR_BHPAGE 162Scroll the field backward half one field page. 163.It REQ_SCR_FCHAR 164Scroll the field horizontally forward one character 165.It REQ_SCR_BCHAR 166Scroll the field horizontally backward one character 167.It REQ_SCR_HFLINE 168Scroll the field horizontally forward one field line. 169.It REQ_SCR_HBLINE 170Scroll the field horizontally backward one field line. 171.It REQ_SCR_HFHALF 172Scroll the field horizontally forward half a field line. 173.It REQ_SCR_HBHALF 174Scroll the field horizontally backward half a field line. 175.It REQ_VALIDATION 176Request the contents of the current field be validated using any field 177validation function that has been set for the field. 178Normally, the field is validated before the current field changes. 179This request allows the current field to be validated. 180.It REQ_PREV_CHOICE 181Select the previous choice in an enumerated type field. 182.It REQ_NEXT_CHOICE 183Select the next choice in an enumerated type field. 184.El 185.Sh RETURN VALUES 186Functions returning pointers will return 187.Dv NULL 188if an error is detected. 189The functions that return an int will return one of the following error 190values: 191.Pp 192.Bl -tag -width E_UNKNOWN_COMMAND -compact 193.It Er E_OK 194The function was successful. 195.It Er E_REQUEST_DENIED 196The forms driver request could not be fulfilled 197.It Er E_UNKNOWN_COMMAND 198The passed character is not a printable character and is not a valid 199forms driver request. 200.It Er E_BAD_ARGUMENT 201A bad argument was passed to the forms driver. 202.It Er E_INVALID_FIELD 203The form passed to the driver has no valid attached fields. 204.It Er E_NOT_POSTED 205The given form is not currently posted to the screen. 206.It Er E_BAD_STATE 207The forms driver was called from within an init or term function. 208.It Er E_INVALID_FIELD 209The character passed to the forms driver fails the character 210validation for the current field. 211.El 212.Sh SEE ALSO 213.Xr curses 3 , 214.Xr forms 3 215.Sh NOTES 216Field sorting is done by location of the field on the form page, the 217fields are sorted by position starting with the top-most, left-most 218field and progressing left to right. 219For the purposes of sorting, the 220fields top left corner is used as the sort criteria. 221The header 222.In form.h 223automatically includes both 224.In curses.h 225and 226.In eti.h . 227