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