1.\" 2.\" 3.\" Copyright (c) 2021-2022 Alfonso Sabato Siciliano 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.Dd September 23, 2022 27.Dt BSDDIALOG 1 28.Os 29.Sh NAME 30.Nm bsddialog 31.Nd TUI dialogs 32.Sh SYNOPSIS 33.Nm 34.Fl Fl help 35.Nm 36.Fl Fl version 37.Nm 38.Op Fl Fl option 39.Fl Fl dialog 40.Ar text 41.Ar rows 42.Ar cols 43.Op Ar dialog-argument 44.Nm 45.Fl Fl dialog1 46.Ar ... 47.Oo Fl Fl and-dialog 48.Fl Fl dialog2 49.Ar ... 50.Oc ... 51.Sh DESCRIPTION 52The 53.Nm bsddialog 54utility builds Text User Interface dialogs and widgets: to display messages, 55to get input and to inform about a computation status. 56.Pp 57The options 58.Fl Fl help 59and 60.Fl Fl version 61print the list of options and the version, respectively, then exit. 62.Fl Fl and-dialog 63builds another dialog unless the previous one returns Error, ESC or Cancel. 64.Pp 65.Ar text 66is a message printed inside the dialog. 67.Ar rows 68and 69.Ar cols 70are the height and width, 0 for autosize and -1 for fullscreen. 71.Pp 72The possible input got from the user interface is printed to standard error. 73.Ss Options 74The following options can change the default behavior of the utility and are 75common to some dialog. 76.Bl -tag -width Ds 77.It Fl Fl alternate-screen 78If available set alternate screen mode, see 79.Xr terminfo 5 . 80.It Fl Fl ascii-lines 81Ascii characters to draw lines. 82.It Fl Fl backtitle Ar backtitle 83Title on the top side of the screen. 84.It Fl Fl begin-x Ar x 85Dialog horizontal position, 0 is the left screen side, -1 center. 86.It Fl Fl begin-y Ar y 87Dialog vertical position, 0 is the top screen side, -1 center. 88.It Fl Fl bikeshed 89Random settings. 90Colors. 91Delimiter and margins around the title. 92Buttons always active or TAB to switch focus with input components, see 93.Fl Fl switch-buttons . 94Zero padding with time or date output. 95.It Fl Fl cancel-label Ar label 96Label for the 97.Dq Cancel 98button. 99.It Fl Fl clear-dialog 100Hide the dialog at exit. 101.It Fl Fl clear-screen 102Clear the screen, after the dialog exit if a dialog is built. 103.It Fl Fl colors 104Enable highlights for text, the following sequences are considered escapes: 105.Bl -column -compact 106.It Dq \eZ0 107black. 108.It Dq \eZ1 109red. 110.It Dq \eZ2 111green. 112.It Dq \eZ3 113yellow. 114.It Dq \eZ4 115blue. 116.It Dq \eZ5 117magenta. 118.It Dq \eZ6 119cyan. 120.It Dq \eZ7 121white. 122.It Dq \eZr 123reverse foreground and background. 124.It Dq \eZR 125disable reverse. 126.It Dq \eZb 127bold. 128.It Dq \eZB 129disable bold. 130.It Dq \eZu 131underline. 132.It Dq \eZU 133disable underline. 134.It Dq \eZn 135restore normal text. 136.El 137.It Fl Fl columns-per-row Ar columns 138Try to set the number of columns for a row of text with autosizing; default 139.Dv 10 . 140.It Fl Fl cr-wrap 141Keep new line in 142.Ar text 143also if it constains a 144.Dq \en , 145see 146.Fl Fl text-unchanged . 147.It Fl Fl date-format Ar format 148String accepted by 149.Xr strftime 3 150to customize the output of 151.Fl Fl datebox 152and 153.Fl Fl calendar 154.It Fl Fl default-button Ar label 155Focus on the button with 156.Ar label 157on startup. 158.It Fl Fl default-item Ar name 159Focus on the item with 160.Ar name , 161for Checklist, Menu, Radiolist and Treeview. 162.It Fl Fl default-no 163Focus on 164.Dq Cancel 165or 166.Dq \&No 167button on startup. 168.It Fl Fl disable-esc 169Disable ESC key to quit. 170.It Fl Fl esc-return-cancel 171ESC key returns 172.Dq Cancel 173button value. 174.It Fl Fl extra-button 175Add a button with 176.Dq Extra 177label. 178.It Fl Fl extra-label Ar label 179Set 180.Ar label 181for the 182.Dq Extra 183button. 184.It Fl Fl generic-button1 Ar label 185Add a button with 186.Ar label . 187.It Fl Fl generic-button2 Ar label 188Add a button with 189.Ar label . 190.It Fl Fl help-button 191Add a button with 192.Dq Help 193label. 194.It Fl Fl help-label Ar label 195Set 196.Ar label 197for 198.Dq Help 199button. 200.It Fl Fl help-print-name 201Print the name of the focused item if the Help button is pressed also 202with 203.Fl Fl item-bottom-desc . 204.It Fl Fl help-status 205Print also the selected items if the 206.Dq Help 207button is pressed. 208.It Fl Fl hfile Ar filename 209Open 210.Ar filename 211in a Textbox if F1 key is pressed, 212.It Fl Fl hline Ar string 213Dialog subtitle. 214.It Fl Fl hmsg Ar string 215Open a Msgbox with 216.Ar string 217if the F1 key is pressed. 218.It Fl Fl ignore 219Do not exit with unknown options. 220.It Fl Fl insecure 221Print 222.Sq * 223to hide passwords while typing; whitespace otherwise. 224.It Fl Fl item-bottom-desc 225Set a help string for each item of a Checklist, Form, Menu, Mixedform, 226Passwordform, Radiolist and Treeview to display at the bottom screen side. 227.It Fl Fl item-depth 228Specify a margin for items, available for Checklist, Menu and Radiolist. 229.It Fl Fl item-prefix 230Set a string to prefix each item of a Checklist, Menu, Radiolist or Treeview. 231.It Fl Fl load-theme Ar file 232Load theme from 233.Ar file . 234.It Fl Fl max-input Ar size 235Maximum length of the input for 236.Fl Fl inputbox 237ans 238.Fl Fl passwordbox , 239default 2048. 240.It Fl Fl no-cancel 241Do not show 242.Dq Cancel 243button. 244.It Fl Fl no-descriptions 245Do not display items desciption, for Checklist, Menu, Radiolist or Treeview. 246.It Fl Fl no-lines 247Do not draw borders and lines. 248.It Fl Fl no-names 249Do not display items name, for Checklist, Menu and Radiolist. 250.It Fl Fl no-ok 251Do not draw 252.Dq OK 253button. 254.It Fl Fl no-shadow 255No not draw the shadow of the dialog. 256.It Fl Fl ok-label Ar label 257Set 258.Ar label 259for 260.Dq OK 261button. 262.It Fl Fl normal-screen 263If available set normal screen mode, see 264.Xr terminfo 5 . 265.It Fl Fl output-fd Ar fd 266Print input from user interface to the specified file descriptor. 267.It Fl Fl output-separator Ar sep 268Set a sepator for the items in output, default whitespace. 269.It Fl Fl print-maxsize 270Screen size. 271This option can be used without a dialog. 272.It Fl Fl print-size 273Print Dialog height and widget at exit. 274.It Fl Fl print-version 275Print version. 276This option can be used without a dialog. 277.It Fl Fl quoted 278Quote items in output, default only when necessary. 279.It Fl Fl save-theme Ar file 280Save the current theme. 281This option can be used without a dialog. 282.It Fl Fl separate-output 283Separate selected items with a new line and avoid to quote. 284.It Fl Fl shadow 285Show a pseudo shadow for the dialog, enabled by default. 286.It Fl Fl single-quoted 287Use single quote for items in output. 288.It Fl Fl sleep Ar secs 289Wait 290.Ar secs 291seconds to close the dialog. 292.It Fl Fl stderr 293Print input from user interface to standand error, default. 294.It Fl Fl stdout 295Print input from user interface to standard output. 296.It Fl Fl switch-buttons 297enables focus switching between buttons and input components pressing TAB, 298otherwise buttons are always active and ENTER key closes the dialog. 299Suitable for: 300.Fl Fl form , 301.Fl Fl inputbox , 302.Fl Fl mixedform , 303.Fl Fl passwordbox , 304.Fl Fl passwordform , 305.Fl Fl timebox , 306.Fl Fl calendar 307and 308.Fl Fl datebox . 309.It Fl Fl tab-escape 310Replace 311.Dq \et 312with a tab in 313.Ar text . 314.It Fl Fl tab-len Ar spaces 315Number of spaces to print a TAB in 316.Ar text . 317.It Fl Fl text-unchanged 318By default the 319.Ar text 320is changed before to be printed. 321If it contains at least a 322.Dq \en 323each new line and TAB is converted to a space, subsequent spaces are merged. 324Otherwise new line characters are preserved and a TAB becomes a space. 325This option disable the 326.Ar text 327modification. 328.It Fl Fl theme Ar theme 329Set a graphical style: blackwhite, bsddialog, flat or dialog. 330.It Fl Fl time-format Ar format 331String accepted by 332.Xr strftime 3 333to customize the output of 334.Fl Fl timebox . 335.It Fl Fl title Ar title 336Dialog title. 337.El 338.Ss Dialogs 339The following dialogs are available: 340.Bl -tag -width Ds 341.It Fl Fl calendar Ar text Ar rows Ar cols Op Ar day Ar month Ar year 342Dialog to select a date. 343.It Fl Fl checklist Ar text Ar rows Ar cols Ar menurows Oo Ar name Ar desc \ 344Ar status Oc ... 345Checklist to select some item from a list via the SPACE key. 346An item has a 347.Ar name , 348.Ar desc 349and a default 350.Ar status 351specified by 352.Dq on 353or 354.Dq off . 355The names of the selected items are printed to standard error. 356.Ar menurows 357is the graphical height of the list, 0 for autosize. 358.It Fl Fl datebox Ar text Ar rows Ar cols Op Ar day Ar month Ar year 359Dialog to select a date. 360.It Fl Fl form Ar text Ar rows Ar cols Ar formrows Oo Ar label Ar ylabel \ 361Ar xlabel Ar init Ar yfield Ar xfield Ar fieldlen Ar maxletters Oc ... 362Dialog to get a list of strings via forms. 363A form has a 364.Ar label 365at the position 366.Ar ylabel 367and 368.Ar xlabel , 369a field to get the input at the position 370.Ar yfield 371and 372.Ar xfield 373with graphical length 374.Ar fieldlen , 375.Ar maxletters 376is the maximum input length. 377The field can be customized, if 378.Ar fieldlen 379is negative the field is read only and its absolute value is the field length. 380If 381.Ar maxletters 382is 0 it is the absolute value of 383.Ar fieldlen . 384.Ar init 385is a default value. 386.Ar formrows 387is the graphical height of the list, 388.Dv 0 389for autosize. 390.It Fl Fl gauge Ar text Ar rows Ar cols Op Ar percentage 391Dialog with a bar to shows 392.Ar percentage , 393then it waits to read 394.Dq XXX 395from the standard input, then the first string replaces percentage and the 396following strings replace 397.Ar text 398until the next 399.Dq XXX , 400the loop ends reading 401.Dv EOF . 402.It Fl Fl infobox Ar text Ar rows Ar cols 403Dialog without buttons to display a message and to exit immediately. 404.It Fl Fl inputbox Ar text Ar rows Ar cols Op Ar init 405Dialog to get a string in input, 406.Ar init 407is the default value. 408.It Fl Fl menu Ar text Ar rows Ar cols Ar menurows Oo Ar name desc Oc ... 409Builds a menu to select an item from a list, Space key is equivalent to Enter. 410An item has a 411.Ar name 412and a 413.Ar desc . 414The name of the selected item is printed to standard error. 415.Ar menurows 416is the graphical height of the list, 0 for autosize. 417.It Fl Fl mixedform Ar text Ar rows Ar cols Ar formrows Oo Ar label Ar ylabel \ 418Ar xlabel Ar init Ar yfield Ar xfield Ar fieldlen Ar maxletters Ar flag Oc ... 419Dialog to get a list of strings via forms. 420A form has a 421.Ar label 422at the position 423.Ar ylabel 424and 425.Ar xlabel , 426a field to get the input with graphical length 427.Ar fieldlen 428at the position 429.Ar yfield 430and 431.Ar xfield , 432.Ar maxletters 433is the maximum input length, 434.Ar init 435is a default value, 436.Ar flag 437can be 0 for normal field, 1 to hide the typed characters and 2 to set the 438field read only. 439.Ar formrows 440is the graphical height of the list, 441.Dv 0 442for autosize. 443.It Fl Fl mixedgauge Ar text Ar rows Ar cols Ar mainperc Oo Ar minilabel \ 444Ar miniperc Oc ... 445Dialog to show a main bar to represent 446.Ar mainperc 447from 0 to 100 and some mini bar with a 448.Ar minilabel 449string and a 450.Ar miniperc 451with value from 0 and 100 or negative to print a descriptive string: -1 452.Dq Succeeded , 453-2 454.Dq Failed , 455-3 456.Dq Passed , 457-4 458.Dq Completed , 459-5 460.Dq Checked , 461-6 462.Dq Done , 463-7 464.Dq Skipped , 465-8 466.Dq \&In Progress , 467-9 468a blank line, 469-10 470.Dq N/A , 471-11 472.Dq Pending . 473.It Fl Fl msgbox Ar text Ar rows Ar cols 474Dialog to diplay a message without the 475.Dq Cancel 476button. 477UP, DOWN, HOME, END, PAGEUP and PAGEDOWN keys are availble to navigate the text. 478.It Fl Fl passwordbox Ar text Ar rows Ar cols Op Ar init 479Dialog to get a password, 480.Ar init 481is the default value. 482.It Fl Fl passwordform Ar text Ar rows Ar cols Ar formrows Oo Ar label \ 483Ar ylabel Ar xlabel Ar init Ar yfield Ar xfield Ar fieldlen Ar maxletters \ 484Oc ... 485Dialog to get a list of passwords, equivalent to 486.Fl Fl form 487except typed characters are hidden. 488.It Fl Fl pause Ar text Ar rows Ar cols Ar seconds 489Dialog runs until the timeout in 490.Ar seconds 491expires or a button is pressed. 492.It Fl Fl radiolist Ar text Ar rows Ar cols Ar menurows Oo Ar name Ar desc \ 493Ar status Oc ... 494Radiolist to select at most an item from a list via the SPACE key. 495An item has a 496.Ar name , 497.Ar desc 498and a default 499.Ar status 500specified by 501.Dq on 502or 503.Dq off . 504The name of the selected item is printed to standard error. 505.Ar menurows 506is the graphical height of the list, 0 for autosize. 507.It Fl Fl rangebox Ar text Ar rows Ar cols Ar min Ar max Op Ar init 508Dialog to select a value between 509.Ar min 510and 511.Ar max , 512.Ar init 513is the default value, the keys UP, DOWN, HOME, END, PAGEUP and PAGEDOWN can 514change it. 515.It Fl Fl textbox Ar file Ar rows Ar cols 516Opens and prints 517.Ar file 518the UP, DOWN, HOME, END, PAGEUP and PAGEDOWN keys are availble to navigate; 519.Dq OK 520button is renamed 521.Dq EXIT . 522.It Fl Fl timebox Ar text Ar rows Ar cols Op Ar hour Ar min Ar sec 523Dialog to select a time. 524.It Fl Fl treeview Ar text Ar rows Ar cols Ar menurows Oo Ar depth Ar name \ 525Ar desc Ar status Oc ... 526Equivalent to Radiolist with 527.Fl Fl item-depth 528and 529.Fl Fl no-name . 530.It Fl Fl yesno Ar text Ar rows Ar cols 531.Dq Yes-No Question , 532.Dq OK 533and 534.Dq Cancel 535buttons are renamed 536.Dq Yes 537and 538.Dq \&No . 539UP, DOWN, HOME, END, PAGEUP and PAGEDOWN keys are availble to navigate the text. 540.El 541.Sh EXIT STATUS 542The 543.Nm 544utility exits 255 on unsuccessful, otherwise depending on the button or key 545pressed the following values can be returned: 546.Bl -column -compact 547.It 0 548.Dq OK , 549.Dq Yes 550or 551.Dq Exit 552button. 553.It 1 554.Dq Cancel 555or 556.Dq \&No 557button. 558.It 2 559.Dq Help 560button. 561.It 3 562.Dq Extra 563button. 564.It 4 565Timeout. 566.It 5 567ESC key. 568.It 6 569Generic 1 button. 570.It 7 571Generic 2 button. 572.El 573.Sh EXAMPLES 574Backtitle, title and message: 575.Dl bsddialog --backtitle MESSAGE --title Msgbox --msgbox Message 0 0 576.Pp 577Yes-No Question and theme: 578.Dl bsddialog --theme blackwhite --yesno Question 10 30 579.Pp 580Save a custom theme: 581.Dl bsddialog --save-theme mytheme.txt --infobox \*qSaving theme...\*q 0 0 582.Pp 583Load a custom theme: 584.Dl bsddialog --load-theme mytheme.txt --infobox \*qCustom theme\*q 0 0 585.Pp 586Checklist: 587.Dl bsddialog --checklist Checklist 0 0 3 N1 \&D1 off N2 D2 on N3 D3 off 588.Pp 589Form: 590.Dl bsddialog --form Form 0 0 0 L1: 0 0 X 0 4 20 25 L2: 1 0 Y 1 4 20 25 591.Pp 592Multi-dialog: 593.Dl bsddialog --normal-screen --begin-y 1 --yesno Continue? 0 0 \e \ 594--and-dialog --begin-y 10 --infobox Yes 0 0 595.Pp 596Bikeshed: 597.Dl bsddialog --bikeshed --inputbox Example 0 0 598.Pp 599Mixedgauge: 600.Dl bsddialog --sleep 3 --mixedgauge Example 10 30 60 L1 \*q -1\*q L2 30 601.Pp 602Mixedgauge script: 603.Bd -literal -offset indent -compact 604perc=0 605while [ $perc -le 100 ] 606do 607 bsddialog --sleep 1 --title Mixedgauge \e 608 --mixedgauge "\enExample...\en" 0 0 $perc \e 609 "Hidden" " -9" \e 610 "Label 1" " -4" \e 611 "Label 2" " -4" \e 612 "Label 3" $perc 613 614 perc=`expr $perc + 20` 615done 616.Ed 617.Pp 618Gauge script: 619.Bd -literal -offset indent -compact 620i=1 621for c in A B C D E F G H 622do 623 sleep 1 624 echo XXX 625 echo "$(expr $(expr $i "*" 100) "/" 8)" 626 echo "[$i/8] Char: $c" 627 echo XXX 628 if [ $i -eq 8 ] 629 then 630 sleep 1 631 echo EOF 632 fi 633 i=`expr $i + 1` 634done | bsddialog --title Gauge --gauge "Starting..." 10 70 635.Ed 636.Sh COMPATIBILITY 637Outdated options are retained for compatibility, properly equivalent options are 638used: 639.Bd -literal -offset indent -compact 640Obsolete Equivalent 641--and-widget --and-dialog 642--calendar <text> 2 <cols> --calendar <text> 0 <cols> 643--clear --clear-screen 644--defaultno --default-no 645--exit-label --ok-label 646--help-tags --help-print-name 647--item-help --item-bottom-desc 648--keep-tite --alternate-screen 649--no-items --no-descriptions 650--no-label --cancel-label 651--no-tags --no-names 652--nocancel --no-cancel 653--nook --no-ok 654--separator --output-separator 655--yes-label --ok-label 656.Ed 657.Sh SEE ALSO 658.Xr bsddialog 3 659.Sh HISTORY 660The 661.Nm bsddialog 662utility first appeared in 663.Fx 14.0 . 664.Sh AUTHORS 665.Nm bsddialog 666was written by 667.An Alfonso Sabato Siciliano 668.Aq Mt asiciliano@FreeBSD.org . 669.Pp 670.Nm bsddialog 671provides a subset of the functionality described in the 672.Nm dialog 673manual. 674The following features were reimplemented: 675.Pp 676Options: 677.Fl Fl and-widget , 678.Fl Fl ascii-lines , 679.Fl Fl backtitle , 680.Fl Fl cancel-label , 681.Fl Fl clear , 682.Fl Fl colors , 683.Fl Fl cr-wrap , 684.Fl Fl date-format , 685.Fl Fl defaultno , 686.Fl Fl default-button , 687.Fl Fl default-no , 688.Fl Fl default-item , 689.Fl Fl exit-label , 690.Fl Fl extra-button , 691.Fl Fl extra-label , 692.Fl Fl help , 693.Fl Fl help-button , 694.Fl Fl help-label , 695.Fl Fl help-status , 696.Fl Fl help-tags , 697.Fl Fl hfile , 698.Fl Fl hline , 699.Fl Fl ignore , 700.Fl Fl insecure , 701.Fl Fl item-help , 702.Fl Fl keep-tite , 703.Fl Fl max-input , 704.Fl Fl no-cancel , 705.Fl Fl nocancel , 706.Fl Fl no-items , 707.Fl Fl no-label , 708.Fl Fl no-lines , 709.Fl Fl no-ok , 710.Fl Fl nook , 711.Fl Fl no-shadow , 712.Fl Fl no-tags , 713.Fl Fl ok-label , 714.Fl Fl output-fd , 715.Fl Fl output-separator , 716.Fl Fl print-maxsize , 717.Fl Fl print-size , 718.Fl Fl print-version , 719.Fl Fl quoted , 720.Fl Fl separate-output , 721.Fl Fl separator , 722.Fl Fl shadow , 723.Fl Fl single-quoted , 724.Fl Fl sleep , 725.Fl Fl stderr , 726.Fl Fl stdout , 727.Fl Fl tab-len , 728.Fl Fl time-format , 729.Fl Fl title , 730.Fl Fl version , 731.Fl Fl yes-label . 732.Pp 733Dialogs: 734.Fl Fl calendar , 735.Fl Fl checklist , 736.Fl Fl form , 737.Fl Fl gauge , 738.Fl Fl infobox , 739.Fl Fl inputbox , 740.Fl Fl menu , 741.Fl Fl mixedform , 742.Fl Fl mixedgauge , 743.Fl Fl msgbox , 744.Fl Fl passwordbox , 745.Fl Fl passwordform , 746.Fl Fl pause , 747.Fl Fl radiolist , 748.Fl Fl rangebox , 749.Fl Fl textbox , 750.Fl Fl timebox , 751.Fl Fl treeview , 752.Fl Fl yesno . 753.Pp 754Some feature differs in input, output, or behavior. 755Compatibility is not a priority for future development. 756.Sh THANKS TO 757.An Baptiste Daroussin 758.Aq Mt bapt@FreeBSD.org , 759.An \&Ed Maste 760.Aq Mt emaste@FreeBSD.org 761and 762.An Juraj Lutter 763.Aq Mt otis@FreeBSD.org 764for suggestions, help, and testing. 765