xref: /netbsd/lib/libform/form.h (revision 30b9da99)
1 /*	$NetBSD: form.h,v 1.23 2015/09/07 15:50:49 joerg Exp $	*/
2 
3 /*-
4  * Copyright (c) 1998-1999 Brett Lymn
5  *               (blymn@baea.com.au, brett_lymn@yahoo.com.au)
6  * All rights reserved.
7  *
8  * This code has been donated to The NetBSD Foundation by the Author.
9  *
10  * Redistribution and use in source and binary forms, with or without
11  * modification, are permitted provided that the following conditions
12  * are met:
13  * 1. Redistributions of source code must retain the above copyright
14  *    notice, this list of conditions and the following disclaimer.
15  * 2. The name of the author may not be used to endorse or promote products
16  *    derived from this software without specific prior written permission
17  *
18  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
19  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
20  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
21  * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
22  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
23  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
24  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
25  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
26  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
27  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28  *
29  *
30  */
31 
32 #ifndef FORM_H
33 #define FORM_H 1
34 #include <sys/queue.h>
35 #include <stdarg.h>
36 #include <curses.h>
37 #include <eti.h>
38 
39 /* Define the types of field justification that can be used. */
40 #define NO_JUSTIFICATION  (0)
41 #define JUSTIFY_RIGHT     (1)
42 #define JUSTIFY_LEFT      (2)
43 #define JUSTIFY_CENTER    (3)
44 
45 /* Define the max and min valid justification styles for range checking */
46 #define MIN_JUST_STYLE    NO_JUSTIFICATION
47 #define MAX_JUST_STYLE    JUSTIFY_CENTER
48 
49 /* Options for the fields */
50 typedef unsigned int Form_Options;
51 
52 /* form options */
53 #define O_BS_OVERLOAD (0x001)
54 #define O_NL_OVERLOAD (0x002)
55 
56 /* field options */
57 #define O_VISIBLE  (0x001)  /* Field is visible */
58 #define O_ACTIVE   (0x002)  /* Field is active in the form */
59 #define O_PUBLIC   (0x004)  /* The contents entered into the field is echoed */
60 #define O_EDIT     (0x008)  /* Can edit the field */
61 #define O_WRAP     (0x010)  /* The field contents can line wrap */
62 #define O_BLANK    (0x020)  /* Blank the field on modification */
63 #define O_AUTOSKIP (0x040)  /* Skip to next field when current is full */
64 #define O_NULLOK   (0x080)  /* Field is allowed to contain no data */
65 #define O_STATIC   (0x100)  /* Field is not dynamic */
66 #define O_PASSOK   (0x200)  /* An umodified field is OK */
67 #define O_REFORMAT (0x400)  /* Insert newlines at linebreaks on buffer get */
68 
69 /*
70  * Form driver requests - be VERY careful about changing the ordering
71  * of the requests below.  The form driver code depends on a particular
72  * order for the requests.
73  */
74 #define REQ_MIN_REQUEST   (KEY_MAX + 0x101) /* must equal value of the
75                                                first request */
76 
77 #define REQ_NEXT_PAGE     (KEY_MAX + 0x101) /* next page in form */
78 #define REQ_PREV_PAGE     (KEY_MAX + 0x102) /* previous page in form */
79 #define REQ_FIRST_PAGE    (KEY_MAX + 0x103) /* goto first page in form */
80 #define REQ_LAST_PAGE     (KEY_MAX + 0x104) /* goto last page in form */
81 
82 #define REQ_NEXT_FIELD    (KEY_MAX + 0x105) /* move to the next field */
83 #define REQ_PREV_FIELD    (KEY_MAX + 0x106) /* move to the previous field */
84 #define REQ_FIRST_FIELD   (KEY_MAX + 0x107) /* goto the first field */
85 #define REQ_LAST_FIELD    (KEY_MAX + 0x108) /* goto the last field */
86 
87 #define REQ_SNEXT_FIELD   (KEY_MAX + 0x109) /* move to the next field
88                                                in sorted order */
89 #define REQ_SPREV_FIELD   (KEY_MAX + 0x10a) /* move to the prev field
90                                                in sorted order */
91 #define REQ_SFIRST_FIELD  (KEY_MAX + 0x10b) /* move to the first
92                                                sorted field */
93 #define REQ_SLAST_FIELD   (KEY_MAX + 0x10c) /* move to the last sorted
94                                                field */
95 
96 #define REQ_LEFT_FIELD    (KEY_MAX + 0x10d) /* go left one field */
97 #define REQ_RIGHT_FIELD   (KEY_MAX + 0x10e) /* go right one field */
98 #define REQ_UP_FIELD      (KEY_MAX + 0x10f) /* go up one field */
99 #define REQ_DOWN_FIELD    (KEY_MAX + 0x110) /* go down one field */
100 
101 #define REQ_NEXT_CHAR     (KEY_MAX + 0x111) /* move to the next char
102                                                in field */
103 #define REQ_PREV_CHAR     (KEY_MAX + 0x112) /* move to the previous
104                                                char in field */
105 #define REQ_NEXT_LINE     (KEY_MAX + 0x113) /* go to the next line in
106                                                the field */
107 #define REQ_PREV_LINE     (KEY_MAX + 0x114) /* go to the previous line
108                                                in the field */
109 #define REQ_NEXT_WORD     (KEY_MAX + 0x115) /* go to the next word in
110                                                the field */
111 #define REQ_PREV_WORD     (KEY_MAX + 0x116) /* go to the previous word
112                                                in the field */
113 #define REQ_BEG_FIELD     (KEY_MAX + 0x117) /* go to the beginning of
114                                                the field */
115 #define REQ_END_FIELD     (KEY_MAX + 0x118) /* go to the end of the field */
116 #define REQ_BEG_LINE      (KEY_MAX + 0x119) /* go to the beginning of
117                                                the line */
118 #define REQ_END_LINE      (KEY_MAX + 0x11a) /* go to the end of the
119                                                line */
120 #define REQ_LEFT_CHAR     (KEY_MAX + 0x11b) /* move left in the field */
121 #define REQ_RIGHT_CHAR    (KEY_MAX + 0x11c) /* move right in the field */
122 #define REQ_UP_CHAR       (KEY_MAX + 0x11d) /* move up in the field */
123 #define REQ_DOWN_CHAR     (KEY_MAX + 0x11e) /* move down in the field */
124 
125 #define REQ_NEW_LINE      (KEY_MAX + 0x11f) /* insert/overlay a new line */
126 #define REQ_INS_CHAR      (KEY_MAX + 0x120) /* insert a blank char at
127                                                the cursor */
128 #define REQ_INS_LINE      (KEY_MAX + 0x121) /* insert a blank line at
129                                                the cursor */
130 
131 #define REQ_DEL_CHAR      (KEY_MAX + 0x122) /* delete the current character */
132 #define REQ_DEL_PREV      (KEY_MAX + 0x123) /* delete the character
133                                                before the current */
134 #define REQ_DEL_LINE      (KEY_MAX + 0x124) /* delete the current line */
135 #define REQ_DEL_WORD      (KEY_MAX + 0x125) /* delete the word at the cursor */
136 #define REQ_CLR_EOL       (KEY_MAX + 0x126) /* clear to the end of the line */
137 #define REQ_CLR_EOF       (KEY_MAX + 0x127) /* clear to the end of the field */
138 #define REQ_CLR_FIELD     (KEY_MAX + 0x128) /* clear the field */
139 
140 #define REQ_OVL_MODE      (KEY_MAX + 0x129) /* overlay mode */
141 #define REQ_INS_MODE      (KEY_MAX + 0x12a) /* insert mode */
142 
143 #define REQ_SCR_FLINE     (KEY_MAX + 0x12b) /* scroll field forward one line */
144 #define REQ_SCR_BLINE     (KEY_MAX + 0x12c) /* scroll field backward
145                                                one line */
146 #define REQ_SCR_FPAGE     (KEY_MAX + 0x12d) /* scroll field forward one page */
147 #define REQ_SCR_BPAGE     (KEY_MAX + 0x12e) /* scroll field backward
148                                                one page */
149 #define REQ_SCR_FHPAGE    (KEY_MAX + 0x12f) /* scroll field forward
150                                                half a page */
151 #define REQ_SCR_BHPAGE    (KEY_MAX + 0x130) /* scroll field backward
152                                                half a page */
153 
154 #define REQ_SCR_FCHAR     (KEY_MAX + 0x131) /* horizontal scroll
155                                                forward a character */
156 #define REQ_SCR_BCHAR     (KEY_MAX + 0x132) /* horizontal scroll
157                                                backward a character */
158 #define REQ_SCR_HFLINE    (KEY_MAX + 0x133) /* horizontal scroll
159                                                forward a line */
160 #define REQ_SCR_HBLINE    (KEY_MAX + 0x134) /* horizontal scroll
161                                                backward a line */
162 #define REQ_SCR_HFHALF    (KEY_MAX + 0x135) /* horizontal scroll
163                                                forward half a line */
164 #define REQ_SCR_HBHALF    (KEY_MAX + 0x136) /* horizontal scroll
165                                                backward half a line */
166 
167 #define REQ_VALIDATION    (KEY_MAX + 0x137) /* validate the field */
168 #define REQ_PREV_CHOICE   (KEY_MAX + 0x138) /* display previous field choice */
169 #define REQ_NEXT_CHOICE   (KEY_MAX + 0x139) /* display next field choice */
170 
171 #define REQ_MAX_COMMAND   (KEY_MAX + 0x139) /* must match the last
172                                                driver command */
173 
174 /* The following defines are for ncurses compatibility */
175 #define MIN_FORM_COMMAND	REQ_MIN_REQUEST
176 #define MAX_FORM_COMMAND	REQ_MAX_COMMAND
177 
178 
179 typedef struct _form_string {
180 	size_t allocated;
181 	unsigned int length;
182 	char *string;
183 } FORM_STR;
184 
185 typedef struct _form_field FIELD;
186 typedef struct _form_struct FORM;
187 typedef struct _form_fieldtype FIELDTYPE;
188 
189 typedef struct _formi_page_struct _FORMI_PAGE_START;
190 typedef struct formi_type_link_struct _FORMI_TYPE_LINK;
191 typedef struct _formi_field_lines _FORMI_FIELD_LINES;
192 
193 
194 typedef void (*Form_Hook)(FORM *);
195 
196 /* definition of a field in the form */
197 struct _form_field {
198 	unsigned int rows; /* rows in the field */
199 	unsigned int cols; /* columns in the field */
200 	unsigned int drows; /* dynamic rows */
201 	unsigned int dcols; /* dynamic columns */
202 	unsigned int max; /* maximum growth */
203 	unsigned int form_row; /* starting row in the form subwindow */
204 	unsigned int form_col; /* starting column in the form subwindow */
205 	unsigned int nrows; /* number of off screen rows */
206 	int index; /* index of this field in form fields array. */
207 	int nbuf; /* number of buffers associated with this field */
208 	int buf0_status; /* set to true if buffer 0 has changed. */
209 	int justification; /* justification style of the field */
210 	int overlay; /* set to true if field is in overlay mode */
211 	_FORMI_FIELD_LINES *cur_line; /* pointer to the current line cursor
212 					 is on */
213 	unsigned int start_char; /* starting char in string (horiz scroll) */
214 	_FORMI_FIELD_LINES *start_line; /* start line in field (vert scroll) */
215 	unsigned int row_count; /* number of rows actually used in field */
216 	unsigned int row_xpos; /* char offset of cursor in field, not same
217 				  as cursor_xpos due to tab expansion */
218 	unsigned int cursor_xpos; /* x pos of cursor in field */
219 	unsigned int cursor_ypos; /* y pos of cursor in field */
220 	short page_break; /* start of a new page on the form if 1 */
221 	short page; /* number of the page this field is on */
222 	chtype fore; /* character attributes for the foreground */
223 	chtype back; /* character attributes for the background */
224 	int pad; /* padding character */
225 	Form_Options opts; /* options for the field */
226 	FORM *parent; /* the form this field is bound to, if any */
227 	FIELD *up; /* field above this one */
228 	FIELD *down; /* field below this one */
229 	FIELD *left; /* field to the left of this one */
230 	FIELD *right; /* field to the right of this one */
231 	void *userptr;  /* user defined pointer. */
232 	FIELD *link; /* used if fields are linked */
233 	FIELDTYPE *type; /* type struct for the field */
234 	TAILQ_ENTRY(_form_field) glue; /* tail queue glue for sorting fields */
235 	char *args; /* args for field type. */
236 	_FORMI_FIELD_LINES *alines; /* array of the starts and ends of lines */
237 	_FORMI_FIELD_LINES *free; /* list of lines available for reuse */
238 	FORM_STR *buffers; /* array of buffers for the field */
239 };
240 
241 /* define the types of fields we can have */
242 extern FIELDTYPE *TYPE_ALNUM;
243 extern FIELDTYPE *TYPE_ALPHA;
244 extern FIELDTYPE *TYPE_ENUM;
245 extern FIELDTYPE *TYPE_INTEGER;
246 extern FIELDTYPE *TYPE_NUMERIC;
247 extern FIELDTYPE *TYPE_REGEXP;
248 extern FIELDTYPE *TYPE_IPV4;
249 extern FIELDTYPE *TYPE_IPV6;
250 extern FIELDTYPE *TYPE_USER;
251 
252 /* definition of a field type. */
253 struct _form_fieldtype {
254 	unsigned flags; /* status of the type */
255 	unsigned refcount; /* in use if > 0 */
256 	_FORMI_TYPE_LINK *link; /* set if this type is linked */
257 
258 	char * (*make_args)(va_list *); /* make the args for the type */
259 	char * (*copy_args)(char *); /* copy the args for the type */
260 	void (*free_args)(char *); /* free storage used by the args */
261 	int (*field_check)(FIELD *, char *); /* field validation routine */
262 	int (*char_check)(int, char *); /* char validation routine */
263 	int (*next_choice)(FIELD *, char *); /* function to select next
264 						choice */
265 	int (*prev_choice)(FIELD *, char *); /* function to select prev
266 						choice */
267 };
268 
269 /*definition of a form */
270 
271 struct _form_struct {
272 	int in_init; /* true if performing a init or term function */
273 	int posted; /* the form is posted */
274 	int wrap; /* wrap from last field to first field if true */
275 	WINDOW *win; /* window for the form */
276 	WINDOW *subwin; /* subwindow for the form */
277 	WINDOW *scrwin; /* this is the window to use for output */
278 	void *userptr; /* user defined pointer */
279 	Form_Options opts; /* options for the form */
280 	Form_Hook form_init; /* function called when form posted and
281 				after page change */
282 	Form_Hook form_term; /* function called when form is unposted and
283 				before page change */
284 	Form_Hook field_init; /* function called when form posted and after
285 				 current field changes */
286 	Form_Hook field_term; /* function called when form unposted and
287 				 before current field changes */
288 	int field_count; /* number of fields attached */
289 	int cur_field; /* current field */
290 	int page; /* current page of form */
291 	int max_page; /* number of pages in the form */
292 	_FORMI_PAGE_START *page_starts; /* dynamic array of fields that start
293 					   the pages */
294 	TAILQ_HEAD(_formi_sort_head, _form_field) sorted_fields; /* sorted field
295 								list */
296 	FIELD **fields; /* array of fields attached to this form. */
297 };
298 
299 /* Public function prototypes. */
300 __BEGIN_DECLS
301 
302 FIELD       *current_field(FORM *);
303 int          data_ahead(FORM *);
304 int          data_behind(FORM *);
305 FIELD       *dup_field(FIELD *, int, int);
306 int          dynamic_field_info(FIELD *, int *, int *, int *);
307 char        *field_arg(FIELD *);
308 chtype       field_back(FIELD *);
309 char        *field_buffer(FIELD *, int);
310 int          field_count(FORM *);
311 chtype       field_fore(FIELD *);
312 int          field_index(FIELD *);
313 int          field_info(FIELD *, int *, int *, int *, int *, int *, int *);
314 Form_Hook    field_init(FORM *);
315 int          field_just(FIELD *);
316 Form_Options field_opts(FIELD *);
317 int          field_opts_off(FIELD *, Form_Options);
318 int          field_opts_on(FIELD *, Form_Options);
319 int          field_pad(FIELD *);
320 int          field_status(FIELD *);
321 Form_Hook    field_term(FORM *);
322 FIELDTYPE   *field_type(FIELD *);
323 void        *field_userptr(FIELD *);
324 int          form_driver(FORM *, int);
325 FIELD      **form_fields(FORM *);
326 Form_Hook    form_init(FORM *);
327 int          form_max_page(FORM *);
328 Form_Options form_opts(FORM *);
329 int          form_opts_off(FORM *, Form_Options);
330 int          form_opts_on(FORM *, Form_Options);
331 int          form_page(FORM *);
332 WINDOW      *form_sub(FORM *);
333 Form_Hook    form_term(FORM *);
334 void        *form_userptr(FORM *);
335 WINDOW      *form_win(FORM *);
336 int          free_field(FIELD *);
337 int          free_fieldtype(FIELDTYPE *);
338 int          free_form(FORM *);
339 FIELD       *link_field(FIELD *, int, int);
340 FIELDTYPE   *link_fieldtype(FIELDTYPE *, FIELDTYPE *);
341 int          move_field(FIELD *, int, int);
342 FIELD       *new_field(int, int, int, int, int, int);
343 FIELDTYPE   *new_fieldtype(int (* field_check)(FIELD *, char *),
344 			   int (* char_check)(int, char *));
345 FORM        *new_form(FIELD **);
346 int          new_page(FIELD *);
347 int          pos_form_cursor(FORM *);
348 int          post_form(FORM *);
349 int          scale_form(FORM *, int *, int *);
350 int          set_current_field(FORM *, FIELD *);
351 int          set_field_back(FIELD *, chtype);
352 int          set_field_buffer(FIELD *, int, const char *);
353 int          set_field_fore(FIELD *, chtype);
354 int          set_field_init(FORM *, Form_Hook);
355 int          set_field_just(FIELD *, int);
356 int          set_field_opts(FIELD *, Form_Options);
357 int          set_field_pad(FIELD *, int);
358 int          set_field_printf(FIELD *, int, char *, ...) __printflike(3, 4);
359 int          set_field_status(FIELD *, int);
360 int          set_field_term(FORM *, Form_Hook);
361 int          set_field_type(FIELD *, FIELDTYPE *, ...);
362 int          set_field_userptr(FIELD *, void *);
363 int          set_fieldtype_arg(FIELDTYPE *, char *(*)(va_list *),
364 			       char *(*)(char *),
365 			       void (*)(char *));
366 int          set_fieldtype_choice(FIELDTYPE *, int (*)(FIELD *, char *),
367 				  int (*)(FIELD *, char *));
368 int          set_form_fields(FORM *, FIELD **);
369 int          set_form_init(FORM *, Form_Hook);
370 int          set_form_opts(FORM *, Form_Options);
371 int          set_form_page(FORM *, int);
372 int          set_form_sub(FORM *, WINDOW *);
373 int          set_form_term(FORM *, Form_Hook);
374 int          set_form_userptr(FORM *, void *);
375 int          set_form_win(FORM *, WINDOW *);
376 int          set_max_field(FIELD *, int);
377 int          set_new_page(FIELD *, int);
378 int          unpost_form(FORM *);
379 
380 __END_DECLS
381 
382 #endif /* FORM_H */
383