contrib/bsddialog/lib/bsddialog.3

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