2 .\" Copyright (c) 1995, Jordan Hubbard
4 .\" All rights reserved.
6 .\" This manual page may be used, modified, copied, distributed, and
7 .\" sold, in both source and binary form provided that the above
8 .\" copyright and these terms are retained, verbatim, as the first
9 .\" lines of this file. Under no circumstances is the author
10 .\" responsible for the proper functioning of the software described herein
11 .\" nor does the author assume any responsibility for damages incurred with
25 .Nm dialog_create_rc ,
32 .Nm dialog_checklist ,
33 .Nm dialog_radiolist ,
35 .Nm dialog_clear_norefresh ,
47 .Nm restore_helpline ,
50 .Nd provide a simple ncurses-based GUI interface
54 .Fn draw_shadow "WINDOW *win" "int y" "int x" "int height" "int width"
56 .Fn draw_box "WINDOW *win" "int y" "int x" "int height" "int width" "chtype box" "chtype border"
66 .Fa "unsigned char *result"
70 .Fn strheight "const char *p"
72 .Fn strwidth "const char *p"
74 .Fn dialog_create_rc "unsigned char *filename"
76 .Fn dialog_yesno "unsigned char *title" "unsigned char *prompt" "int height" "int width"
78 .Fn dialog_noyes "unsigned char *title" "unsigned char *prompt" "int height" "int width"
80 .Fn dialog_prgbox "unsigned char *title" "const unsigned char *line" "int height" "int width" "int pause" "int use_shell"
82 .Fn dialog_textbox "unsigned char *title" "unsigned char *file" "int height" "int width"
85 .Fa "unsigned char *title"
86 .Fa "unsigned char *prompt"
92 .Fa "unsigned char *result"
97 .Fn dialog_checklist "unsigned char *title" "unsigned char *prompt" "int height" "int width" "int list_height" "int cnt" "void *it" "unsigned char *result"
99 .Fn dialog_radiolist "unsigned char *title" "unsigned char *prompt" "int height" "int width" "int list_height" "int cnt" "void *it" "unsigned char *result"
101 .Fn dialog_inputbox "unsigned char *title" "unsigned char *prompt" "int height" "int width" "unsigned char *result"
103 .Fn dialog_fselect "char *dir" "char *fmask"
105 .Fn dialog_dselect "char *dir" "char *fmask"
107 .Fn dialog_notify "char *msg"
109 .Fn dialog_mesgbox "unsigned char *title" "unsigned char *prompt" "int height" "int width"
111 .Fn dialog_gauge "char *title" "char *prompt" "int y" "int x" "int height" "int width" "int perc"
113 .Fn use_helpfile "char *hfile"
115 .Fn use_helpline "char *hline"
117 .Fn get_helpline "void"
119 .Fn dialog_clear_norefresh "void"
121 .Fn dialog_clear "void"
123 .Fn dialog_update "void"
125 .Fn init_dialog "void"
127 .Fn end_dialog "void"
129 .Fn dialog_ftree "unsigned char *filename" "unsigned char FS" "unsigned char *title" "unsigned char *prompt" "int height" "int width" "int menu_height" "unsigned char **result"
132 .Fa "unsigned char **names"
134 .Fa "unsigned char FS"
135 .Fa "unsigned char *title"
136 .Fa "unsigned char *prompt"
139 .Fa "int menu_height"
140 .Fa "unsigned char **result"
143 The dialog library attempts to provide a fairly simplistic set of
144 fixed-presentation menus, input boxes, gauges, file requestors and
145 other general purpose GUI (a bit of a stretch, since it uses
146 ncurses) objects. Since the library also had its roots in a
147 shell-script writer's utility (see the
150 early API was somewhat primitively based on strings being passed in or
151 out and parsed. This API was later extended to take either the
152 original arguments or arrays of
155 giving the user much more control over the internal behavior of each
158 structure internals are public:
159 .Bd -literal -offset indent
160 typedef struct _dmenu_item {
163 int (*checked)(struct _dmenu_item *self);
164 int (*fire)(struct _dmenu_item *self);
165 int (*selected)(struct _dmenu_item *self, int is_selected);
167 char lbra, mark, rbra;
176 strings are pretty much self-explanatory,
181 function pointers provide optional
182 display and action hooks (the
184 variable being available for
185 the convenience of those hooks) when more tightly coupled feedback between
186 a menu object and user code is required. The
189 allows you to verify whether or not a given item is selected (the cursor is
190 over it) for implementing pretty much any possible context-sensitive
191 behavior. A number of clever tricks for simulating various kinds of item
192 types can also be done by adjusting the values of
196 (default: '*' for radio menus, 'X' for check menus)
199 (default: ']') and declaring a reasonable
202 which should return TRUE for the
208 field is not used internally, and is available for miscellaneous usage.
211 hook associated with it, it will also be called
212 whenever the item is "toggled" in some way and should return one of the
214 .Bd -literal -offset 4n
215 #define DITEM_SUCCESS 0 /* Successful completion */
216 #define DITEM_FAILURE 1 /* Failed to "fire" */
219 The following flags are in the upper 16 bits of return status:
220 .Bd -literal -offset 4n
221 #define DITEM_LEAVE_MENU (1 << 16)
222 #define DITEM_REDRAW (1 << 17)
223 #define DITEM_RECREATE (1 << 18)
224 #define DITEM_RESTORE (1 << 19)
225 #define DITEM_CONTINUE (1 << 20)
228 Two special globals also exist for putting a dialog at any arbitrary
229 X,Y location (the early designers rather short-sightedly made no provisions
230 for this). If set to zero, the default centering behavior will be in
233 Below is a short description of the various functions:
236 draws a shadow in curses window
238 using the dimensions of
244 draws a bordered box using the dimensions of
252 are used, if specified, while painting the box and border regions of the
256 invoke a simple line editor with an edit box of dimensions
260 The field length is constrained by
264 character specified and
265 optionally displayed with character attributes
267 The string being edited is stored in
269 Returns 0 on success, 1 on Cancel, and -1 on failure or ESC.
272 returns the height of string in
277 returns the width of string in
282 dump dialog library settings into
284 for later retrieval as defaults. Returns 0 on success, -1 on failure.
287 display a text box using
291 strings of dimensions
299 buttons at the bottom.
300 The default selection is
304 button is chosen, return FALSE. If
311 except the default selection is
315 display a text box of dimensions
319 containing the output of command
325 is passed as an argument to
327 otherwise it is simply passed to
331 is TRUE, a final confirmation requestor will be put up when execution
332 terminates. Returns 0 on success, -1 on failure.
335 display a text box containing the contents of
343 display a menu of dimensions
347 with an optional internal menu height of
353 arguments are of particular importance since they,
354 together, determine which of the 2 available APIs to use. To use the
355 older and traditional interface,
358 integer representing the number of string pointer pairs to find in
360 (which should be of type
363 expected to be in prompt and title order for each item and the
365 parameter is expected to point to an array where the
366 prompt string of the item selected will be copied. To use the newer
371 integer representing the number of
373 structures pointed to by
375 (which should be of type
376 .Vt dialogMenuItem "*" ) ,
377 one structure per item. In the new interface, the
379 variable is used as a simple boolean (not a pointer) and should be NULL if
381 only points to menu items and the default OK and Cancel buttons are desired. If
385 is actually expected to point 2 locations
387 the start of the menu item list.
390 point to an item representing the Cancel button, from which the
394 actions are used to override the default behavior, and
396 to the same for the OK button.
398 Using either API behavior, the
402 values may be passed in to preserve current
403 item selection and scroll position values across calls.
406 display a menu of dimensions
411 optional internal menu height of
417 arguments are of particular importance since they,
418 together, determine which of the 2 available APIs to use. To use the
419 older and traditional interface,
422 integer representing the number of string pointer tuples to find in
424 (which should be of type
427 expected to be in prompt, title and state ("on" or "off") order for
430 parameter is expected to point to an
431 array where the prompt string of the item(s) selected will be
432 copied. To use the newer interface,
436 integer representing the number of
438 structures pointed to by
440 (which should be of type
441 .Ft "dialogMenuItem *" ) ,
442 one structure per item. In the new interface,
445 variable is used as a simple boolean (not a pointer)
446 and should be NULL if
448 only points to menu items and the default OK and Cancel
449 buttons are desired. If
453 is actually expected to
456 the start of the menu item list.
458 is then expected to point to an item representing the Cancel
459 button, from which the
463 actions are used to override the default behavior, and
465 to the same for the OK button.
467 In the standard API model, the menu supports the selection of multiple items,
468 each of which is marked with an `X' character to denote selection. When
469 the OK button is selected, the prompt values for all items selected are
470 concatenated into the
474 In the new API model, it is not actually necessary to preserve
475 "checklist" semantics at all since practically everything about how
476 each item is displayed or marked as "selected" is fully configurable.
477 You could have a single checklist menu that actually contained a group
478 of items with "radio" behavior, "checklist" behavior and standard menu
479 item behavior. The only reason to call
483 in the new API model is to inherit the base
484 behavior, you're no longer constrained by it.
486 Returns 0 on success, 1 on Cancel, and -1 on failure or ESC.
489 display a menu of dimensions
494 optional internal menu height of
500 arguments are of particular importance since they,
501 together, determine which of the 2 available APIs to use. To use the
502 older and traditional interface,
505 integer representing the number of string pointer tuples to find in
507 (which should be of type
510 expected to be in prompt, title and state ("on" or "off") order for
513 parameter is expected to point to an
514 array where the prompt string of the item(s) selected will be
515 copied. To use the newer interface,
519 integer representing the number of
521 structures pointed to by
523 (which should be of type
524 .Ft "dialogMenuItem *" ,
525 one structure per item. In the new interface,
528 variable is used as a simple boolean (not a pointer)
529 and should be NULL if
531 only points to menu items and the default OK and Cancel
532 buttons are desired. If
536 is actually expected to point 2 locations
538 the start of the menu item list.
540 is then expected to point to an item representing the Cancel
541 button, from which the
545 actions are used to override the default behavior, and
547 does the same for the traditional OK button.
549 In the standard API model, the menu supports the selection of only one
550 of multiple items, the currently active item marked with an `*'
551 character to denote selection. When the OK button is selected, the
552 prompt value for this item is copied into the
556 In the new API model, it is not actually necessary to preserve
557 "radio button" semantics at all since practically everything about how
558 each item is displayed or marked as "selected" is fully configurable.
559 You could have a single radio menu that actually contained a group
560 of items with "checklist" behavior, "radio" behavior and standard menu
561 item behavior. The only reason to call
564 .Fn dialog_checklistlist
565 in the new API model is to inherit the base
568 Returns 0 on success, 1 on Cancel and -1 on failure or ESC.
571 displays a single-line text input field in a box displaying
579 The field entered is stored in
582 Returns 0 on success, -1 on failure or ESC.
585 brings up a file selector dialog starting at
587 and showing only those file names
591 Returns filename selected or NULL.
594 brings up a directory selector dialog starting at
596 and showing only those directory names
600 Returns directory name selected or NULL.
603 brings up a generic "hey, you!" notifier dialog containing
607 like a notifier dialog, but with more control over
613 This object will also wait for user confirmation, unlike
616 Returns 0 on success, -1 on failure.
619 displays a horizontal bar-graph style gauge. A value of
623 constitutes a full gauge, a value of
628 for any menu supporting context sensitive help, invoke the text box
629 object on this file whenever the
634 displays this line of helpful text below any menu being displayed.
637 get the current value of the helpful text line.
639 .Fn dialog_clear_norefresh
640 clear the screen back to the dialog background color, but don't refresh the
644 clear the screen back to the dialog background color immediately.
647 do any pending screen refreshes now.
650 initialize the dialog library (call this routine before any other dialog
654 shut down the dialog library (call this if you need to get back to sanity).
657 shows a tree described by the data from the file
659 The data in the file should look like
664 output, the field separator
672 are positive numbers, they set the absolute
679 are negative numbers, the size of the
681 box will be calculated automatically.
683 sets the height of the tree subwindow inside the
687 is shown centered on the upper border of the
693 box above the tree subwindow and can contain
695 to split lines. One can navigate in
696 the tree by pressing UP/DOWN or
698 .So \&+ Sc \&/ So \&- Sc ,
707 .So g Sc \&/ So G Sc .
710 tree is selected by pressing TAB or LEFT/RIGHT the OK
711 button and pressing ENTER. filename may contain data like
713 output, as well as like the output of
717 option. Some of the transient paths to the leaves of the tree may
718 be absent. Such data is corrected when fed from filename.
720 The function returns 0 and a pointer to the selected leaf (to the path to
721 the leaf from the root of the tree) into result, if the OK button was
722 selected. The memory allocated for the building of the tree is freed on
725 The memory for the result line should be freed
726 later manually, if necessary. If the Cancel button was selected, the
727 function returns 1. In case of exiting
729 on ESC, the function returns -1.
732 function returns the same results as
734 If 0 is returned, result will contain a pointer from the array
736 .\" \fBdialog_tree\fR displays the tree very much like \fBdialog_ftree\fR does,
737 .\" with some exceptions. The source data for the building of the tree is an
738 .\" array \fBnames\fR of paths to the leaves (should be similar to \fBfind(1)\fR
739 .\" output) of the size \fBsize\fR. However, there is no correction of data like
740 .\" in \fBdialog_ftree\fR. Thus, to display a correct tree, the array must
741 .\" already contain correct data. Besides, in each session every unique use of
742 .\" \fBdialog_tree\fR is kept in memory, and later, when calling
743 .\" \fBdialog_tree\fR with the same \fBnames\fR, \fBsize\fR, \fBFS\fR,
744 .\" \fBheight\fR, \fBwidth\fR and \fBmenu_height\fR the position of the cursor
745 .\" in the tree subwindow is restored.
750 The primary author would appear to be
751 .An Savio Lam Aq lam836@cs.cuhk.hk
752 with contributions over the years by
753 .An Stuart Herbert Aq S.Herbert@sheffield.ac.uk ,
754 .An Marc van Kempen Aq wmbfmk@urc.tue.nl ,
755 .An Andrey Chernov Aq ache@FreeBSD.org ,
756 .An Jordan Hubbard Aq jkh@FreeBSD.org
758 .An Anatoly A. Orehovsky Aq tolik@mpeks.tomsk.su .
760 These functions appeared in
764 command and were soon split into a separate library
767 .An Marc van Kempen implemented most of the
768 extra controls and objects,
770 added the dialogMenuItem renovations and this man page and
771 .An Anatoly A. Orehovsky