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