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

NAME

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

SYNOPSIS

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

DESCRIPTION

14   form_driver
15       Once a form has been posted (displayed), you should funnel input events
16       to it through form_driver.  This routine has three major input cases:
17
18       ·   The input is a form navigation request.  Navigation  request  codes
19           are constants defined in <form.h>, which are distinct from the key-
20           and character codes returned by wgetch(3X).
21
22       ·   The input is a printable character.   Printable  characters  (which
23           must  be positive, less than 256) are checked according to the pro‐
24           gram's locale settings.
25
26       ·   The input is the KEY_MOUSE special key  associated  with  an  mouse
27           event.
28
29   form_driver_w
30       This extension simplifies the use of the forms library using wide char‐
31       acters.  The input is either a key code (a request) or a wide character
32       returned  by  get_wch(3X).   The type must be passed as well, to enable
33       the library to determine whether the parameter is a wide character or a
34       request.
35
36   Form-driver requests
37       The form driver requests are as follows:
38
39       Name               Description
40       ─────────────────────────────────────────────────────────────────────
41       REQ_BEG_FIELD      Move to the beginning of the field.
42       REQ_BEG_LINE       Move to the beginning of the line.
43       REQ_CLR_EOF        Clear to end of field from cursor.
44       REQ_CLR_EOL        Clear to end of line from cursor.
45       REQ_CLR_FIELD      Clear the entire field.
46       REQ_DEL_CHAR       Delete character at the cursor.
47       REQ_DEL_LINE       Delete line at the cursor.
48       REQ_DEL_PREV       Delete character before the cursor.
49       REQ_DEL_WORD       Delete blank-delimited word at the cursor.
50       REQ_DOWN_CHAR      Move down in the field.
51       REQ_DOWN_FIELD     Move down to a field.
52       REQ_END_FIELD      Move to the end of the field.
53       REQ_END_LINE       Move to the end of the line.
54       REQ_FIRST_FIELD    Move to the first field.
55       REQ_FIRST_PAGE     Move to the first page.
56       REQ_INS_CHAR       Insert a blank at the cursor.
57       REQ_INS_LINE       Insert a blank line at the cursor.
58       REQ_INS_MODE       Enter insert mode.
59       REQ_LAST_FIELD     Move to the last field.
60       REQ_LAST_PAGE      Move to the last field.
61       REQ_LEFT_CHAR      Move left in the field.
62       REQ_LEFT_FIELD     Move left to a field.
63       REQ_NEW_LINE       Insert or overlay a new line.
64       REQ_NEXT_CHAR      Move to the next char.
65       REQ_NEXT_CHOICE    Display next field choice.
66
67       REQ_NEXT_FIELD     Move to the next field.
68       REQ_NEXT_LINE      Move to the next line.
69       REQ_NEXT_PAGE      Move to the next page.
70       REQ_NEXT_PAGE      Move to the next page.
71       REQ_NEXT_WORD      Move to the next word.
72       REQ_OVL_MODE       Enter overlay mode.
73       REQ_PREV_CHAR      Move to the previous char.
74       REQ_PREV_CHOICE    Display previous field choice.
75       REQ_PREV_FIELD     Move to the previous field.
76       REQ_PREV_LINE      Move to the previous line.
77       REQ_PREV_PAGE      Move to the previous page.
78       REQ_PREV_WORD      Move to the previous word.
79       REQ_RIGHT_CHAR     Move right in the field.
80       REQ_RIGHT_FIELD    Move right to a field.
81       REQ_SCR_BCHAR      Scroll the field backward a character.
82       REQ_SCR_BHPAGE     Scroll the field backward half a page.
83       REQ_SCR_BLINE      Scroll the field backward a line.
84       REQ_SCR_BPAGE      Scroll the field backward a page.
85       REQ_SCR_FCHAR      Scroll the field forward a character.
86       REQ_SCR_FHPAGE     Scroll the field forward half a page.
87       REQ_SCR_FLINE      Scroll the field forward a line.
88       REQ_SCR_FPAGE      Scroll the field forward a page.
89       REQ_SCR_HBHALF     Horizontal scroll the field backward half a line.
90       REQ_SCR_HBLINE     Horizontal scroll the field backward a line.
91       REQ_SCR_HFHALF     Horizontal scroll the field forward half a line.
92       REQ_SCR_HFLINE     Horizontal scroll the field forward a line.
93       REQ_SFIRST_FIELD   Move to the sorted first field.
94       REQ_SLAST_FIELD    Move to the sorted last field.
95       REQ_SNEXT_FIELD    Move to the sorted next field.
96       REQ_SPREV_FIELD    Move to the sorted previous field.
97       REQ_UP_CHAR        Move up in the field.
98       REQ_UP_FIELD       Move up to a field.
99       REQ_VALIDATION     Validate field.
100
101       If  the  second argument is a printable character, the driver places it
102       in the current position in the current field.  If  it  is  one  of  the
103       forms requests listed above, that request is executed.
104
105   Field validation
106       The  form  library  makes  updates  to  the window associated with form
107       fields rather than directly to the field buffers.
108
109       The form driver provides low-level control over  updates  to  the  form
110       fields.   The  form driver also provides for validating modified fields
111       to ensure that the contents meet whatever  constraints  an  application
112       may attach using set_field_type.
113
114       You  can  validate  a  field  without  making  any  changes to it using
115       REQ_VALIDATION.  The form driver also validates a field in these cases:
116
117       ·   a call to set_current_field attempts to move to a different field.
118
119       ·   a call to set_current_page attempts to move to a different page  of
120           the form.
121
122       ·   a request attempts to move to a different field.
123
124       ·   a request attempts to move to a different page of the form.
125
126       In each case, the move fails if the field is invalid.
127
128       If  the  modified  field  is valid, the form driver copies the modified
129       data from the window associated with the field to the field buffer.
130
131   Mouse handling
132       If the second argument is the KEY_MOUSE  special  key,  the  associated
133       mouse  event  is translated into one of the above pre-defined requests.
134       Currently only clicks in the user window (e.g., inside the form display
135       area or the decoration window) are handled.
136
137       If you click above the display region of the form:
138
139          a REQ_PREV_FIELD is generated for a single click,
140
141          a REQ_PREV_PAGE is generated for a double-click and
142
143          a REQ_FIRST_FIELD is generated for a triple-click.
144
145       If you click below the display region of the form:
146
147          a REQ_NEXT_FIELD is generated for a single click,
148
149          a REQ_NEXT_PAGE is generated for a double-click and
150
151          a REQ_LAST_FIELD is generated for a triple-click.
152
153       If you click at an field inside the display area of the form:
154
155          ·   the form cursor is positioned to that field.
156
157          ·   If  you  double-click  a field, the form cursor is positioned to
158              that field and E_UNKNOWN_COMMAND is returned.  This return value
159              makes sense, because a double click usually means that an field-
160              specific action should be returned.  It is exactly  the  purpose
161              of this return value to signal that an application specific com‐
162              mand should be executed.
163
164          ·   If a translation into a request was  done,  form_driver  returns
165              the result of this request.
166
167       If  you clicked outside the user window or the mouse event could not be
168       translated into a form request an E_REQUEST_DENIED is returned.
169
170   Application-defined commands
171       If the second argument is neither printable nor one of the  above  pre-
172       defined form requests, the driver assumes it is an application-specific
173       command and returns  E_UNKNOWN_COMMAND.   Application-defined  commands
174       should  be  defined relative to MAX_COMMAND, the maximum value of these
175       pre-defined requests.
176

RETURN VALUE

178       form_driver returns one of the following error codes:
179
180       E_OK The routine succeeded.
181
182       E_BAD_ARGUMENT
183            Routine detected an incorrect or out-of-range argument.
184
185       E_BAD_STATE
186            Routine was called from an initialization or termination function.
187
188       E_NOT_POSTED
189            The form has not been posted.
190
191       E_INVALID_FIELD
192            Contents of field is invalid.
193
194       E_REQUEST_DENIED
195            The form driver could not process the request.
196
197       E_SYSTEM_ERROR
198            System error occurred (see errno).
199
200       E_UNKNOWN_COMMAND
201            The form driver code saw an unknown request code.
202

SEE ALSO

204       curses(3X), form(3X), form_field_buffer(3X), form_field_validation(3X),
205       form_fieldtype(3X), form_variables(3X), getch(3X).
206

NOTES

208       The  header  file  <form.h>  automatically  includes  the  header files
209       <curses.h>.
210

PORTABILITY

212       These routines emulate the System V forms library.  They were not  sup‐
213       ported on Version 7 or BSD versions.
214

AUTHORS

216       Juergen Pfeifer.  Manual pages and adaptation for new curses by Eric S.
217       Raymond.
218
219
220
221                                                               form_driver(3X)
Impressum