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