man/form_driver.3x

   1 .\"***************************************************************************
   2 .\" Copyright (c) 1998-2002,2006 Free Software Foundation, Inc.              *
   3 .\"                                                                          *
   4 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
   5 .\" copy of this software and associated documentation files (the            *
   6 .\" "Software"), to deal in the Software without restriction, including      *
   7 .\" without limitation the rights to use, copy, modify, merge, publish,      *
   8 .\" distribute, distribute with modifications, sublicense, and/or sell       *
   9 .\" copies of the Software, and to permit persons to whom the Software is    *
  10 .\" furnished to do so, subject to the following conditions:                 *
  11 .\"                                                                          *
  12 .\" The above copyright notice and this permission notice shall be included  *
  13 .\" in all copies or substantial portions of the Software.                   *
  14 .\"                                                                          *
  15 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  16 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  17 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  18 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  19 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  20 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  21 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  22 .\"                                                                          *
  23 .\" Except as contained in this notice, the name(s) of the above copyright   *
  24 .\" holders shall not be used in advertising or otherwise to promote the     *
  25 .\" sale, use or other dealings in this Software without prior written       *
  26 .\" authorization.                                                           *
  27 .\"***************************************************************************
  28 .\"
  29 .\" $Id: form_driver.3x,v 1.12 2006/11/04 18:51:00 tom Exp $
  30 .TH form_driver 3X ""
  31 .SH NAME
  32 \fBform_driver\fR - command-processing loop of the form system
  33 .SH SYNOPSIS
  34 \fB#include <form.h>\fR
  35 .br
  36 int form_driver(FORM *form, int c);
  37 .br
  38 .SH DESCRIPTION
  39 Once a form has been posted (displayed), you should funnel input events to it
  40 through \fBform_driver\fR.  This routine has two major input cases; either
  41 the input is a form navigation request or it's a printable ASCII character.
  42 The form driver requests are as follows:
  43 .TP 5
  44 REQ_NEXT_PAGE
  45 Move to the next page.
  46 .TP 5
  47 REQ_PREV_PAGE
  48 Move to the previous page.
  49 .TP 5
  50 REQ_FIRST_PAGE
  51 Move to the first page.
  52 .TP 5
  53 REQ_LAST_PAGE
  54 Move to the last field.
  55 .sp
  56 .TP 5
  57 REQ_NEXT_FIELD
  58 Move to the next field.
  59 .TP 5
  60 REQ_PREV_FIELD
  61 Move to the previous field.
  62 .TP 5
  63 REQ_FIRST_FIELD
  64 Move to the first field.
  65 .TP 5
  66 REQ_LAST_FIELD
  67 Move to the last field.
  68 .TP 5
  69 REQ_SNEXT_FIELD
  70 Move to the sorted next field.
  71 .TP 5
  72 REQ_SPREV_FIELD
  73 Move to the sorted previous field.
  74 .TP 5
  75 REQ_SFIRST_FIELD
  76 Move to the sorted first field.
  77 .TP 5
  78 REQ_SLAST_FIELD
  79 Move to the sorted last field.
  80 .TP 5
  81 REQ_LEFT_FIELD
  82 Move left to a field.
  83 .TP 5
  84 REQ_RIGHT_FIELD
  85 Move right to a field.
  86 .TP 5
  87 REQ_UP_FIELD
  88 Move up to a field.
  89 .TP 5
  90 REQ_DOWN_FIELD
  91 Move down to a field.
  92 .sp
  93 .TP 5
  94 REQ_NEXT_CHAR
  95 Move to the next char.
  96 .TP 5
  97 REQ_PREV_CHAR
  98 Move to the previous char.
  99 .TP 5
 100 REQ_NEXT_LINE
 101 Move to the next line.
 102 .TP 5
 103 REQ_PREV_LINE
 104 Move to the previous line.
 105 .TP 5
 106 REQ_NEXT_WORD
 107 Move to the next word.
 108 .TP 5
 109 REQ_PREV_WORD
 110 Move to the previous word.
 111 .TP 5
 112 REQ_BEG_FIELD
 113 Move to the beginning of the field.
 114 .TP 5
 115 REQ_END_FIELD
 116 Move to the end of the field.
 117 .TP 5
 118 REQ_BEG_LINE
 119 Move to the beginning of the line.
 120 .TP 5
 121 REQ_END_LINE
 122 Move to the end of the line.
 123 .TP 5
 124 REQ_LEFT_CHAR
 125 Move left in the field.
 126 .TP 5
 127 REQ_RIGHT_CHAR
 128 Move right in the field.
 129 .TP 5
 130 REQ_UP_CHAR
 131 Move up in the field.
 132 .TP 5
 133 REQ_DOWN_CHAR
 134 Move down in the field.
 135 .sp
 136 .TP 5
 137 REQ_NEW_LINE
 138 Insert or overlay a new line.
 139 .TP 5
 140 REQ_INS_CHAR
 141 Insert a blank at the cursor.
 142 .TP 5
 143 REQ_INS_LINE
 144 Insert a blank line at the cursor.
 145 .TP 5
 146 REQ_DEL_CHAR
 147 Delete character at the cursor.
 148 .TP 5
 149 REQ_DEL_PREV
 150 Delete character before the cursor.
 151 .TP 5
 152 REQ_DEL_LINE
 153 Delete line at the cursor.
 154 .TP 5
 155 REQ_DEL_WORD
 156 Delete blank-delimited word at the cursor.
 157 .TP 5
 158 REQ_CLR_EOL
 159 Clear to end of line from cursor.
 160 .TP 5
 161 REQ_CLR_EOF
 162 Clear to end of field from cursor.
 163 .TP 5
 164 REQ_CLR_FIELD
 165 Clear the entire field.
 166 .TP 5
 167 REQ_OVL_MODE
 168 Enter overlay mode.
 169 .TP 5
 170 REQ_INS_MODE
 171 Enter insert mode.
 172 .sp
 173 .TP 5
 174 REQ_SCR_FLINE
 175 Scroll the field forward a line.
 176 .TP 5
 177 REQ_SCR_BLINE
 178 Scroll the field backward a line.
 179 .TP 5
 180 REQ_SCR_FPAGE
 181 Scroll the field forward a page.
 182 .TP 5
 183 REQ_SCR_BPAGE
 184 Scroll the field backward a page.
 185 .TP 5
 186 REQ_SCR_FHPAGE
 187 Scroll the field forward half a page.
 188 .TP 5
 189 REQ_SCR_BHPAGE
 190 Scroll the field backward half a page.
 191 .sp
 192 .TP 5
 193 REQ_SCR_FCHAR
 194 Scroll the field forward a character.
 195 .TP 5
 196 REQ_SCR_BCHAR
 197 Scroll the field backward a character.
 198 .TP 5
 199 REQ_SCR_HFLINE
 200 Horizontal scroll the field forward a line.
 201 .TP 5
 202 REQ_SCR_HBLINE
 203 Horizontal scroll the field backward a line.
 204 .TP 5
 205 REQ_SCR_HFHALF
 206 Horizontal scroll the field forward half a line.
 207 .TP 5
 208 REQ_SCR_HBHALF
 209 Horizontal scroll the field backward half a line.
 210 .sp
 211 .TP
 212 REQ_VALIDATION
 213 Validate field.
 214 .TP
 215 REQ_NEXT_CHOICE
 216 Display next field choice.
 217 .TP
 218 REQ_PREV_CHOICE
 219 Display previous field choice.
 220 .PP
 221 If the second argument is a printable ASCII character, the driver places it
 222 in the current position in the current field.  If it is one of the forms
 223 requests listed above, that request is executed.
 224 .PP
 225 If the second argument is neither printable ASCII nor one of the above
 226 pre-defined form requests, the driver assumes it is an application-specific
 227 command and returns \fBE_UNKNOWN_COMMAND\fR.  Application-defined commands
 228 should be defined relative to \fBMAX_COMMAND\fR, the maximum value of these
 229 pre-defined requests.
 230 .SH RETURN VALUE
 231 \fBform_driver\fR returns one of the following error codes:
 232 .TP 5
 233 .B E_OK
 234 The routine succeeded.
 235 .TP 5
 236 .B E_BAD_ARGUMENT
 237 Routine detected an incorrect or out-of-range argument.
 238 .TP 5
 239 .B E_BAD_STATE
 240 Routine was called from an initialization or termination function.
 241 .TP 5
 242 .B E_NOT_POSTED
 243 The form has not been posted.
 244 .TP 5
 245 .B E_INVALID_FIELD
 246 Contents of field is invalid.
 247 .TP 5
 248 .B E_REQUEST_DENIED
 249 The form driver could not process the request.
 250 .TP 5
 251 .B E_SYSTEM_ERROR
 252 System error occurred (see \fBerrno\fR).
 253 .TP 5
 254 .B E_UNKNOWN_COMMAND
 255 The form driver code saw an unknown request code.
 256 .
 257 .SH SEE ALSO
 258 \fBcurses\fR(3X), \fBform\fR(3X).
 259 .SH NOTES
 260 The header file \fB<form.h>\fR automatically includes the header files
 261 \fB<curses.h>\fR.
 262 .SH PORTABILITY
 263 These routines emulate the System V forms library.  They were not supported on
 264 Version 7 or BSD versions.
 265 .SH AUTHORS
 266 Juergen Pfeifer.  Manual pages and adaptation for new curses by Eric
 267 S. Raymond.
 268 .\"#
 269 .\"# The following sets edit modes for GNU EMACS
 270 .\"# Local Variables:
 271 .\"# mode:nroff
 272 .\"# fill-column:79
 273 .\"# End: