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
14 .\" $FreeBSD: src/gnu/lib/libdialog/dialog.3,v 1.12.2.6 2001/12/14 14:28:53 ru Exp $
15 .\" $DragonFly: src/gnu/lib/libdialog/dialog.3,v 1.2 2003/06/17 04:25:43 dillon Exp $
26 .Nm dialog_create_rc ,
33 .Nm dialog_checklist ,
34 .Nm dialog_radiolist ,
36 .Nm dialog_clear_norefresh ,
48 .Nm restore_helpline ,
51 .Nd provide a simple ncurses-based GUI interface
55 .Fn draw_shadow "WINDOW *win" "int y" "int x" "int height" "int width"
57 .Fn draw_box "WINDOW *win" "int y" "int x" "int height" "int width" "chtype box" "chtype border"
67 .Fa "unsigned char *result"
71 .Fn strheight "const char *p"
73 .Fn strwidth "const char *p"
75 .Fn dialog_create_rc "unsigned char *filename"
77 .Fn dialog_yesno "unsigned char *title" "unsigned char *prompt" "int height" "int width"
79 .Fn dialog_noyes "unsigned char *title" "unsigned char *prompt" "int height" "int width"
81 .Fn dialog_prgbox "unsigned char *title" "const unsigned char *line" "int height" "int width" "int pause" "int use_shell"
83 .Fn dialog_textbox "unsigned char *title" "unsigned char *file" "int height" "int width"
86 .Fa "unsigned char *title"
87 .Fa "unsigned char *prompt"
93 .Fa "unsigned char *result"
98 .Fn dialog_checklist "unsigned char *title" "unsigned char *prompt" "int height" "int width" "int list_height" "int cnt" "void *it" "unsigned char *result"
100 .Fn dialog_radiolist "unsigned char *title" "unsigned char *prompt" "int height" "int width" "int list_height" "int cnt" "void *it" "unsigned char *result"
102 .Fn dialog_inputbox "unsigned char *title" "unsigned char *prompt" "int height" "int width" "unsigned char *result"
104 .Fn dialog_fselect "char *dir" "char *fmask"
106 .Fn dialog_dselect "char *dir" "char *fmask"
108 .Fn dialog_notify "char *msg"
110 .Fn dialog_mesgbox "unsigned char *title" "unsigned char *prompt" "int height" "int width"
112 .Fn dialog_gauge "char *title" "char *prompt" "int y" "int x" "int height" "int width" "int perc"
114 .Fn use_helpfile "char *hfile"
116 .Fn use_helpline "char *hline"
118 .Fn get_helpline "void"
120 .Fn dialog_clear_norefresh "void"
122 .Fn dialog_clear "void"
124 .Fn dialog_update "void"
126 .Fn init_dialog "void"
128 .Fn end_dialog "void"
130 .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"
133 .Fa "unsigned char **names"
135 .Fa "unsigned char FS"
136 .Fa "unsigned char *title"
137 .Fa "unsigned char *prompt"
140 .Fa "int menu_height"
141 .Fa "unsigned char **result"
144 The dialog library attempts to provide a fairly simplistic set of
145 fixed-presentation menus, input boxes, gauges, file requestors and
146 other general purpose GUI (a bit of a stretch, since it uses
147 ncurses) objects. Since the library also had its roots in a
148 shell-script writer's utility (see the
151 early API was somewhat primitively based on strings being passed in or
152 out and parsed. This API was later extended to take either the
153 original arguments or arrays of
156 giving the user much more control over the internal behavior of each
159 structure internals are public:
160 .Bd -literal -offset indent
161 typedef struct _dmenu_item {
164 int (*checked)(struct _dmenu_item *self);
165 int (*fire)(struct _dmenu_item *self);
166 int (*selected)(struct _dmenu_item *self, int is_selected);
168 char lbra, mark, rbra;
177 strings are pretty much self-explanatory,
182 function pointers provide optional
183 display and action hooks (the
185 variable being available for
186 the convenience of those hooks) when more tightly coupled feedback between
187 a menu object and user code is required. The
190 allows you to verify whether or not a given item is selected (the cursor is
191 over it) for implementing pretty much any possible context-sensitive
192 behavior. A number of clever tricks for simulating various kinds of item
193 types can also be done by adjusting the values of
197 (default: '*' for radio menus, 'X' for check menus)
200 (default: ']') and declaring a reasonable
203 which should return TRUE for the
209 field is not used internally, and is available for miscellaneous usage.
212 hook associated with it, it will also be called
213 whenever the item is "toggled" in some way and should return one of the
215 .Bd -literal -offset 4n
216 #define DITEM_SUCCESS 0 /* Successful completion */
217 #define DITEM_FAILURE 1 /* Failed to "fire" */
220 The following flags are in the upper 16 bits of return status:
221 .Bd -literal -offset 4n
222 #define DITEM_LEAVE_MENU (1 << 16)
223 #define DITEM_REDRAW (1 << 17)
224 #define DITEM_RECREATE (1 << 18)
225 #define DITEM_RESTORE (1 << 19)
226 #define DITEM_CONTINUE (1 << 20)
229 Two special globals also exist for putting a dialog at any arbitrary
230 X,Y location (the early designers rather short-sightedly made no provisions
231 for this). If set to zero, the default centering behavior will be in
234 Below is a short description of the various functions:
237 draws a shadow in curses window
239 using the dimensions of
245 draws a bordered box using the dimensions of
253 are used, if specified, while painting the box and border regions of the
257 invoke a simple line editor with an edit box of dimensions
261 The field length is constrained by
265 character specified and
266 optionally displayed with character attributes
268 The string being edited is stored in
270 Returns 0 on success, 1 on Cancel, and -1 on failure or ESC.
273 returns the height of string in
278 returns the width of string in
283 dump dialog library settings into
285 for later retrieval as defaults. Returns 0 on success, -1 on failure.
288 display a text box using
292 strings of dimensions
300 buttons at the bottom.
301 The default selection is
305 button is chosen, return FALSE. If
312 except the default selection is
316 display a text box of dimensions
320 containing the output of command
326 is passed as an argument to
328 otherwise it is simply passed to
332 is TRUE, a final confirmation requestor will be put up when execution
333 terminates. Returns 0 on success, -1 on failure.
336 display a text box containing the contents of
344 display a menu of dimensions
348 with an optional internal menu height of
354 arguments are of particular importance since they,
355 together, determine which of the 2 available APIs to use. To use the
356 older and traditional interface,
359 integer representing the number of string pointer pairs to find in
361 (which should be of type
364 expected to be in prompt and title order for each item and the
366 parameter is expected to point to an array where the
367 prompt string of the item selected will be copied. To use the newer
372 integer representing the number of
374 structures pointed to by
376 (which should be of type
377 .Vt dialogMenuItem "*" ) ,
378 one structure per item. In the new interface, the
380 variable is used as a simple boolean (not a pointer) and should be NULL if
382 only points to menu items and the default OK and Cancel buttons are desired. If
386 is actually expected to point 2 locations
388 the start of the menu item list.
391 point to an item representing the Cancel button, from which the
395 actions are used to override the default behavior, and
397 to the same for the OK button.
399 Using either API behavior, the
403 values may be passed in to preserve current
404 item selection and scroll position values across calls.
407 display a menu of dimensions
412 optional internal menu height of
418 arguments are of particular importance since they,
419 together, determine which of the 2 available APIs to use. To use the
420 older and traditional interface,
423 integer representing the number of string pointer tuples to find in
425 (which should be of type
428 expected to be in prompt, title and state ("on" or "off") order for
431 parameter is expected to point to an
432 array where the prompt string of the item(s) selected will be
433 copied. To use the newer interface,
437 integer representing the number of
439 structures pointed to by
441 (which should be of type
442 .Ft "dialogMenuItem *" ) ,
443 one structure per item. In the new interface,
446 variable is used as a simple boolean (not a pointer)
447 and should be NULL if
449 only points to menu items and the default OK and Cancel
450 buttons are desired. If
454 is actually expected to
457 the start of the menu item list.
459 is then expected to point to an item representing the Cancel
460 button, from which the
464 actions are used to override the default behavior, and
466 to the same for the OK button.
468 In the standard API model, the menu supports the selection of multiple items,
469 each of which is marked with an `X' character to denote selection. When
470 the OK button is selected, the prompt values for all items selected are
471 concatenated into the
475 In the new API model, it is not actually necessary to preserve
476 "checklist" semantics at all since practically everything about how
477 each item is displayed or marked as "selected" is fully configurable.
478 You could have a single checklist menu that actually contained a group
479 of items with "radio" behavior, "checklist" behavior and standard menu
480 item behavior. The only reason to call
484 in the new API model is to inherit the base
485 behavior, you're no longer constrained by it.
487 Returns 0 on success, 1 on Cancel, and -1 on failure or ESC.
490 display a menu of dimensions
495 optional internal menu height of
501 arguments are of particular importance since they,
502 together, determine which of the 2 available APIs to use. To use the
503 older and traditional interface,
506 integer representing the number of string pointer tuples to find in
508 (which should be of type
511 expected to be in prompt, title and state ("on" or "off") order for
514 parameter is expected to point to an
515 array where the prompt string of the item(s) selected will be
516 copied. To use the newer interface,
520 integer representing the number of
522 structures pointed to by
524 (which should be of type
525 .Ft "dialogMenuItem *" ,
526 one structure per item. In the new interface,
529 variable is used as a simple boolean (not a pointer)
530 and should be NULL if
532 only points to menu items and the default OK and Cancel
533 buttons are desired. If
537 is actually expected to point 2 locations
539 the start of the menu item list.
541 is then expected to point to an item representing the Cancel
542 button, from which the
546 actions are used to override the default behavior, and
548 does the same for the traditional OK button.
550 In the standard API model, the menu supports the selection of only one
551 of multiple items, the currently active item marked with an `*'
552 character to denote selection. When the OK button is selected, the
553 prompt value for this item is copied into the
557 In the new API model, it is not actually necessary to preserve
558 "radio button" semantics at all since practically everything about how
559 each item is displayed or marked as "selected" is fully configurable.
560 You could have a single radio menu that actually contained a group
561 of items with "checklist" behavior, "radio" behavior and standard menu
562 item behavior. The only reason to call
565 .Fn dialog_checklistlist
566 in the new API model is to inherit the base
569 Returns 0 on success, 1 on Cancel and -1 on failure or ESC.
572 displays a single-line text input field in a box displaying
580 The field entered is stored in
583 Returns 0 on success, -1 on failure or ESC.
586 brings up a file selector dialog starting at
588 and showing only those file names
592 Returns filename selected or NULL.
595 brings up a directory selector dialog starting at
597 and showing only those directory names
601 Returns directory name selected or NULL.
604 brings up a generic "hey, you!" notifier dialog containing
608 like a notifier dialog, but with more control over
614 This object will also wait for user confirmation, unlike
617 Returns 0 on success, -1 on failure.
620 displays a horizontal bar-graph style gauge. A value of
624 constitutes a full gauge, a value of
629 for any menu supporting context sensitive help, invoke the text box
630 object on this file whenever the
635 displays this line of helpful text below any menu being displayed.
638 get the current value of the helpful text line.
640 .Fn dialog_clear_norefresh
641 clear the screen back to the dialog background color, but don't refresh the
645 clear the screen back to the dialog background color immediately.
648 do any pending screen refreshes now.
651 initialize the dialog library (call this routine before any other dialog
655 shut down the dialog library (call this if you need to get back to sanity).
658 shows a tree described by the data from the file
660 The data in the file should look like
665 output, the field separator
673 are positive numbers, they set the absolute
680 are negative numbers, the size of the
682 box will be calculated automatically.
684 sets the height of the tree subwindow inside the
688 is shown centered on the upper border of the
694 box above the tree subwindow and can contain
696 to split lines. One can navigate in
697 the tree by pressing UP/DOWN or
699 .So \&+ Sc \&/ So \&- Sc ,
708 .So g Sc \&/ So G Sc .
711 tree is selected by pressing TAB or LEFT/RIGHT the OK
712 button and pressing ENTER. filename may contain data like
714 output, as well as like the output of
718 option. Some of the transient paths to the leaves of the tree may
719 be absent. Such data is corrected when fed from filename.
721 The function returns 0 and a pointer to the selected leaf (to the path to
722 the leaf from the root of the tree) into result, if the OK button was
723 selected. The memory allocated for the building of the tree is freed on
726 The memory for the result line should be freed
727 later manually, if necessary. If the Cancel button was selected, the
728 function returns 1. In case of exiting
730 on ESC, the function returns -1.
733 function returns the same results as
735 If 0 is returned, result will contain a pointer from the array
737 .\" \fBdialog_tree\fR displays the tree very much like \fBdialog_ftree\fR does,
738 .\" with some exceptions. The source data for the building of the tree is an
739 .\" array \fBnames\fR of paths to the leaves (should be similar to \fBfind(1)\fR
740 .\" output) of the size \fBsize\fR. However, there is no correction of data like
741 .\" in \fBdialog_ftree\fR. Thus, to display a correct tree, the array must
742 .\" already contain correct data. Besides, in each session every unique use of
743 .\" \fBdialog_tree\fR is kept in memory, and later, when calling
744 .\" \fBdialog_tree\fR with the same \fBnames\fR, \fBsize\fR, \fBFS\fR,
745 .\" \fBheight\fR, \fBwidth\fR and \fBmenu_height\fR the position of the cursor
746 .\" in the tree subwindow is restored.
751 The primary author would appear to be
752 .An Savio Lam Aq lam836@cs.cuhk.hk
753 with contributions over the years by
754 .An Stuart Herbert Aq S.Herbert@sheffield.ac.uk ,
755 .An Marc van Kempen Aq wmbfmk@urc.tue.nl ,
756 .An Andrey Chernov Aq ache@FreeBSD.org ,
757 .An Jordan Hubbard Aq jkh@FreeBSD.org
759 .An Anatoly A. Orehovsky Aq tolik@mpeks.tomsk.su .
761 These functions appeared in
765 command and were soon split into a separate library
768 .An Marc van Kempen implemented most of the
769 extra controls and objects,
771 added the dialogMenuItem renovations and this man page and
772 .An Anatoly A. Orehovsky