1.\" 2.\" Copyright (c) 2021-2022 Alfonso Sabato Siciliano 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.Dd January 23, 2022 26.Dt BSDDIALOG 3 27.Os 28.Sh NAME 29.Nm bsddialog_backtitle , 30.Nm bsddialog_clearterminal , 31.Nm bsddialog_color , 32.Nm bsddialog_checklist , 33.Nm bsddialog_datebox , 34.Nm bsddialog_end , 35.Nm bsddialog_form , 36.Nm bsddialog_gauge , 37.Nm bsddialog_geterror , 38.Nm bsddialog_get_theme , 39.Nm bsddialog_infobox , 40.Nm bsddialog_init , 41.Nm bsddialog_initconf , 42.Nm bsddialog_menu , 43.Nm bsddialog_mixedgauge , 44.Nm bsddialog_mixedlist , 45.Nm bsddialog_msgbox , 46.Nm bsddialog_pause , 47.Nm bsddialog_radiolist , 48.Nm bsddialog_rangebox , 49.Nm bsddialog_set_theme , 50.Nm bsddialog_set_default_theme , 51.Nm bsddialog_textbox , 52.Nm bsddialog_timebox , 53.Nm bsddialog_yesno 54.Nd TUI dialogs 55.Sh LIBRARY 56.Lb libbsddialog 57.Sh SYNOPSIS 58.In bsddialog.h 59.Ft int 60.Fn bsddialog_backtitle "struct bsddialog_conf *conf" "const char *backtitle" 61.Ft int 62.Fo bsddialog_checklist 63.Fa "struct bsddialog_conf *conf" 64.Fa "const char *text" 65.Fa "int rows" 66.Fa "int cols" 67.Fa "unsigned int menurows" 68.Fa "unsigned int nitems" 69.Fa "struct bsddialog_menuitem *items" 70.Fa "int *focusitem" 71.Fc 72.Ft int 73.Fn bsddialog_clearterminal "void" 74.Ft int 75.Fo bsddialog_datebox" 76.Fa "struct bsddialog_conf *conf" 77.Fa "const char *text" 78.Fa "int rows" 79.Fa "int cols" 80.Fa "unsigned int *yy" 81.Fa "unsigned int *mm" 82.Fa "unsigned int *dd" 83.Fc 84.Ft int 85.Fn bsddialog_end "void" 86.Ft int 87.Fo bsddialog_form 88.Fa "struct bsddialog_conf *conf" 89.Fa "const char *text" 90.Fa "int rows" 91.Fa "int cols" 92.Fa "unsigned int formrows" 93.Fa "unsigned int nitems" 94.Fa "struct bsddialog_formitem *items" 95.Fc 96.Ft int 97.Fo bsddialog_gauge 98.Fa "struct bsddialog_conf *conf" 99.Fa "const char *text" 100.Fa "int rows" 101.Fa "int cols" 102.Fa "unsigned int perc" 103.Fa "int fd" 104.Fa "const char *sep" 105.Fc 106.Ft const char * 107.Fn bsddialog_geterror "void" 108.Ft int 109.Fo bsddialog_infobox 110.Fa "struct bsddialog_conf *conf" 111.Fa "const char *text" 112.Fa "int rows" 113.Fa "int cols" 114.Fc 115.Ft int 116.Fn bsddialog_init "void" 117.Ft int 118.Fn bsddialog_initconf "struct bsddialog_conf *conf" 119.Ft int 120.Fo bsddialog_menu 121.Fa "struct bsddialog_conf *conf" 122.Fa "const char *text" 123.Fa "int rows" 124.Fa "int cols" 125.Fa "unsigned int menurows" 126.Fa "unsigned int nitems" 127.Fa "struct bsddialog_menuitem *items" 128.Fa "int *focusitem" 129.Fc 130.Ft int 131.Fo bsddialog_mixedgauge 132.Fa "struct bsddialog_conf *conf" 133.Fa "const char *text" 134.Fa "int rows" 135.Fa "int cols" 136.Fa "unsigned int mainperc" 137.Fa "unsigned int nminibars" 138.Fa "char **minilabels" 139.Fa "int *minipercs" 140.Fc 141.Ft int 142.Fo bsddialog_mixedlist 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 ngroups" 149.Fa "struct bsddialog_menugroup *groups" 150.Fa "int *focuslist" 151.Fa "int *focusitem" 152.Fc 153.Ft int 154.Fo bsddialog_msgbox 155.Fa "struct bsddialog_conf *conf" 156.Fa "const char *text" 157.Fa "int rows" 158.Fa "int cols" 159.Fc 160.Ft int 161.Fo bsddialog_pause 162.Fa "struct bsddialog_conf *conf" 163.Fa "const char *text" 164.Fa "int rows" 165.Fa "int cols" 166.Fa "unsigned int seconds" 167.Fc 168.Ft int 169.Fo bsddialog_radiolist 170.Fa "struct bsddialog_conf *conf" 171.Fa "const char *text" 172.Fa "int rows" 173.Fa "int cols" 174.Fa "unsigned int menurows" 175.Fa "unsigned int nitems" 176.Fa "struct bsddialog_menuitem *items" 177.Fa "int *focusitem" 178.Fc 179.Ft int 180.Fo bsddialog_rangebox 181.Fa "struct bsddialog_conf *conf" 182.Fa "const char *text" 183.Fa "int rows" 184.Fa "int cols" 185.Fa "int min" 186.Fa "int max" 187.Fa "int *value" 188.Fc 189.Ft int 190.Fo bsddialog_textbox 191.Fa "struct bsddialog_conf *conf" 192.Fa "const char *file" 193.Fa "int rows" 194.Fa "int cols" 195.Fc 196.Ft int 197.Fo bsddialog_timebox 198.Fa "struct bsddialog_conf *conf" 199.Fa "const char *text" 200.Fa "int rows" 201.Fa "int cols" 202.Fa "unsigned int *hh" 203.Fa "unsigned int *mm" 204.Fa "unsigned int *ss" 205.Fc 206.Ft int 207.Fo bsddialog_yesno 208.Fa "struct bsddialog_conf *conf" 209.Fa "const char *text" 210.Fa "int rows" 211.Fa "int cols" 212.Fc 213.In bsddialog_theme.h 214.Ft int 215.Fo bsddialog_color 216.Fa "enum bsddialog_color foreground" 217.Fa "enum bsddialog_color background" 218.Fa "unsigned int flags" 219.Fc 220.Ft int 221.Fn bsddialog_get_theme "struct bsddialog_theme *theme" 222.Ft int 223.Fn bsddialog_set_default_theme "enum bsddialog_default_theme theme" 224.Ft int 225.Fn bsddialog_set_theme "struct bsddialog_theme *theme" 226.Sh DESCRIPTION 227The 228.Nm bsddialog 229library provides an API to build Text User Interface dialogs and widgets: to 230display messages, to get input and to inform about a computation status. 231.Pp 232.Fn bsddialog_init 233initializes the library, the only functions that can be called before is 234.Fn bsddialog_initconf 235described later. 236After the initialization the input and output should be handled via the library 237API. 238.Fn bsddialog_end 239restores the screen like before 240.Fn bsddialog_init , 241then it is not possible to use the library functions. 242.Pp 243.Fn bsddialog_error 244returns a string to describe the last error, it should be called after a 245.Dv BSDDIALOG_ERROR 246returned value. 247.Fn bsddialog_clearterminal 248clears the screen. 249.Fn bsddialog_backtitle 250prints 251.Fa backtitle 252on the top of the screen, it is possible to set 253.Fa conf.ascii_lines 254and 255.Fa conf.no_lines ; 256.Fa conf 257is described later. 258.Pp 259Each 260.Fa char* 261argument has to be a well terminated string, can be empty 262.Pq Dq 263but not 264.Dv NULL . 265.Ss Dialogs 266The dialogs have common arguments. 267.Fa text 268is a string printed inside the dialog. 269.Fa rows 270and 271.Fa cols 272are height and width, their value can be between 2 and the screen size, 273.Dv BSDDIALOG_AUTOSIZE 274or 275.Dv BSDDIALOG_FULLSCREEN . 276.Fa conf 277is a struct to customize the dialog, it does not set global properties to the 278library. 279.Pp 280.Bd -literal -offset indent -compact 281struct bsddialog_conf { 282 bool ascii_lines; 283 unsigned int auto_minheight; 284 unsigned int auto_minwidth; 285 const char *bottomtitle; 286 bool clear; 287 const char *f1_file; 288 const char *f1_message; 289 int *get_height; 290 int *get_width; 291 bool no_lines; 292 bool shadow; 293 unsigned int sleep; 294 const char *title; 295 int y; 296 int x; 297 struct { 298 bool enable_esc; 299 } key; 300 struct { 301 bool highlight; 302 unsigned int tablen; 303 } text; 304 struct { 305 bool align_left; 306 bool no_desc; 307 bool no_name; 308 bool shortcut_buttons; 309 } menu; 310 struct { 311 int securech; 312 bool value_withcancel; 313 bool value_withextra; 314 bool value_withhelp; 315 } form; 316 struct { 317 bool without_ok; 318 const char *ok_label; 319 bool with_extra; 320 const char *extra_label; 321 bool without_cancel; 322 const char *cancel_label; 323 bool default_cancel; 324 bool with_help; 325 const char *help_label; 326 const char *generic1_label; 327 const char *generic2_label; 328 const char *default_label; 329 } button; 330}; 331.Ed 332.Pp 333.Bl -column -compact 334.It Fa conf.ascii_lines 335ascii characters to draw lines, default wide characters. 336.It Fa conf.auto_minheight 337minimum height if 338.Fa rows 339is 340.Dv BSDDIALOG_AUTOSIZE . 341.It Fa conf.auto_minwidth 342minimum width if 343.Fa cols 344is 345.Dv BSDDIALOG_AUTOSIZE . 346.It Fa conf.bottomtitle 347subtitle at the dialog bottom side. 348.It Fa conf.clear 349hide the dialog at exit. 350.It Fa conf.f1_file 351file to open if F1 is pressed. 352.It Fa conf.f1_message 353message to display if F1 is pressed. 354.It Fa conf.get_height 355if not 356.Dv NULL 357is set like the dialog height. 358.It Fa conf.get_width 359if not 360.Dv NULL 361is set like the dialog width. 362.It Fa conf.no_lines 363not draw lines. 364.It Fa conf.shadow 365draw shadow. 366.It Fa conf.sleep 367wait before to return, the value is in seconds. 368.It Fa conf.title 369title at the top dialog side. 370.It Fa conf.y 371vertical position, 0 is top screen size, can be 372.Dv BSDDIALOG_CENTER . 373.It Fa conf.x 374horizontal position, 0 is left screen side, can be 375.Dv BSDDIALOG_CENTER . 376.El 377.Pp 378.Fa conf.key.enable_esc 379enables 380.Dv ESC 381key to close the dialog. 382.Pp 383.Fa conf.text.highlight 384enables highlights for 385.Fa text , 386properly the following sequences are considered escapes: 387.Bl -column -compact 388.It Dq \eZ0 389black. 390.It Dq \eZ1 391red. 392.It Dq \eZ2 393green. 394.It Dq \eZ3 395yellow. 396.It Dq \eZ4 397blue. 398.It Dq \eZ5 399magenta. 400.It Dq \eZ6 401cyan. 402.It Dq \eZ7 403white. 404.It Dq \eZr 405reverse colors between foreground and background. 406.It Dq \eZR 407disable reverse. 408.It Dq \eZb 409bold. 410.It Dq \eZB 411disable bold. 412.It Dq \eZu 413underline. 414.It Dq \eZU 415disable underline. 416.It Dq \eZn 417disable each customization. 418.El 419.Fa conf.text.tablen 420tab length. 421.Pp 422.Bl -column -compact 423.It Fa conf.button.without_ok 424disable OK button. 425.It Fa conf.button.ok_label 426set label for OK button. 427.It Fa conf.button.with_extra 428add Extra button. 429.It Fa conf.button.extra_label 430set a label for Extra button. 431.It Fa conf.button.without_cancel 432disable Cancel button. 433.It Fa conf.button.cancel_label 434sets a label for Cancel button. 435.It Fa conf.button.default_cancel 436on startup focus on the Cancel button. 437.It Fa conf.button.with_help 438add Help button. 439.It Fa conf.button.help_label 440set a label for Help button. 441.It Fa conf.button.generic1_label 442add a button with the specified label. 443.It Fa conf.button.generic2_label 444add a button with the specified label. 445.It Fa conf.button.default_label 446focus on the button with the specified label. 447.El 448.Pp 449.Fn bsddialog_initconf 450initializes 451.Fa conf 452disabling each property, except 453.Fa conf.shadow 454to true, 455.Fa conf.y 456and 457.Fa conf.x 458to 459.Dv BSDDIALOG_CENTER . 460.Pp 461.Fn bsddialog_infobox 462builds a dialog without buttons and returns instantly. 463.Fn bsddialog_msgbox 464builds a dialog with OK button. 465.Fn bsddialog_yesno 466provides a dialog for a 467.Dq Yes-No Question , 468the labels on buttons are Yes and No. 469.Pp 470.Fn bsddialog_pause 471builds a dialog waiting until the timeout in 472.Fa seconds 473expires or a button is pressed. 474.Pp 475.Fn bsddialog_datebox 476builds a dialog to select a date, 477.Fa yy , 478.Fa mm , 479and 480.Fa dd 481are default values on startup, selected date at exit. 482.Fn bsddialog_timebox 483builds a dialog to choose a time, 484.Fa hh , 485.Fa mm , 486and 487.Fa ss 488are default values on startup, selected time at exit. 489.Pp 490.Fn bsddialog_checklist , 491.Fn bsddialog_menu 492and 493.Fn bsddialog_radiolist 494build dialogs to select some item from a list via the SPACE key, an item is 495defined like: 496.Pp 497.Bd -literal -offset indent -compact 498struct bsddialog_menuitem { 499 const char *prefix; 500 bool on; 501 unsigned int depth; 502 const char *name; 503 const char *desc; 504 const char *bottomdesc; 505}; 506.Ed 507.Pp 508.Fa prefix , 509.Fa name 510and 511.Fa desc 512are strings to describe the item and are printed on its row, 513.Fa bottomdesc 514is printed on the bottom side of the screen, 515.Fa depth 516is a margin between the 517.Fa prefix 518and 519.Fa name 520useful to implement a 521.Dq treeview, 522.Fa on 523is set to 524.Dv true 525if the item is selected, 526.Dv false 527otherwise. 528.Fa items 529is an array of items of 530.Fa nitem 531elements, 532.Fa menurows 533specifies the graphical fixed height of the list, if 534.Fa cols 535is set to 536.Dv BSDDIALOG_AUTOSIZE 537.Fa menurows 538specifies a maximum value. 539Finally, if not 540.Dv NULL , 541.Fa focusitem 542specifies the default item on startup and the last focused item at exit, could 543be a negative value if no item is focused. 544.Pp 545.Fn bsddialog_mixedlist 546builds a dialog with collections of checklists, radiolists and separators. 547A collection is a set defined like: 548.Pp 549.Bd -literal -offset indent -compact 550enum bsddialog_grouptype { 551 BSDDIALOG_CHECKLIST, 552 BSDDIALOG_RADIOLIST, 553 BSDDIALOG_SEPARATOR, 554}; 555 556struct bsddialog_menugroup { 557 enum bsddialog_grouptype type; 558 unsigned int nitems; 559 struct bsddialog_menuitem *items; 560}; 561.Ed 562.Pp 563.Fa groups 564is an array of sets of 565.Fa ngroups 566elements. 567.Fa menurows 568is the graphical height size for the list. 569If not 570.Dv NULL , 571.Fa focuslist 572and 573.Fa focusitem 574specify the default item on startup and the last focused item at exit, could be 575a negative value if no item is focused. 576.Pp 577.Fn bsddialog_checklist , 578.Fn bsddialog_menu , 579.Fn bsddialog_mixedlist 580and 581.Fn bsddialog_radiolist 582can be costomizated by: 583.Bl -column -compact 584.It Fa conf.menu.align_left 585aligns items to left, default center. 586.It Fa conf.menu.no_desc 587hide description. 588.It Fa conf.menu.no_name 589hide names. 590.It Fa conf.menu.on_without_ok 591set items 592.Fa on 593also if the OK button is not pressed. 594.It Fa conf.menu.shortcut_buttons 595enable shortcut keys on buttons, default on items. 596.El 597.Pp 598.Fn bsddialog_form 599builds a dialog to display a list of items to get strings in input, an item is 600defined like: 601.Pp 602.Bd -literal -offset indent -compact 603struct bsddialog_formitem { 604 const char *label; 605 unsigned int ylabel; 606 unsigned int xlabel; 607 608 const char *init; 609 unsigned int yfield; 610 unsigned int xfield; 611 unsigned int fieldlen; 612 unsigned int maxvaluelen; 613 char *value; 614 615 unsigned int flags; 616 617 const char *bottomdesc; 618}; 619.Ed 620.Pp 621.Fa label 622describes the request, it is printed at the position 623.Fa ylabel 624and 625.Fa xlabel . 626The field for the input is at the position 627.Fa yfield 628and 629.Fa xfield , 630.Fa fieldlen 631is its graphical width, while 632.Fa maxvalelen 633is the maximum length of the input string, 634.Fa init 635is the default value. 636If the OK button is pressed 637.Fa value 638is the allocated memory with the current field string. 639.Fa flags 640is an OR value to set the 641.Dv BSDDIALOG_FIELDHIDDEN 642and 643.Dv BSDDIALOG_FIELDREADONLY 644flags for the field. 645.Fa bottomdesc 646is printed on the bottom side of the screen if the item is focused. 647.Fa items 648is an array of items of 649.Fa nitems 650elements, 651.Fa formrows 652specifies the graphical fixed height for the items list; 653.Fa ylabel 654and 655.Fa yfield 656have to be between 1 and 657.Fa formrows . 658.Pp 659.Fn bsddialog_form 660can be customized by: 661.Bl -column -compact 662.It Fa conf.form.securech 663charachter to hide the input 664with 665.Dv BSDDIALOG_FIELDHIDDEN . 666.It Fa conf.form.value_without_ok 667allocate memory and set 668.Fa value 669also if the OK button is not pressed. 670.El 671.Pp 672.Fn bsddialog_gauge 673builds a dialog with a bar to shows 674.Fa perc , 675if the file descriptor 676.Fa fd 677is greater or equal to 0 the dialog waits to read 678.Fa separator 679from it, then the first string replaces 680.Fa perc 681and the following strings replace 682.Fa text 683until the next 684.Fa separator , 685the loop ends reading 686.Dv EOF . 687.Pp 688.Fn bsddialog_mixedgauge 689draws a main bar with the 690.Fa mainperc 691percentage and 692.Fa nminibars 693each one with a 694.Fa minilabel 695and a 696.Fa miniperc 697with a value between 0 and 100 or 698.Dv BSDDIALOG_MG_SUCCEEDED , 699.Dv BSDDIALOG_MG_FAILED , 700.Dv BSDDIALOG_MG_PASSED , 701.Dv BSDDIALOG_MG_COMPLETED , 702.Dv BSDDIALOG_MG_CHECKED , 703.Dv BSDDIALOG_MG_DONE , 704.Dv BSDDIALOG_MG_SKIPPED , 705.Dv BSDDIALOG_MG_INPROGRESS , 706.Dv BSDDIALOG_MG_BLANK , 707.Dv BSDDIALOG_MG_NA 708or 709.Dv BSDDIALOG_MG_PENDING 710to print a descriptive string. 711.Pp 712.Fn bsddialog_rangebox 713to select a value between 714.Fa min 715and 716.Fa max . 717.Fa value 718is the default value on startup and the selected value at exit. 719The current value is printed inside a bar, the keys UP, DOWN, HOME, END, PAGEUP 720and PAGEDOWN can change it. 721.Pp 722.Fn bsddialog_textbox 723opens and prints 724.Fa file 725in a dialog, the UP, DOWN, HOME, END, PAGEUP and PAGEDOWN keys are availble to 726navigate the file. 727OK button is renamed EXIT. 728.Ss Theme 729The graphical properties are global to the library, they are represented by 730.Fa struct bsddialog_theme 731and can be customized at runtime via the 732.In bsddialog_theme.h 733API. 734.Pp 735.Bd -literal -offset indent -compact 736struct bsddialog_theme { 737 struct { 738 int color; 739 } screen; 740 struct { 741 int color; 742 unsigned int h; 743 unsigned int w; 744 } shadow; 745 struct { 746 int color; 747 bool delimtitle; 748 int titlecolor; 749 int lineraisecolor; 750 int linelowercolor; 751 int bottomtitlecolor; 752 } dialog; 753 struct { 754 int arrowcolor; 755 int selectorcolor; 756 int f_namecolor; 757 int namecolor; 758 int f_desccolor; 759 int desccolor; 760 int namesepcolor; 761 int descsepcolor; 762 int f_shortcutcolor; 763 int shortcutcolor; 764 } menu; 765 struct { 766 int f_fieldcolor; 767 int fieldcolor; 768 int readonlycolor; 769 } form; 770 struct { 771 int f_color; 772 int color; 773 } bar; 774 struct { 775 unsigned int space; 776 int leftch; 777 int rightch; 778 int delimcolor; 779 int f_delimcolor; 780 int color; 781 int f_color; 782 int shortcutcolor; 783 int f_shortcutcolor; 784 } button; 785}; 786.Ed 787.Pp 788A member with the 789.Dq f_ 790prefix refers to an element with focus. 791.Pp 792.Fn bsddialog_get_theme 793sets 794.Fa theme 795like the current theme. 796.Pp 797A color can be set by the value returned by 798.Fn bsddialog_color , 799Possible values for 800.Fa background 801and 802.Fa foreground 803are: 804.Dv BSDDIALOG_BLACK , 805.Dv BSDDIALOG_RED , 806.Dv BSDDIALOG_GREEN , 807.Dv BSDDIALOG_YELLOW , 808.Dv BSDDIALOG_BLUE , 809.Dv BSDDIALOG_MAGENTA , 810.Dv BSDDIALOG_CYAN , 811and 812.Dv BSDDIALOG_WHITE , 813.Fa flags 814specifies OR-flags, possible values: 815.Dv BSDDIALOG_BOLD , 816.Dv BSDDIALOG_REVERSE 817and 818.Dv BSDDIALOG_UNDERLINE . 819.Pp 820.Fn bsddialog_set_theme 821sets 822.Fa theme 823like current theme, the changes takes effect only for dialogs built after the 824call. 825.Pp 826The library provides predefined themes: 827.Dv BSDDIALOG_THEME_BLACKWHITE , 828.Dv BSDDIALOG_THEME_BSDDIALOG , 829.Dv BSDDIALOG_THEME_DEFAULT 830and 831.Dv BSDDIALOG_THEME_DIALOG , 832they can be set via 833.Fn bsddialog_set_default_theme . 834.Sh RETURN VALUES 835The functions return the value 836.Dv BSDDIALOG_ERROR 837if unsuccessful; 838otherwise, depending on the pressed button, the following values can be 839returned: 840.Dv BSDDIALOG_OK , 841.Dv BSDDIALOG_CANCEL , 842.Dv BSDDIALOG_HELP , 843.Dv BSDDIALOG_EXTRA , 844.Dv BSDDIALOG_GENERIC1 845or 846.Dv BSDDIALOG_GENERIC2 . 847.Dv BSDDIALOG_YES 848and 849.Dv BSDDIALOG_NO 850are aliases for 851.Dv BSDDIALOG_OK 852and 853.Dv BSDDIALOG_CANCEL , 854respectively. 855.Pp 856The functions return 857.Dv BSDDIALOG_ESC 858if 859.Fa conf.key.enable_esc 860is enabled and the ESC key is pressed. 861.Pp 862.Fn bsddialog_pause 863returns 864.Dv BSDDIALOG_TIMEOUT 865if the timeout expires. 866.Sh EXAMPLES 867.Dq Yes-No Question 868Example: 869.Pp 870.Bd -literal -offset indent -compact 871int output; 872struct bsddialog_conf conf; 873 874if (bsddialog_init() == BSDDIALOG_ERROR) 875 return (1); 876 877bsddialog_initconf(&conf); 878conf.title = "yesno"; 879output = bsddialog_yesno(&conf, "Example", 7, 25); 880 881bsddialog_end(); 882 883switch (output) { 884case BSDDIALOG_YES: 885 printf("Yes\\n"); 886 break; 887case BSDDIALOG_NO 888 printf("NO\\n"); 889 break; 890case BSDDIALOG_ERROR: 891 printf("Error: %s\\n", bsddialog_geterror()); 892} 893.Ed 894.Pp 895Theme Example: 896.Pp 897.Bd -literal -offset indent -compact 898struct bsddialog_conf conf; 899struct bsddialog_theme theme; 900 901if (bsddialog_init() == BSDDIALOG_ERROR) 902 903bsddialog_initconf(&conf); 904bsddialog_msgbox(&conf, "Default theme", 7, 25); 905 906bsddialog_get_theme(&theme); 907theme.screen.color = bsddialog_color(BSDDIALOG_RED, BSDDIALOG_GREEN, 908 BSDDIALOG_BOLD); 909bsddialog_set_theme(&theme); 910bsddialog_backtitle(&conf, "Red foreground and Green background"); 911bsddialog_msgbox(&conf, "Change screen color", 7, 25); 912 913bsddialog_set_default_theme(BSDDIALOG_THEME_BLACKWHITE); 914bsddialog_msgbox(&conf, "Black and White theme", 7, 25); 915 916bsddialog_end(); 917.Ed 918.Pp 919Mixedlist Example: 920.Pp 921.Bd -literal -offset indent -compact 922unsigned int i, j; 923struct bsddialog_conf conf; 924struct bsddialog_menuitem item; 925struct bsddialog_menuitem check[2] = { 926 { "1", true, 0, "Name 1", "Desc 1", "Check Bottom Desc 1" }, 927 { "2", false, 0, "Name 2", "Desc 2", "Check Bottom Desc 2" } 928}; 929struct bsddialog_menuitem sep[1] = { 930 { "3", true, 0, "Radiolist", "(desc)", "" } 931}; 932struct bsddialog_menuitem radio[5] = { 933 { "4", true, 0, "Name 1", "Desc 1", "Radio Bottom Desc 1" }, 934 { "5", false, 0, "Name 2", "Desc 2", "Radio Bottom Desc 2" } 935}; 936struct bsddialog_menugroup group[3] = { 937 { BSDDIALOG_CHECKLIST, 2, check }, 938 { BSDDIALOG_SEPARATOR, 1, sep }, 939 { BSDDIALOG_RADIOLIST, 2, radio } 940}; 941 942bsddialog_init(); 943bsddialog_initconf(&conf); 944bsddialog_mixedlist(&conf, "Example", 20, 30, 11, 3, group, NULL, 945 NULL); 946bsddialog_end(); 947 948for (i = 0; i < 3; i++) { 949 for (j = 0; j < group[i].nitems; j++) { 950 item = group[i].items[j]; 951 switch (item.type) { 952 case BSDDIALOG_SEPARATOR: 953 printf("---- %s ----\\n", item.name); 954 break; 955 case BSDDIALOG_RADIOLIST: 956 printf(" (%c) %s\\n", 957 item.on ? '*' : ' ', item.name); 958 break; 959 case BSDDIALOG_CHECKLIST: 960 printf(" [%c] %s\\n", 961 item.on ? 'X' : ' ', item.name); 962 break; 963 } 964 } 965} 966.Ed 967.Sh SEE ALSO 968.Xr bsddialog 1 , 969.Xr curses 3 , 970.Xr ncurses 3 971.Sh HISTORY 972The 973.Nm bsddialog 974library first appeared in 975.Fx 14.0 . 976.Sh AUTHORS 977.Nm bsddialog 978was written by 979.An Alfonso Sabato Siciliano Aq Mt alf.siciliano@gmail.com . 980.Sh BUGS 981.Fn bsddialog_form 982does not resize the dialog after a terminal resize and does not provide 983scrolling for items.