DIALOG(3) BSD Library Functions Manual 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 fixed-
presentation menus, input boxes, gauges, file requestors and other gen‐
eral purpose GUI (a bit of a stretch, since it uses ncurses) objects.
Since the library also had its roots in a shell-script writer'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 inter‐
nals 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-explanatory, 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 object and user
code is required. The selected hook also allows you to verify whether or
not a given item is selected (the cursor is over it) for implementing
pretty much any possible context-sensitive behavior. A number of clever
tricks for simulating various kinds of item types can also be done by
adjusting the values of lbra (default: '['), mark (default: '*' for radio
menus, 'X' for check menus) and rbra (default: ']') and declaring a rea‐
sonable checked hook, which should return TRUE for the “marked” state and
FALSE for “unmarked”. The aux field is not used internally, 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 "toggled" in some
way and should return one of the following codes:
#define DITEM_SUCCESS 0 /* Successful completion */
#define DITEM_FAILURE 1 /* Failed to "fire" */
The following flags are in the upper 16 bits of return status:
#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:
draw_shadow() draws a shadow in curses window win using the dimensions of
x, y, width and height.
draw_box() draws a bordered box using the dimensions 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.
line_edit() invoke 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 optionally 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.
strheight() returns the height of string in p, counting newlines.
strwidth() returns the width of string in p, counting newlines.
dialog_create_rc() dump dialog library settings into filename for later
retrieval as defaults. Returns 0 on success, -1 on failure.
dialog_yesno() display 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.
dialog_noyes() is the same as dialog_yesno(), except the default selec‐
tion is No.
dialog_prgbox() display a text box of dimensions height and width con‐
taining 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 execu‐
tion terminates. Returns 0 on success, -1 on failure.
dialog_textbox() display a text box containing the contents of file with
dimensions of height and width.
dialog_menu() display 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 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 struc‐
ture 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 default 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.
Using either API behavior, the ch and sc values may be passed in to pre‐
serve current item selection and scroll position values across calls.
dialog_checklist() display a menu of dimensions height and width with an
optional internal menu height of list_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
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 default OK and Cancel but‐
tons 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 denote 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 preserve "check‐
list" 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 behav‐
ior. The only reason to call dialog_checklist() over dialog_radiolist()
in the new API model is to inherit the base behavior, you're no longer
constrained by it.
Returns 0 on success, 1 on Cancel, and -1 on failure or ESC.
dialog_radiolist() display a menu of dimensions height and width with an
optional internal menu height of list_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
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 default OK and Cancel but‐
tons 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 preserve "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.
dialog_inputbox() displays a single-line text input field in a box dis‐
playing title and prompt of dimensions height and width. The field
entered is stored in result.
Returns 0 on success, -1 on failure or ESC.
dialog_fselect() brings up a file selector dialog starting at dir and
showing only those file names matching fmask.
Returns filename selected or NULL.
dialog_dselect() brings up a directory selector dialog starting at dir
and showing only those directory names matching fmask.
Returns directory name selected or NULL.
dialog_notify() brings up a generic "hey, you!" notifier dialog contain‐
ing msg.
dialog_mesgbox() like 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.
dialog_gauge() displays a horizontal bar-graph style gauge. A value of
100 for perc constitutes a full gauge, a value of 0 an empty one.
use_helpfile() for any menu supporting context sensitive help, invoke the
text box object on this file whenever the F1 key is pressed.
use_helpline() displays this line of helpful text below any menu being
displayed.
get_helpline() get the current value of the helpful text line.
dialog_clear_norefresh() clear the screen back to the dialog background
color, but don't refresh the contents just yet.
dialog_clear() clear the screen back to the dialog background color imme‐
diately.
dialog_update() do any pending screen refreshes now.
init_dialog() initialize the dialog library (call this routine before any
other dialog API calls).
end_dialog() shut down the dialog library (call this if you need to get
back to sanity).
dialog_ftree() 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 pos‐
itive numbers, they set the absolute size of the whole dialog_ftree()
box. If height and width are negative numbers, 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 ‘\n’ 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 selected, the
function returns 1. In case of exiting dialog_ftree() on ESC, the func‐
tion returns -1.
dialog_tree() function returns the same results as dialog_ftree(). If 0
is returned, result will contain a pointer from the array names.
SEE ALSOdialog(1), ncurses(3)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⟩.
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 objects, Jordan
Hubbard added the dialogMenuItem renovations and this man page and
Anatoly A. Orehovsky implemented dialog_ftree() and dialog_tree().
BUGS
Sure!
BSD January 1, 2000 BSD
