contrib/bsddialog/lib/bsddialog.3

   1 .\"
   2 .\" Copyright (c) 2021-2022 Alfonso Sabato Siciliano
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   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.
  12 .\"
  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
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .Dd August 29, 2022
  26 .Dt BSDDIALOG 3
  27 .Os
  28 .Sh NAME
  29 .Nm bsddialog_backtitle ,
  30 .Nm bsddialog_clearterminal ,
  31 .Nm bsddialog_color ,
  32 .Nm bsddialog_color_attrs ,
  33 .Nm bsddialog_checklist ,
  34 .Nm bsddialog_datebox ,
  35 .Nm bsddialog_end ,
  36 .Nm bsddialog_form ,
  37 .Nm bsddialog_gauge ,
  38 .Nm bsddialog_geterror ,
  39 .Nm bsddialog_get_theme ,
  40 .Nm bsddialog_hascolors ,
  41 .Nm bsddialog_infobox ,
  42 .Nm bsddialog_init ,
  43 .Nm bsddialog_init_notheme ,
  44 .Nm bsddialog_initconf ,
  45 .Nm bsddialog_menu ,
  46 .Nm bsddialog_mixedgauge ,
  47 .Nm bsddialog_mixedlist ,
  48 .Nm bsddialog_msgbox ,
  49 .Nm bsddialog_pause ,
  50 .Nm bsddialog_radiolist ,
  51 .Nm bsddialog_rangebox ,
  52 .Nm bsddialog_set_theme ,
  53 .Nm bsddialog_set_default_theme ,
  54 .Nm bsddialog_textbox ,
  55 .Nm bsddialog_timebox ,
  56 .Nm bsddialog_yesno
  57 .Nd TUI dialogs
  58 .Sh LIBRARY
  59 .Lb libbsddialog
  60 .Sh SYNOPSIS
  61 .In bsddialog.h
  62 .Ft int
  63 .Fn bsddialog_backtitle "struct bsddialog_conf *conf" "const char *backtitle"
  64 .Ft int
  65 .Fo bsddialog_checklist
  66 .Fa "struct bsddialog_conf *conf"
  67 .Fa "const char *text"
  68 .Fa "int rows"
  69 .Fa "int cols"
  70 .Fa "unsigned int menurows"
  71 .Fa "unsigned int nitems"
  72 .Fa "struct bsddialog_menuitem *items"
  73 .Fa "int *focusitem"
  74 .Fc
  75 .Ft int
  76 .Fn bsddialog_clearterminal "void"
  77 .Ft int
  78 .Fo bsddialog_datebox"
  79 .Fa "struct bsddialog_conf *conf"
  80 .Fa "const char *text"
  81 .Fa "int rows"
  82 .Fa "int cols"
  83 .Fa "unsigned int *yy"
  84 .Fa "unsigned int *mm"
  85 .Fa "unsigned int *dd"
  86 .Fc
  87 .Ft int
  88 .Fn bsddialog_end "void"
  89 .Ft int
  90 .Fo bsddialog_form
  91 .Fa "struct bsddialog_conf *conf"
  92 .Fa "const char *text"
  93 .Fa "int rows"
  94 .Fa "int cols"
  95 .Fa "unsigned int formrows"
  96 .Fa "unsigned int nitems"
  97 .Fa "struct bsddialog_formitem *items"
  98 .Fc
  99 .Ft int
 100 .Fo bsddialog_gauge
 101 .Fa "struct bsddialog_conf *conf"
 102 .Fa "const char *text"
 103 .Fa "int rows"
 104 .Fa "int cols"
 105 .Fa "unsigned int perc"
 106 .Fa "int fd"
 107 .Fa "const char *sep"
 108 .Fc
 109 .Ft const char *
 110 .Fn bsddialog_geterror "void"
 111 .Ft int
 112 .Fo bsddialog_infobox
 113 .Fa "struct bsddialog_conf *conf"
 114 .Fa "const char *text"
 115 .Fa "int rows"
 116 .Fa "int cols"
 117 .Fc
 118 .Ft int
 119 .Fn bsddialog_init "void"
 120 .Ft int
 121 .Fn bsddialog_init_notheme "void"
 122 .Ft int
 123 .Fn bsddialog_initconf "struct bsddialog_conf *conf"
 124 .Ft int
 125 .Fo bsddialog_menu
 126 .Fa "struct bsddialog_conf *conf"
 127 .Fa "const char *text"
 128 .Fa "int rows"
 129 .Fa "int cols"
 130 .Fa "unsigned int menurows"
 131 .Fa "unsigned int nitems"
 132 .Fa "struct bsddialog_menuitem *items"
 133 .Fa "int *focusitem"
 134 .Fc
 135 .Ft int
 136 .Fo bsddialog_mixedgauge
 137 .Fa "struct bsddialog_conf *conf"
 138 .Fa "const char *text"
 139 .Fa "int rows"
 140 .Fa "int cols"
 141 .Fa "unsigned int mainperc"
 142 .Fa "unsigned int nminibars"
 143 .Fa "char **minilabels"
 144 .Fa "int *minipercs"
 145 .Fc
 146 .Ft int
 147 .Fo bsddialog_mixedlist
 148 .Fa "struct bsddialog_conf *conf"
 149 .Fa "const char *text"
 150 .Fa "int rows"
 151 .Fa "int cols"
 152 .Fa "unsigned int menurows"
 153 .Fa "unsigned int ngroups"
 154 .Fa "struct bsddialog_menugroup *groups"
 155 .Fa "int *focuslist"
 156 .Fa "int *focusitem"
 157 .Fc
 158 .Ft int
 159 .Fo bsddialog_msgbox
 160 .Fa "struct bsddialog_conf *conf"
 161 .Fa "const char *text"
 162 .Fa "int rows"
 163 .Fa "int cols"
 164 .Fc
 165 .Ft int
 166 .Fo bsddialog_pause
 167 .Fa "struct bsddialog_conf *conf"
 168 .Fa "const char *text"
 169 .Fa "int rows"
 170 .Fa "int cols"
 171 .Fa "unsigned int seconds"
 172 .Fc
 173 .Ft int
 174 .Fo bsddialog_radiolist
 175 .Fa "struct bsddialog_conf *conf"
 176 .Fa "const char *text"
 177 .Fa "int rows"
 178 .Fa "int cols"
 179 .Fa "unsigned int menurows"
 180 .Fa "unsigned int nitems"
 181 .Fa "struct bsddialog_menuitem *items"
 182 .Fa "int *focusitem"
 183 .Fc
 184 .Ft int
 185 .Fo bsddialog_rangebox
 186 .Fa "struct bsddialog_conf *conf"
 187 .Fa "const char *text"
 188 .Fa "int rows"
 189 .Fa "int cols"
 190 .Fa "int min"
 191 .Fa "int max"
 192 .Fa "int *value"
 193 .Fc
 194 .Ft int
 195 .Fo bsddialog_textbox
 196 .Fa "struct bsddialog_conf *conf"
 197 .Fa "const char *file"
 198 .Fa "int rows"
 199 .Fa "int cols"
 200 .Fc
 201 .Ft int
 202 .Fo bsddialog_timebox
 203 .Fa "struct bsddialog_conf *conf"
 204 .Fa "const char *text"
 205 .Fa "int rows"
 206 .Fa "int cols"
 207 .Fa "unsigned int *hh"
 208 .Fa "unsigned int *mm"
 209 .Fa "unsigned int *ss"
 210 .Fc
 211 .Ft int
 212 .Fo bsddialog_yesno
 213 .Fa "struct bsddialog_conf *conf"
 214 .Fa "const char *text"
 215 .Fa "int rows"
 216 .Fa "int cols"
 217 .Fc
 218 .In bsddialog_theme.h
 219 .Ft int
 220 .Fo bsddialog_color
 221 .Fa "enum bsddialog_color foreground"
 222 .Fa "enum bsddialog_color background"
 223 .Fa "unsigned int flags"
 224 .Fc
 225 .Ft int
 226 .Fo bsddialog_color_attrs
 227 .Fa "int color"
 228 .Fa "enum bsddialog_color *foreground"
 229 .Fa "enum bsddialog_color *background"
 230 .Fa "unsigned int *flags"
 231 .Fc
 232 .Ft int
 233 .Fn bsddialog_get_theme "struct bsddialog_theme *theme"
 234 .Ft bool
 235 .Fn bsddialog_hascolors "void"
 236 .Ft int
 237 .Fn bsddialog_set_default_theme "enum bsddialog_default_theme theme"
 238 .Ft int
 239 .Fn bsddialog_set_theme "struct bsddialog_theme *theme"
 240 .Sh DESCRIPTION
 241 The
 242 .Nm bsddialog
 243 library provides an API to build Text User Interface dialogs and widgets: to
 244 display messages, to get input and to inform about a computation status.
 245 .Pp
 246 .Fn bsddialog_init
 247 initializes the library, the only functions that can be called before is
 248 .Fn bsddialog_initconf
 249 described later.
 250 After the initialization the input and output should be handled via the library
 251 API.
 252 .Fn bsddialog_end
 253 restores the screen like before
 254 .Fn bsddialog_init ,
 255 then it is not possible to use the library functions.
 256 .Fn bsddialog_init_notheme
 257 is equivalent to
 258 .Fn bsddialog_init
 259 except it does not set the default graphical theme; see
 260 .Sx Theme
 261 subsection to set a theme explicitly.
 262 .Pp
 263 .Fn bsddialog_error
 264 returns a string to describe the last error, it should be called after a
 265 .Dv BSDDIALOG_ERROR
 266 returned value.
 267 .Fn bsddialog_clearterminal
 268 clears the screen.
 269 .Fn bsddialog_backtitle
 270 prints
 271 .Fa backtitle
 272 on the top of the screen, it is possible to set
 273 .Fa conf.ascii_lines
 274 and
 275 .Fa conf.no_lines ;
 276 .Fa conf
 277 is described later.
 278 .Pp
 279 Each
 280 .Fa char*
 281 argument has to be a well terminated string, it can be a multibyte character
 282 string depending on current locale, see
 283 .Xr setlocale 3 .
 284 .Ss Dialogs
 285 The dialogs have common arguments.
 286 .Fa text
 287 is a string printed inside the dialog.
 288 .Fa rows
 289 and
 290 .Fa cols
 291 are height and width, their value can be between 2 and the screen size,
 292 .Dv BSDDIALOG_AUTOSIZE
 293 or
 294 .Dv BSDDIALOG_FULLSCREEN .
 295 .Fa conf
 296 is a struct to customize the dialog, it does not set global properties to the
 297 library.
 298 .Pp
 299 .Bd -literal -offset indent -compact
 300 struct bsddialog_conf {
 301         bool ascii_lines;
 302         unsigned int auto_minheight;
 303         unsigned int auto_minwidth;
 304         unsigned int auto_topmargin;
 305         unsigned int auto_downmargin;
 306         const char *bottomtitle;
 307         bool clear;
 308         int *get_height;
 309         int *get_width;
 310         bool no_lines;
 311         bool shadow;
 312         unsigned int sleep;
 313         const char *title;
 314         int y;
 315         int x;
 316         struct {
 317                 bool enable_esc;
 318                 const char *f1_file;
 319                 const char *f1_message;
 320         } key;
 321         struct {
 322                 unsigned int cols_per_row;
 323                 bool highlight;
 324                 unsigned int tablen;
 325         } text;
 326         struct {
 327                 bool align_left;
 328                 bool no_desc;
 329                 bool no_name;
 330                 bool on_without_ok;
 331                 bool shortcut_buttons;
 332         } menu;
 333         struct {
 334                 char securech;
 335                 char *securembch;
 336                 bool value_wchar;
 337                 bool value_without_ok;
 338         } form;
 339         struct {
 340                 bool always_active;
 341                 bool without_ok;
 342                 const char *ok_label;
 343                 bool with_extra;
 344                 const char *extra_label;
 345                 bool without_cancel;
 346                 const char *cancel_label;
 347                 bool default_cancel;
 348                 bool with_help;
 349                 const char *help_label;
 350                 const char *generic1_label;
 351                 const char *generic2_label;
 352                 const char *default_label;
 353         } button;
 354 };
 355 .Ed
 356 .Pp
 357 .Bl -column -compact
 358 .It Fa conf.ascii_lines
 359 ascii characters to draw lines, default wide characters.
 360 .It Fa conf.auto_minheight
 361 minimum height if
 362 .Fa rows
 363 is
 364 .Dv BSDDIALOG_AUTOSIZE .
 365 .It Fa conf.auto_minwidth
 366 minimum width if
 367 .Fa cols
 368 is
 369 .Dv BSDDIALOG_AUTOSIZE .
 370 .It Fa conf.auto_topmargin
 371 top margin if
 372 .Fa rows
 373 is
 374 .Dv BSDDIALOG_AUTOSIZE
 375 or
 376 .Dv BSDDIALOG_FULLSCREEN ,
 377 .Fa conf.y
 378 has to be
 379 .Dv BSDDIALOG_CENTER .
 380 .It Fa conf.auto_downmargin
 381 down margin if
 382 .Fa rows
 383 is
 384 .Dv BSDDIALOG_AUTOSIZE
 385 or
 386 .Dv BSDDIALOG_FULLSCREEN .
 387 .It Fa conf.bottomtitle
 388 subtitle at the dialog bottom side.
 389 .It Fa conf.clear
 390 hide the dialog at exit.
 391 .It Fa conf.get_height
 392 if not
 393 .Dv NULL
 394 is set like the dialog height.
 395 .It Fa conf.get_width
 396 if not
 397 .Dv NULL
 398 is set like the dialog width.
 399 .It Fa conf.no_lines
 400 not draw lines.
 401 .It Fa conf.shadow
 402 draw shadow.
 403 .It Fa conf.sleep
 404 wait before to return, the value is in seconds.
 405 .It Fa conf.title
 406 title at the top dialog side.
 407 .It Fa conf.y
 408 vertical position, 0 is top screen size, can be
 409 .Dv BSDDIALOG_CENTER .
 410 .It Fa conf.x
 411 horizontal position, 0 is left screen side, can be
 412 .Dv BSDDIALOG_CENTER .
 413 .El
 414 .Pp
 415 .Bl -column -compact
 416 .It Fa conf.key.enable_esc
 417 enables
 418 .Dv ESC
 419 key to close the dialog.
 420 .It Fa conf.key.f1_file
 421 file to open if F1 is pressed.
 422 .It Fa conf.key.f1_message
 423 message to display if F1 is pressed.
 424 .El
 425 .Pp
 426 .Bl -column -compact
 427 .It Fa conf.text.cols_per_row
 428 Try to set the number of columns for a row of
 429 .Fa text
 430 with autosizing; default
 431 .Dv 10 .
 432 .It Fa conf.text.highlight
 433 enables highlights for
 434 .Fa text ,
 435 properly the following sequences are considered escapes:
 436 .It Dq \eZ0
 437 black.
 438 .It Dq \eZ1
 439 red.
 440 .It Dq \eZ2
 441 green.
 442 .It Dq \eZ3
 443 yellow.
 444 .It Dq \eZ4
 445 blue.
 446 .It Dq \eZ5
 447 magenta.
 448 .It Dq \eZ6
 449 cyan.
 450 .It Dq \eZ7
 451 white.
 452 .It Dq \eZr
 453 reverse foreground and background.
 454 .It Dq \eZR
 455 disable reverse.
 456 .It Dq \eZb
 457 bold.
 458 .It Dq \eZB
 459 disable bold.
 460 .It Dq \eZu
 461 underline.
 462 .It Dq \eZU
 463 disable underline.
 464 .It Dq \eZn
 465 disable each customization.
 466 .It Fa conf.text.tablen
 467 tab length for
 468 .Fa text
 469 argument and
 470 .Fn bsddialog_textbox
 471 function.
 472 .El
 473 .Pp
 474 .Bl -column -compact
 475 .It Fa conf.button.always_active
 476 buttons always active, avoidind focus switch between buttons and input fields or
 477 input boxes in
 478 .Fn bsddialog_form ,
 479 .Fn bsddialog_datebox
 480 and
 481 .Fn bsddialog_timebox .
 482 .It Fa conf.button.without_ok
 483 disable OK button.
 484 .It Fa conf.button.ok_label
 485 set label for OK button.
 486 .It Fa conf.button.with_extra
 487 add Extra button.
 488 .It Fa conf.button.extra_label
 489 set a label for Extra button.
 490 .It Fa conf.button.without_cancel
 491 disable Cancel button.
 492 .It Fa conf.button.cancel_label
 493 sets a label for Cancel button.
 494 .It Fa conf.button.default_cancel
 495 on startup focus on the Cancel button.
 496 .It Fa conf.button.with_help
 497 add Help button.
 498 .It Fa conf.button.help_label
 499 set a label for Help button.
 500 .It Fa conf.button.generic1_label
 501 add a button with the specified label.
 502 .It Fa conf.button.generic2_label
 503 add a button with the specified label.
 504 .It Fa conf.button.default_label
 505 focus on the button with the specified label.
 506 .El
 507 .Pp
 508 .Fn bsddialog_initconf
 509 initializes
 510 .Fa conf
 511 disabling each property, except
 512 .Fa conf.shadow
 513 to true,
 514 .Fa conf.y
 515 and
 516 .Fa conf.x
 517 to
 518 .Dv BSDDIALOG_CENTER .
 519 .Pp
 520 .Fn bsddialog_infobox
 521 builds a dialog without buttons and returns instantly.
 522 .Fn bsddialog_msgbox
 523 builds a dialog with OK button.
 524 .Fn bsddialog_yesno
 525 provides a dialog for a
 526 .Dq Yes-No Question ,
 527 the labels on buttons are Yes and No.
 528 .Pp
 529 .Fn bsddialog_pause
 530 builds a dialog waiting until the timeout in
 531 .Fa seconds
 532 expires or a button is pressed.
 533 .Pp
 534 .Fn bsddialog_datebox
 535 builds a dialog to select a date,
 536 .Fa yy ,
 537 .Fa mm ,
 538 and
 539 .Fa dd
 540 are default values on startup, selected date at exit.
 541 .Fn bsddialog_timebox
 542 builds a dialog to choose a time,
 543 .Fa hh ,
 544 .Fa mm ,
 545 and
 546 .Fa ss
 547 are default values on startup, selected time at exit.
 548 .Pp
 549 .Fn bsddialog_checklist ,
 550 .Fn bsddialog_menu
 551 and
 552 .Fn bsddialog_radiolist
 553 build dialogs to select some item from a list via the SPACE key, an item is
 554 defined like:
 555 .Pp
 556 .Bd -literal -offset indent -compact
 557 struct bsddialog_menuitem {
 558         const char *prefix;
 559         bool on;
 560         unsigned int depth;
 561         const char *name;
 562         const char *desc;
 563         const char *bottomdesc;
 564 };
 565 .Ed
 566 .Pp
 567 .Fa prefix ,
 568 .Fa name
 569 and
 570 .Fa desc
 571 are strings to describe the item and are printed on its row,
 572 .Fa bottomdesc
 573 is printed on the bottom side of the screen,
 574 .Fa depth
 575 is a margin between the
 576 .Fa prefix
 577 and
 578 .Fa name
 579 useful to implement a
 580 .Dq treeview,
 581 .Fa on
 582 is set to
 583 .Dv true
 584 if the item is selected,
 585 .Dv false
 586 otherwise.
 587 .Fa items
 588 is an array of items of
 589 .Fa nitem
 590 elements,
 591 .Fa menurows
 592 specifies the graphical fixed height of the list, if
 593 .Fa cols
 594 is set to
 595 .Dv BSDDIALOG_AUTOSIZE
 596 .Fa menurows
 597 specifies a maximum value.
 598 Finally, if not
 599 .Dv NULL ,
 600 .Fa focusitem
 601 specifies the default item on startup and the last focused item at exit, could
 602 be a negative value if no item is focused.
 603 .Pp
 604 .Fn bsddialog_mixedlist
 605 builds a dialog with collections of checklists, radiolists and separators.
 606 A collection is a set defined like:
 607 .Pp
 608 .Bd -literal -offset indent -compact
 609 enum bsddialog_grouptype {
 610         BSDDIALOG_CHECKLIST,
 611         BSDDIALOG_RADIOLIST,
 612         BSDDIALOG_SEPARATOR,
 613 };
 614
 615 struct bsddialog_menugroup {
 616         enum bsddialog_grouptype type;
 617         unsigned int nitems;
 618         struct bsddialog_menuitem *items;
 619 };
 620 .Ed
 621 .Pp
 622 .Fa groups
 623 is an array of sets of
 624 .Fa ngroups
 625 elements.
 626 .Fa menurows
 627 is the graphical height size for the list.
 628 If not
 629 .Dv NULL ,
 630 .Fa focuslist
 631 and
 632 .Fa focusitem
 633 specify the default item on startup and the last focused item at exit, could be
 634 a negative value if no item is focused.
 635 .Pp
 636 .Fn bsddialog_checklist ,
 637 .Fn bsddialog_menu ,
 638 .Fn bsddialog_mixedlist
 639 and
 640 .Fn bsddialog_radiolist
 641 can be costomizated by:
 642 .Bl -column -compact
 643 .It Fa conf.menu.align_left
 644 aligns items to left, default center.
 645 .It Fa conf.menu.no_desc
 646 hide description.
 647 .It Fa conf.menu.no_name
 648 hide names.
 649 .It Fa conf.menu.on_without_ok
 650 set items
 651 .Fa on
 652 also if the OK button is not pressed.
 653 .It Fa conf.menu.shortcut_buttons
 654 enable shortcut keys on buttons, default on items.
 655 .El
 656 .Pp
 657 .Fn bsddialog_form
 658 builds a dialog to display an array of
 659 .Fa items
 660 of
 661 .Fa nitems
 662 elements to get strings in input.
 663 .Fa formrows
 664 specifies the graphical height for the box around the items,
 665 .Dv 0
 666 for autosizing.
 667 An item is defined like:
 668 .Pp
 669 .Bd -literal -offset indent -compact
 670 struct bsddialog_formitem {
 671         const char *label;
 672         unsigned int ylabel;
 673         unsigned int xlabel;
 674
 675         const char *init;
 676         unsigned int yfield;
 677         unsigned int xfield;
 678         unsigned int fieldlen;
 679         unsigned int maxvaluelen;
 680         char *value;
 681
 682         unsigned int flags;
 683
 684         const char *bottomdesc;
 685 };
 686 .Ed
 687 .Pp
 688 .Fa label
 689 is a string to describe the request, it is printed at the position
 690 .Fa ylabel
 691 and
 692 .Fa xlabel .
 693 The field for the input is at the position
 694 .Fa yfield
 695 and
 696 .Fa xfield ,
 697 .Fa fieldlen
 698 is its graphical width, while
 699 .Fa maxvalelen
 700 is the maximum number of characters of the input string.
 701 .Fa init
 702 is the default field value.
 703 If the OK button is pressed
 704 .Fa value
 705 is the allocated memory with the current field string, its size depends on
 706 the current locale.
 707 .Fa flags
 708 is an OR value to set the
 709 .Dv BSDDIALOG_FIELDHIDDEN ,
 710 .Dv BSDDIALOG_FIELDREADONLY ,
 711 .Dv BSDDIALOG_FIELDNOCOLOR ,
 712 .Dv BSDDIALOG_FIELDCURSOREND ,
 713 .Dv BSDDIALOG_FIELDEXTEND
 714 and
 715 .Dv BSDDIALOG_FIELDSINGLEBYTE .
 716 flags for the field.
 717 .Fa bottomdesc
 718 is printed on the bottom side of the screen if the item is focused.
 719 .Pp
 720 .Fn bsddialog_form
 721 can be customized by:
 722 .Bl -column -compact
 723 .It Fa conf.form.securech
 724 charachter to hide the input with
 725 .Dv BSDDIALOG_FIELDHIDDEN .
 726 .It Fa conf.form.securembch
 727 multibyte charachter to hide the input with
 728 .Dv BSDDIALOG_FIELDHIDDEN ,
 729 .Fa conf.form.securech
 730 is ignored.
 731 .It Fa conf.form.value_wchar
 732 the allocated
 733 .Fa value
 734 is a
 735 .Em wchar_t*
 736 string.
 737 .It Fa conf.form.value_without_ok
 738 allocate memory and set
 739 .Fa value
 740 also if the OK button is not pressed.
 741 .El
 742 .Pp
 743 .Fn bsddialog_gauge
 744 builds a dialog with a bar to shows
 745 .Fa perc ,
 746 if the file descriptor
 747 .Fa fd
 748 is greater or equal to 0 the dialog waits to read
 749 .Fa separator
 750 from it, then the first string replaces
 751 .Fa perc
 752 and the following strings replace
 753 .Fa text
 754 until the next
 755 .Fa separator ,
 756 the loop ends reading
 757 .Dv EOF .
 758 .Pp
 759 .Fn bsddialog_mixedgauge
 760 draws a main bar with the
 761 .Fa mainperc
 762 percentage and
 763 .Fa nminibars
 764 each one with a
 765 .Fa minilabel
 766 and a
 767 .Fa miniperc
 768 with a value between 0 and 100 or
 769 .Dv BSDDIALOG_MG_SUCCEEDED ,
 770 .Dv BSDDIALOG_MG_FAILED ,
 771 .Dv BSDDIALOG_MG_PASSED ,
 772 .Dv BSDDIALOG_MG_COMPLETED ,
 773 .Dv BSDDIALOG_MG_CHECKED ,
 774 .Dv BSDDIALOG_MG_DONE ,
 775 .Dv BSDDIALOG_MG_SKIPPED ,
 776 .Dv BSDDIALOG_MG_INPROGRESS ,
 777 .Dv BSDDIALOG_MG_BLANK ,
 778 .Dv BSDDIALOG_MG_NA
 779 or
 780 .Dv BSDDIALOG_MG_PENDING
 781 to print a descriptive string.
 782 .Pp
 783 .Fn bsddialog_rangebox
 784 to select a value between
 785 .Fa min
 786 and
 787 .Fa max .
 788 .Fa value
 789 is the default value on startup and the selected value at exit.
 790 The current value is printed inside a bar, the keys UP, DOWN, HOME, END, PAGEUP
 791 and PAGEDOWN can change it.
 792 .Pp
 793 .Fn bsddialog_textbox
 794 opens and prints
 795 .Fa file
 796 in a dialog, the UP, DOWN, HOME, END, PAGEUP and PAGEDOWN keys are availble to
 797 navigate the file.
 798 OK button is renamed EXIT.
 799 .Ss Theme
 800 The graphical properties are global to the library, they are represented by
 801 .Fa struct bsddialog_theme
 802 and can be customized at runtime via the
 803 .In bsddialog_theme.h
 804 API.
 805 .Pp
 806 .Bd -literal -offset indent -compact
 807 struct bsddialog_theme {
 808         struct {
 809                 int color;
 810         } screen;
 811         struct {
 812                 int color;
 813                 unsigned int y;
 814                 unsigned int x;
 815         } shadow;
 816         struct {
 817                 int  color;
 818                 bool delimtitle;
 819                 int  titlecolor;
 820                 int  lineraisecolor;
 821                 int  linelowercolor;
 822                 int  bottomtitlecolor;
 823                 int  arrowcolor;
 824         } dialog;
 825         struct {
 826                 int f_selectorcolor;
 827                 int selectorcolor;
 828                 int f_namecolor;
 829                 int namecolor;
 830                 int f_desccolor;
 831                 int desccolor;
 832                 int namesepcolor;
 833                 int descsepcolor;
 834                 int f_shortcutcolor;
 835                 int shortcutcolor;
 836                 int bottomdesccolor;
 837         } menu;
 838         struct {
 839                 int f_fieldcolor;
 840                 int fieldcolor;
 841                 int readonlycolor;
 842                 int bottomdesccolor;
 843         } form;
 844         struct {
 845                 int f_color;
 846                 int color;
 847         } bar;
 848         struct {
 849                 unsigned int minmargin;
 850                 unsigned int maxmargin;
 851                 char leftdelim;
 852                 char rightdelim;
 853                 int delimcolor;
 854                 int f_delimcolor;
 855                 int color;
 856                 int f_color;
 857                 int shortcutcolor;
 858                 int f_shortcutcolor;
 859         } button;
 860 };
 861 .Ed
 862 .Pp
 863 A member with the
 864 .Dq f_
 865 prefix refers to an element with focus.
 866 .Pp
 867 .Fn bsddialog_get_theme
 868 sets
 869 .Fa theme
 870 like the current theme.
 871 .Pp
 872 A color can be set by the value returned by
 873 .Fn bsddialog_color ,
 874 Possible values for
 875 .Fa background
 876 and
 877 .Fa foreground
 878 are:
 879 .Dv BSDDIALOG_BLACK ,
 880 .Dv BSDDIALOG_RED ,
 881 .Dv BSDDIALOG_GREEN ,
 882 .Dv BSDDIALOG_YELLOW ,
 883 .Dv BSDDIALOG_BLUE ,
 884 .Dv BSDDIALOG_MAGENTA ,
 885 .Dv BSDDIALOG_CYAN ,
 886 and
 887 .Dv BSDDIALOG_WHITE ,
 888 .Fa flags
 889 specifies OR-flags, possible values:
 890 .Dv BSDDIALOG_BOLD ,
 891 .Dv BSDDIALOG_REVERSE
 892 and
 893 .Dv BSDDIALOG_UNDERLINE .
 894 .Fn bsddialog_color_attrs
 895 gets the properties of a color.
 896 .Pp
 897 .Fn bsddialog_set_theme
 898 sets
 899 .Fa theme
 900 like current theme, the changes takes effect only for dialogs built after the
 901 call.
 902 .Pp
 903 The library provides predefined themes:
 904 .Dv BSDDIALOG_THEME_BLACKWHITE ,
 905 .Dv BSDDIALOG_THEME_BSDDIALOG ,
 906 .Dv BSDDIALOG_THEME_FLAT
 907 and
 908 .Dv BSDDIALOG_THEME_DIALOG ,
 909 they can be set via
 910 .Fn bsddialog_set_default_theme .
 911 .Pp
 912 .Fn bsddialog_hascolors
 913 returns
 914 .Dv true
 915 if the terminal provides colors,
 916 .Dv false
 917 otherwise.
 918 .Sh RETURN VALUES
 919 The functions return the value
 920 .Dv BSDDIALOG_ERROR
 921 if unsuccessful;
 922 otherwise, depending on the pressed button, the following values can be
 923 returned:
 924 .Dv BSDDIALOG_OK ,
 925 .Dv BSDDIALOG_CANCEL ,
 926 .Dv BSDDIALOG_HELP ,
 927 .Dv BSDDIALOG_EXTRA ,
 928 .Dv BSDDIALOG_GENERIC1
 929 or
 930 .Dv BSDDIALOG_GENERIC2 .
 931 .Dv BSDDIALOG_YES
 932 and
 933 .Dv BSDDIALOG_NO
 934 are aliases for
 935 .Dv BSDDIALOG_OK
 936 and
 937 .Dv BSDDIALOG_CANCEL ,
 938 respectively.
 939 .Pp
 940 The functions return
 941 .Dv BSDDIALOG_ESC
 942 if
 943 .Fa conf.key.enable_esc
 944 is enabled and the ESC key is pressed.
 945 .Pp
 946 .Fn bsddialog_pause
 947 returns
 948 .Dv BSDDIALOG_TIMEOUT
 949 if the timeout expires.
 950 .Sh EXAMPLES
 951 .Dq Yes-No Question
 952 Example:
 953 .Pp
 954 .Bd -literal -offset indent -compact
 955 int output;
 956 struct bsddialog_conf conf;
 957
 958 if (bsddialog_init() == BSDDIALOG_ERROR)
 959         return (1);
 960
 961 bsddialog_initconf(&conf);
 962 conf.title = "yesno";
 963 output = bsddialog_yesno(&conf, "Example", 7, 25);
 964
 965 bsddialog_end();
 966
 967 switch (output) {
 968 case BSDDIALOG_YES:
 969         printf("Yes\\n");
 970         break;
 971 case BSDDIALOG_NO
 972         printf("NO\\n");
 973         break;
 974 case BSDDIALOG_ERROR:
 975         printf("Error: %s\\n", bsddialog_geterror());
 976 }
 977 .Ed
 978 .Pp
 979 Theme Example:
 980 .Pp
 981 .Bd -literal -offset indent -compact
 982 struct bsddialog_conf conf;
 983 struct bsddialog_theme theme;
 984
 985 bsddialog_init();
 986
 987 bsddialog_initconf(&conf);
 988 bsddialog_msgbox(&conf, "Default theme", 7, 25);
 989
 990 bsddialog_get_theme(&theme);
 991 theme.screen.color = bsddialog_color(BSDDIALOG_RED, BSDDIALOG_GREEN,
 992     BSDDIALOG_BOLD);
 993 bsddialog_set_theme(&theme);
 994 bsddialog_backtitle(&conf, "Red foreground and Green background");
 995 bsddialog_msgbox(&conf, "Change screen color", 7, 25);
 996
 997 bsddialog_set_default_theme(BSDDIALOG_THEME_BLACKWHITE);
 998 bsddialog_msgbox(&conf, "Black and White theme", 7, 25);
 999
1000 bsddialog_end();
1001 .Ed
1002 .Pp
1003 Mixedlist Example:
1004 .Pp
1005 .Bd -literal -offset indent -compact
1006 unsigned int i, j;
1007 struct bsddialog_conf conf;
1008 struct bsddialog_menuitem item;
1009 struct bsddialog_menuitem check[2] = {
1010     { "1", true,  0, "Name 1", "Desc 1", "Check Bottom Desc 1" },
1011     { "2", false, 0, "Name 2", "Desc 2", "Check Bottom Desc 2" }
1012 };
1013 struct bsddialog_menuitem sep[1] = {
1014     { "3", true, 0, "Radiolist", "(desc)", "" }
1015 };
1016 struct bsddialog_menuitem radio[5] = {
1017     { "4", true,  0, "Name 1", "Desc 1", "Radio Bottom Desc 1" },
1018     { "5", false, 0, "Name 2", "Desc 2", "Radio Bottom Desc 2" }
1019 };
1020 struct bsddialog_menugroup group[3] = {
1021     { BSDDIALOG_CHECKLIST, 2, check },
1022     { BSDDIALOG_SEPARATOR, 1, sep   },
1023     { BSDDIALOG_RADIOLIST, 2, radio }
1024 };
1025
1026 bsddialog_init();
1027 bsddialog_initconf(&conf);
1028 bsddialog_mixedlist(&conf, "Example", 20, 30, 11, 3, group, NULL,
1029     NULL);
1030 bsddialog_end();
1031
1032 for (i = 0; i < 3; i++) {
1033         for (j = 0; j < group[i].nitems; j++) {
1034                 item = group[i].items[j];
1035                 switch (item.type) {
1036                 case BSDDIALOG_SEPARATOR:
1037                         printf("---- %s ----\\n", item.name);
1038                         break;
1039                 case BSDDIALOG_RADIOLIST:
1040                         printf(" (%c) %s\\n",
1041                             item.on ? '*' : ' ', item.name);
1042                         break;
1043                 case BSDDIALOG_CHECKLIST:
1044                         printf(" [%c] %s\\n",
1045                             item.on ? 'X' : ' ', item.name);
1046                         break;
1047                 }
1048         }
1049 }
1050 .Ed
1051 .Sh SEE ALSO
1052 .Xr bsddialog 1 ,
1053 .Xr curses 3
1054 .Sh HISTORY
1055 The
1056 .Nm bsddialog
1057 library first appeared in
1058 .Fx 14.0 .
1059 .Sh AUTHORS
1060 .Nm bsddialog
1061 was written by
1062 .An Alfonso Sabato Siciliano Aq Mt asiciliano@FreeBSD.org .