Manual Pages  — BSDDIALOG

bsddialog – TUI dialogs

SYNOPSIS DESCRIPTION Options Dialogs EXIT STATUS EXAMPLES COMPATIBILITY SEE ALSO HISTORY AUTHORS THANKS TO

bsddialog -help
bsddialog -version
bsddialog [-option] -dialog text rows cols [dialog-argument]
bsddialog -dialog1 ... [-and-dialog -dialog2 ... ]...

The bsddialog utility builds Text User Interface dialogs and widgets: to display messages, to get input and to inform about a computation status.

The options -help and -version print the list of options and the version, respectively, then exit. -and-dialog builds another dialog unless the previous one returns Error, ESC or Cancel.

text is a message printed inside the dialog. rows and cols are the height and width, 0 for autosize and -1 for fullscreen.

The possible input got from the user interface is printed to standard error.

The following options can change the default behavior of the utility and are common to some dialog.

-alternate-screen
	If available set alternate screen mode, see terminfo(5).
-ascii-lines
	Ascii characters to draw lines.
-backtitle backtitle
	Title on the top side of the screen.
-begin-x x
	Dialog horizontal position, 0 is the left screen side, -1 center.
-begin-y y
	Dialog vertical position, 0 is the top screen side, -1 center.
-bikeshed
	Random settings. Colors. Delimiter and margins around the title. Buttons always active or TAB to switch focus with input components, see -switch-buttons. Zero padding with time or date output.
-cancel-label label
	Label for the "Cancel" button.
-clear-dialog
	Hide the dialog at exit.
-clear-screen
	Clear the screen, after the dialog exit if a dialog is built.
-colors
	Enable highlights for text, the following sequences are considered escapes: "\Z0"black. "\Z1"red. "\Z2"green. "\Z3"yellow. "\Z4"blue. "\Z5"magenta. "\Z6"cyan. "\Z7"white. "\Zr"reverse foreground and background. "\ZR"disable reverse. "\Zb"bold. "\ZB"disable bold. "\Zu"underline. "\ZU"disable underline. "\Zn"restore normal text.
-columns-per-row columns
	Try to set the number of columns for a row of text with autosizing; default 10.
-cr-wrap
	Keep new line in text also if it constains a "\n", see -text-unchanged.
-date-format format
	String accepted by strftime(3) to customize the output of -datebox and -calendar
-default-button label
	Focus on the button with label on startup.
-default-item name
	Focus on the item with name, for Checklist, Menu, Radiolist and Treeview.
-default-no
	Focus on "Cancel" or "amp;No" button on startup.
-disable-esc
	Disable ESC key to quit.
-esc-return-cancel
	ESC key returns "Cancel" button value.
-extra-button
	Add a button with "Extra" label.
-extra-label label
	Set label for the "Extra" button.
-generic-button1 label
	Add a button with label.
-generic-button2 label
	Add a button with label.
-help-button
	Add a button with "Help" label.
-help-label label
	Set label for "Help" button.
-help-print-name
	Print the name of the focused item if the Help button is pressed also with -item-bottom-desc.
-help-status
	Print also the selected items if the "Help" button is pressed.
-hfile filename
	Open filename in a Textbox if F1 key is pressed,
-hline string
	Dialog subtitle.
-hmsg string
	Open a Msgbox with string if the F1 key is pressed.
-ignore
	Do not exit with unknown options.
-insecure
	Print '*' to hide passwords while typing; whitespace otherwise.
-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.
-item-depth
	Specify a margin for items, available for Checklist, Menu and Radiolist.
-item-prefix
	Set a string to prefix each item of a Checklist, Menu, Radiolist or Treeview.
-load-theme file
	Load theme from file.
-max-input size
	Maximum length of the input for -inputbox ans -passwordbox, default 2048.
-no-cancel
	Do not show "Cancel" button.
-no-descriptions
	Do not display items desciption, for Checklist, Menu, Radiolist or Treeview.
-no-lines
	Do not draw borders and lines.
-no-names
	Do not display items name, for Checklist, Menu and Radiolist.
-no-ok
	Do not draw "OK" button.
-no-shadow
	No not draw the shadow of the dialog.
-ok-label label
	Set label for "OK" button.
-normal-screen
	If available set normal screen mode, see terminfo(5).
-output-fd fd
	Print input from user interface to the specified file descriptor.
-output-separator sep
	Set a sepator for the items in output, default whitespace.
-print-maxsize
	Screen size. This option can be used without a dialog.
-print-size
	Print Dialog height and widget at exit.
-print-version
	Print version. This option can be used without a dialog.
-quoted
	Quote items in output, default only when necessary.
-save-theme file
	Save the current theme. This option can be used without a dialog.
-separate-output
	Separate selected items with a new line and avoid to quote.
-shadow
	Show a pseudo shadow for the dialog, enabled by default.
-single-quoted
	Use single quote for items in output.
-sleep secs
	Wait secs seconds to close the dialog.
-stderr
	Print input from user interface to standand error, default.
-stdout
	Print input from user interface to standard output.
-switch-buttons
	enables focus switching between buttons and input components pressing TAB, otherwise buttons are always active and ENTER key closes the dialog. Suitable for: -form, -inputbox, -mixedform, -passwordbox, -passwordform, -timebox, -calendar and -datebox.
-tab-escape
	Replace "\t" with a tab in text.
-tab-len spaces
	Number of spaces to print a TAB in text.
-text-unchanged
	By default the text is changed before to be printed. If it contains at least a "\n" 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. This option disable the text modification.
-theme theme
	Set a graphical style: blackwhite, bsddialog, flat or dialog.
-time-format format
	String accepted by strftime(3) to customize the output of -timebox.
-title title
	Dialog title.

The following dialogs are available:

-calendar text rows cols [day month year]
	Dialog to select a date.
-checklist text rows cols menurows [name desc
	Ar status Oc ... Checklist to select some item from a list via the SPACE key. An item has a name, desc and a default status specified by "on" or "off". The names of the selected items are printed to standard error. menurows is the graphical height of the list, 0 for autosize.
-datebox text rows cols [day month year]
	Dialog to select a date.
-form text rows cols formrows [label 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 label at the position ylabel and xlabel, a field to get the input at the position yfield and xfield with graphical length fieldlen, maxletters is the maximum input length. The field can be customized, if fieldlen is negative the field is read only and its absolute value is the field length. If maxletters is 0 it is the absolute value of fieldlen. init is a default value. formrows is the graphical height of the list, 0 for autosize.
-gauge text rows cols [percentage]
	Dialog with a bar to shows percentage, then it waits to read "XXX" from the standard input, then the first string replaces percentage and the following strings replace text until the next "XXX", the loop ends reading EOF.
-infobox text rows cols
	Dialog without buttons to display a message and to exit immediately.
-inputbox text rows cols [init]
	Dialog to get a string in input, init is the default value.
-menu text rows cols menurows [name desc ]...
	Builds a menu to select an item from a list, Space key is equivalent to Enter. An item has a name and a desc. The name of the selected item is printed to standard error. menurows is the graphical height of the list, 0 for autosize.
-mixedform text rows cols formrows [label 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 label at the position ylabel and xlabel, a field to get the input with graphical length fieldlen at the position yfield and xfield, maxletters is the maximum input length, init is a default value, flag can be 0 for normal field, 1 to hide the typed characters and 2 to set the field read only. formrows is the graphical height of the list, 0 for autosize.
-mixedgauge text rows cols mainperc [minilabel
	Ar miniperc Oc ... Dialog to show a main bar to represent mainperc from 0 to 100 and some mini bar with a minilabel string and a miniperc with value from 0 and 100 or negative to print a descriptive string: -1 "Succeeded", -2 "Failed", -3 "Passed", -4 "Completed", -5 "Checked", -6 "Done", -7 "Skipped", -8 "amp;In Progress", -9 a blank line, -10 "N/A", -11 "Pending".
-msgbox text rows cols
	Dialog to diplay a message without the "Cancel" button. UP, DOWN, HOME, END, PAGEUP and PAGEDOWN keys are availble to navigate the text.
-passwordbox text rows cols [init]
	Dialog to get a password, init is the default value.
-passwordform text rows cols formrows [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 -form except typed characters are hidden.
-pause text rows cols seconds
	Dialog runs until the timeout in seconds expires or a button is pressed.
-radiolist text rows cols menurows [name desc
	Ar status Oc ... Radiolist to select at most an item from a list via the SPACE key. An item has a name, desc and a default status specified by "on" or "off". The name of the selected item is printed to standard error. menurows is the graphical height of the list, 0 for autosize.
-rangebox text rows cols min max [init]
	Dialog to select a value between min and max, init is the default value, the keys UP, DOWN, HOME, END, PAGEUP and PAGEDOWN can change it.
-textbox file rows cols
	Opens and prints file the UP, DOWN, HOME, END, PAGEUP and PAGEDOWN keys are availble to navigate; "OK" button is renamed "EXIT".
-timebox text rows cols [hour min sec]
	Dialog to select a time.
-treeview text rows cols menurows [depth name
	Ar desc Ar status Oc ... Equivalent to Radiolist with -item-depth and -no-name.
-yesno text rows cols
	"Yes-No Question", "OK" and "Cancel" buttons are renamed "Yes" and "amp;No". UP, DOWN, HOME, END, PAGEUP and PAGEDOWN keys are availble to navigate the text.

The bsddialog utility exits 255 on unsuccessful, otherwise depending on the button or key pressed the following values can be returned:

0"OK", "Yes" or "Exit" button.

1"Cancel" or "amp;No" button.

2"Help" button.

3"Extra" button.

4Timeout.

5ESC key.

6Generic 1 button.

7Generic 2 button.

Backtitle, title and message:

    bsddialog --backtitle MESSAGE --title Msgbox --msgbox Message 0 0

Yes-No Question and theme:

    bsddialog --theme blackwhite --yesno Question 10 30

Save a custom theme:

    bsddialog --save-theme mytheme.txt --infobox qSaving theme...q 0 0

Load a custom theme:

    bsddialog --load-theme mytheme.txt --infobox qCustom themeq 0 0

Checklist:

    bsddialog --checklist Checklist 0 0 3 N1 amp;D1 off N2 D2 on N3 D3 off

Form:

    bsddialog --form Form 0 0 0 L1: 0 0 X 0 4 20 25 L2: 1 0 Y 1 4 20 25

Multi-dialog:

    bsddialog --normal-screen --begin-y 1 --yesno Continue? 0 0 \

--and-dialog --begin-y 10 --infobox Yes 0 0

Bikeshed:

    bsddialog --bikeshed --inputbox Example 0 0

Mixedgauge:

    bsddialog --sleep 3 --mixedgauge Example 10 30 60 L1 q -1q L2 30

Mixedgauge script:

perc=0
while [ $perc -le 100 ]
do
        bsddialog --sleep 1 --title Mixedgauge          \
                --mixedgauge "\nExample...\n" 0 0 $perc \
                "Hidden"   " -9"                        \
                "Label 1"  " -4"                        \
                "Label 2"  " -4"                        \
                "Label 3"  $perc

        perc=`expr $perc + 20`
done

Gauge script:

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

Outdated options are retained for compatibility, properly equivalent options are used:

Obsolete                     Equivalent
--and-widget                 --and-dialog
--calendar <text> 2 <cols>   --calendar <text> 0 <cols>
--clear                      --clear-screen
--defaultno                  --default-no
--exit-label                 --ok-label
--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

The bsddialog utility first appeared in FreeBSD 14.0 .

bsddialog was written by Alfonso Sabato Siciliano <Mt asiciliano@FreeBSD.org>.

bsddialog provides a subset of the functionality described in the dialog manual. The following features were reimplemented:

Options: -and-widget, -ascii-lines, -backtitle, -cancel-label, -clear, -colors, -cr-wrap, -date-format, -defaultno, -default-button, -default-no, -default-item, -exit-label, -extra-button, -extra-label, -help, -help-button, -help-label, -help-status, -help-tags, -hfile, -hline, -ignore, -insecure, -item-help, -keep-tite, -max-input, -no-cancel, -nocancel, -no-items, -no-label, -no-lines, -no-ok, -nook, -no-shadow, -no-tags, -ok-label, -output-fd, -output-separator, -print-maxsize, -print-size, -print-version, -quoted, -separate-output, -separator, -shadow, -single-quoted, -sleep, -stderr, -stdout, -tab-len, -time-format, -title, -version, -yes-label.

Dialogs: -calendar, -checklist, -form, -gauge, -infobox, -inputbox, -menu, -mixedform, -mixedgauge, -msgbox, -passwordbox, -passwordform, -pause, -radiolist, -rangebox, -textbox, -timebox, -treeview, -yesno.

Some feature differs in input, output, or behavior. Compatibility is not a priority for future development.

Baptiste Daroussin <Mt bapt@FreeBSD.org>, amp;Ed Maste <Mt emaste@FreeBSD.org> and Juraj Lutter <Mt otis@FreeBSD.org> for suggestions, help, and testing.