The libBSDDialog library provides an API to build TUI dialogs and widgets. This is the manual page, for an introduction and examples https://gitlab.com/alfix/bsddialog.
BSDDIALOG(3) FreeBSD Library Functions Manual BSDDIALOG(3)
NAME
bsddialog_backtitle, bsddialog_calendar, bsddialog_clear,
bsddialog_color, bsddialog_color_attrs, bsddialog_checklist,
bsddialog_datebox, bsddialog_end, bsddialog_form, bsddialog_gauge,
bsddialog_geterror, bsddialog_get_theme, bsddialog_hascolors,
bsddialog_infobox, bsddialog_init, bsddialog_init_notheme,
bsddialog_initconf, bsddialog_inmode, bsddialog_menu,
bsddialog_mixedgauge, bsddialog_mixedlist, bsddialog_msgbox,
bsddialog_pause, bsddialog_radiolist, bsddialog_rangebox,
bsddialog_refresh, bsddialog_set_theme, bsddialog_set_default_theme,
bsddialog_textbox, bsddialog_timebox, bsddialog_yesno - TUI dialogs
LIBRARY
library "libbsddialog"
SYNOPSIS
#include <bsddialog.h>
int
bsddialog_backtitle(struct bsddialog_conf *conf, const char *backtitle);
int
bsddialog_calendar(struct bsddialog_conf *conf, const char *text,
int rows, int cols, unsigned int *year, unsigned int *month,
unsigned int *day);
int
bsddialog_checklist(struct bsddialog_conf *conf, const char *text,
int rows, int cols, unsigned int menurows, unsigned int nitems,
struct bsddialog_menuitem *items, int *focusitem);
void
bsddialog_clear(unsigned int y);
int
bsddialog_datebox(struct bsddialog_conf *conf, const char *text,
int rows, int cols, unsigned int *year, unsigned int *month,
unsigned int *day);
int
bsddialog_end(void);
int
bsddialog_form(struct bsddialog_conf *conf, const char *text, int rows,
int cols, unsigned int formrows, unsigned int nitems,
struct bsddialog_formitem *items, int *focusitem);
int
bsddialog_gauge(struct bsddialog_conf *conf, const char *text, int rows,
int cols, unsigned int perc, int fd, const char *sep,
const char *end);
const char *
bsddialog_geterror(void);
int
bsddialog_infobox(struct bsddialog_conf *conf, const char *text,
int rows, int cols);
int
bsddialog_init(void);
int
bsddialog_init_notheme(void);
bool
bsddialog_inmode(void);
int
bsddialog_initconf(struct bsddialog_conf *conf);
int
bsddialog_menu(struct bsddialog_conf *conf, const char *text, int rows,
int cols, unsigned int menurows, unsigned int nitems,
struct bsddialog_menuitem *items, int *focusitem);
int
bsddialog_mixedgauge(struct bsddialog_conf *conf, const char *text,
int rows, int cols, unsigned int mainperc, unsigned int nminibars,
char **minilabels, int *minipercs);
int
bsddialog_mixedlist(struct bsddialog_conf *conf, const char *text,
int rows, int cols, unsigned int menurows, unsigned int ngroups,
struct bsddialog_menugroup *groups, int *focuslist, int *focusitem);
int
bsddialog_msgbox(struct bsddialog_conf *conf, const char *text, int rows,
int cols);
int
bsddialog_pause(struct bsddialog_conf *conf, const char *text, int rows,
int cols, unsigned int *seconds);
int
bsddialog_radiolist(struct bsddialog_conf *conf, const char *text,
int rows, int cols, unsigned int menurows, unsigned int nitems,
struct bsddialog_menuitem *items, int *focusitem);
int
bsddialog_rangebox(struct bsddialog_conf *conf, const char *text,
int rows, int cols, int min, int max, int *value);
void
bsddialog_refresh(void);
int
bsddialog_textbox(struct bsddialog_conf *conf, const char *file,
int rows, int cols);
int
bsddialog_timebox(struct bsddialog_conf *conf, const char *text,
int rows, int cols, unsigned int *hh, unsigned int *mm,
unsigned int *ss);
int
bsddialog_yesno(struct bsddialog_conf *conf, const char *text, int rows,
int cols);
#include <bsddialog_theme.h>
int
bsddialog_color(enum bsddialog_color foreground,
enum bsddialog_color background, unsigned int flags);
int
bsddialog_color_attrs(int color, enum bsddialog_color *foreground,
enum bsddialog_color *background, unsigned int *flags);
int
bsddialog_get_theme(struct bsddialog_theme *theme);
bool
bsddialog_hascolors(void);
int
bsddialog_set_default_theme(enum bsddialog_default_theme theme);
int
bsddialog_set_theme(struct bsddialog_theme *theme);
DESCRIPTION
The bsddialog library provides an API to build Text User Interface
dialogs and widgets.
bsddialog_init() initializes the library, the only functions that can be
called before is bsddialog_initconf() described later. After the
initialization the input and output should be handled via the library
API.
bsddialog_init_notheme() is equivalent to bsddialog_init() except it does
not set the default graphical theme; see Theme subsection to set a theme
explicitly.
bsddialog_end() restores the screen like before bsddialog_init(). After
the call is not possible to use the library functions.
bsddialog_inmode() returns true after bsddialog_init() or
bsddialog_init_notheme() and before bsddialog_end(), false otherwise.
bsddialog_backtitle() prints backtitle on the top of the screen. The
function handles conf.ascii_lines and conf.no_lines described later.
bsddialog_error() returns a string to describe the last error. The
function should be called after a BSDDIALOG_ERROR returned value.
bsddialog_clear() clears the screen from y.
bsddialog_refresh() useful to refresh the screen after a terminal mode
change, see terminfo(5).
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;
};
conf.ascii_lines ascii characters to draw lines, default wide characters.
conf.auto_minheight minimum height if rows is BSDDIALOG_AUTOSIZE.
conf.auto_minwidth minimum width if cols is BSDDIALOG_AUTOSIZE.
conf.auto_topmargin top margin if rows is BSDDIALOG_AUTOSIZE or
BSDDIALOG_FULLSCREEN, conf.y has to be BSDDIALOG_CENTER.
conf.auto_downmargin down margin if rows is BSDDIALOG_AUTOSIZE or
BSDDIALOG_FULLSCREEN.
conf.bottomtitle dialog subtitle.
conf.clear hide the dialog at exit.
conf.get_height if not NULL is set like the dialog height.
conf.get_width if not NULL is set like the dialog width.
conf.no_lines not draw lines.
conf.shadow draw shadow.
conf.sleep wait before to return, the value is in seconds.
conf.title dialog title.
conf.y dialog vertical position, 0 is top screen, can be
BSDDIALOG_CENTER.
conf.x dialog horizontal position, 0 is left screen, can be
BSDDIALOG_CENTER.
conf.key.enable_esc enable ESC key to close the dialog.
conf.key.f1_file open a file in a textbox if F1 is pressed.
conf.key.f1_message build a msgbox with message if F1 is pressed.
conf.text.cols_per_row Try to set the number of columns for a row of text
with autosizing, default 10.
conf.text.escape enable escapes in text:
"\Z0" black.
"\Z1" red.
"\Z2" green.
"\Z3" yellow.
"\Z4" blue.
"\Z5" magenta.
"\Z6" cyan.
"\Z7" white.
"\Zb" bold.
"\ZB" disable bold.
"\Zd" Half bright.
"\ZD" disable half bright.
"\Zk" Blink.
"\ZK" disable blinking.
"\Zr" reverse foreground and background.
"\ZR" disable reverse.
"\Zs" Highlight.
"\ZS" disable highlighting.
"\Zu" underline.
"\ZU" disable underline.
"\Zn" disable each customization.
conf.text.tablen tab length for text argument and bsddialog_textbox()
function.
conf.button.always_active buttons always active, avoiding focus switch
between buttons and input fields or input boxes in bsddialog_form(),
bsddialog_datebox(), bsddialog_calendar() and bsddialog_timebox().
conf.button.left1_label add a button with the specified label.
conf.button.left2_label add a button with the specified label.
conf.button.left3_label add a button with the specified label.
conf.button.without_ok disable OK button.
conf.button.ok_label set label for OK button.
conf.button.with_extra add Extra button.
conf.button.extra_label set a label for Extra button.
conf.button.without_cancel disable Cancel button.
conf.button.cancel_label sets a label for Cancel button.
conf.button.default_cancel on startup focus on the Cancel button.
conf.button.with_help add Help button.
conf.button.help_label set a label for Help button.
conf.button.right1_label add a button with the specified label.
conf.button.right2_label add a button with the specified label.
conf.button.right3_label add a button with the specified label.
conf.button.default_label focus on the button with the specified label.
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:
conf.date.format date format user interface, possible values: "d/m/y",
"m/d/y", "y/m/d".
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:
conf.form.securech charachter to hide the input with
BSDDIALOG_FIELDHIDDEN.
conf.form.securembch multibyte charachter to hide the input with
BSDDIALOG_FIELDHIDDEN, conf.form.securech is ignored.
conf.form.value_wchar the allocated value is a wchar_t* string.
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
or 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:
conf.menu.align_left align items to left, default center.
conf.menu.no_desc hide items description.
conf.menu.no_name hide items name, mutually exclusive with
conf.menu.no_desc.
conf.menu.shortcut_buttons enable shortcut keys on buttons, default on
items.
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, the keys UP, DOWN, HOME, END, PAGEUP and
PAGEDOWN can change it.
bsddialog_textbox() opens and prints file. UP, DOWN, LEFT, RIGHT, HOME,
END, PAGEUP and PAGEDOWN keys are available to navigate the file, TAB
changes button. "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.
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.
RETURN VALUES
The functions return the value BSDDIALOG_ERROR if unsuccessful;
otherwise, depending on the pressed button, the following values can be
returned: BSDDIALOG_OK, BSDDIALOG_CANCEL, BSDDIALOG_HELP,
BSDDIALOG_EXTRA, BSDDIALOG_LEFT1, BSDDIALOG_LEFT2, BSDDIALOG_LEFT3,
BSDDIALOG_RIGHT1, BSDDIALOG_RIGHT2, BSDDIALOG_RIGHT3. BSDDIALOG_YES and
BSDDIALOG_NO are aliases for BSDDIALOG_OK and BSDDIALOG_CANCEL,
respectively.
The functions return BSDDIALOG_ESC if conf.key.enable_esc is enabled and
the ESC key is pressed.
bsddialog_pause() returns BSDDIALOG_TIMEOUT if the timeout expires.
EXAMPLES
"Yes-No Question" Example:
int output;
struct bsddialog_conf conf;
if (bsddialog_init() == BSDDIALOG_ERROR)
return (1);
bsddialog_initconf(&conf);
conf.title = "yesno";
output = bsddialog_yesno(&conf, "Example", 7, 25);
bsddialog_end();
switch (output) {
case BSDDIALOG_YES:
printf("Yes\n");
break;
case BSDDIALOG_NO
printf("NO\n");
break;
case BSDDIALOG_ERROR:
printf("Error: %s\n", bsddialog_geterror());
break;
}
Theme Example:
struct bsddialog_conf conf;
struct bsddialog_theme theme;
bsddialog_init();
bsddialog_initconf(&conf);
bsddialog_msgbox(&conf, "Default theme", 7, 25);
bsddialog_get_theme(&theme);
theme.screen.color = bsddialog_color(BSDDIALOG_RED, BSDDIALOG_GREEN,
BSDDIALOG_BOLD);
bsddialog_set_theme(&theme);
bsddialog_backtitle(&conf, "Red foreground and Green background");
bsddialog_msgbox(&conf, "Change screen color", 7, 25);
bsddialog_set_default_theme(BSDDIALOG_THEME_BLACKWHITE);
bsddialog_msgbox(&conf, "Black and White theme", 7, 25);
bsddialog_end();
Mixedlist Example:
unsigned int i, j;
struct bsddialog_conf conf;
struct bsddialog_menuitem item;
struct bsddialog_menuitem check[2] = {
{ "1", true, 0, "Name 1", "Desc 1", "Check Bottom Desc 1" },
{ "2", false, 0, "Name 2", "Desc 2", "Check Bottom Desc 2" }
};
struct bsddialog_menuitem sep[1] = {
{ "3", true, 0, "Radiolist", "(desc)", "" }
};
struct bsddialog_menuitem radio[2] = {
{ "4", true, 0, "Name 1", "Desc 1", "Radio Bottom Desc 1" },
{ "5", false, 0, "Name 2", "Desc 2", "Radio Bottom Desc 2" }
};
struct bsddialog_menugroup group[3] = {
{ BSDDIALOG_CHECKLIST, 2, check },
{ BSDDIALOG_SEPARATOR, 1, sep },
{ BSDDIALOG_RADIOLIST, 2, radio }
};
bsddialog_init();
bsddialog_initconf(&conf);
bsddialog_mixedlist(&conf, "Example", 20, 30, 11, 3, group, NULL,
NULL);
bsddialog_end();
for (i = 0; i < 3; i++) {
for (j = 0; j < group[i].nitems; j++) {
item = group[i].items[j];
switch (item.type) {
case BSDDIALOG_SEPARATOR:
printf("---- %s ----\n", item.name);
break;
case BSDDIALOG_RADIOLIST:
printf(" (%c) %s\n",
item.on ? '*' : ' ', item.name);
break;
case BSDDIALOG_CHECKLIST:
printf(" [%c] %s\n",
item.on ? 'X' : ' ', item.name);
break;
}
}
}
SEE ALSO
bsddialog(1), curses(3)
HISTORY
The bsddialog library first appeared in FreeBSD 14.0.
AUTHORS
bsddialog was written by Alfonso Sabato Siciliano
<asiciliano@FreeBSD.org>.
FreeBSD 14.0-CURRENT July 28, 2023 FreeBSD 14.0-CURRENT