1.\" 2.\" Copyright (c) 2021-2024 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 March 16, 2024 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 and ENTER. 723An item is defined like: 724.Pp 725.Bd -literal -offset indent -compact 726struct bsddialog_menuitem { 727 const char *prefix; 728 bool on; 729 unsigned int depth; 730 const char *name; 731 const char *desc; 732 const char *bottomdesc; 733}; 734.Ed 735.Pp 736.Fa prefix , 737.Fa name 738and 739.Fa desc 740are printed at the item row. 741.Fa bottomdesc 742is printed at bottom screen if the item is focused. 743.Fa depth 744is a margin between 745.Fa prefix 746and 747.Fa name . 748At exit 749.Fa on 750is set to 751.Dv true 752if the item is selected, 753.Dv false 754otherwise. 755.Fa items 756is an array of items of 757.Fa nitem 758elements. 759.Fa menurows 760is the graphical height of the list inside the dialog, if 761.Fa cols 762is 763.Dv BSDDIALOG_AUTOSIZE 764.Fa menurows 765specifies a maximum value. 766if not 767.Dv NULL 768.Fa focusitem 769is the default item index on startup and the last focused item at exit, a 770negative value if no item is focused. 771.Pp 772.Fn bsddialog_checklist , 773.Fn bsddialog_menu , 774.Fn bsddialog_mixedlist 775and 776.Fn bsddialog_radiolist 777can be customized by: 778.Bl -column -compact 779.It Fa conf.menu.align_left 780align items to left, default center. 781.It Fa conf.menu.no_desc 782hide items description. 783.It Fa conf.menu.no_name 784hide items name, mutually exclusive with 785.Fa conf.menu.no_desc . 786.It Fa conf.menu.shortcut_buttons 787enable shortcut keys on buttons, default on items. 788.El 789.Pp 790.Fn bsddialog_mixedgauge 791builds a dialog with a main bar with the 792.Fa mainperc 793percentage and 794.Fa nminibars 795each one with a 796.Fa minilabel 797and a 798.Fa miniperc . 799.Fa miniperc 800can be: a positive value to print a bar with a percentace, a negative constant 801.Dv BSDDIALOG_MG_SUCCEEDED , 802.Dv BSDDIALOG_MG_FAILED , 803.Dv BSDDIALOG_MG_PASSED , 804.Dv BSDDIALOG_MG_COMPLETED , 805.Dv BSDDIALOG_MG_CHECKED , 806.Dv BSDDIALOG_MG_DONE , 807.Dv BSDDIALOG_MG_SKIPPED , 808.Dv BSDDIALOG_MG_INPROGRESS , 809.Dv BSDDIALOG_MG_BLANK 810to hide 811.Fa miniperc , 812.Dv BSDDIALOG_MG_NA , 813.Dv BSDDIALOG_MG_PENDING 814to print a descriptive string, otherwise 815.Dq "UNKNOWN" 816is printed. 817.Pp 818.Fn bsddialog_mixedlist 819builds a dialog with collections of checklists, radiolists and separators. 820A collection is a set defined like: 821.Pp 822.Bd -literal -offset indent -compact 823enum bsddialog_menutype { 824 BSDDIALOG_CHECKLIST, 825 BSDDIALOG_RADIOLIST, 826 BSDDIALOG_SEPARATOR, 827}; 828 829struct bsddialog_menugroup { 830 enum bsddialog_menutype type; 831 unsigned int nitems; 832 struct bsddialog_menuitem *items; 833 unsigned int min_on; /* unused for now */ 834}; 835.Ed 836.Pp 837.Fa groups 838is an array of sets of 839.Fa ngroups 840elements. 841.Fa menurows 842is the graphical height size for the list. 843If not 844.Dv NULL , 845.Fa focuslist 846and 847.Fa focusitem 848specify the default item on startup and the last focused item at exit, could be 849a negative value if no item is focused. 850The dialog can be customized by 851.Fa conf.menu.* , 852see 853.Fn bsddialog_menu . 854.Pp 855.Fn bsddialog_msgbox 856builds a dialog with OK button. 857.Pp 858.Fn bsddialog_pause 859builds a dialog waiting until the timeout in 860.Fa seconds 861expires or a button is pressed. 862At exit 863.Fa seconds 864is set like remaining time. 865.Pp 866.Fn bsddialog_radiolist 867builds dialogs to select at most an item from a list via the SPACE key, can be 868customized by 869.Fa conf.menu.* . 870See 871.Fn bsddialog_menu . 872.Pp 873.Fn bsddialog_rangebox 874to select a value between 875.Fa min 876and 877.Fa max . 878.Fa value 879is the default value on startup and the selected value at exit. 880The current value is printed inside a bar. 881.Pp 882.Fn bsddialog_textbox 883opens and prints 884.Fa file . 885TAB key changes button. 886Extra keys 0, h, l, k, j are available to navigate the text. 887.Dq OK 888button is renamed 889.Dq EXIT . 890.Pp 891.Fn bsddialog_timebox 892builds a dialog to choose a time. 893.Fa hh , 894.Fa mm , 895and 896.Fa ss 897are default values on startup, selected time at exit. 898.Pp 899.Fn bsddialog_yesno 900provides a dialog for a 901.Dq Yes-No Question , 902the labels on buttons are 903.Dq Yes 904and 905.Dq No . 906.Ss Keys 907.Bl -tag -width Ds 908.It Ctrl-l 909Redraw the dialog. 910.It F1 911Refer to 912.Fa conf.key.f1_file 913and 914.Fa conf.key.f1_message . 915.It SPACE 916Select menu item. 917.It UP DOWN LEFT RIGHT - + HOME END PAGEUP PAGEDOWN Ctrl-p Ctrl-n TAB 918Navigate elements and set value, depending on the dialog. 919.El 920.Ss Theme 921The graphical properties are global to the library. 922They are represented by 923.Fa struct bsddialog_theme 924and can be customized at runtime via the 925.In bsddialog_theme.h 926API. 927.Pp 928.Bd -literal -offset indent -compact 929struct bsddialog_theme { 930 struct { 931 int color; 932 } screen; 933 struct { 934 int color; 935 unsigned int y; 936 unsigned int x; 937 } shadow; 938 struct { 939 int color; 940 bool delimtitle; 941 int titlecolor; 942 int lineraisecolor; 943 int linelowercolor; 944 int bottomtitlecolor; 945 int arrowcolor; 946 } dialog; 947 struct { 948 int f_prefixcolor; 949 int prefixcolor; 950 int f_selectorcolor; 951 int selectorcolor; 952 int f_namecolor; 953 int namecolor; 954 int f_desccolor; 955 int desccolor; 956 int f_shortcutcolor; 957 int shortcutcolor; 958 int bottomdesccolor; 959 int sepnamecolor; 960 int sepdesccolor; 961 } menu; 962 struct { 963 int f_fieldcolor; 964 int fieldcolor; 965 int readonlycolor; 966 int bottomdesccolor; 967 } form; 968 struct { 969 int f_color; 970 int color; 971 } bar; 972 struct { 973 unsigned int minmargin; 974 unsigned int maxmargin; 975 char leftdelim; 976 char rightdelim; 977 int f_delimcolor; 978 int delimcolor; 979 int f_color; 980 int color; 981 int f_shortcutcolor; 982 int shortcutcolor; 983 } button; 984}; 985.Ed 986.Pp 987A member with the 988.Dq f_ 989refers to focus when an element can be in selected or not selected state. 990.Pp 991.Fn bsddialog_color 992generates and returns a color to set a 993.Fa struct bsddialog_theme 994color member. 995An 996.Fa enum bsddialog_color 997can be: 998.Dv BSDDIALOG_BLACK , 999.Dv BSDDIALOG_RED , 1000.Dv BSDDIALOG_GREEN , 1001.Dv BSDDIALOG_YELLOW , 1002.Dv BSDDIALOG_BLUE , 1003.Dv BSDDIALOG_MAGENTA , 1004.Dv BSDDIALOG_CYAN , 1005.Dv BSDDIALOG_WHITE . 1006.Fa flags 1007is an OR value: 1008.Dv BSDDIALOG_BLINK , 1009.Dv BSDDIALOG_BOLD , 1010.Dv BSDDIALOG_HALFBRIGHT , 1011.Dv BSDDIALOG_HIGHLIGHT , 1012.Dv BSDDIALOG_REVERSE , 1013.Dv BSDDIALOG_UNDERLINE . 1014.Pp 1015.Fn bsddialog_color_attrs 1016sets, if not NULL, 1017.Fa foreground , 1018.Fa background , 1019.Fa flags , 1020like the properties of 1021.Fa color , 1022see 1023.Fn bsddialog_color . 1024.Pp 1025.Fn bsddialog_get_theme 1026sets 1027.Fa theme 1028like the current runtime theme. 1029.Pp 1030.Fn bsddialog_hascolors 1031returns 1032.Dv true 1033if the terminal provides colors, 1034.Dv false 1035otherwise. 1036.Pp 1037.Fn bsddialog_set_theme 1038sets 1039.Fa theme 1040like current runtime theme. 1041Changes take effect only for dialogs built after 1042the call. 1043.Pp 1044.Fn bsddialog_set_default_theme 1045sets a library default theme like current theme, possible values: 1046.Dv BSDDIALOG_THEME_BLACKWHITE , 1047.Dv BSDDIALOG_THEME_FLAT , 1048.Dv BSDDIALOG_THEME_3D . 1049Changes take effect only for dialogs built after the call. 1050.Sh RETURN VALUES 1051The functions return the value 1052.Dv BSDDIALOG_ERROR 1053if unsuccessful; 1054otherwise, depending on the pressed button, the following values can be 1055returned: 1056.Dv BSDDIALOG_OK , 1057.Dv BSDDIALOG_CANCEL , 1058.Dv BSDDIALOG_HELP , 1059.Dv BSDDIALOG_EXTRA , 1060.Dv BSDDIALOG_LEFT1 , 1061.Dv BSDDIALOG_LEFT2 , 1062.Dv BSDDIALOG_LEFT3 , 1063.Dv BSDDIALOG_RIGHT1 , 1064.Dv BSDDIALOG_RIGHT2 , 1065.Dv BSDDIALOG_RIGHT3 . 1066.Dv BSDDIALOG_YES 1067and 1068.Dv BSDDIALOG_NO 1069are aliases for 1070.Dv BSDDIALOG_OK 1071and 1072.Dv BSDDIALOG_CANCEL , 1073respectively. 1074.Pp 1075The functions return 1076.Dv BSDDIALOG_ESC 1077if 1078.Fa conf.key.enable_esc 1079is enabled and the ESC key is pressed. 1080.Pp 1081.Fn bsddialog_pause 1082returns 1083.Dv BSDDIALOG_TIMEOUT 1084if the timeout expires. 1085.Sh EXAMPLES 1086.Dq Yes-No Question 1087Example: 1088.Pp 1089.Bd -literal -offset indent -compact 1090int output; 1091struct bsddialog_conf conf; 1092 1093if (bsddialog_init() == BSDDIALOG_ERROR) 1094 return (1); 1095 1096bsddialog_initconf(&conf); 1097conf.title = "yesno"; 1098output = bsddialog_yesno(&conf, "Example", 7, 25); 1099 1100bsddialog_end(); 1101 1102switch (output) { 1103case BSDDIALOG_YES: 1104 printf("Yes\\n"); 1105 break; 1106case BSDDIALOG_NO 1107 printf("No\\n"); 1108 break; 1109case BSDDIALOG_ERROR: 1110 printf("Error: %s\\n", bsddialog_geterror()); 1111 break; 1112} 1113.Ed 1114.Pp 1115Theme Example: 1116.Pp 1117.Bd -literal -offset indent -compact 1118struct bsddialog_conf conf; 1119struct bsddialog_theme theme; 1120 1121bsddialog_init(); 1122 1123bsddialog_initconf(&conf); 1124bsddialog_msgbox(&conf, "Default theme", 7, 25); 1125 1126bsddialog_get_theme(&theme); 1127theme.screen.color = bsddialog_color(BSDDIALOG_RED, BSDDIALOG_GREEN, 1128 BSDDIALOG_BOLD); 1129bsddialog_set_theme(&theme); 1130bsddialog_backtitle(&conf, "Red foreground and Green background"); 1131bsddialog_msgbox(&conf, "Change screen color", 7, 25); 1132 1133bsddialog_set_default_theme(BSDDIALOG_THEME_BLACKWHITE); 1134bsddialog_msgbox(&conf, "Black and White theme", 7, 25); 1135 1136bsddialog_end(); 1137.Ed 1138.Pp 1139Mixedlist Example: 1140.Pp 1141.Bd -literal -offset indent -compact 1142unsigned int i, j; 1143struct bsddialog_conf conf; 1144struct bsddialog_menuitem item; 1145struct bsddialog_menuitem check[2] = { 1146 { "1", true, 0, "Name 1", "Desc 1", "Check Bottom Desc 1" }, 1147 { "2", false, 0, "Name 2", "Desc 2", "Check Bottom Desc 2" } 1148}; 1149struct bsddialog_menuitem sep[1] = { 1150 { "3", true, 0, "Radiolist", "(desc)", "" } 1151}; 1152struct bsddialog_menuitem radio[2] = { 1153 { "4", true, 0, "Name 1", "Desc 1", "Radio Bottom Desc 1" }, 1154 { "5", false, 0, "Name 2", "Desc 2", "Radio Bottom Desc 2" } 1155}; 1156struct bsddialog_menugroup group[3] = { 1157 { BSDDIALOG_CHECKLIST, 2, check }, 1158 { BSDDIALOG_SEPARATOR, 1, sep }, 1159 { BSDDIALOG_RADIOLIST, 2, radio } 1160}; 1161 1162bsddialog_init(); 1163bsddialog_initconf(&conf); 1164bsddialog_mixedlist(&conf, "Example", 20, 30, 11, 3, group, NULL, 1165 NULL); 1166bsddialog_end(); 1167 1168for (i = 0; i < 3; i++) { 1169 for (j = 0; j < group[i].nitems; j++) { 1170 item = group[i].items[j]; 1171 switch (item.type) { 1172 case BSDDIALOG_SEPARATOR: 1173 printf("---- %s ----\\n", item.name); 1174 break; 1175 case BSDDIALOG_RADIOLIST: 1176 printf(" (%c) %s\\n", 1177 item.on ? '*' : ' ', item.name); 1178 break; 1179 case BSDDIALOG_CHECKLIST: 1180 printf(" [%c] %s\\n", 1181 item.on ? 'X' : ' ', item.name); 1182 break; 1183 } 1184 } 1185} 1186.Ed 1187.Sh SEE ALSO 1188.Xr bsddialog 1 , 1189.Xr curses 3 1190.Sh HISTORY 1191The 1192.Nm bsddialog 1193library first appeared in 1194.Fx 14.0 . 1195.Sh AUTHORS 1196.Nm bsddialog 1197was written by 1198.An Alfonso Sabato Siciliano Aq Mt asiciliano@FreeBSD.org . 1199