BSDDIALOG(3)
β¨ NAME β¨
okay so welcome to the bsddialog(3) manual page, bestie β this is the TUI dialogs era, and these are the functions in the cast. Say hi to the whole group chat: bsddialog_backtitle, bsddialog_backtitle_rf, 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.
π LIBRARY π
library βlibbsddialogβ β that's the library line, no cap. That's the whole vibe.
π οΈ SYNOPSIS π οΈ
here's the exact prototype lineup, because we do not mess with signatures, bestie:
#include <bsddialog.h>
int
bsddialog_backtitle(struct bsddialog_conf *conf, const char *backtitle);
int
bsddialog_backtitle_rf(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 gives you an API for building Text User Interface dialogs and widgets β yes, TUI, we're fancy like that π
.
bsddialog_init() initializes the library. The only function you can call before it is bsddialog_initconf(), which gets described later. After initialization, input and output should be handled via the library API, bestie. That's the whole system.
bsddialog_init_notheme() is equivalent to bsddialog_init() except it does not set the default graphical theme. See the βThemeβ subsection if you wanna set a theme explicitly. No cap.
bsddialog_end() restores the screen like before bsddialog_init(). After that call, it is not possible to use the library functions. So don't call the library after bsddialog_end(), periodt.
bsddialog_inmode() returns true after bsddialog_init() or bsddialog_init_notheme() and before bsddialog_end(), and false otherwise. Easy vibe check.
bsddialog_backtitle_rf() prints backtitle on the top of the screen. This function handles conf.ascii_lines and conf.no_lines, which are described later. π
bsddialog_backtitle() is like bsddialog_backtitle_rf() but it does not update the screen β use it if a dialog is gonna be built later.
bsddialog_error() returns a string to describe the last error. The function should be called after a BSDDIALOG_ERROR returned value, fr fr.
bsddialog_clear() clears the screen from y.
bsddialog_refresh() is 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 is wide characters. π¨conf.auto_minheightβ minimum height ifrowsisBSDDIALOG_AUTOSIZE.conf.auto_minwidthβ minimum width ifcolsisBSDDIALOG_AUTOSIZE.conf.auto_topmarginβ top margin ifrowsisBSDDIALOG_AUTOSIZEorBSDDIALOG_FULLSCREEN;conf.yhas to beBSDDIALOG_CENTER.conf.auto_downmarginβ down margin ifrowsisBSDDIALOG_AUTOSIZEorBSDDIALOG_FULLSCREEN.conf.bottomtitleβ dialog subtitle.conf.clearβ hide the dialog at exit.conf.get_heightβ if it's notNULL, it's set like the dialog height.conf.get_widthβ if it's notNULL, it's 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;0is top screen, can beBSDDIALOG_CENTER.conf.xβ dialog horizontal position;0is left screen, can beBSDDIALOG_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, default10.conf.text.escapeβ enable escapes in text:\Z0black.\Z1red.\Z2green.\Z3yellow.\Z4blue.\Z5magenta.\Z6cyan.\Z7white.\Zbbold.\ZBdisable bold.\ZdHalf bright.\ZDdisable half bright.\ZkBlink.\ZKdisable blinking.\Zrreverse foreground and background.\ZRdisable reverse.\ZsHighlight.\ZSdisable highlighting.\Zuunderline.\ZUdisable underline.\Zndisable each customization.
conf.text.tablenβ tab length fortextargument andbsddialog_textbox()function.
okay so, picking up right where we left off with the conf.button.* crew β these are the little button-behavior knobs, and every single one is here:
conf.button.always_activeβ buttons are always active, so no focus-switch drama between buttons and input fields or input boxes inbsddialog_form(),bsddialog_datebox(),bsddialog_calendar(), andbsddialog_timebox().conf.button.left1_labelβ adds a button with the specified label.conf.button.left2_labelβ adds a button with the specified label.conf.button.left3_labelβ adds a button with the specified label.conf.button.without_okβ disables the OK button.conf.button.ok_labelβ sets the label for the OK button.conf.button.with_extraβ adds an Extra button.conf.button.extra_labelβ sets a label for the Extra button.conf.button.without_cancelβ disables the Cancel button.conf.button.cancel_labelβ sets a label for the Cancel button.conf.button.default_cancelβ on startup, focuses on the Cancel button.conf.button.with_helpβ adds a Help button.conf.button.help_labelβ sets a label for the Help button.conf.button.right1_labelβ adds a button with the specified label.conf.button.right2_labelβ adds a button with the specified label.conf.button.right3_labelβ adds a button with the specified label.conf.button.default_labelβ focuses on the button with the specified label.
bsddialog_initconf() initializes conf with every property disabled, except it sets conf.shadow to true, conf.y and conf.x to BSDDIALOG_CENTER, and conf.text.cols_per_row to 10. defaults, slay β¨
bsddialog_calendar() builds a dialog to select a date. year, month, and day are default values on startup, and the selected date at exit. ποΈ
bsddialog_checklist() builds dialogs to select some item from a list via the SPACE key, and it 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, and the selected date at exit. The function can be customized by:
conf.date.formatβ date format for the 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, with 0 for autosizing. If focusitem is not NULL, it is the default item index on startup and the last focused item at exit; a negative value means 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, and 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 the bottom of the screen if the item is focused.
bsddialog_form() can be customized by:
conf.form.securechβ character to hide the input withBSDDIALOG_FIELDHIDDEN.conf.form.securembchβ multibyte character to hide the input withBSDDIALOG_FIELDHIDDEN;conf.form.securechis ignored.conf.form.value_wcharβ the allocated value is awchar_t*string.
bsddialog_gauge() builds a dialog with a bar to show perc. If the file descriptor fd is greater than 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. blink and you miss it π
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 the bottom of the 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, and 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 means no item is focused.
bsddialog_checklist(), bsddialog_menu(), bsddialog_mixedlist(), and bsddialog_radiolist() can be customized by:
conf.menu.align_leftβ aligns items to the left; default is center.conf.menu.no_descβ hides item descriptions.conf.menu.no_nameβ hides item names; mutually exclusive withconf.menu.no_desc.conf.menu.shortcut_buttonsβ enables shortcut keys on buttons; default is 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 percentage, 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; this 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 an 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 the remaining time. β³
bsddialog_radiolist() builds dialogs to select at most an item from a list via the SPACE key, and it can be customized by conf.menu.*. See bsddialog_menu().
bsddialog_rangebox() selects 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. The TAB key changes button. Extra keys 0, h, l, k, j are available to navigate the text. The "OK" button is renamed "EXIT". π
bsddialog_timebox() builds a dialog to choose a time. hh, mm, and ss are default values on startup, and the selected time at exit. π°οΈ
bsddialog_yesno() provides a dialog for a "Yes-No Question"; the labels on the buttons are "Yes" and "&No". π«Ά
π KEYS π
Ctrl-lβ redraws the dialog.F1β refers toconf.key.f1_fileandconf.key.f1_message.SPACEβ selects a menu item.UP DOWN LEFT RIGHT - + HOME END PAGEUP PAGEDOWN Ctrl-p Ctrl-nβ 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_ prefix 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()β setsforeground,background, andflags(only when they're notNULL, bestie) just like the properties of a color β peepbsddialog_color()for the deets. β¨bsddialog_get_theme()β setsthemeto be like the current runtime theme. πbsddialog_hascolors()β returnstrueif the terminal provides colors, andfalseotherwise. πbsddialog_set_theme()β setsthemeto match the current runtime theme. Heads up: changes only take effect for dialogs built after the call. πbsddialog_set_default_theme()β sets the library default theme to be like the current theme. Possible values areBSDDIALOG_THEME_BLACKWHITE,BSDDIALOG_THEME_FLAT, andBSDDIALOG_THEME_3D. Changes take effect only for dialogs built after the call. π
π RETURN VALUES π
If a function fails, it returns BSDDIALOG_ERROR; otherwise, depending on the button that got pressed, you can get BSDDIALOG_OK, BSDDIALOG_CANCEL, BSDDIALOG_HELP, BSDDIALOG_EXTRA, BSDDIALOG_LEFT1, BSDDIALOG_LEFT2, BSDDIALOG_LEFT3, BSDDIALOG_RIGHT1, BSDDIALOG_RIGHT2, or BSDDIALOG_RIGHT3. Also: BSDDIALOG_YES and BSDDIALOG_NO are aliases for BSDDIALOG_OK and BSDDIALOG_CANCEL, respectively. π«Ά
These functions return BSDDIALOG_ESC when conf.key.enable_esc is enabled and the ESC key is pressed. π
And bsddialog_pause() returns BSDDIALOG_TIMEOUT if the timeout expires. β°
π¦ EXAMPLES π¦
okay these examples are lowkey iconic, let's go π
π β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 π
β HISTORY β
The bsddialog library first appeared in FreeBSD 14.0. π¦
π AUTHORS π
bsddialog was written by Alfonso Sabato Siciliano <asiciliano@FreeBSD.org>. π
okay that's the whole page, bestie π«Ά this one's from Debian, dated June 22, 2025, tagged BSDDIALOG(3) β periodt π
β¨
π¦ where this page comes from
- freebsd 15.1: base 15.1
- Copyright (c) 2021-2025 Alfonso Sabato Siciliano
- π girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on : a language model's rewrite of the original, under its terms