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 260The 261.Nm bsddialog 262library provides an API to build Text User Interface dialogs and widgets. 263.Pp 264.Fn bsddialog_init 265initializes the library, the only functions that can be called before is 266.Fn bsddialog_initconf 267described later. 268After the initialization the input and output should be handled via the library 269API. 270.Pp 271.Fn bsddialog_init_notheme 272is equivalent to 273.Fn bsddialog_init 274except it does not set the default graphical theme; see 275.Sx Theme 276subsection to set a theme explicitly. 277.Pp 278.Fn bsddialog_end 279restores the screen like before 280.Fn bsddialog_init . 281After the call is not possible to use the library functions. 282.Pp 283.Fn bsddialog_inmode 284returns 285.Dv true 286after 287.Fn bsddialog_init 288or 289.Fn bsddialog_init_notheme 290and before 291.Fn bsddialog_end , 292.Dv false 293otherwise. 294.Pp 295.Fn bsddialog_backtitle 296prints 297.Fa backtitle 298on the top of the screen. 299The function handles 300.Fa conf.ascii_lines 301and 302.Fa conf.no_lines 303described later. 304.Pp 305.Fn bsddialog_error 306returns a string to describe the last error. 307The function should be called after a 308.Dv BSDDIALOG_ERROR 309returned value. 310.Pp 311.Fn bsddialog_clear 312clears the screen from 313.Fa y . 314.Pp 315.Fn bsddialog_refresh 316useful to refresh the screen after a terminal mode change, see 317.Xr terminfo 5 . 318.Ss Dialogs 319The dialogs have common arguments. 320.Fa text 321is a string printed inside the dialog. 322Each 323.Fa char* 324parameter can be a multibyte character string depending on current locale, see 325.Xr setlocale 3 . 326.Fa rows 327and 328.Fa cols 329are height and width, their value can be a fixed size, 330.Dv BSDDIALOG_AUTOSIZE 331or 332.Dv BSDDIALOG_FULLSCREEN . 333.Fa conf 334is a struct to customize the current dialog, it does not set global properties 335to the library. 336.Pp 337.Bd -literal -offset indent -compact 338struct 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 402ascii characters to draw lines, default wide characters. 403.It Fa conf.auto_minheight 404minimum height if 405.Fa rows 406is 407.Dv BSDDIALOG_AUTOSIZE . 408.It Fa conf.auto_minwidth 409minimum width if 410.Fa cols 411is 412.Dv BSDDIALOG_AUTOSIZE . 413.It Fa conf.auto_topmargin 414top margin if 415.Fa rows 416is 417.Dv BSDDIALOG_AUTOSIZE 418or 419.Dv BSDDIALOG_FULLSCREEN , 420.Fa conf.y 421has to be 422.Dv BSDDIALOG_CENTER . 423.It Fa conf.auto_downmargin 424down margin if 425.Fa rows 426is 427.Dv BSDDIALOG_AUTOSIZE 428or 429.Dv BSDDIALOG_FULLSCREEN . 430.It Fa conf.bottomtitle 431dialog subtitle. 432.It Fa conf.clear 433hide the dialog at exit. 434.It Fa conf.get_height 435if not 436.Dv NULL 437is set like the dialog height. 438.It Fa conf.get_width 439if not 440.Dv NULL 441is set like the dialog width. 442.It Fa conf.no_lines 443not draw lines. 444.It Fa conf.shadow 445draw shadow. 446.It Fa conf.sleep 447wait before to return, the value is in seconds. 448.It Fa conf.title 449dialog title. 450.It Fa conf.y 451dialog vertical position, 0 is top screen, can be 452.Dv BSDDIALOG_CENTER . 453.It Fa conf.x 454dialog 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 460enable 461.Dv ESC 462key to close the dialog. 463.It Fa conf.key.f1_file 464open a file in a textbox if F1 is pressed. 465.It Fa conf.key.f1_message 466build a msgbox with message if F1 is pressed. 467.El 468.Pp 469.Bl -column -compact 470.It Fa conf.text.cols_per_row 471Try to set the number of columns for a row of 472.Fa text 473with autosizing, default 474.Dv 10 . 475.It Fa conf.text.escape 476enable escapes in 477.Fa text : 478.It Dq \eZ0 479black. 480.It Dq \eZ1 481red. 482.It Dq \eZ2 483green. 484.It Dq \eZ3 485yellow. 486.It Dq \eZ4 487blue. 488.It Dq \eZ5 489magenta. 490.It Dq \eZ6 491cyan. 492.It Dq \eZ7 493white. 494.It Dq \eZb 495bold. 496.It Dq \eZB 497disable bold. 498.It Dq \eZd 499Half bright. 500.It Dq \eZD 501disable half bright. 502.It Dq \eZk 503Blink. 504.It Dq \eZK 505disable blinking. 506.It Dq \eZr 507reverse foreground and background. 508.It Dq \eZR 509disable reverse. 510.It Dq \eZs 511Highlight. 512.It Dq \eZS 513disable highlighting. 514.It Dq \eZu 515underline. 516.It Dq \eZU 517disable underline. 518.It Dq \eZn 519disable each customization. 520.It Fa conf.text.tablen 521tab length for 522.Fa text 523argument and 524.Fn bsddialog_textbox 525function. 526.El 527.Pp 528.Bl -column -compact 529.It Fa conf.button.always_active 530buttons always active, avoiding focus switch between buttons and input fields or 531input boxes in 532.Fn bsddialog_form , 533.Fn bsddialog_datebox , 534.Fn bsddialog_calendar 535and 536.Fn bsddialog_timebox . 537.It Fa conf.button.left1_label 538add a button with the specified label. 539.It Fa conf.button.left2_label 540add a button with the specified label. 541.It Fa conf.button.left3_label 542add a button with the specified label. 543.It Fa conf.button.without_ok 544disable OK button. 545.It Fa conf.button.ok_label 546set label for OK button. 547.It Fa conf.button.with_extra 548add Extra button. 549.It Fa conf.button.extra_label 550set a label for Extra button. 551.It Fa conf.button.without_cancel 552disable Cancel button. 553.It Fa conf.button.cancel_label 554sets a label for Cancel button. 555.It Fa conf.button.default_cancel 556on startup focus on the Cancel button. 557.It Fa conf.button.with_help 558add Help button. 559.It Fa conf.button.help_label 560set a label for Help button. 561.It Fa conf.button.right1_label 562add a button with the specified label. 563.It Fa conf.button.right2_label 564add a button with the specified label. 565.It Fa conf.button.right3_label 566add a button with the specified label. 567.It Fa conf.button.default_label 568focus on the button with the specified label. 569.El 570.Pp 571.Fn bsddialog_initconf 572initializes 573.Fa conf 574disabling each property, except 575.Fa conf.shadow 576to true, 577.Fa conf.y 578and 579.Fa conf.x 580to 581.Dv BSDDIALOG_CENTER , 582.Fa conf.text.cols_per_row 583to 584.Dv 10 . 585.Pp 586.Fn bsddialog_calendar 587builds a dialog to select a date. 588.Fa year , 589.Fa month , 590and 591.Fa day 592are default values on startup, selected date at exit. 593.Pp 594.Fn bsddialog_checklist 595builds dialogs to select some item from a list via the SPACE key, can be 596customized by 597.Fa conf.menu.* . 598See 599.Fn bsddialog_menu . 600.Pp 601.Fn bsddialog_datebox 602builds a dialog to select a date. 603.Fa year , 604.Fa month , 605and 606.Fa day 607are default values on startup, selected date at exit. 608The function can be customized by: 609.Bl -column -compact 610.It Fa conf.date.format 611date 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 618builds a dialog to display an array of 619.Fa items 620of 621.Fa nitems 622elements to get input strings. 623.Fa formrows 624is the graphical height for the items inside the dialog, 625.Dv 0 626for autosizing. 627If not 628.Dv NULL 629.Fa focusitem 630is the default item index on startup and the last focused item at exit, a 631negative value if no item is focused. 632An item is defined like: 633.Pp 634.Bd -literal -offset indent -compact 635struct 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 654is a string to describe the request at the position 655.Fa ylabel 656and 657.Fa xlabel . 658The field for the input is at the position 659.Fa yfield 660and 661.Fa xfield , 662.Fa fieldlen 663is its graphical width, while 664.Fa maxvalelen 665is the maximum number of characters of the input string. 666.Fa init 667is the default field value. 668If no error occurs 669.Fa value 670is the allocated memory with the current field string at exit, its size depends 671on the current locale. 672.Fa flags 673is 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 681is printed at bottom screen if the item is focused. 682.Pp 683.Fn bsddialog_form 684can be customized by: 685.Bl -column -compact 686.It Fa conf.form.securech 687charachter to hide the input with 688.Dv BSDDIALOG_FIELDHIDDEN . 689.It Fa conf.form.securembch 690multibyte charachter to hide the input with 691.Dv BSDDIALOG_FIELDHIDDEN , 692.Fa conf.form.securech 693is ignored. 694.It Fa conf.form.value_wchar 695the allocated 696.Fa value 697is a 698.Em wchar_t* 699string. 700.El 701.Pp 702.Fn bsddialog_gauge 703builds a dialog with a bar to show 704.Fa perc . 705If the file descriptor 706.Fa fd 707is greater or equal to 0 the dialog waits to read 708.Fa sep 709from it, then the first string replaces 710.Fa perc 711and the following strings replace 712.Fa text 713until the next 714.Fa sep , 715the loop ends reading 716.Fa end . 717.Pp 718.Fn bsddialog_infobox 719builds a dialog without buttons and returns instantly. 720.Pp 721.Fn bsddialog_menu 722builds a dialog to select an item from a list via SPACE or ENTER. 723An item is 724defined like: 725.Pp 726.Bd -literal -offset indent -compact 727struct 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 739and 740.Fa desc 741are printed at the item row. 742.Fa bottomdesc 743is printed at bottom screen if the item is focused. 744.Fa depth 745is a margin between 746.Fa prefix 747and 748.Fa name . 749At exit 750.Fa on 751is set to 752.Dv true 753if the item is selected, 754.Dv false 755otherwise. 756.Fa items 757is an array of items of 758.Fa nitem 759elements. 760.Fa menurows 761is the graphical height of the list inside the dialog, if 762.Fa cols 763is 764.Dv BSDDIALOG_AUTOSIZE 765.Fa menurows 766specifies a maximum value. 767if not 768.Dv NULL 769.Fa focusitem 770is the default item index on startup and the last focused item at exit, a 771negative value if no item is focused. 772.Pp 773.Fn bsddialog_checklist , 774.Fn bsddialog_menu , 775.Fn bsddialog_mixedlist 776and 777.Fn bsddialog_radiolist 778can be customized by: 779.Bl -column -compact 780.It Fa conf.menu.align_left 781align items to left, default center. 782.It Fa conf.menu.no_desc 783hide items description. 784.It Fa conf.menu.no_name 785hide items name, mutually exclusive with 786.Fa conf.menu.no_desc . 787.It Fa conf.menu.shortcut_buttons 788enable shortcut keys on buttons, default on items. 789.El 790.Pp 791.Fn bsddialog_mixedgauge 792builds a dialog with a main bar with the 793.Fa mainperc 794percentage and 795.Fa nminibars 796each one with a 797.Fa minilabel 798and a 799.Fa miniperc . 800.Fa miniperc 801can 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 811to hide 812.Fa miniperc , 813.Dv BSDDIALOG_MG_NA , 814.Dv BSDDIALOG_MG_PENDING 815to print a descriptive string, otherwise 816.Dq "UNKNOWN" 817is printed. 818.Pp 819.Fn bsddialog_mixedlist 820builds a dialog with collections of checklists, radiolists and separators. 821A collection is a set defined like: 822.Pp 823.Bd -literal -offset indent -compact 824enum bsddialog_menutype { 825 BSDDIALOG_CHECKLIST, 826 BSDDIALOG_RADIOLIST, 827 BSDDIALOG_SEPARATOR, 828}; 829 830struct 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 839is an array of sets of 840.Fa ngroups 841elements. 842.Fa menurows 843is the graphical height size for the list. 844If not 845.Dv NULL , 846.Fa focuslist 847and 848.Fa focusitem 849specify the default item on startup and the last focused item at exit, could be 850a negative value if no item is focused. 851The dialog can be customized by 852.Fa conf.menu.* , 853see 854.Fn bsddialog_menu . 855.Pp 856.Fn bsddialog_msgbox 857builds a dialog with OK button. 858.Pp 859.Fn bsddialog_pause 860builds a dialog waiting until the timeout in 861.Fa seconds 862expires or a button is pressed. 863At exit 864.Fa seconds 865is set like remaining time. 866.Pp 867.Fn bsddialog_radiolist 868builds dialogs to select at most an item from a list via the SPACE key, can be 869customized by 870.Fa conf.menu.* . 871See 872.Fn bsddialog_menu . 873.Pp 874.Fn bsddialog_rangebox 875to select a value between 876.Fa min 877and 878.Fa max . 879.Fa value 880is the default value on startup and the selected value at exit. 881The current value is printed inside a bar, the keys UP, DOWN, HOME, END, PAGEUP 882and PAGEDOWN can change it. 883.Pp 884.Fn bsddialog_textbox 885opens and prints 886.Fa file . 887UP, DOWN, LEFT, RIGHT, HOME, END, PAGEUP and PAGEDOWN keys are available to 888navigate the file, TAB changes button. 889.Dq OK 890button is renamed 891.Dq EXIT . 892.Pp 893.Fn bsddialog_timebox 894builds a dialog to choose a time. 895.Fa hh , 896.Fa mm , 897and 898.Fa ss 899are default values on startup, selected time at exit. 900.Pp 901.Fn bsddialog_yesno 902provides a dialog for a 903.Dq Yes-No Question , 904the labels on buttons are Yes and No. 905.Ss Theme 906The graphical properties are global to the library. 907They are represented by 908.Fa struct bsddialog_theme 909and can be customized at runtime via the 910.In bsddialog_theme.h 911API. 912.Pp 913.Bd -literal -offset indent -compact 914struct 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 972A member with the 973.Dq f_ 974refers to focus when an element can be in selected or not selected state. 975.Pp 976.Fn bsddialog_color 977generates and returns a color to set a 978.Fa struct bsddialog_theme 979color member. 980An 981.Fa enum bsddialog_color 982can 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 992is 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 1001sets, if not NULL, 1002.Fa foreground , 1003.Fa background , 1004.Fa flags , 1005like the properties of 1006.Fa color , 1007see 1008.Fn bsddialog_color . 1009.Pp 1010.Fn bsddialog_get_theme 1011sets 1012.Fa theme 1013like the current runtime theme. 1014.Pp 1015.Fn bsddialog_hascolors 1016returns 1017.Dv true 1018if the terminal provides colors, 1019.Dv false 1020otherwise. 1021.Pp 1022.Fn bsddialog_set_theme 1023sets 1024.Fa theme 1025like current runtime theme. 1026Changes take effect only for dialogs built after 1027the call. 1028.Pp 1029.Fn bsddialog_set_default_theme 1030sets a library default theme like current theme, possible values: 1031.Dv BSDDIALOG_THEME_BLACKWHITE , 1032.Dv BSDDIALOG_THEME_FLAT , 1033.Dv BSDDIALOG_THEME_3D . 1034Changes take effect only for dialogs built after the call. 1035.Sh RETURN VALUES 1036The functions return the value 1037.Dv BSDDIALOG_ERROR 1038if unsuccessful; 1039otherwise, depending on the pressed button, the following values can be 1040returned: 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 1052and 1053.Dv BSDDIALOG_NO 1054are aliases for 1055.Dv BSDDIALOG_OK 1056and 1057.Dv BSDDIALOG_CANCEL , 1058respectively. 1059.Pp 1060The functions return 1061.Dv BSDDIALOG_ESC 1062if 1063.Fa conf.key.enable_esc 1064is enabled and the ESC key is pressed. 1065.Pp 1066.Fn bsddialog_pause 1067returns 1068.Dv BSDDIALOG_TIMEOUT 1069if the timeout expires. 1070.Sh EXAMPLES 1071.Dq Yes-No Question 1072Example: 1073.Pp 1074.Bd -literal -offset indent -compact 1075int output; 1076struct bsddialog_conf conf; 1077 1078if (bsddialog_init() == BSDDIALOG_ERROR) 1079 return (1); 1080 1081bsddialog_initconf(&conf); 1082conf.title = "yesno"; 1083output = bsddialog_yesno(&conf, "Example", 7, 25); 1084 1085bsddialog_end(); 1086 1087switch (output) { 1088case BSDDIALOG_YES: 1089 printf("Yes\\n"); 1090 break; 1091case BSDDIALOG_NO 1092 printf("NO\\n"); 1093 break; 1094case BSDDIALOG_ERROR: 1095 printf("Error: %s\\n", bsddialog_geterror()); 1096 break; 1097} 1098.Ed 1099.Pp 1100Theme Example: 1101.Pp 1102.Bd -literal -offset indent -compact 1103struct bsddialog_conf conf; 1104struct bsddialog_theme theme; 1105 1106bsddialog_init(); 1107 1108bsddialog_initconf(&conf); 1109bsddialog_msgbox(&conf, "Default theme", 7, 25); 1110 1111bsddialog_get_theme(&theme); 1112theme.screen.color = bsddialog_color(BSDDIALOG_RED, BSDDIALOG_GREEN, 1113 BSDDIALOG_BOLD); 1114bsddialog_set_theme(&theme); 1115bsddialog_backtitle(&conf, "Red foreground and Green background"); 1116bsddialog_msgbox(&conf, "Change screen color", 7, 25); 1117 1118bsddialog_set_default_theme(BSDDIALOG_THEME_BLACKWHITE); 1119bsddialog_msgbox(&conf, "Black and White theme", 7, 25); 1120 1121bsddialog_end(); 1122.Ed 1123.Pp 1124Mixedlist Example: 1125.Pp 1126.Bd -literal -offset indent -compact 1127unsigned int i, j; 1128struct bsddialog_conf conf; 1129struct bsddialog_menuitem item; 1130struct 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}; 1134struct bsddialog_menuitem sep[1] = { 1135 { "3", true, 0, "Radiolist", "(desc)", "" } 1136}; 1137struct 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}; 1141struct bsddialog_menugroup group[3] = { 1142 { BSDDIALOG_CHECKLIST, 2, check }, 1143 { BSDDIALOG_SEPARATOR, 1, sep }, 1144 { BSDDIALOG_RADIOLIST, 2, radio } 1145}; 1146 1147bsddialog_init(); 1148bsddialog_initconf(&conf); 1149bsddialog_mixedlist(&conf, "Example", 20, 30, 11, 3, group, NULL, 1150 NULL); 1151bsddialog_end(); 1152 1153for (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 1176The 1177.Nm bsddialog 1178library first appeared in 1179.Fx 14.0 . 1180.Sh AUTHORS 1181.Nm bsddialog 1182was written by 1183.An Alfonso Sabato Siciliano Aq Mt asiciliano@FreeBSD.org . 1184