Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
DIALOG(3)	       FreeBSD 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:

     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 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.

     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 optionally dis-
     played 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 new-
     lines.

     The strwidth() function returns the width of string in p, counting	new-
     lines.

     The dialog_create_rc() function dumps dialog library settings into
     filename for later	retrieval as defaults.	Returns	0 on success, -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 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.

     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 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.

     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.

     The dialog_checklist() function displays 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 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	behav-
     ior, 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 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	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 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	behav-
     ior, 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.

     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 dialog 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 dia-
     log background color, but do not refresh the contents just	yet.

     The dialog_clear()	function clears	the screen back	to the dialog back-
     ground color immediately.

     The dialog_update() function does any pending screen refreshes now.

     The init_dialog() function	initializes the	dialog library (call this rou-
     tine 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 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.

     The dialog_tree() function	returns	the same results as dialog_ftree().
     If	0 is returned, result will contain a pointer from the array names.

SEE ALSO
     dialog(1),	ncurses(3)

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().

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!

FreeBSD	6.0			January	1, 2000			   FreeBSD 6.0

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO | HISTORY | AUTHORS | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=dialog&sektion=3&manpath=FreeBSD+6.0-RELEASE>

home | help