b5f269b5e781bf2f3653b7d514ad13cf57d6824a
[ncurses.git] / man / form_driver.3x
1 .'" $Id: form_driver.3x,v 0.5 1997/12/14 01:26:33 tom Exp $
2 .TH form_driver 3X ""
3 .SH NAME
4 \fBform_driver\fR - command-processing loop of the form system
5 .SH SYNOPSIS
6 \fB#include <form.h>\fR
7 .br
8 int form_driver(FORM *form, int c);
9 .br
10 .SH DESCRIPTION
11 Once a form has been posted (displayed), you should funnel input events to it
12 through \fBform_driver\fR.  This routine has two major input cases; either
13 the input is a form navigation request or it's a printable ASCII character.
14 The form driver requests are as follows:
15 .TP 5
16 REQ_NEXT_PAGE
17 Move to the next page.
18 .TP 5
19 REQ_PREV_PAGE
20 Move to the previous page.
21 .TP 5
22 REQ_FIRST_PAGE
23 Move to the first page.
24 .TP 5
25 REQ_LAST_PAGE
26 Move to the last field.
27
28 .TP 5
29 REQ_NEXT_FIELD
30 Move to the next field.
31 .TP 5
32 REQ_PREV_FIELD
33 Move to the previous field.
34 .TP 5
35 REQ_FIRST_FIELD
36 Move to the first field.
37 .TP 5
38 REQ_LAST_FIELD
39 Move to the last field.
40 .TP 5
41 REQ_SNEXT_FIELD
42 Move to the sorted next field.
43 .TP 5
44 REQ_SPREV_FIELD
45 Move to the sorted previous field.
46 .TP 5
47 REQ_SFIRST_FIELD
48 Move to the sorted first field.
49 .TP 5
50 REQ_SLAST_FIELD
51 Move to the sorted last field.
52 .TP 5
53 REQ_LEFT_FIELD
54 Move left to a field.
55 .TP 5
56 REQ_RIGHT_FIELD
57 Move right to a field.
58 .TP 5
59 REQ_UP_FIELD
60 Move up to a field.
61 .TP 5
62 REQ_DOWN_FIELD
63 Move down to a field.
64
65 .TP 5
66 REQ_NEXT_CHAR
67 Move to the next char.
68 .TP 5
69 REQ_PREV_CHAR
70 Move to the previous char.
71 .TP 5
72 REQ_NEXT_LINE
73 Move to the next line.
74 .TP 5
75 REQ_PREV_LINE
76 Move to the previous line.
77 .TP 5
78 REQ_NEXT_WORD
79 Move to the next word.
80 .TP 5
81 REQ_PREV_WORD
82 Move to the previous word.
83 .TP 5
84 REQ_BEG_FIELD
85 Move to the beginning of the field.
86 .TP 5
87 REQ_END_FIELD
88 Move to the end of the field.
89 .TP 5
90 REQ_BEG_LINE
91 Move to the beginning of the line.
92 .TP 5
93 REQ_END_LINE
94 Move to the end of the line.
95 .TP 5
96 REQ_LEFT_CHAR
97 Move left in the field.
98 .TP 5
99 REQ_RIGHT_CHAR
100 Move right in the field.
101 .TP 5
102 REQ_UP_CHAR
103 Move up in the field.
104 .TP 5
105 REQ_DOWN_CHAR
106 Move down in the field.
107
108 .TP 5
109 REQ_NEW_LINE
110 Insert or overlay a new line.
111 .TP 5
112 REQ_INS_CHAR
113 Insert a blank at the cursor.
114 .TP 5
115 REQ_INS_LINE
116 Insert a blank line at the cursor.
117 .TP 5
118 REQ_DEL_CHAR
119 Delete character at the cursor.
120 .TP 5
121 REQ_DEL_PREV
122 Delete character before the cursor.
123 .TP 5
124 REQ_DEL_LINE
125 Delete line at the cursor.
126 .TP 5
127 REQ_DEL_WORD
128 Delete blank-delimited word at the cursor.
129 .TP 5
130 REQ_CLR_EOL
131 Clear to end of line from cursor.
132 .TP 5
133 REQ_CLR_EOF
134 Clear to end of field from cursor.
135 .TP 5
136 REQ_CLR_FIELD
137 Clear the entire field.
138 .TP 5
139 REQ_OVL_MODE
140 Enter overlay mode.
141 .TP 5
142 REQ_INS_MODE
143 Enter insert mode.
144
145 .TP 5
146 REQ_SCR_FLINE
147 Scroll the field forward a line.
148 .TP 5
149 REQ_SCR_BLINE
150 Scroll the field backward a line.
151 .TP 5
152 REQ_SCR_FPAGE
153 Scroll the field forward a page.
154 .TP 5
155 REQ_SCR_BPAGE
156 Scroll the field backward a page.
157 .TP 5
158 REQ_SCR_FHPAGE
159 Scroll the field forward half a page.
160 .TP 5
161 REQ_SCR_BHPAGE
162 Scroll the field backward half a page.
163
164 .TP 5
165 REQ_SCR_FCHAR
166 Scroll the field forward a character.
167 .TP 5
168 REQ_SCR_BCHAR
169 Scroll the field backward a character.
170 .TP 5
171 REQ_SCR_HFLINE
172 Horizontal scroll the field forward a line.
173 .TP 5
174 REQ_SCR_HBLINE
175 Horizontal scroll the field backward a line.
176 .TP 5
177 REQ_SCR_HFHALF
178 Horizontal scroll the field forward half a line.
179 .TP 5
180 REQ_SCR_HBHALF
181 Horizontal scroll the field backward half a line.
182
183 .TP
184 REQ_VALIDATION
185 Validate field.
186 .TP
187 REQ_NEXT_CHOICE
188 Display next field choice.
189 .TP
190 REQ_PREV_CHOICE
191 Display previous field choice.
192 .PP
193 If the second argument is a printable ASCII character, the driver places it
194 in the current position in the current field.  If it is one of the forms
195 requests listed above, that request is executed.
196 .PP
197 If the second argument is neither printable ASCII nor one of the above
198 pre-defined form requests, the drive assumes it is an application-specific
199 command and returns \fBE_UNKNOWN_COMMAND\fR.  Application-defined commands
200 should be defined relative to \fBMAX_COMMAND\fR, the maximum value of these
201 pre-defined requests.
202 .SH RETURN VALUE
203 \fBform_driver\fR return one of the following error codes:
204 .TP 5
205 \fBE_OK\fR
206 The routine succeeded.
207 .TP 5
208 \fBE_SYSTEM_ERROR\fR
209 System error occurred (see \fBerrno\fR).
210 .TP 5
211 \fBE_BAD_ARGUMENT\fR
212 Routine detected an incorrect or out-of-range argument.
213 .TP 5
214 \fBE_BAD_STATE\fR
215 Routine was called from an initialization or termination function.
216 .TP 5
217 \fBE_NOT_POSTED\fR
218 The form has not been posted.
219 .TP 5
220 \fBE_UNKNOWN_COMMAND\fR
221 The form driver code saw an unknown request code.
222 .TP 5
223 \fBE_INVALID_FIELD\fR
224 Contents of field is invalid.
225 .TP 5
226 \fBE_REQUEST_DENIED\fR
227 The form driver could not process the request.
228 .SH SEE ALSO
229 \fBcurses\fR(3X), \fBform\fR(3X).
230 .SH NOTES
231 The header file \fB<form.h>\fR automatically includes the header files
232 \fB<curses.h>\fR.
233 .SH PORTABILITY
234 These routines emulate the System V forms library.  They were not supported on
235 Version 7 or BSD versions.
236 .SH AUTHORS
237 Juergen Pfeifer.  Manual pages and adaptation for new curses by Eric
238 S. Raymond.
239 .\"#
240 .\"# The following sets edit modes for GNU EMACS
241 .\"# Local Variables:
242 .\"# mode:nroff
243 .\"# fill-column:79
244 .\"# End: