.\" .\" Copyright (c) 2021-2023 Alfonso Sabato Siciliano .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd July 25, 2023 .Dt BSDDIALOG 1 .Os .Sh NAME .Nm bsddialog .Nd TUI dialogs .Sh SYNOPSIS .Nm .Fl Fl help | Fl Fl version .Nm .Op Fl Fl option .Fl Fl dialog .Ar text .Ar rows .Ar cols .Op Ar dialog-argument .Op Fl Fl option .Nm \&... .Fl Fl dialog1 .Ar ... .Oo Fl Fl and-dialog .Fl Fl dialog2 .Ar ... .Oc ... .Sh DESCRIPTION The .Nm bsddialog utility builds Text User Interface dialogs and widgets. .Pp The option .Fl Fl help prints a brief list of features and exits. The option .Fl Fl version prints the version and exits. The option .Fl Fl and-dialog builds another dialog unless the previous one returns Error, ESC or Cancel. .Pp Each dialog accepts .Ar text to print a message inside, .Ar rows and .Ar cols to set height and width, .Dv 0 for autosize and .Dv -1 for fullscreen. .Pp The possible input from the user interface is printed to standard error at exit. .Ss Options The following options can change the default behavior of the utility and are common to some dialog. .Bl -tag -width Ds .It Fl Fl alternate-screen If available set alternate screen mode, see .Xr terminfo 5 . .It Fl Fl ascii-lines Ascii characters to draw lines. .It Fl Fl backtitle Ar backtitle Screen title. .It Fl Fl begin-x Ar x Set dialog horizontal position, .Dv -1 center, .Dv 0 left screen. .It Fl Fl begin-y Ar y Set dialog vertical position, .Dv -1 center, .Dv 0 top screen. .It Fl Fl bikeshed Random settings. Colors, title delimiter, button delimiter; see theme features. Title margin. Buttons always active or TAB to switch focus with other components, see .Fl Fl switch-buttons . Zero padding with time output; see .Fl Fl time-format . Zero padding with date output; see .Fl Fl date-format . User Interface date format for .Fl Fl datebox ; see .Fl Fl datebox-format . .It Fl Fl cancel-exit-code Ar retval Set an exit code value for the .Dq Cancel button. .It Fl Fl cancel-label Ar label Label for the .Dq Cancel button. .It Fl Fl clear-dialog Hide the dialog at exit. .It Fl Fl clear-screen Clear the screen, wait a dialog if built. .It Fl Fl columns-per-row Ar columns Try to set the number of columns for a row of text with autosizing; default .Dv 10 . .It Fl Fl cr-wrap Keep new line in .Ar text also if it constains a .Dq \en , see .Fl Fl text-unchanged . .It Fl Fl datebox-format Ar format String to customize .Fl Fl datebox interface, possible values: .Dq d/m/y , .Dq m/y/d , .Dq y/m/d . .It Fl Fl date-format Ar format String accepted by .Xr strftime 3 to customize the output of .Fl Fl datebox and .Fl Fl calendar . .It Fl Fl default-button Ar label Focus on the button with .Ar label on startup. .It Fl Fl default-item Ar name Focus on the item with .Ar name , for Checklist, Menu, Radiolist and Treeview. .It Fl Fl default-no Focus on .Dq Cancel or .Dq \&No button on startup. .It Fl Fl disable-esc Disable ESC key to quit. .It Fl Fl error-exit-code Ar retval Set an exit code value for the .Nm errors. .It Fl Fl esc-exit-code Ar retval Set an exit code value for the .Dv ESC key. .It Fl Fl extra-button Add a button with .Dq Extra label. .It Fl Fl extra-exit-code Ar retval Set an exit code value for the .Dq Extra button. .It Fl Fl extra-label Ar label Set .Ar label for the .Dq Extra button. .It Fl Fl left1-button Ar label Add a button with .Ar label . .It Fl Fl left1-exit-code Ar retval Set an exit code for .Fl Fl left1-button . .It Fl Fl left2-button Ar label Add a button with .Ar label . .It Fl Fl left2-exit-code Ar retval Set an exit code for .Fl Fl left2-button . .It Fl Fl left3-button Ar label Add a button with .Ar label . .It Fl Fl left3-exit-code Ar retval Set an exit code for .Fl Fl left3-button . .It Fl Fl help-button Add a button with .Dq Help label. .It Fl Fl help-exit-code Ar retval Set an exit code value for the .Dq Help button. .It Fl Fl help-label Ar label Set .Ar label for .Dq Help button. .It Fl Fl help-print-items Print also the selected items or form values if the .Dq Help button is pressed. .It Fl Fl help-print-name Print the name of the focused item if the .Dq Help button is pressed also with .Fl Fl item-bottom-desc . .It Fl Fl hfile Ar filename Open .Ar filename in a Textbox if F1 key is pressed. .It Fl Fl hline Ar string Dialog subtitle. .It Fl Fl hmsg Ar string Open a Msgbox with .Ar string if the F1 key is pressed. .It Fl Fl ignore Do not exit with unknown options. .It Fl Fl insecure Print .Sq * to hide passwords while typing, white space otherwise. .It Fl Fl item-bottom-desc Set a help string for each item of a Checklist, Form, Menu, Mixedform, Passwordform, Radiolist and Treeview to display at the bottom screen side. .It Fl Fl item-depth Specify a margin for items, available for Checklist, Menu and Radiolist. .It Fl Fl item-prefix Set a string to prefix each item of a Checklist, Menu, Radiolist or Treeview. .It Fl Fl load-theme Ar file Load theme from .Ar file . .It Fl Fl max-input Ar size Maximum length of the input for .Fl Fl inputbox and .Fl Fl passwordbox , default 2048. .It Fl Fl no-cancel Do not show .Dq Cancel button. .It Fl Fl no-descriptions Do not display items desciption, for Checklist, Menu, Radiolist or Treeview; mutually exclusive with .Fl Fl no-names . .It Fl Fl no-lines Do not draw borders and lines. .It Fl Fl no-names Do not display items name, for Checklist, Menu and Radiolist; mutually exclusive with .Fl Fl no-descriptions . .It Fl Fl no-ok Do not draw .Dq OK button. .It Fl Fl no-shadow No not draw the shadow of the dialog. .It Fl Fl ok-label Ar label Set .Ar label for .Dq OK button. .It Fl Fl ok-exit-code Ar retval Set an exit code value for the .Dq Ok button. .It Fl Fl normal-screen If available set normal screen mode, see .Xr terminfo 5 . .It Fl Fl output-fd Ar fd Print input from user interface to the specified file descriptor. .It Fl Fl output-separator Ar sep Set a sepator for the items in output, default white space. .It Fl Fl print-maxsize Screen size. This option can be used without a dialog. .It Fl Fl print-size Print dialog height and width at exit. .It Fl Fl print-version Print version. This option can be used without a dialog. .It Fl Fl quoted Quote items in output, default only when necessary. .It Fl Fl right1-button Ar label Add a button with .Ar label . .It Fl Fl right1-exit-code Ar retval Set an exit code for .Fl Fl right1-button . .It Fl Fl right2-button Ar label Add a button with .Ar label . .It Fl Fl right2-exit-code Ar retval Set an exit code for .Fl Fl right2-button . .It Fl Fl right3-button Ar label Add a button with .Ar label . .It Fl Fl right3-exit-code Ar retval Set an exit code for .Fl Fl right3-button . .It Fl Fl save-theme Ar file Save the current theme. This option can be used without a dialog. .It Fl Fl separate-output Print selected items separated by a new line and avoid to quote. .It Fl Fl shadow Show a shadow for the dialog, enabled by default. .It Fl Fl single-quoted Use single quote for items in output. .It Fl Fl sleep Ar secs Wait .Ar secs seconds to close the dialog. .It Fl Fl stderr Print input from user interface to standand error, default. .It Fl Fl stdout Print input from user interface to standard output. .It Fl Fl switch-buttons Enable focus switching between buttons and input components pressing TAB, otherwise buttons are always active and ENTER key closes the dialog. Suitable for: .Fl Fl form , .Fl Fl inputbox , .Fl Fl mixedform , .Fl Fl passwordbox , .Fl Fl passwordform , .Fl Fl timebox , .Fl Fl calendar and .Fl Fl datebox . .It Fl Fl tab-escape Replace .Dq \et with a tab in .Ar text . .It Fl Fl tab-len Ar spaces Number of spaces to print a TAB in .Ar text . .It Fl Fl text-escape Enable escapes in .Ar text : .Bl -column -compact .It Dq \eZ0 black. .It Dq \eZ1 red. .It Dq \eZ2 green. .It Dq \eZ3 yellow. .It Dq \eZ4 blue. .It Dq \eZ5 magenta. .It Dq \eZ6 cyan. .It Dq \eZ7 white. .It Dq \eZb bold. .It Dq \eZB disable bold. .It Dq \eZd Half bright. .It Dq \eZD disable half bright. .It Dq \eZk Blink. .It Dq \eZK disable blinking. .It Dq \eZr reverse foreground and background. .It Dq \eZR disable reverse. .It Dq \eZs Highlight. .It Dq \eZS disable highlighting. .It Dq \eZu underline. .It Dq \eZU disable underline. .It Dq \eZn disable each customization. .El .It Fl Fl text-unchanged Disable .Ar text modification. By default .Ar text is changed before to be printed in the dialog. If it contains at least a .Dq \en each new line and TAB is converted to a space, subsequent spaces are merged. Otherwise new line characters are preserved and a TAB becomes a space. .It Fl Fl theme Ar theme Set theme, possible values: .Dq 3d , .Dq blackwhite , .Dq flat . .It Fl Fl time-format Ar format String accepted by .Xr strftime 3 to customize the output of .Fl Fl timebox . .It Fl Fl timeout-exit-code Ar retval Set an exit code value for the .Fl Fl pause timeout. .It Fl Fl title Ar title Dialog title. .El .Ss Dialogs The following dialogs are available: .Bl -tag -width Ds .It Fl Fl calendar Ar text Ar rows Ar cols Op Ar day Ar month Ar year Dialog to select a date. .It Fl Fl checklist Ar text Ar rows Ar cols Ar menurows Oo Ar name Ar desc \ Ar status Oc ... Checklist to select some item from a list via the SPACE key. An item has a .Ar name , .Ar desc and a default .Ar status specified by .Dq on or .Dq off . The names of the selected items are printed to standard error. .Ar menurows is the graphical height of the list, 0 for autosize. .It Fl Fl datebox Ar text Ar rows Ar cols Op Ar day Ar month Ar year Dialog to select a date. .It Fl Fl form Ar text Ar rows Ar cols Ar formrows Oo Ar label Ar ylabel \ Ar xlabel Ar init Ar yfield Ar xfield Ar fieldlen Ar maxletters Oc ... Dialog to get a list of strings via forms. A form has a .Ar label at the position .Ar ylabel and .Ar xlabel , a field to get the input at the position .Ar yfield and .Ar xfield with graphical length .Ar fieldlen , .Ar maxletters is the maximum input length. The field can be customized, if .Ar fieldlen is negative the field is read only and its absolute value is the field length. If .Ar maxletters is 0 it is the absolute value of .Ar fieldlen . .Ar init is a default value. .Ar formrows is the graphical height of the list, .Dv 0 for autosize. .It Fl Fl gauge Ar text Ar rows Ar cols Op Ar percentage Dialog with a bar to shows .Ar percentage , then it waits to read .Dq XXX from the standard input, then the first string replaces percentage and the following strings replace .Ar text until the next .Dq XXX , the loop ends reading .Dq EOF . .It Fl Fl infobox Ar text Ar rows Ar cols Dialog without buttons to display a message and to exit immediately. .It Fl Fl inputbox Ar text Ar rows Ar cols Op Ar init Dialog to get a string in input, .Ar init is the default value. .It Fl Fl menu Ar text Ar rows Ar cols Ar menurows Oo Ar name desc Oc ... Builds a menu to select an item from a list, Space key is equivalent to Enter. An item has a .Ar name and a .Ar desc . The name of the selected item is printed to standard error. .Ar menurows is the graphical height of the list, 0 for autosize. .It Fl Fl mixedform Ar text Ar rows Ar cols Ar formrows Oo Ar label Ar ylabel \ Ar xlabel Ar init Ar yfield Ar xfield Ar fieldlen Ar maxletters Ar flag Oc ... Dialog to get a list of strings via forms. A form has a .Ar label at the position .Ar ylabel and .Ar xlabel , a field to get the input with graphical length .Ar fieldlen at the position .Ar yfield and .Ar xfield , .Ar maxletters is the maximum input length, .Ar init is a default value, .Ar flag can be 0 for normal field, 1 to hide the typed characters and 2 to set the field read only. .Ar formrows is the graphical height of the list, .Dv 0 for autosize. .It Fl Fl mixedgauge Ar text Ar rows Ar cols Ar mainperc Oo Ar minilabel \ Ar miniperc Oc ... Dialog to show a main bar to represent .Ar mainperc from 0 to 100. Some mini bar with a .Ar minilabel string and a .Ar miniperc with a value from 0 and 100 or negative to print a descriptive string: -1 .Dq Succeeded , -2 .Dq Failed , -3 .Dq Passed , -4 .Dq Completed , -5 .Dq Checked , -6 .Dq Done , -7 .Dq Skipped , -8 .Dq \&In Progress , -9 to hide .Fa miniperc , -10 .Dq N/A , -11 .Dq Pending , otherwise .Dq UNKNOWN . .It Fl Fl msgbox Ar text Ar rows Ar cols Dialog to diplay a message without the .Dq Cancel button. UP, DOWN, HOME, END, PAGEUP and PAGEDOWN keys are availble to scroll the text. .It Fl Fl passwordbox Ar text Ar rows Ar cols Op Ar init Dialog to get a password, .Ar init is the default value. .It Fl Fl passwordform Ar text Ar rows Ar cols Ar formrows Oo Ar label \ Ar ylabel Ar xlabel Ar init Ar yfield Ar xfield Ar fieldlen Ar maxletters \ Oc ... Dialog to get a list of passwords, equivalent to .Fl Fl form except typed characters are hidden. .It Fl Fl pause Ar text Ar rows Ar cols Ar seconds Dialog runs until .Ar seconds timeout expires or a button is pressed. .It Fl Fl radiolist Ar text Ar rows Ar cols Ar menurows Oo Ar name Ar desc \ Ar status Oc ... Radiolist to select at most an item from a list via the SPACE key. An item has a .Ar name , .Ar desc and a default .Ar status specified by .Dq on or .Dq off . The name of the selected item is printed to standard error. .Ar menurows is the graphical height of the list, 0 for autosize. .It Fl Fl rangebox Ar text Ar rows Ar cols Ar min Ar max Op Ar init Dialog to select a value between .Ar min and .Ar max , .Ar init is the default value, the keys UP, DOWN, HOME, END, PAGEUP and PAGEDOWN can change it. .It Fl Fl textbox Ar file Ar rows Ar cols Opens and prints .Ar file . UP, DOWN, LEFT, RIGHT, HOME, END, PAGEUP and PAGEDOWN keys are available to navigate the file, TAB changes button. .Dq OK button is renamed .Dq EXIT . .It Fl Fl timebox Ar text Ar rows Ar cols Op Ar hour Ar min Ar sec Dialog to select a time. .It Fl Fl treeview Ar text Ar rows Ar cols Ar menurows Oo Ar depth Ar name \ Ar desc Ar status Oc ... Equivalent to Radiolist with .Fl Fl item-depth and .Fl Fl no-name . .It Fl Fl yesno Ar text Ar rows Ar cols .Dq Yes-No Question , .Dq OK and .Dq Cancel buttons are renamed .Dq Yes and .Dq \&No . UP, DOWN, HOME, END, PAGEUP and PAGEDOWN keys are availble to scroll the text. .El .Sh ENVIRONMENT The following environment variables take effect only on startup, other options can override their setting. .Bl -tag -width indent .It Ev NO_COLOR If present and not an empty string (regardless of its value) equivalent to .Fl Fl theme Ar blackwhite . .It Ev BSDDIALOG_ERROR , Ev BSDDIALOG_OK , Ev BSDDIALOG_CANCEL , \ Ev BSDDIALOG_HELP , Ev BSDDIALOG_EXTRA , Ev BSDDIALOG_TIMEOUT , \ Ev BSDDIALOG_ESC , Ev BSDDIALOG_LEFT1 , Ev BSDDIALOG_LEFT2 , \ Ev BSDDIALOG_LEFT3 , Ev BSDDIALOG_RIGHT1 , Ev BSDDIALOG_RIGHT2 , \ Ev BSDDIALOG_RIGHT3 Set exit codes. .It Ev BSDDIALOG_THEMEFILE Ar file Equivalent to .Fl Fl load-theme Ar file . .El .Sh FILES The theme file .Pa $HOME/.bsddialog.conf is read on startup if exists. .Sh EXIT STATUS The .Nm utility exits 255 on unsuccessful, otherwise depending on the button or key pressed the following values can be returned: .Bl -column -compact .It 0 .Dq OK , .Dq Yes or .Dq Exit button. .It 1 .Dq Cancel or .Dq \&No button. .It 2 .Dq Help button. .It 3 .Dq Extra button. .It 4 Timeout. .It 5 ESC key. .It 6 Left1 generic button. .It 7 Left2 generic button. .It 8 Left3 generic button. .It 9 Right1 generic button. .It 10 Right2 generic button. .It 11 Right2 generic button. .El .Sh EXAMPLES Backtitle, title and message: .Dl bsddialog --backtitle MESSAGE --title Msgbox --msgbox Message 0 0 .Pp Yes-No Question and theme: .Dl bsddialog --theme blackwhite --yesno Question 10 30 .Pp Save a custom theme: .Dl bsddialog --save-theme mytheme.txt --infobox \*qSaving theme...\*q 0 0 .Pp Load a custom theme: .Dl bsddialog --load-theme mytheme.txt --infobox \*qCustom theme\*q 0 0 .Pp Checklist: .Dl bsddialog --checklist Checklist 0 0 3 N1 \&D1 off N2 D2 on N3 D3 off .Pp Form: .Dl bsddialog --form Form 0 0 0 L1: 0 0 X 0 4 20 25 L2: 1 0 Y 1 4 20 25 .Pp Multi-dialog: .Dl bsddialog --normal-screen --begin-y 1 --yesno Continue? 0 0 \e \ --and-dialog --begin-y 10 --infobox Yes 0 0 .Pp Bikeshed: .Dl bsddialog --bikeshed --inputbox Example 0 0 .Dl bsddialog --bikeshed --datebox Example 0 0 .Pp Mixedgauge: .Dl bsddialog --sleep 3 --mixedgauge Example 10 30 60 L1 \*q -1\*q L2 30 .Pp Mixedgauge script: .Bd -literal -offset indent -compact perc=0 while [ $perc -le 100 ] do bsddialog --sleep 1 --title Mixedgauge \e --mixedgauge "\enExample...\en" 0 0 $perc \e "Hidden" " -9" \e "Label 1" " -4" \e "Label 2" " -4" \e "Label 3" $perc perc=`expr $perc + 20` done .Ed .Pp Gauge script: .Bd -literal -offset indent -compact i=1 for c in A B C D E F G H do sleep 1 echo XXX echo "$(expr $(expr $i "*" 100) "/" 8)" echo "[$i/8] Char: $c" echo XXX if [ $i -eq 8 ] then sleep 1 echo EOF fi i=`expr $i + 1` done | bsddialog --title Gauge --gauge "Starting..." 10 70 .Ed .Sh COMPATIBILITY Outdated options are retained for compatibility, properly equivalent options are used: .Bd -literal -offset indent -compact Obsolete Equivalent --and-widget --and-dialog --calendar 2 --calendar 0 --clear --clear-screen --colors --text-escape --defaultno --default-no --exit-label --ok-label --help-status --help-print-items --help-tags --help-print-name --item-help --item-bottom-desc --keep-tite --alternate-screen --no-items --no-descriptions --no-label --cancel-label --no-tags --no-names --nocancel --no-cancel --nook --no-ok --separator --output-separator --yes-label --ok-label .Ed .Sh SEE ALSO .Xr bsddialog 3 , .Xr strftime 3 , .Xr terminfo 5 .Sh HISTORY The .Nm bsddialog utility first appeared in .Fx 14.0 . .Sh AUTHORS .Nm bsddialog was written by .An Alfonso Sabato Siciliano .Aq Mt asiciliano@FreeBSD.org . .Pp .Nm bsddialog provides also a subset of the functionality described in the .Nm dialog manual. The following features were reimplemented: .Pp Options: .Fl Fl and-widget , .Fl Fl ascii-lines , .Fl Fl backtitle , .Fl Fl cancel-label , .Fl Fl clear , .Fl Fl colors , .Fl Fl cr-wrap , .Fl Fl date-format , .Fl Fl defaultno , .Fl Fl default-button , .Fl Fl default-no , .Fl Fl default-item , .Fl Fl exit-label , .Fl Fl extra-button , .Fl Fl extra-label , .Fl Fl help , .Fl Fl help-button , .Fl Fl help-label , .Fl Fl help-status , .Fl Fl help-tags , .Fl Fl hfile , .Fl Fl hline , .Fl Fl ignore , .Fl Fl insecure , .Fl Fl item-help , .Fl Fl keep-tite , .Fl Fl max-input , .Fl Fl no-cancel , .Fl Fl nocancel , .Fl Fl no-items , .Fl Fl no-label , .Fl Fl no-lines , .Fl Fl no-ok , .Fl Fl nook , .Fl Fl no-shadow , .Fl Fl no-tags , .Fl Fl ok-label , .Fl Fl output-fd , .Fl Fl output-separator , .Fl Fl print-maxsize , .Fl Fl print-size , .Fl Fl print-version , .Fl Fl quoted , .Fl Fl separate-output , .Fl Fl separator , .Fl Fl shadow , .Fl Fl single-quoted , .Fl Fl sleep , .Fl Fl stderr , .Fl Fl stdout , .Fl Fl tab-len , .Fl Fl time-format , .Fl Fl title , .Fl Fl version , .Fl Fl yes-label . .Pp Dialogs: .Fl Fl calendar , .Fl Fl checklist , .Fl Fl form , .Fl Fl gauge , .Fl Fl infobox , .Fl Fl inputbox , .Fl Fl menu , .Fl Fl mixedform , .Fl Fl mixedgauge , .Fl Fl msgbox , .Fl Fl passwordbox , .Fl Fl passwordform , .Fl Fl pause , .Fl Fl radiolist , .Fl Fl rangebox , .Fl Fl textbox , .Fl Fl timebox , .Fl Fl treeview , .Fl Fl yesno . .Pp Some feature differs in input, output, or behavior. Compatibility is not a priority for future development. .Sh THANKS TO .An Baptiste Daroussin .Aq Mt bapt@FreeBSD.org , .An \&Ed Maste .Aq Mt emaste@FreeBSD.org , .An Juraj Lutter .Aq Mt otis@FreeBSD.org and .An Trenton Schulz for suggestions, help, and testing.