lib/libform/form_driver.3

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