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
29 .Nm bsddialog_backtitle ,
30 .Nm bsddialog_clearterminal ,
32 .Nm bsddialog_checklist ,
33 .Nm bsddialog_datebox ,
37 .Nm bsddialog_geterror ,
38 .Nm bsddialog_get_theme ,
39 .Nm bsddialog_infobox ,
41 .Nm bsddialog_initconf ,
43 .Nm bsddialog_mixedgauge ,
44 .Nm bsddialog_mixedlist ,
45 .Nm bsddialog_msgbox ,
47 .Nm bsddialog_radiolist ,
48 .Nm bsddialog_rangebox ,
49 .Nm bsddialog_set_theme ,
50 .Nm bsddialog_set_default_theme ,
51 .Nm bsddialog_textbox ,
52 .Nm bsddialog_timebox ,
60 .Fn bsddialog_backtitle "struct bsddialog_conf *conf" "const char *backtitle"
62 .Fo bsddialog_checklist
63 .Fa "struct bsddialog_conf *conf"
64 .Fa "const char *text"
67 .Fa "unsigned int menurows"
68 .Fa "unsigned int nitems"
69 .Fa "struct bsddialog_menuitem *items"
73 .Fn bsddialog_clearterminal "void"
75 .Fo bsddialog_datebox"
76 .Fa "struct bsddialog_conf *conf"
77 .Fa "const char *text"
80 .Fa "unsigned int *yy"
81 .Fa "unsigned int *mm"
82 .Fa "unsigned int *dd"
85 .Fn bsddialog_end "void"
88 .Fa "struct bsddialog_conf *conf"
89 .Fa "const char *text"
92 .Fa "unsigned int formrows"
93 .Fa "unsigned int nitems"
94 .Fa "struct bsddialog_formitem *items"
98 .Fa "struct bsddialog_conf *conf"
99 .Fa "const char *text"
102 .Fa "unsigned int perc"
104 .Fa "const char *sep"
107 .Fn bsddialog_geterror "void"
109 .Fo bsddialog_infobox
110 .Fa "struct bsddialog_conf *conf"
111 .Fa "const char *text"
116 .Fn bsddialog_init "void"
118 .Fn bsddialog_initconf "struct bsddialog_conf *conf"
121 .Fa "struct bsddialog_conf *conf"
122 .Fa "const char *text"
125 .Fa "unsigned int menurows"
126 .Fa "unsigned int nitems"
127 .Fa "struct bsddialog_menuitem *items"
131 .Fo bsddialog_mixedgauge
132 .Fa "struct bsddialog_conf *conf"
133 .Fa "const char *text"
136 .Fa "unsigned int mainperc"
137 .Fa "unsigned int nminibars"
138 .Fa "char **minilabels"
142 .Fo bsddialog_mixedlist
143 .Fa "struct bsddialog_conf *conf"
144 .Fa "const char *text"
147 .Fa "unsigned int menurows"
148 .Fa "unsigned int ngroups"
149 .Fa "struct bsddialog_menugroup *groups"
155 .Fa "struct bsddialog_conf *conf"
156 .Fa "const char *text"
162 .Fa "struct bsddialog_conf *conf"
163 .Fa "const char *text"
166 .Fa "unsigned int seconds"
169 .Fo bsddialog_radiolist
170 .Fa "struct bsddialog_conf *conf"
171 .Fa "const char *text"
174 .Fa "unsigned int menurows"
175 .Fa "unsigned int nitems"
176 .Fa "struct bsddialog_menuitem *items"
180 .Fo bsddialog_rangebox
181 .Fa "struct bsddialog_conf *conf"
182 .Fa "const char *text"
190 .Fo bsddialog_textbox
191 .Fa "struct bsddialog_conf *conf"
192 .Fa "const char *file"
197 .Fo bsddialog_timebox
198 .Fa "struct bsddialog_conf *conf"
199 .Fa "const char *text"
202 .Fa "unsigned int *hh"
203 .Fa "unsigned int *mm"
204 .Fa "unsigned int *ss"
208 .Fa "struct bsddialog_conf *conf"
209 .Fa "const char *text"
213 .In bsddialog_theme.h
216 .Fa "enum bsddialog_color foreground"
217 .Fa "enum bsddialog_color background"
218 .Fa "unsigned int flags"
221 .Fn bsddialog_get_theme "struct bsddialog_theme *theme"
223 .Fn bsddialog_set_default_theme "enum bsddialog_default_theme theme"
225 .Fn bsddialog_set_theme "struct bsddialog_theme *theme"
229 library provides an API to build Text User Interface dialogs and widgets: to
230 display messages, to get input and to inform about a computation status.
233 initializes the library, the only functions that can be called before is
234 .Fn bsddialog_initconf
236 After the initialization the input and output should be handled via the library
239 restores the screen like before
241 then it is not possible to use the library functions.
244 returns a string to describe the last error, it should be called after a
247 .Fn bsddialog_clearterminal
249 .Fn bsddialog_backtitle
252 on the top of the screen, it is possible to set
261 argument has to be a well terminated string, can be empty
266 The dialogs have common arguments.
268 is a string printed inside the dialog.
272 are height and width, their value can be between 2 and the screen size,
273 .Dv BSDDIALOG_AUTOSIZE
275 .Dv BSDDIALOG_FULLSCREEN .
277 is a struct to customize the dialog, it does not set global properties to the
280 .Bd -literal -offset indent -compact
281 struct bsddialog_conf {
283 unsigned int auto_minheight;
284 unsigned int auto_minwidth;
285 const char *bottomtitle;
298 const char *f1_message;
309 bool shortcut_buttons;
314 bool value_without_ok;
318 const char *ok_label;
320 const char *extra_label;
322 const char *cancel_label;
325 const char *help_label;
326 const char *generic1_label;
327 const char *generic2_label;
328 const char *default_label;
334 .It Fa conf.ascii_lines
335 ascii characters to draw lines, default wide characters.
336 .It Fa conf.auto_minheight
340 .Dv BSDDIALOG_AUTOSIZE .
341 .It Fa conf.auto_minwidth
345 .Dv BSDDIALOG_AUTOSIZE .
346 .It Fa conf.bottomtitle
347 subtitle at the dialog bottom side.
349 hide the dialog at exit.
350 .It Fa conf.get_height
353 is set like the dialog height.
354 .It Fa conf.get_width
357 is set like the dialog width.
363 wait before to return, the value is in seconds.
365 title at the top dialog side.
367 vertical position, 0 is top screen size, can be
368 .Dv BSDDIALOG_CENTER .
370 horizontal position, 0 is left screen side, can be
371 .Dv BSDDIALOG_CENTER .
375 .It Fa conf.key.enable_esc
378 key to close the dialog.
379 .It Fa conf.key.f1_file
380 file to open if F1 is pressed.
381 .It Fa conf.key.f1_message
382 message to display if F1 is pressed.
385 .Fa conf.text.highlight
386 enables highlights for
388 properly the following sequences are considered escapes:
407 reverse colors between foreground and background.
419 disable each customization.
425 .It Fa conf.button.without_ok
427 .It Fa conf.button.ok_label
428 set label for OK button.
429 .It Fa conf.button.with_extra
431 .It Fa conf.button.extra_label
432 set a label for Extra button.
433 .It Fa conf.button.without_cancel
434 disable Cancel button.
435 .It Fa conf.button.cancel_label
436 sets a label for Cancel button.
437 .It Fa conf.button.default_cancel
438 on startup focus on the Cancel button.
439 .It Fa conf.button.with_help
441 .It Fa conf.button.help_label
442 set a label for Help button.
443 .It Fa conf.button.generic1_label
444 add a button with the specified label.
445 .It Fa conf.button.generic2_label
446 add a button with the specified label.
447 .It Fa conf.button.default_label
448 focus on the button with the specified label.
451 .Fn bsddialog_initconf
454 disabling each property, except
461 .Dv BSDDIALOG_CENTER .
463 .Fn bsddialog_infobox
464 builds a dialog without buttons and returns instantly.
466 builds a dialog with OK button.
468 provides a dialog for a
469 .Dq Yes-No Question ,
470 the labels on buttons are Yes and No.
473 builds a dialog waiting until the timeout in
475 expires or a button is pressed.
477 .Fn bsddialog_datebox
478 builds a dialog to select a date,
483 are default values on startup, selected date at exit.
484 .Fn bsddialog_timebox
485 builds a dialog to choose a time,
490 are default values on startup, selected time at exit.
492 .Fn bsddialog_checklist ,
495 .Fn bsddialog_radiolist
496 build dialogs to select some item from a list via the SPACE key, an item is
499 .Bd -literal -offset indent -compact
500 struct bsddialog_menuitem {
506 const char *bottomdesc;
514 are strings to describe the item and are printed on its row,
516 is printed on the bottom side of the screen,
518 is a margin between the
522 useful to implement a
527 if the item is selected,
531 is an array of items of
535 specifies the graphical fixed height of the list, if
538 .Dv BSDDIALOG_AUTOSIZE
540 specifies a maximum value.
544 specifies the default item on startup and the last focused item at exit, could
545 be a negative value if no item is focused.
547 .Fn bsddialog_mixedlist
548 builds a dialog with collections of checklists, radiolists and separators.
549 A collection is a set defined like:
551 .Bd -literal -offset indent -compact
552 enum bsddialog_grouptype {
558 struct bsddialog_menugroup {
559 enum bsddialog_grouptype type;
561 struct bsddialog_menuitem *items;
566 is an array of sets of
570 is the graphical height size for the list.
576 specify the default item on startup and the last focused item at exit, could be
577 a negative value if no item is focused.
579 .Fn bsddialog_checklist ,
581 .Fn bsddialog_mixedlist
583 .Fn bsddialog_radiolist
584 can be costomizated by:
586 .It Fa conf.menu.align_left
587 aligns items to left, default center.
588 .It Fa conf.menu.no_desc
590 .It Fa conf.menu.no_name
592 .It Fa conf.menu.on_without_ok
595 also if the OK button is not pressed.
596 .It Fa conf.menu.shortcut_buttons
597 enable shortcut keys on buttons, default on items.
601 builds a dialog to display a list of items to get strings in input, an item is
604 .Bd -literal -offset indent -compact
605 struct bsddialog_formitem {
613 unsigned int fieldlen;
614 unsigned int maxvaluelen;
619 const char *bottomdesc;
624 describes the request, it is printed at the position
628 The field for the input is at the position
633 is its graphical width, while
635 is the maximum length of the input string,
637 is the default value.
638 If the OK button is pressed
640 is the allocated memory with the current field string.
642 is an OR value to set the
643 .Dv BSDDIALOG_FIELDHIDDEN
645 .Dv BSDDIALOG_FIELDREADONLY
648 is printed on the bottom side of the screen if the item is focused.
650 is an array of items of
654 specifies the graphical fixed height for the items list;
658 have to be between 1 and
662 can be customized by:
664 .It Fa conf.form.enable_wchar
665 enables characters greater than 127 in the field,
667 is a pointer to allocated memory for a
670 .It Fa conf.form.securech
671 charachter to hide the input
673 .Dv BSDDIALOG_FIELDHIDDEN .
674 .It Fa conf.form.value_without_ok
675 allocate memory and set
677 also if the OK button is not pressed.
681 builds a dialog with a bar to shows
683 if the file descriptor
685 is greater or equal to 0 the dialog waits to read
687 from it, then the first string replaces
689 and the following strings replace
693 the loop ends reading
696 .Fn bsddialog_mixedgauge
697 draws a main bar with the
705 with a value between 0 and 100 or
706 .Dv BSDDIALOG_MG_SUCCEEDED ,
707 .Dv BSDDIALOG_MG_FAILED ,
708 .Dv BSDDIALOG_MG_PASSED ,
709 .Dv BSDDIALOG_MG_COMPLETED ,
710 .Dv BSDDIALOG_MG_CHECKED ,
711 .Dv BSDDIALOG_MG_DONE ,
712 .Dv BSDDIALOG_MG_SKIPPED ,
713 .Dv BSDDIALOG_MG_INPROGRESS ,
714 .Dv BSDDIALOG_MG_BLANK ,
717 .Dv BSDDIALOG_MG_PENDING
718 to print a descriptive string.
720 .Fn bsddialog_rangebox
721 to select a value between
726 is the default value on startup and the selected value at exit.
727 The current value is printed inside a bar, the keys UP, DOWN, HOME, END, PAGEUP
728 and PAGEDOWN can change it.
730 .Fn bsddialog_textbox
733 in a dialog, the UP, DOWN, HOME, END, PAGEUP and PAGEDOWN keys are availble to
735 OK button is renamed EXIT.
737 The graphical properties are global to the library, they are represented by
738 .Fa struct bsddialog_theme
739 and can be customized at runtime via the
740 .In bsddialog_theme.h
743 .Bd -literal -offset indent -compact
744 struct bsddialog_theme {
759 int bottomtitlecolor;
784 unsigned int hmargin;
799 prefix refers to an element with focus.
801 .Fn bsddialog_get_theme
804 like the current theme.
806 A color can be set by the value returned by
807 .Fn bsddialog_color ,
813 .Dv BSDDIALOG_BLACK ,
815 .Dv BSDDIALOG_GREEN ,
816 .Dv BSDDIALOG_YELLOW ,
818 .Dv BSDDIALOG_MAGENTA ,
821 .Dv BSDDIALOG_WHITE ,
823 specifies OR-flags, possible values:
825 .Dv BSDDIALOG_REVERSE
827 .Dv BSDDIALOG_UNDERLINE .
829 .Fn bsddialog_set_theme
832 like current theme, the changes takes effect only for dialogs built after the
835 The library provides predefined themes:
836 .Dv BSDDIALOG_THEME_BLACKWHITE ,
837 .Dv BSDDIALOG_THEME_BSDDIALOG ,
838 .Dv BSDDIALOG_THEME_FLAT
840 .Dv BSDDIALOG_THEME_DIALOG ,
842 .Fn bsddialog_set_default_theme .
844 The functions return the value
847 otherwise, depending on the pressed button, the following values can be
850 .Dv BSDDIALOG_CANCEL ,
852 .Dv BSDDIALOG_EXTRA ,
853 .Dv BSDDIALOG_GENERIC1
855 .Dv BSDDIALOG_GENERIC2 .
862 .Dv BSDDIALOG_CANCEL ,
868 .Fa conf.key.enable_esc
869 is enabled and the ESC key is pressed.
873 .Dv BSDDIALOG_TIMEOUT
874 if the timeout expires.
879 .Bd -literal -offset indent -compact
881 struct bsddialog_conf conf;
883 if (bsddialog_init() == BSDDIALOG_ERROR)
886 bsddialog_initconf(&conf);
887 conf.title = "yesno";
888 output = bsddialog_yesno(&conf, "Example", 7, 25);
899 case BSDDIALOG_ERROR:
900 printf("Error: %s\\n", bsddialog_geterror());
906 .Bd -literal -offset indent -compact
907 struct bsddialog_conf conf;
908 struct bsddialog_theme theme;
912 bsddialog_initconf(&conf);
913 bsddialog_msgbox(&conf, "Default theme", 7, 25);
915 bsddialog_get_theme(&theme);
916 theme.screen.color = bsddialog_color(BSDDIALOG_RED, BSDDIALOG_GREEN,
918 bsddialog_set_theme(&theme);
919 bsddialog_backtitle(&conf, "Red foreground and Green background");
920 bsddialog_msgbox(&conf, "Change screen color", 7, 25);
922 bsddialog_set_default_theme(BSDDIALOG_THEME_BLACKWHITE);
923 bsddialog_msgbox(&conf, "Black and White theme", 7, 25);
930 .Bd -literal -offset indent -compact
932 struct bsddialog_conf conf;
933 struct bsddialog_menuitem item;
934 struct bsddialog_menuitem check[2] = {
935 { "1", true, 0, "Name 1", "Desc 1", "Check Bottom Desc 1" },
936 { "2", false, 0, "Name 2", "Desc 2", "Check Bottom Desc 2" }
938 struct bsddialog_menuitem sep[1] = {
939 { "3", true, 0, "Radiolist", "(desc)", "" }
941 struct bsddialog_menuitem radio[5] = {
942 { "4", true, 0, "Name 1", "Desc 1", "Radio Bottom Desc 1" },
943 { "5", false, 0, "Name 2", "Desc 2", "Radio Bottom Desc 2" }
945 struct bsddialog_menugroup group[3] = {
946 { BSDDIALOG_CHECKLIST, 2, check },
947 { BSDDIALOG_SEPARATOR, 1, sep },
948 { BSDDIALOG_RADIOLIST, 2, radio }
952 bsddialog_initconf(&conf);
953 bsddialog_mixedlist(&conf, "Example", 20, 30, 11, 3, group, NULL,
957 for (i = 0; i < 3; i++) {
958 for (j = 0; j < group[i].nitems; j++) {
959 item = group[i].items[j];
961 case BSDDIALOG_SEPARATOR:
962 printf("---- %s ----\\n", item.name);
964 case BSDDIALOG_RADIOLIST:
965 printf(" (%c) %s\\n",
966 item.on ? '*' : ' ', item.name);
968 case BSDDIALOG_CHECKLIST:
969 printf(" [%c] %s\\n",
970 item.on ? 'X' : ' ', item.name);
983 library first appeared in
988 .An Alfonso Sabato Siciliano Aq Mt alf.siciliano@gmail.com .
991 does not resize the dialog after a terminal resize and does not provide