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