dialog(3)

NAME
draw_shadow, draw_box, line_edit, strheight, strwidth, dialog_create_rc, dialog_yesno, 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 - Provide a simple ncurses-based GUI interface.

DESCRIPTION
The dialog library attempts to provide a fairly simplistic set of fixed-presentation 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 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 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;
} 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: '['), rk (default: '*' for radio 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.' 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" */
#define DITEM_LEAVE_MENU        -2      /* Treat selection as "Ok" */
#define DITEM_REDRAW            -3      /* Menu has changed, redraw it */
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.

SYNOPSIS
#include <dialog.h>
void
draw_shadow(WINDOW *win, int y, int x, int height, int width);
Draws a shadow in curses window win using the dimensions of x, y, width and height. Returns 0 on success, -1 on failure.
void
draw_box(WINDOW *win, int y, int x, int height, int width, chtype box, chtype border);
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.
int
line_edit(WINDOW *dialog, int box_y, int box_x, int flen, int box_width, chtype attrs, int first, unsigned char *result, int attr_mask);
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 attrs. The string being edited is stored in result. Returns 0 on success, -1 on failure.
int
strheight(const char *p);
Returns the height of string in p, counting newlines.
int
strwidth(const char *p);
Returns the width of string in p, counting newlines.
void
dialog_create_rc(unsigned char *filename);
Dump dialog library settings into filename for later retreival as defaults. Returns 0 on success, -1 on failure.
int
dialog_yesno(unsigned char *title, unsigned char *prompt, int height, int width);
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. If the Yes button is chosen, return FALSE. If No, return TRUE.
int
dialog_prgbox(unsigned char *title, const unsigned char *line, int height, int width, int pause, int use_shell);
Display a text box of dimensions 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.
int
dialog_textbox(unsigned char *title, unsigned char *prompt, int height, int width);
Display a text box containing the contents of string prompt of dimensions height and width. Returns 0 on success, -1 on failure.
int
dialog_menu(unsigned char *title, unsigned char *prompt, int height, int width, int menu_height, int item_no, void *itptr, unsigned char *result, int *ch, int *sc);
Display a menu of dimensions height and width with an optional internal menu height of menu_height. The item_no and itptr arguments are of particular importance since they, together, determine which of the 2 available APIs to use. To use the older and traditional interface, item_no should be a positive integer representing the number of string pointer pairs to find in itptr (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, item_no should be a negative integer representing the number of dialogMenuItem structures pointed to by itptr (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 itptr only points to menu items and the default OK and Cancel buttons are desired. If result is non-NULL, then itptr is actually expected to point 2 locations past the start of the menu item list. itptr[-1] 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 itptr[-2] 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. Returns 0 on success, 1 on Cancel and -1 on failure or ESC.
int
dialog_checklist(unsigned char *title, unsigned char *prompt, int height, int width, int m_height, int item_no, void *itptr, unsigned char *result);
Display a menu of dimensions height and width with an optional internal menu height of menu_height. The item_no and itptr arguments are of particular importance since they, together, determine which of the 2 available APIs to use. To use the older and traditional interface, item_no should be a positive integer representing the number of string pointer tuples to find in itptr (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, item_no should be a negative integer representing the number of dialogMenuItem structures pointed to by itptr (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 itptr only points to menu items and the default OK and Cancel buttons are desired. If result is non-NULL, then itptr is actually expected to point 2 locations past the start of the menu item list. itptr[-1] 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 itptr[-2] 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 "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're no longer constrained by it. Returns 0 on success, 1 on Cancel and -1 on failure or ESC.
int
dialog_radiolist(unsigned char *title, unsigned char *prompt, int height, int width, int m_height, int item_no, void *it, unsigned char *result);
Display a menu of dimensions height and width with an optional internal menu height of menu_height. The item_no and itptr arguments are of particular importance since they, together, determine which of the 2 available APIs to use. To use the older and traditional interface, item_no should be a positive integer representing the number of string pointer tuples to find in itptr (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, item_no should be a negative integer representing the number of dialogMenuItem structures pointed to by itptr (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 itptr only points to menu items and the default OK and Cancel buttons are desired. If result is non-NULL, then itptr is actually expected to point 2 locations past the start of the menu item list. itptr[-1] 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 itptr[-2] 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.
int
dialog_inputbox(unsigned char *title, unsigned char *prompt, int height, int width, unsigned char *result);
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.
char *
dialog_fselect(char *dir, char *fmask);
Brings up a file selector dialog starting at dir and showing only those file names matching fmask. Returns filename selected or NULL.
int
dialog_dselect(char *dir, char *fmask);
Brings up a directory selector dialog starting at dir and showing only those directory names matching fmask. Returns directory name selected or NULL.
void
dialog_notify(char *msg);
Bring up a generic "hey, you!" notifier dialog containing msg.
int
dialog_mesgbox(unsigned char *title, unsigned char *prompt, int height, int width);
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.
void
dialog_gauge(char *title, char *prompt, int y, int x, int height, int width, int perc);
Display a horizontal bar-graph style gauge. A value of 100 for perc constitutes a full gauge, a value of 0 an empty one.
void
use_helpfile(char *helpfile);
For any menu supporting context sensitive help, invoke the text box object on this file whenever the F1 key is pressed.
void
use_helpline(char *helpline);
Display this line of helpful text below any menu being displayed.
char *
get_helpline(void);
Get the current value of the helpful text line.
void
dialog_clear_norefresh(void);
Clear the screen back to the dialog background color, but don't refresh the contents just yet.
void
dialog_clear(void);
Clear the screen back to the dialog background color immediately.
void
dialog_update(void);
Do any pending screen refreshes now.
void
init_dialog(void);
Initialize the dialog library (call this routine before any other dialog API calls).
void
end_dialog(void);
Shut down the dialog library (call this if you need to get back to sanity).

SEE ALSO
dialog(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> and Jordan Hubbard <jkh@freebsd.org>.

HISTORY
These functions appeared in FreeBSD-2.0 as the dialog(1) command and were soon split into library and command by Andrey Chernov. Marc van Kempen implemented most of the extra controls and objects and Jordan Hubbard added the dialogMenuItem renovations and this man page.

BUGS
Sure!