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