1form_driver(3X)                                                form_driver(3X)
2
3
4

NAME

6       form_driver - command-processing loop of the form system
7

SYNOPSIS

9       #include <form.h>
10       int form_driver(FORM *form, int c);
11

DESCRIPTION

13       Once a form has been posted (displayed), you should funnel input events
14       to it through form_driver.  This routine has three major input cases:
15
16       -  The input is a form navigation request.   Navigation  request  codes
17          are  constants defined in <form.h>, which are distinct from the key-
18          and character codes returned by wgetch.
19
20       -  The input is a printable  character.   Printable  characters  (which
21          must  be  positive, less than 256) are checked according to the pro‐
22          gram's locale settings.
23
24       -  The input is the KEY_MOUSE special  key  associated  with  an  mouse
25          event.
26
27       The form driver requests are as follows:
28
29       REQ_NEXT_PAGE
30            Move to the next page.
31
32       REQ_PREV_PAGE
33            Move to the previous page.
34
35       REQ_FIRST_PAGE
36            Move to the first page.
37
38       REQ_LAST_PAGE
39            Move to the last field.
40
41
42       REQ_NEXT_FIELD
43            Move to the next field.
44
45       REQ_PREV_FIELD
46            Move to the previous field.
47
48       REQ_FIRST_FIELD
49            Move to the first field.
50
51       REQ_LAST_FIELD
52            Move to the last field.
53
54       REQ_SNEXT_FIELD
55            Move to the sorted next field.
56
57       REQ_SPREV_FIELD
58            Move to the sorted previous field.
59
60       REQ_SFIRST_FIELD
61            Move to the sorted first field.
62
63       REQ_SLAST_FIELD
64            Move to the sorted last field.
65
66       REQ_LEFT_FIELD
67            Move left to a field.
68
69       REQ_RIGHT_FIELD
70            Move right to a field.
71
72       REQ_UP_FIELD
73            Move up to a field.
74
75       REQ_DOWN_FIELD
76            Move down to a field.
77
78
79       REQ_NEXT_CHAR
80            Move to the next char.
81
82       REQ_PREV_CHAR
83            Move to the previous char.
84
85       REQ_NEXT_LINE
86            Move to the next line.
87
88       REQ_PREV_LINE
89            Move to the previous line.
90
91       REQ_NEXT_WORD
92            Move to the next word.
93
94       REQ_PREV_WORD
95            Move to the previous word.
96
97       REQ_BEG_FIELD
98            Move to the beginning of the field.
99
100       REQ_END_FIELD
101            Move to the end of the field.
102
103       REQ_BEG_LINE
104            Move to the beginning of the line.
105
106       REQ_END_LINE
107            Move to the end of the line.
108
109       REQ_LEFT_CHAR
110            Move left in the field.
111
112       REQ_RIGHT_CHAR
113            Move right in the field.
114
115       REQ_UP_CHAR
116            Move up in the field.
117
118       REQ_DOWN_CHAR
119            Move down in the field.
120
121
122       REQ_NEW_LINE
123            Insert or overlay a new line.
124
125       REQ_INS_CHAR
126            Insert a blank at the cursor.
127
128       REQ_INS_LINE
129            Insert a blank line at the cursor.
130
131       REQ_DEL_CHAR
132            Delete character at the cursor.
133
134       REQ_DEL_PREV
135            Delete character before the cursor.
136
137       REQ_DEL_LINE
138            Delete line at the cursor.
139
140       REQ_DEL_WORD
141            Delete blank-delimited word at the cursor.
142
143       REQ_CLR_EOL
144            Clear to end of line from cursor.
145
146       REQ_CLR_EOF
147            Clear to end of field from cursor.
148
149       REQ_CLR_FIELD
150            Clear the entire field.
151
152       REQ_OVL_MODE
153            Enter overlay mode.
154
155       REQ_INS_MODE
156            Enter insert mode.
157
158
159       REQ_SCR_FLINE
160            Scroll the field forward a line.
161
162       REQ_SCR_BLINE
163            Scroll the field backward a line.
164
165       REQ_SCR_FPAGE
166            Scroll the field forward a page.
167
168       REQ_SCR_BPAGE
169            Scroll the field backward a page.
170
171       REQ_SCR_FHPAGE
172            Scroll the field forward half a page.
173
174       REQ_SCR_BHPAGE
175            Scroll the field backward half a page.
176
177
178       REQ_SCR_FCHAR
179            Scroll the field forward a character.
180
181       REQ_SCR_BCHAR
182            Scroll the field backward a character.
183
184       REQ_SCR_HFLINE
185            Horizontal scroll the field forward a line.
186
187       REQ_SCR_HBLINE
188            Horizontal scroll the field backward a line.
189
190       REQ_SCR_HFHALF
191            Horizontal scroll the field forward half a line.
192
193       REQ_SCR_HBHALF
194            Horizontal scroll the field backward half a line.
195
196
197       REQ_VALIDATION
198            Validate field.
199
200       REQ_NEXT_CHOICE
201            Display next field choice.
202
203       REQ_PREV_CHOICE
204            Display previous field choice.
205
206       If  the  second argument is a printable character, the driver places it
207       in the current position in the current field.  If  it  is  one  of  the
208       forms requests listed above, that request is executed.
209
210   MOUSE HANDLING
211       If  the  second  argument  is the KEY_MOUSE special key, the associated
212       mouse event is translated into one of the above  pre-defined  requests.
213       Currently  only clicks in the user window (e.g. inside the form display
214       area or the decoration window) are handled.
215
216       If you click above the display region of the form:
217
218              a REQ_PREV_FIELD is generated for a single click,
219
220              a REQ_PREV_PAGE is generated for a double-click and
221
222              a REQ_FIRST_FIELD is generated for a triple-click.
223
224       If you click below the display region of the form:
225
226              a REQ_NEXT_FIELD is generated for a single click,
227
228              a REQ_NEXT_PAGE is generated for a double-click and
229
230              a REQ_LAST_FIELD is generated for a triple-click.
231
232       If you click at an field inside the display area of the form:
233
234              -  the form cursor is positioned to that field.
235
236              -  If you double-click a field, the form cursor is positioned to
237                 that  field  and  E_UNKNOWN_COMMAND is returned.  This return
238                 value makes sense, because a double click usually means  that
239                 an  field-specific  action should be returned.  It is exactly
240                 the purpose of this return value to signal that  an  applica‐
241                 tion specific command should be executed.
242
243              -  If a translation into a request was done, form_driver returns
244                 the result of this request.
245
246       If you clicked outside the user window or the mouse event could not  be
247       translated into a form request an E_REQUEST_DENIED is returned.
248
249   APPLICATION-DEFINED COMMANDS
250       If  the  second argument is neither printable nor one of the above pre-
251       defined form requests, the driver assumes it is an application-specific
252       command  and  returns  E_UNKNOWN_COMMAND.  Application-defined commands
253       should be defined relative to MAX_COMMAND, the maximum value  of  these
254       pre-defined requests.
255

RETURN VALUE

257       form_driver returns one of the following error codes:
258
259       E_OK The routine succeeded.
260
261       E_BAD_ARGUMENT
262            Routine detected an incorrect or out-of-range argument.
263
264       E_BAD_STATE
265            Routine was called from an initialization or termination function.
266
267       E_NOT_POSTED
268            The form has not been posted.
269
270       E_INVALID_FIELD
271            Contents of field is invalid.
272
273       E_REQUEST_DENIED
274            The form driver could not process the request.
275
276       E_SYSTEM_ERROR
277            System error occurred (see errno).
278
279       E_UNKNOWN_COMMAND
280            The form driver code saw an unknown request code.
281

SEE ALSO

283       curses(3X), form(3X), wgetch(3X).
284

NOTES

286       The  header  file  <form.h>  automatically  includes  the  header files
287       <curses.h>.
288

PORTABILITY

290       These routines emulate the System V forms library.  They were not  sup‐
291       ported on Version 7 or BSD versions.
292

AUTHORS

294       Juergen Pfeifer.  Manual pages and adaptation for new curses by Eric S.
295       Raymond.
296
297
298
299                                                               form_driver(3X)
Impressum