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