dialog(3)

NAME

draw_shadow, draw_box, line_edit, strheight, strwidth,
dialog_create_rc,
dialog_yesno, dialog_noyes, dialog_prgbox, dialog_msgbox,
dialog_textbox,
dialog_menu, dialog_checklist, dialog_radiolist,
dialog_inputbox,
dialog_clear_norefresh, dialog_clear, dialog_update,
dialog_fselect,
dialog_notify, dialog_mesgbox, dialog_gauge, init_dialog,
end_dialog,
use_helpfile, use_helpline, get_helpline, restore_helpline,
dialog_ftree,
dialog_tree - provide a simple ncurses-based GUI interface

SYNOPSIS

#include <dialog.h>
void
draw_shadow(WINDOW *win, int  y,  int  x,  int  height,  int
width);
void
draw_box(WINDOW  *win,  int y, int x, int height, int width,
chtype box,
        chtype border);
int
line_edit(WINDOW *dialog, int box_y, int  box_x,  int  flen,
int box_width,
        chtype  attr,  int first, unsigned char *result, int
attr_mask);
int
strheight(const char *p);
int
strwidth(const char *p);
void
dialog_create_rc(unsigned char *filename);
int
dialog_yesno(unsigned char *title,  unsigned  char  *prompt,
int height,
        int width);
int
dialog_noyes(unsigned  char  *title,  unsigned char *prompt,
int height,
        int width);
int
dialog_prgbox(unsigned  char  *title,  const  unsigned  char
*line,
        int height, int width, int pause, int use_shell);
int
dialog_textbox(unsigned  char  *title,  unsigned char *file,
int height,
        int width);
int
dialog_menu(unsigned char *title, unsigned char *prompt, int
height,
        int width, int menu_height, int cnt, void *it,
        unsigned char *result, int *ch, int *sc);
int
dialog_checklist(unsigned   char   *title,   unsigned   char
*prompt, int height,
        int width, int list_height, int cnt, void *it,
        unsigned char *result);
int
dialog_radiolist(unsigned   char   *title,   unsigned   char
*prompt, int height,
        int width, int list_height, int cnt, void *it,
        unsigned char *result);
int
dialog_inputbox(unsigned char *title, unsigned char *prompt,
int height,
        int width, unsigned char *result);
char *
dialog_fselect(char *dir, char *fmask);
int
dialog_dselect(char *dir, char *fmask);
void
dialog_notify(char *msg);
int
dialog_mesgbox(unsigned char *title, unsigned char  *prompt,
int height,
        int width);
void
dialog_gauge(char  *title,  char  *prompt, int y, int x, int
height,
        int width, int perc);
void
use_helpfile(char *hfile);
void
use_helpline(char *hline);
char *
get_helpline(void);
void
dialog_clear_norefresh(void);
void
dialog_clear(void);
void
dialog_update(void);
void
init_dialog(void);
void
end_dialog(void);
int
dialog_ftree(unsigned char *filename, unsigned char FS,
        unsigned char *title,  unsigned  char  *prompt,  int
height,
        int width, int menu_height, unsigned char **result);
int
dialog_tree(unsigned char **names, int size,  unsigned  char
FS,
        unsigned  char  *title,  unsigned  char *prompt, int
height,
        int width, int menu_height, unsigned char **result);

DESCRIPTION

The dialog library attempts to provide a fairly simplistic
set of fixedpresentation menus, input boxes, gauges, file requestors and
other general purpose GUI (a bit of a stretch, since it uses ncurses)
objects. Since the library also had its roots in a shell-script writ
er's utility (see the dialog(1) command), the early API was somewhat
primitively based on strings being passed in or out and parsed. This API was
later extended to take either the original arguments or arrays of dialogMenuItem structures, giving the user much more control
over the internal behavior of each control. The dialogMenuItem
structure internals are public:: typedef struct _dmenu_item {
char *prompt;
char *title;
int (*checked)(struct _dmenu_item *self);
int (*fire)(struct _dmenu_item *self);
int (*selected)(struct _dmenu_item *self, int

is_selected);
void *data;
char lbra, mark, rbra;
long aux;; } dialogMenuItem;
The prompt and title strings are pretty much self-explanato
ry, and the checked and fire function pointers provide optional display
and action hooks (the data variable being available for the convenience
of those hooks) when more tightly coupled feedback between a menu ob
ject and user code is required. The selected hook also allows you to ver
ify whether or not a given item is selected (the cursor is over it) for im
plementing pretty much any possible context-sensitive behavior. A num
ber of clever tricks for simulating various kinds of item types can also
be done by adjusting the values of lbra (default: '['), mark (default: menus, 'X' for check menus) and rbra (default: ']') and
declaring a reasonable checked hook, which should return TRUE for the
``marked'' state and FALSE for ``unmarked''. The aux field is not used in
ternally, and is available for miscellaneous usage. If an item has a fire
hook associated with it, it will also be called whenever the item is "tog
gled" in some way and should return one of the following codes:: #define DITEM_SUCCESS 0 /* Successful com; pletion */
#define DITEM_FAILURE 1 /* Failed to "fire"; */
The following flags are in the upper 16 bits of return sta
tus:: #define DITEM_LEAVE_MENU (1 << 16)
#define DITEM_REDRAW (1 << 17)
#define DITEM_RECREATE (1 << 18)
#define DITEM_RESTORE (1 << 19)
#define DITEM_CONTINUE (1 << 20)
Two special globals also exist for putting a dialog at any
arbitrary X,Y location (the early designers rather short-sightedly made no
provisions for this). If set to zero, the default centering behavior
will be in effect.
Below is a short description of the various functions:
The draw_shadow() function draws a shadow in curses window
win using the dimensions of x, y, width and height.
The draw_box() function draws a bordered box using the di
mensions of x, y, width and height. The attributes from box and border are
used, if specified, while painting the box and border regions of the
object.
The line_edit() function invokes a simple line editor with
an edit box of
dimensions box_x, box_y and box_width. The field length is
constrained by flen, starting at the first character specified and op
tionally displayed with character attributes attr. The string being
edited is stored in result. Returns 0 on success, 1 on Cancel, and -1 on
failure or ESC.
The strheight() function returns the height of string in p,
counting newlines.
The strwidth() function returns the width of string in p,
counting newlines.
The dialog_create_rc() function dumps dialog library set
tings into filename for later retrieval as defaults. Returns 0 on suc
cess, -1 on failure.
The dialog_yesno() function displays a text box using title
and prompt strings of dimensions height and width. Also paint a pair
of Yes and No buttons at the bottom. The default selection is Yes. If
the Yes button is chosen, return FALSE. If No, return TRUE.
The dialog_noyes() function is the same as dialog_yesno(),
except the default selection is No.
The dialog_prgbox() function displays a text box of dimen
sions height and
width containing the output of command line. If use_shell
is TRUE, line is passed as an argument to sh(1), otherwise it is simply
passed to exec(3). If pause is TRUE, a final confirmation requestor
will be put up when execution terminates. Returns 0 on success, -1 on
failure.
The dialog_textbox() function displays a text box containing
the contents of file with dimensions of height and width.
The dialog_menu() function displays a menu of dimensions
height and width
with an optional internal menu height of menu_height. The
cnt and it arguments are of particular importance since they, together,
determine which of the 2 available APIs to use. To use the older and
traditional interface, cnt should be a positive integer representing the
number of string pointer pairs to find in it (which should be of type
char **), the
strings are expected to be in prompt and title order for
each item and the result parameter is expected to point to an array where
the prompt string of the item selected will be copied. To use the new
er interface, cnt should be a negative integer representing the number of dialogMenuItem structures pointed to by it (which should be
of type dialogMenuItem *), one structure per item. In the new in
terface, the result variable is used as a simple boolean (not a pointer)
and should be NULL if it only points to menu items and the default OK and
Cancel buttons are desired. If result is non-NULL, then it is actual
ly expected to point 2 locations past the start of the menu item list. it
is then expected to point to an item representing the Cancel button,
from which the prompt and fire actions are used to override the default
behavior, and it to the same for the OK button.
Using either API behavior, the ch and sc values may be
passed in to preserve current item selection and scroll position values
across calls.
The dialog_checklist() function displays a menu of dimen
sions height and
width with an optional internal menu height of list_height.
The cnt and it arguments are of particular importance since they, to
gether, determine which of the 2 available APIs to use. To use the older and
traditional interface, cnt should be a positive integer representing the
number of string pointer tuples to find in it (which should be of type
char **),
the strings are expected to be in prompt, title and state
("on" or "off") order for each item and the result parameter is expected to
point to an array where the prompt string of the item(s) selected will
be copied. To use the newer interface, cnt should be a negative integer
representing the number of dialogMenuItem structures pointed to by it
(which should be of type dialogMenuItem *), one structure per item. In the
new interface, the result variable is used as a simple boolean (not a
pointer) and should be NULL if it only points to menu items and the de
fault OK and Cancel buttons are desired. If result is non-NULL, then it
is actually expected to point 2 locations past the start of the menu
item list. it is then expected to point to an item representing the Cancel
button, from which the prompt and fire actions are used to override the
default behavior, and it to the same for the OK button.
In the standard API model, the menu supports the selection
of multiple items, each of which is marked with an `X' character to de
note selection. When the OK button is selected, the prompt values for all
items selected are concatenated into the result string.
In the new API model, it is not actually necessary to pre
serve "checklist" semantics at all since practically everything about
how each item is displayed or marked as "selected" is fully configurable.
You could have a single checklist menu that actually contained a group
of items with "radio" behavior, "checklist" behavior and standard
menu item behavior. The only reason to call dialog_checklist() over
dialog_radiolist()
in the new API model is to inherit the base behavior, you
are no longer constrained by it.
Returns 0 on success, 1 on Cancel, and -1 on failure or ESC.
The dialog_radiolist() function displays a menu of dimen
sions height and
width with an optional internal menu height of list_height.
The cnt and it arguments are of particular importance since they, to
gether, determine which of the 2 available APIs to use. To use the older and
traditional interface, cnt should be a positive integer representing the
number of string pointer tuples to find in it (which should be of type
char **),
the strings are expected to be in prompt, title and state
("on" or "off") order for each item and the result parameter is expected to
point to an array where the prompt string of the item(s) selected will
be copied. To use the newer interface, cnt should be a negative integer
representing the number of dialogMenuItem structures pointed to by it
(which should be of type dialogMenuItem *, one structure per item. In the
new interface, the result variable is used as a simple boolean (not a
pointer) and should be NULL if it only points to menu items and the de
fault OK and Cancel buttons are desired. If result is non-NULL, then it
is actually expected to point 2 locations past the start of the menu
item list. it is then expected to point to an item representing the Cancel
button, from which the prompt and fire actions are used to override the
default behavior, and it does the same for the traditional OK button.
In the standard API model, the menu supports the selection
of only one of multiple items, the currently active item marked with an `*'
character to denote selection. When the OK button is selected, the
prompt value for this item is copied into the result string.
In the new API model, it is not actually necessary to pre
serve "radio button" semantics at all since practically everything about
how each item is displayed or marked as "selected" is fully configurable.
You could have a single radio menu that actually contained a group of
items with "checklist" behavior, "radio" behavior and standard menu
item behavior.
The only reason to call dialog_radiolist() over
dialog_checklistlist() in
the new API model is to inherit the base behavior.
Returns 0 on success, 1 on Cancel and -1 on failure or ESC.
The dialog_inputbox() function displays a single-line text
input field in a box displaying title and prompt of dimensions height and
width. The field entered is stored in result.
Returns 0 on success, -1 on failure or ESC.
The dialog_fselect() function brings up a file selector dia
log starting at dir and showing only those file names matching fmask.
Returns filename selected or NULL.
The dialog_dselect() function brings up a directory selector
dialog starting at dir and showing only those directory names
matching fmask.
Returns directory name selected or NULL.
The dialog_notify() function brings up a generic "hey, you!"
notifier dialog containing msg.
The dialog_mesgbox() function displays a notifier dialog,
but with more control over title, prompt, width and height. This object
will also wait
for user confirmation, unlike dialog_notify().
Returns 0 on success, -1 on failure.
The dialog_gauge() function displays a horizontal bar-graph
style gauge. A value of 100 for perc constitutes a full gauge, a value of
0 an empty one.
The use_helpfile() function for any menu supporting context
sensitive help, invokes the text box object on this file whenever the
F1 key is pressed.
The use_helpline() function displays this line of helpful
text below any menu being displayed.
The get_helpline() function gets the current value of the
helpful text line.
The dialog_clear_norefresh() function clears the screen back
to the dialog background color, but do not refresh the contents just
yet.
The dialog_clear() function clears the screen back to the
dialog background color immediately.
The dialog_update() function does any pending screen re
freshes now.
The init_dialog() function initializes the dialog library
(call this routine before any other dialog API calls).
The end_dialog() function shuts down the dialog library
(call this if you need to get back to sanity).
The dialog_ftree() function shows a tree described by the
data from the file filename. The data in the file should look like
find(1) output. For the find(1) output, the field separator FS will be
``/''. If height and width are positive numbers, they set the absolute size
of the whole
dialog_ftree() box. If height and width are negative num
bers, the size
of the dialog_ftree() box will be calculated automatically.
menu_height
sets the height of the tree subwindow inside the
dialog_ftree() box and
must be set. title is shown centered on the upper border of
the
dialog_ftree() box. prompt is shown inside the
dialog_ftree() box above
the tree subwindow and can contain `0 to split lines. One
can navigate in the tree by pressing UP/DOWN or `+'/`-', PG_UP/PG_DOWN or
`b'/SPACE and HOME/END or `g'/`G'. A leaf of the tree is selected by
pressing TAB or LEFT/RIGHT the OK button and pressing ENTER. filename
may contain data like find(1) output, as well as like the output of
find(1) with -d option. Some of the transient paths to the leaves of the
tree may be absent. Such data is corrected when fed from filename.
The function returns 0 and a pointer to the selected leaf
(to the path to the leaf from the root of the tree) into result, if the OK
button was selected. The memory allocated for the building of the tree
is freed on
exiting dialog_ftree(). The memory for the result line
should be freed later manually, if necessary. If the Cancel button was se
lected, the
function returns 1. In case of exiting dialog_ftree() on
ESC, the function returns -1.
The dialog_tree() function returns the same results as
dialog_ftree().
If 0 is returned, result will contain a pointer from the ar
ray names.

HISTORY

These functions appeared in FreeBSD 2.0 as the dialog(1)
command and were soon split into a separate library and command by Andrey
Chernov. Marc van Kempen implemented most of the extra controls and ob
jects, Jordan Hubbard added the dialogMenuItem renovations and this man
page and
Anatoly A. Orehovsky implemented dialog_ftree() and
dialog_tree().

AUTHORS

The primary author would appear to be Savio Lam
<lam836@cs.cuhk.hk> with contributions over the years by Stuart Herbert <S.Herbert@sheffield.ac.uk>, Marc van Kempen
<wmbfmk@urc.tue.nl>, Andrey Chernov <ache@FreeBSD.org>, Jordan Hubbard <jkh@FreeBSD.org>
and Anatoly A. Orehovsky <tolik@mpeks.tomsk.su>.

BUGS

Sure!
BSD January 1, 2000

docs.sk

comprehensive documentation repository

See also

dialog(3)

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO

HISTORY

AUTHORS

BUGS