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
147 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
153 This API was later extended to take either the
154 original arguments or arrays of
157 giving the user much more control over the internal behavior of each
161 structure internals are public:
162 .Bd -literal -offset indent
163 typedef struct _dmenu_item {
166 int (*checked)(struct _dmenu_item *self);
167 int (*fire)(struct _dmenu_item *self);
168 int (*selected)(struct _dmenu_item *self, int is_selected);
170 char lbra, mark, rbra;
179 strings are pretty much self-explanatory,
184 function pointers provide optional
185 display and action hooks (the
187 variable being available for
188 the convenience of those hooks) when more tightly coupled feedback between
189 a menu object and user code is required.
193 allows you to verify whether or not a given item is selected (the cursor is
194 over it) for implementing pretty much any possible context-sensitive
196 A number of clever tricks for simulating various kinds of item
197 types can also be done by adjusting the values of
201 (default: '*' for radio menus, 'X' for check menus)
204 (default: ']') and declaring a reasonable
207 which should return TRUE for the
213 field is not used internally, and is available for miscellaneous usage.
216 hook associated with it, it will also be called
217 whenever the item is "toggled" in some way and should return one of the
219 .Bd -literal -offset 4n
220 #define DITEM_SUCCESS 0 /* Successful completion */
221 #define DITEM_FAILURE 1 /* Failed to "fire" */
224 The following flags are in the upper 16 bits of return status:
225 .Bd -literal -offset 4n
226 #define DITEM_LEAVE_MENU (1 << 16)
227 #define DITEM_REDRAW (1 << 17)
228 #define DITEM_RECREATE (1 << 18)
229 #define DITEM_RESTORE (1 << 19)
230 #define DITEM_CONTINUE (1 << 20)
233 Two special globals also exist for putting a dialog at any arbitrary
234 X,Y location (the early designers rather short-sightedly made no provisions
236 If set to zero, the default centering behavior will be in
239 Below is a short description of the various functions:
243 function draws a shadow in curses window
245 using the dimensions of
252 function draws a bordered box using the dimensions of
260 are used, if specified, while painting the box and border regions of the
265 function invokes a simple line editor with an edit box of dimensions
269 The field length is constrained by
273 character specified and
274 optionally displayed with character attributes
276 The string being edited is stored in
278 Returns 0 on success, 1 on Cancel, and -1 on failure or ESC.
282 function returns the height of string in
288 function returns the width of string in
294 function dumps dialog library settings into
296 for later retrieval as defaults.
297 Returns 0 on success, -1 on failure.
301 function displays a text box using
305 strings of dimensions
313 buttons at the bottom.
314 The default selection is
318 button is chosen, return FALSE.
325 function is the same as
327 except the default selection is
332 function displays a text box of dimensions
336 containing the output of command
342 is passed as an argument to
344 otherwise it is simply passed to
348 is TRUE, a final confirmation requestor will be put up when execution
350 Returns 0 on success, -1 on failure.
354 function displays a text box containing the contents of
363 function displays a menu of dimensions
367 with an optional internal menu height of
373 arguments are of particular importance since they,
374 together, determine which of the 2 available APIs to use.
376 older and traditional interface,
379 integer representing the number of string pointer pairs to find in
381 (which should be of type
384 expected to be in prompt and title order for each item and the
386 parameter is expected to point to an array where the
387 prompt string of the item selected will be copied.
393 integer representing the number of
395 structures pointed to by
397 (which should be of type
398 .Vt dialogMenuItem "*" ) ,
399 one structure per item.
400 In the new interface, the
402 variable is used as a simple boolean (not a pointer) and should be NULL if
404 only points to menu items and the default OK and Cancel buttons are desired.
409 is actually expected to point 2 locations
411 the start of the menu item list.
414 point to an item representing the Cancel button, from which the
418 actions are used to override the default behavior, and
420 to the same for the OK button.
422 Using either API behavior, the
426 values may be passed in to preserve current
427 item selection and scroll position values across calls.
431 function displays a menu of dimensions
436 optional internal menu height of
442 arguments are of particular importance since they,
443 together, determine which of the 2 available APIs to use.
445 older and traditional interface,
448 integer representing the number of string pointer tuples to find in
450 (which should be of type
453 expected to be in prompt, title and state ("on" or "off") order for
456 parameter is expected to point to an
457 array where the prompt string of the item(s) selected will be
459 To use the newer interface,
463 integer representing the number of
465 structures pointed to by
467 (which should be of type
468 .Ft "dialogMenuItem *" ) ,
469 one structure per item.
470 In the new interface,
473 variable is used as a simple boolean (not a pointer)
474 and should be NULL if
476 only points to menu items and the default OK and Cancel
482 is actually expected to
485 the start of the menu item list.
487 is then expected to point to an item representing the Cancel
488 button, from which the
492 actions are used to override the default behavior, and
494 to the same for the OK button.
496 In the standard API model, the menu supports the selection of multiple items,
497 each of which is marked with an `X' character to denote selection.
499 the OK button is selected, the prompt values for all items selected are
500 concatenated into the
504 In the new API model, it is not actually necessary to preserve
505 "checklist" semantics at all since practically everything about how
506 each item is displayed or marked as "selected" is fully configurable.
507 You could have a single checklist menu that actually contained a group
508 of items with "radio" behavior, "checklist" behavior and standard menu
510 The only reason to call
514 in the new API model is to inherit the base
515 behavior, you are no longer constrained by it.
517 Returns 0 on success, 1 on Cancel, and -1 on failure or ESC.
521 function displays a menu of dimensions
526 optional internal menu height of
532 arguments are of particular importance since they,
533 together, determine which of the 2 available APIs to use.
535 older and traditional interface,
538 integer representing the number of string pointer tuples to find in
540 (which should be of type
543 expected to be in prompt, title and state ("on" or "off") order for
546 parameter is expected to point to an
547 array where the prompt string of the item(s) selected will be
549 To use the newer interface,
553 integer representing the number of
555 structures pointed to by
557 (which should be of type
558 .Ft "dialogMenuItem *" ,
559 one structure per item.
560 In the new interface,
563 variable is used as a simple boolean (not a pointer)
564 and should be NULL if
566 only points to menu items and the default OK and Cancel
572 is actually expected to point 2 locations
574 the start of the menu item list.
576 is then expected to point to an item representing the Cancel
577 button, from which the
581 actions are used to override the default behavior, and
583 does the same for the traditional OK button.
585 In the standard API model, the menu supports the selection of only one
586 of multiple items, the currently active item marked with an `*'
587 character to denote selection.
588 When the OK button is selected, the
589 prompt value for this item is copied into the
593 In the new API model, it is not actually necessary to preserve
594 "radio button" semantics at all since practically everything about how
595 each item is displayed or marked as "selected" is fully configurable.
596 You could have a single radio menu that actually contained a group
597 of items with "checklist" behavior, "radio" behavior and standard menu
599 The only reason to call
602 .Fn dialog_checklistlist
603 in the new API model is to inherit the base
606 Returns 0 on success, 1 on Cancel and -1 on failure or ESC.
610 function displays a single-line text input field in a box displaying
618 The field entered is stored in
621 Returns 0 on success, -1 on failure or ESC.
625 function brings up a file selector dialog starting at
627 and showing only those file names
631 Returns filename selected or NULL.
635 function brings up a directory selector dialog starting at
637 and showing only those directory names
641 Returns directory name selected or NULL.
645 function brings up a generic "hey, you!" notifier dialog containing
650 function displays a notifier dialog, but with more control over
656 This object will also wait for user confirmation, unlike
659 Returns 0 on success, -1 on failure.
663 function displays a horizontal bar-graph style gauge.
668 constitutes a full gauge, a value of
674 function for any menu supporting context sensitive help, invokes the text box
675 object on this file whenever the
681 function displays this line of helpful text below any menu being displayed.
685 function gets the current value of the helpful text line.
688 .Fn dialog_clear_norefresh
689 function clears the screen back to the dialog background color, but do not
690 refresh the contents just yet.
694 function clears the screen back to the dialog background color immediately.
698 function does any pending screen refreshes now.
702 function initializes the dialog library (call this routine before any other
707 function shuts down the dialog library (call this if you need to get back to
712 function shows a tree described by the data from the file
714 The data in the file should look like
719 output, the field separator
727 are positive numbers, they set the absolute
735 are negative numbers, the size of the
737 box will be calculated automatically.
739 sets the height of the tree subwindow inside the
743 is shown centered on the upper border of the
749 box above the tree subwindow and can contain
753 the tree by pressing UP/DOWN or
755 .So \&+ Sc \&/ So \&- Sc ,
764 .So g Sc \&/ So G Sc .
767 tree is selected by pressing TAB or LEFT/RIGHT the OK
768 button and pressing ENTER.
769 filename may contain data like
771 output, as well as like the output of
776 Some of the transient paths to the leaves of the tree may
778 Such data is corrected when fed from filename.
780 The function returns 0 and a pointer to the selected leaf (to the path to
781 the leaf from the root of the tree) into result, if the OK button was
783 The memory allocated for the building of the tree is freed on
786 The memory for the result line should be freed
787 later manually, if necessary.
788 If the Cancel button was selected, the
792 on ESC, the function returns -1.
796 function returns the same results as
798 If 0 is returned, result will contain a pointer from the array
800 .\" \fBdialog_tree\fR displays the tree very much like \fBdialog_ftree\fR does,
801 .\" with some exceptions. The source data for the building of the tree is an
802 .\" array \fBnames\fR of paths to the leaves (should be similar to \fBfind(1)\fR
803 .\" output) of the size \fBsize\fR. However, there is no correction of data like
804 .\" in \fBdialog_ftree\fR. Thus, to display a correct tree, the array must
805 .\" already contain correct data. Besides, in each session every unique use of
806 .\" \fBdialog_tree\fR is kept in memory, and later, when calling
807 .\" \fBdialog_tree\fR with the same \fBnames\fR, \fBsize\fR, \fBFS\fR,
808 .\" \fBheight\fR, \fBwidth\fR and \fBmenu_height\fR the position of the cursor
809 .\" in the tree subwindow is restored.
814 These functions appeared in
818 command and were soon split into a separate library
822 implemented most of the extra controls and objects,
824 added the dialogMenuItem renovations and this man page and
825 .An Anatoly A. Orehovsky
832 The primary author would appear to be
833 .An Savio Lam Aq lam836@cs.cuhk.hk
834 with contributions over the years by
835 .An Stuart Herbert Aq S.Herbert@sheffield.ac.uk ,
836 .An Marc van Kempen Aq wmbfmk@urc.tue.nl ,
837 .An Andrey Chernov Aq ache@FreeBSD.org ,
838 .An Jordan Hubbard Aq jkh@FreeBSD.org
840 .An Anatoly A. Orehovsky Aq tolik@mpeks.tomsk.su .