2 .\" Copyright (c) 2021-2022 Alfonso Sabato Siciliano
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25 .Dd September 23, 2022
29 .Nm bsddialog_backtitle ,
30 .Nm bsddialog_calendar ,
31 .Nm bsddialog_clearterminal ,
33 .Nm bsddialog_color_attrs ,
34 .Nm bsddialog_checklist ,
35 .Nm bsddialog_datebox ,
39 .Nm bsddialog_geterror ,
40 .Nm bsddialog_get_theme ,
41 .Nm bsddialog_hascolors ,
42 .Nm bsddialog_infobox ,
44 .Nm bsddialog_init_notheme ,
45 .Nm bsddialog_initconf ,
47 .Nm bsddialog_mixedgauge ,
48 .Nm bsddialog_mixedlist ,
49 .Nm bsddialog_msgbox ,
51 .Nm bsddialog_radiolist ,
52 .Nm bsddialog_rangebox ,
53 .Nm bsddialog_set_theme ,
54 .Nm bsddialog_set_default_theme ,
55 .Nm bsddialog_textbox ,
56 .Nm bsddialog_timebox ,
64 .Fn bsddialog_backtitle "struct bsddialog_conf *conf" "const char *backtitle"
66 .Fo bsddialog_calendar
67 .Fa "struct bsddialog_conf *conf"
68 .Fa "const char *text"
71 .Fa "unsigned int *yy"
72 .Fa "unsigned int *mm"
73 .Fa "unsigned int *dd"
76 .Fo bsddialog_checklist
77 .Fa "struct bsddialog_conf *conf"
78 .Fa "const char *text"
81 .Fa "unsigned int menurows"
82 .Fa "unsigned int nitems"
83 .Fa "struct bsddialog_menuitem *items"
87 .Fn bsddialog_clearterminal "void"
90 .Fa "struct bsddialog_conf *conf"
91 .Fa "const char *text"
94 .Fa "unsigned int *yy"
95 .Fa "unsigned int *mm"
96 .Fa "unsigned int *dd"
99 .Fn bsddialog_end "void"
102 .Fa "struct bsddialog_conf *conf"
103 .Fa "const char *text"
106 .Fa "unsigned int formrows"
107 .Fa "unsigned int nitems"
108 .Fa "struct bsddialog_formitem *items"
112 .Fa "struct bsddialog_conf *conf"
113 .Fa "const char *text"
116 .Fa "unsigned int perc"
118 .Fa "const char *sep"
121 .Fn bsddialog_geterror "void"
123 .Fo bsddialog_infobox
124 .Fa "struct bsddialog_conf *conf"
125 .Fa "const char *text"
130 .Fn bsddialog_init "void"
132 .Fn bsddialog_init_notheme "void"
134 .Fn bsddialog_initconf "struct bsddialog_conf *conf"
137 .Fa "struct bsddialog_conf *conf"
138 .Fa "const char *text"
141 .Fa "unsigned int menurows"
142 .Fa "unsigned int nitems"
143 .Fa "struct bsddialog_menuitem *items"
147 .Fo bsddialog_mixedgauge
148 .Fa "struct bsddialog_conf *conf"
149 .Fa "const char *text"
152 .Fa "unsigned int mainperc"
153 .Fa "unsigned int nminibars"
154 .Fa "char **minilabels"
158 .Fo bsddialog_mixedlist
159 .Fa "struct bsddialog_conf *conf"
160 .Fa "const char *text"
163 .Fa "unsigned int menurows"
164 .Fa "unsigned int ngroups"
165 .Fa "struct bsddialog_menugroup *groups"
171 .Fa "struct bsddialog_conf *conf"
172 .Fa "const char *text"
178 .Fa "struct bsddialog_conf *conf"
179 .Fa "const char *text"
182 .Fa "unsigned int seconds"
185 .Fo bsddialog_radiolist
186 .Fa "struct bsddialog_conf *conf"
187 .Fa "const char *text"
190 .Fa "unsigned int menurows"
191 .Fa "unsigned int nitems"
192 .Fa "struct bsddialog_menuitem *items"
196 .Fo bsddialog_rangebox
197 .Fa "struct bsddialog_conf *conf"
198 .Fa "const char *text"
206 .Fo bsddialog_textbox
207 .Fa "struct bsddialog_conf *conf"
208 .Fa "const char *file"
213 .Fo bsddialog_timebox
214 .Fa "struct bsddialog_conf *conf"
215 .Fa "const char *text"
218 .Fa "unsigned int *hh"
219 .Fa "unsigned int *mm"
220 .Fa "unsigned int *ss"
224 .Fa "struct bsddialog_conf *conf"
225 .Fa "const char *text"
229 .In bsddialog_theme.h
232 .Fa "enum bsddialog_color foreground"
233 .Fa "enum bsddialog_color background"
234 .Fa "unsigned int flags"
237 .Fo bsddialog_color_attrs
239 .Fa "enum bsddialog_color *foreground"
240 .Fa "enum bsddialog_color *background"
241 .Fa "unsigned int *flags"
244 .Fn bsddialog_get_theme "struct bsddialog_theme *theme"
246 .Fn bsddialog_hascolors "void"
248 .Fn bsddialog_set_default_theme "enum bsddialog_default_theme theme"
250 .Fn bsddialog_set_theme "struct bsddialog_theme *theme"
254 library provides an API to build Text User Interface dialogs and widgets: to
255 display messages, to get input and to inform about a computation status.
258 initializes the library, the only functions that can be called before is
259 .Fn bsddialog_initconf
261 After the initialization the input and output should be handled via the library
264 restores the screen like before
266 then it is not possible to use the library functions.
267 .Fn bsddialog_init_notheme
270 except it does not set the default graphical theme; see
272 subsection to set a theme explicitly.
275 returns a string to describe the last error, it should be called after a
278 .Fn bsddialog_clearterminal
280 .Fn bsddialog_backtitle
283 on the top of the screen, it is possible to set
292 argument has to be a well terminated string, it can be a multibyte character
293 string depending on current locale, see
296 The dialogs have common arguments.
298 is a string printed inside the dialog.
302 are height and width, their value can be between 2 and the screen size,
303 .Dv BSDDIALOG_AUTOSIZE
305 .Dv BSDDIALOG_FULLSCREEN .
307 is a struct to customize the dialog, it does not set global properties to the
310 .Bd -literal -offset indent -compact
311 struct bsddialog_conf {
313 unsigned int auto_minheight;
314 unsigned int auto_minwidth;
315 unsigned int auto_topmargin;
316 unsigned int auto_downmargin;
317 const char *bottomtitle;
330 const char *f1_message;
333 unsigned int cols_per_row;
342 bool shortcut_buttons;
348 bool value_without_ok;
353 const char *ok_label;
355 const char *extra_label;
357 const char *cancel_label;
360 const char *help_label;
361 const char *generic1_label;
362 const char *generic2_label;
363 const char *default_label;
369 .It Fa conf.ascii_lines
370 ascii characters to draw lines, default wide characters.
371 .It Fa conf.auto_minheight
375 .Dv BSDDIALOG_AUTOSIZE .
376 .It Fa conf.auto_minwidth
380 .Dv BSDDIALOG_AUTOSIZE .
381 .It Fa conf.auto_topmargin
385 .Dv BSDDIALOG_AUTOSIZE
387 .Dv BSDDIALOG_FULLSCREEN ,
390 .Dv BSDDIALOG_CENTER .
391 .It Fa conf.auto_downmargin
395 .Dv BSDDIALOG_AUTOSIZE
397 .Dv BSDDIALOG_FULLSCREEN .
398 .It Fa conf.bottomtitle
399 subtitle at the dialog bottom side.
401 hide the dialog at exit.
402 .It Fa conf.get_height
405 is set like the dialog height.
406 .It Fa conf.get_width
409 is set like the dialog width.
415 wait before to return, the value is in seconds.
417 title at the top dialog side.
419 vertical position, 0 is top screen size, can be
420 .Dv BSDDIALOG_CENTER .
422 horizontal position, 0 is left screen side, can be
423 .Dv BSDDIALOG_CENTER .
427 .It Fa conf.key.enable_esc
430 key to close the dialog.
431 .It Fa conf.key.f1_file
432 file to open if F1 is pressed.
433 .It Fa conf.key.f1_message
434 message to display if F1 is pressed.
438 .It Fa conf.text.cols_per_row
439 Try to set the number of columns for a row of
441 with autosizing; default
443 .It Fa conf.text.highlight
444 enables highlights for
446 properly the following sequences are considered escapes:
464 reverse foreground and background.
476 disable each customization.
477 .It Fa conf.text.tablen
481 .Fn bsddialog_textbox
486 .It Fa conf.button.always_active
487 buttons always active, avoidind focus switch between buttons and input fields or
490 .Fn bsddialog_datebox ,
491 .Fn bsddialog_calendar
493 .Fn bsddialog_timebox .
494 .It Fa conf.button.without_ok
496 .It Fa conf.button.ok_label
497 set label for OK button.
498 .It Fa conf.button.with_extra
500 .It Fa conf.button.extra_label
501 set a label for Extra button.
502 .It Fa conf.button.without_cancel
503 disable Cancel button.
504 .It Fa conf.button.cancel_label
505 sets a label for Cancel button.
506 .It Fa conf.button.default_cancel
507 on startup focus on the Cancel button.
508 .It Fa conf.button.with_help
510 .It Fa conf.button.help_label
511 set a label for Help button.
512 .It Fa conf.button.generic1_label
513 add a button with the specified label.
514 .It Fa conf.button.generic2_label
515 add a button with the specified label.
516 .It Fa conf.button.default_label
517 focus on the button with the specified label.
520 .Fn bsddialog_initconf
523 disabling each property, except
530 .Dv BSDDIALOG_CENTER ,
531 .Fa conf.text.cols_per_row
535 .Fn bsddialog_infobox
536 builds a dialog without buttons and returns instantly.
538 builds a dialog with OK button.
540 provides a dialog for a
541 .Dq Yes-No Question ,
542 the labels on buttons are Yes and No.
545 builds a dialog waiting until the timeout in
547 expires or a button is pressed.
549 .Fn bsddialog_calendar
551 .Fn bsddialog_datebox
552 build a dialog to select a date,
557 are default values on startup, selected date at exit.
558 .Fn bsddialog_timebox
559 builds a dialog to choose a time,
564 are default values on startup, selected time at exit.
566 .Fn bsddialog_checklist ,
569 .Fn bsddialog_radiolist
570 build dialogs to select some item from a list via the SPACE key, an item is
573 .Bd -literal -offset indent -compact
574 struct bsddialog_menuitem {
580 const char *bottomdesc;
588 are strings to describe the item and are printed on its row,
590 is printed on the bottom side of the screen,
592 is a margin between the
596 useful to implement a
601 if the item is selected,
605 is an array of items of
609 specifies the graphical fixed height of the list, if
612 .Dv BSDDIALOG_AUTOSIZE
614 specifies a maximum value.
618 specifies the default item on startup and the last focused item at exit, could
619 be a negative value if no item is focused.
621 .Fn bsddialog_mixedlist
622 builds a dialog with collections of checklists, radiolists and separators.
623 A collection is a set defined like:
625 .Bd -literal -offset indent -compact
626 enum bsddialog_menutype {
632 struct bsddialog_menugroup {
633 enum bsddialog_menutype type;
635 struct bsddialog_menuitem *items;
640 is an array of sets of
644 is the graphical height size for the list.
650 specify the default item on startup and the last focused item at exit, could be
651 a negative value if no item is focused.
653 .Fn bsddialog_checklist ,
655 .Fn bsddialog_mixedlist
657 .Fn bsddialog_radiolist
658 can be costomizated by:
660 .It Fa conf.menu.align_left
661 aligns items to left, default center.
662 .It Fa conf.menu.no_desc
664 .It Fa conf.menu.no_name
666 .It Fa conf.menu.on_without_ok
669 also if the OK button is not pressed.
670 .It Fa conf.menu.shortcut_buttons
671 enable shortcut keys on buttons, default on items.
675 builds a dialog to display an array of
679 elements to get strings in input.
681 specifies the graphical height for the box around the items,
684 An item is defined like:
686 .Bd -literal -offset indent -compact
687 struct bsddialog_formitem {
695 unsigned int fieldlen;
696 unsigned int maxvaluelen;
701 const char *bottomdesc;
706 is a string to describe the request, it is printed at the position
710 The field for the input is at the position
715 is its graphical width, while
717 is the maximum number of characters of the input string.
719 is the default field value.
720 If the OK button is pressed
722 is the allocated memory with the current field string, its size depends on
725 is an OR value to set the
726 .Dv BSDDIALOG_FIELDHIDDEN ,
727 .Dv BSDDIALOG_FIELDREADONLY ,
728 .Dv BSDDIALOG_FIELDNOCOLOR ,
729 .Dv BSDDIALOG_FIELDCURSOREND ,
730 .Dv BSDDIALOG_FIELDEXTEND
732 .Dv BSDDIALOG_FIELDSINGLEBYTE .
735 is printed on the bottom side of the screen if the item is focused.
738 can be customized by:
740 .It Fa conf.form.securech
741 charachter to hide the input with
742 .Dv BSDDIALOG_FIELDHIDDEN .
743 .It Fa conf.form.securembch
744 multibyte charachter to hide the input with
745 .Dv BSDDIALOG_FIELDHIDDEN ,
746 .Fa conf.form.securech
748 .It Fa conf.form.value_wchar
754 .It Fa conf.form.value_without_ok
755 allocate memory and set
757 also if the OK button is not pressed.
761 builds a dialog with a bar to shows
763 if the file descriptor
765 is greater or equal to 0 the dialog waits to read
767 from it, then the first string replaces
769 and the following strings replace
773 the loop ends reading
776 .Fn bsddialog_mixedgauge
777 draws a main bar with the
785 with a value between 0 and 100 or
786 .Dv BSDDIALOG_MG_SUCCEEDED ,
787 .Dv BSDDIALOG_MG_FAILED ,
788 .Dv BSDDIALOG_MG_PASSED ,
789 .Dv BSDDIALOG_MG_COMPLETED ,
790 .Dv BSDDIALOG_MG_CHECKED ,
791 .Dv BSDDIALOG_MG_DONE ,
792 .Dv BSDDIALOG_MG_SKIPPED ,
793 .Dv BSDDIALOG_MG_INPROGRESS ,
794 .Dv BSDDIALOG_MG_BLANK ,
797 .Dv BSDDIALOG_MG_PENDING
798 to print a descriptive string.
800 .Fn bsddialog_rangebox
801 to select a value between
806 is the default value on startup and the selected value at exit.
807 The current value is printed inside a bar, the keys UP, DOWN, HOME, END, PAGEUP
808 and PAGEDOWN can change it.
810 .Fn bsddialog_textbox
813 in a dialog, the UP, DOWN, HOME, END, PAGEUP and PAGEDOWN keys are availble to
815 OK button is renamed EXIT.
817 The graphical properties are global to the library, they are represented by
818 .Fa struct bsddialog_theme
819 and can be customized at runtime via the
820 .In bsddialog_theme.h
823 .Bd -literal -offset indent -compact
824 struct bsddialog_theme {
839 int bottomtitlecolor;
866 unsigned int minmargin;
867 unsigned int maxmargin;
882 prefix refers to an element with focus.
884 .Fn bsddialog_get_theme
887 like the current theme.
889 A color can be set by the value returned by
890 .Fn bsddialog_color ,
896 .Dv BSDDIALOG_BLACK ,
898 .Dv BSDDIALOG_GREEN ,
899 .Dv BSDDIALOG_YELLOW ,
901 .Dv BSDDIALOG_MAGENTA ,
904 .Dv BSDDIALOG_WHITE ,
906 specifies OR-flags, possible values:
908 .Dv BSDDIALOG_REVERSE
910 .Dv BSDDIALOG_UNDERLINE .
911 .Fn bsddialog_color_attrs
912 gets the properties of a color.
914 .Fn bsddialog_set_theme
917 like current theme, the changes takes effect only for dialogs built after the
920 The library provides predefined themes:
921 .Dv BSDDIALOG_THEME_BLACKWHITE ,
922 .Dv BSDDIALOG_THEME_BSDDIALOG ,
923 .Dv BSDDIALOG_THEME_FLAT
925 .Dv BSDDIALOG_THEME_DIALOG ,
927 .Fn bsddialog_set_default_theme .
929 .Fn bsddialog_hascolors
932 if the terminal provides colors,
936 The functions return the value
939 otherwise, depending on the pressed button, the following values can be
942 .Dv BSDDIALOG_CANCEL ,
944 .Dv BSDDIALOG_EXTRA ,
945 .Dv BSDDIALOG_GENERIC1
947 .Dv BSDDIALOG_GENERIC2 .
954 .Dv BSDDIALOG_CANCEL ,
960 .Fa conf.key.enable_esc
961 is enabled and the ESC key is pressed.
965 .Dv BSDDIALOG_TIMEOUT
966 if the timeout expires.
971 .Bd -literal -offset indent -compact
973 struct bsddialog_conf conf;
975 if (bsddialog_init() == BSDDIALOG_ERROR)
978 bsddialog_initconf(&conf);
979 conf.title = "yesno";
980 output = bsddialog_yesno(&conf, "Example", 7, 25);
991 case BSDDIALOG_ERROR:
992 printf("Error: %s\\n", bsddialog_geterror());
998 .Bd -literal -offset indent -compact
999 struct bsddialog_conf conf;
1000 struct bsddialog_theme theme;
1004 bsddialog_initconf(&conf);
1005 bsddialog_msgbox(&conf, "Default theme", 7, 25);
1007 bsddialog_get_theme(&theme);
1008 theme.screen.color = bsddialog_color(BSDDIALOG_RED, BSDDIALOG_GREEN,
1010 bsddialog_set_theme(&theme);
1011 bsddialog_backtitle(&conf, "Red foreground and Green background");
1012 bsddialog_msgbox(&conf, "Change screen color", 7, 25);
1014 bsddialog_set_default_theme(BSDDIALOG_THEME_BLACKWHITE);
1015 bsddialog_msgbox(&conf, "Black and White theme", 7, 25);
1022 .Bd -literal -offset indent -compact
1024 struct bsddialog_conf conf;
1025 struct bsddialog_menuitem item;
1026 struct bsddialog_menuitem check[2] = {
1027 { "1", true, 0, "Name 1", "Desc 1", "Check Bottom Desc 1" },
1028 { "2", false, 0, "Name 2", "Desc 2", "Check Bottom Desc 2" }
1030 struct bsddialog_menuitem sep[1] = {
1031 { "3", true, 0, "Radiolist", "(desc)", "" }
1033 struct bsddialog_menuitem radio[2] = {
1034 { "4", true, 0, "Name 1", "Desc 1", "Radio Bottom Desc 1" },
1035 { "5", false, 0, "Name 2", "Desc 2", "Radio Bottom Desc 2" }
1037 struct bsddialog_menugroup group[3] = {
1038 { BSDDIALOG_CHECKLIST, 2, check },
1039 { BSDDIALOG_SEPARATOR, 1, sep },
1040 { BSDDIALOG_RADIOLIST, 2, radio }
1044 bsddialog_initconf(&conf);
1045 bsddialog_mixedlist(&conf, "Example", 20, 30, 11, 3, group, NULL,
1049 for (i = 0; i < 3; i++) {
1050 for (j = 0; j < group[i].nitems; j++) {
1051 item = group[i].items[j];
1052 switch (item.type) {
1053 case BSDDIALOG_SEPARATOR:
1054 printf("---- %s ----\\n", item.name);
1056 case BSDDIALOG_RADIOLIST:
1057 printf(" (%c) %s\\n",
1058 item.on ? '*' : ' ', item.name);
1060 case BSDDIALOG_CHECKLIST:
1061 printf(" [%c] %s\\n",
1062 item.on ? 'X' : ' ', item.name);
1074 library first appeared in
1079 .An Alfonso Sabato Siciliano Aq Mt asiciliano@FreeBSD.org .