Dialogs

The dialogs have common arguments. text is a string printed inside the dialog. Each char* parameter can be a multibyte character string depending on current locale, see setlocale(3). rows and cols are height and width, their value can be a fixed size, BSDDIALOG_AUTOSIZE or BSDDIALOG_FULLSCREEN. conf is a struct to customize the current dialog, it does not set global properties to the library.

struct bsddialog_conf {
	bool ascii_lines;
	unsigned int auto_minheight;
	unsigned int auto_minwidth;
	unsigned int auto_topmargin;
	unsigned int auto_downmargin;
	const char *bottomtitle;
	bool clear;
	int *get_height;
	int *get_width;
	bool no_lines;
	bool shadow;
	unsigned int sleep;
	const char *title;
	int y;
	int x;
	struct {
		bool enable_esc;
		const char *f1_file;
		const char *f1_message;
	} key;
	struct {
		unsigned int cols_per_row;
		bool escape;
		unsigned int tablen;
	} text;
	struct {
		bool align_left;
		bool no_desc;
		bool no_name;
		bool shortcut_buttons;
	} menu;
	struct {
		char securech;
		char *securembch;
		bool value_wchar;
	} form;
	struct {
		const char *format;
	} date;
	struct {
		bool always_active;
		const char *left1_label;
		const char *left2_label;
		const char *left3_label;
		bool without_ok;
		const char *ok_label;
		bool with_extra;
		const char *extra_label;
		bool without_cancel;
		const char *cancel_label;
		bool default_cancel;
		bool with_help;
		const char *help_label;
		const char *right1_label;
		const char *right2_label;
		const char *right3_label;
		const char *default_label;
	} button;
};

bsddialog_initconf() initializes conf disabling each property, except conf.shadow to true, conf.y and conf.x to BSDDIALOG_CENTER, conf.text.cols_per_row to 10.

bsddialog_calendar() builds a dialog to select a date. year, month, and day are default values on startup, selected date at exit.

bsddialog_checklist() builds dialogs to select some item from a list via the SPACE key, can be customized by conf.menu.*. See bsddialog_menu().

bsddialog_datebox() builds a dialog to select a date. year, month, and day are default values on startup, selected date at exit. The function can be customized by:

bsddialog_form() builds a dialog to display an array of items of nitems elements to get input strings. formrows is the graphical height for the items inside the dialog, 0 for autosizing. If not NULL focusitem is the default item index on startup and the last focused item at exit, a negative value if no item is focused. An item is defined like:

struct bsddialog_formitem {
	const char *label;
	unsigned int ylabel;
	unsigned int xlabel;

	const char *init;
	unsigned int yfield;
	unsigned int xfield;
	unsigned int fieldlen;
	unsigned int maxvaluelen;
	char *value;

	unsigned int flags;

	const char *bottomdesc;
};

label is a string to describe the request at the position ylabel and xlabel. The field for the input is at the position yfield and xfield, fieldlen is its graphical width, while maxvalelen is the maximum number of characters of the input string. init is the default field value. If no error occurs value is the allocated memory with the current field string at exit, its size depends on the current locale. flags is an OR value to set the field: BSDDIALOG_FIELDHIDDEN, BSDDIALOG_FIELDREADONLY, BSDDIALOG_FIELDNOCOLOR, BSDDIALOG_FIELDCURSOREND, BSDDIALOG_FIELDEXTEND, BSDDIALOG_FIELDSINGLEBYTE. bottomdesc is printed at bottom screen if the item is focused.

bsddialog_form() can be customized by:

bsddialog_gauge() builds a dialog with a bar to show perc. If the file descriptor fd is greater or equal to 0 the dialog waits to read sep from it, then the first string replaces perc and the following strings replace text until the next sep, the loop ends reading end.

bsddialog_infobox() builds a dialog without buttons and returns instantly.

bsddialog_menu() builds a dialog to select an item from a list via SPACE and ENTER. An item is defined like:

struct bsddialog_menuitem {
	const char *prefix;
	bool on;
	unsigned int depth;
	const char *name;
	const char *desc;
	const char *bottomdesc;
};

prefix, name and desc are printed at the item row. bottomdesc is printed at bottom screen if the item is focused. depth is a margin between prefix and name. At exit on is set to true if the item is selected, false otherwise. items is an array of items of nitem elements. menurows is the graphical height of the list inside the dialog, if cols is BSDDIALOG_AUTOSIZE menurows specifies a maximum value. if not NULL focusitem is the default item index on startup and the last focused item at exit, a negative value if no item is focused.

bsddialog_checklist(), bsddialog_menu(), bsddialog_mixedlist() and bsddialog_radiolist() can be customized by:

bsddialog_mixedgauge() builds a dialog with a main bar with the mainperc percentage and nminibars each one with a minilabel and a miniperc. miniperc can be: a positive value to print a bar with a percentace, a negative constant BSDDIALOG_MG_SUCCEEDED, BSDDIALOG_MG_FAILED, BSDDIALOG_MG_PASSED, BSDDIALOG_MG_COMPLETED, BSDDIALOG_MG_CHECKED, BSDDIALOG_MG_DONE, BSDDIALOG_MG_SKIPPED, BSDDIALOG_MG_INPROGRESS, BSDDIALOG_MG_BLANK to hide miniperc, BSDDIALOG_MG_NA, BSDDIALOG_MG_PENDING to print a descriptive string, otherwise “UNKNOWN” is printed.

bsddialog_mixedlist() builds a dialog with collections of checklists, radiolists and separators. A collection is a set defined like:

enum bsddialog_menutype {
	BSDDIALOG_CHECKLIST,
	BSDDIALOG_RADIOLIST,
	BSDDIALOG_SEPARATOR,
};

struct bsddialog_menugroup {
	enum bsddialog_menutype type;
	unsigned int nitems;
	struct bsddialog_menuitem *items;
	unsigned int min_on; /* unused for now */
};

groups is an array of sets of ngroups elements. menurows is the graphical height size for the list. If not NULL, focuslist and focusitem specify the default item on startup and the last focused item at exit, could be a negative value if no item is focused. The dialog can be customized by conf.menu.*, see bsddialog_menu().

bsddialog_msgbox() builds a dialog with OK button.

bsddialog_pause() builds a dialog waiting until the timeout in seconds expires or a button is pressed. At exit seconds is set like remaining time.

bsddialog_radiolist() builds dialogs to select at most an item from a list via the SPACE key, can be customized by conf.menu.*. See bsddialog_menu().

bsddialog_rangebox() to select a value between min and max. value is the default value on startup and the selected value at exit. The current value is printed inside a bar.

bsddialog_textbox() opens and prints file. TAB key changes button. Extra keys 0, h, l, k, j are available to navigate the text. “OK” button is renamed “EXIT”.

bsddialog_timebox() builds a dialog to choose a time. hh, mm, and ss are default values on startup, selected time at exit.

bsddialog_yesno() provides a dialog for a “Yes-No Question”, the labels on buttons are “Yes” and “&No”.

Keys

Ctrl-l

Redraw the dialog.

F1

Refer to conf.key.f1_file and conf.key.f1_message.

SPACE

Select menu item.

UP DOWN LEFT RIGHT - + HOME END PAGEUP PAGEDOWN Ctrl-p Ctrl-n TAB

Navigate elements and set value, depending on the dialog.

Theme

The graphical properties are global to the library. They are represented by struct bsddialog_theme and can be customized at runtime via the <bsddialog_theme.h> API.

struct bsddialog_theme {
	struct {
		int color;
	} screen;
	struct {
		int color;
		unsigned int y;
		unsigned int x;
	} shadow;
	struct {
		int  color;
		bool delimtitle;
		int  titlecolor;
		int  lineraisecolor;
		int  linelowercolor;
		int  bottomtitlecolor;
		int  arrowcolor;
	} dialog;
	struct {
		int f_prefixcolor;
		int prefixcolor;
		int f_selectorcolor;
		int selectorcolor;
		int f_namecolor;
		int namecolor;
		int f_desccolor;
		int desccolor;
		int f_shortcutcolor;
		int shortcutcolor;
		int bottomdesccolor;
		int sepnamecolor;
		int sepdesccolor;
	} menu;
	struct {
		int f_fieldcolor;
		int fieldcolor;
		int readonlycolor;
		int bottomdesccolor;
	} form;
	struct {
		int f_color;
		int color;
	} bar;
	struct {
		unsigned int minmargin;
		unsigned int maxmargin;
		char leftdelim;
		char rightdelim;
		int f_delimcolor;
		int delimcolor;
		int f_color;
		int color;
		int f_shortcutcolor;
		int shortcutcolor;
	} button;
};

A member with the “f_” refers to focus when an element can be in selected or not selected state.

bsddialog_color() generates and returns a color to set a struct bsddialog_theme color member. An enum bsddialog_color can be: BSDDIALOG_BLACK, BSDDIALOG_RED, BSDDIALOG_GREEN, BSDDIALOG_YELLOW, BSDDIALOG_BLUE, BSDDIALOG_MAGENTA, BSDDIALOG_CYAN, BSDDIALOG_WHITE. flags is an OR value: BSDDIALOG_BLINK, BSDDIALOG_BOLD, BSDDIALOG_HALFBRIGHT, BSDDIALOG_HIGHLIGHT, BSDDIALOG_REVERSE, BSDDIALOG_UNDERLINE.

bsddialog_color_attrs() sets, if not NULL, foreground, background, flags, like the properties of color, see bsddialog_color().

bsddialog_get_theme() sets theme like the current runtime theme.

bsddialog_hascolors() returns true if the terminal provides colors, false otherwise.

bsddialog_set_theme() sets theme like current runtime theme. Changes take effect only for dialogs built after the call.

bsddialog_set_default_theme() sets a library default theme like current theme, possible values: BSDDIALOG_THEME_BLACKWHITE, BSDDIALOG_THEME_FLAT, BSDDIALOG_THEME_3D. Changes take effect only for dialogs built after the call.