The BSDDialog utility builds TUI dialogs and widgets. This is the manual page, for an introduction and examples https://gitlab.com/alfix/bsddialog.
BSDDIALOG(1) FreeBSD General Commands Manual BSDDIALOG(1)
NAME
bsddialog - TUI dialogs
SYNOPSIS
bsddialog --help | --version
bsddialog [--option] --dialog text rows cols [dialog-argument] [--option]
bsddialog ... --dialog1 ... [--and-dialog --dialog2 ...] ...
DESCRIPTION
The bsddialog utility builds Text User Interface dialogs and widgets.
The option --help prints a brief list of features and exits. The option
--version prints the version and exits. The option --and-dialog builds
another dialog unless the previous one returns Error, ESC or Cancel.
Each dialog accepts text to print a message inside, rows and cols to set
height and width, 0 for autosize and -1 for fullscreen.
The possible input from the user interface is printed to standard error
at exit.
Options
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
Screen title.
--begin-x x
Set dialog horizontal position, -1 center, 0 left screen.
--begin-y y
Set dialog vertical position, -1 center, 0 top screen.
--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 --switch-buttons. Zero
padding with time output; see --time-format. Zero padding with
date output; see --date-format. User Interface date format for
--datebox; see --datebox-format.
--cancel-exit-code retval
Set an exit code value for the "Cancel" button.
--cancel-label label
Label for the "Cancel" button.
--clear-dialog
Hide the dialog at exit.
--clear-screen
Clear the screen, wait a dialog if built.
--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.
--datebox-format format
String to customize --datebox interface, possible values:
"d/m/y", "m/y/d", "y/m/d".
--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 "No" button on startup.
--disable-esc
Disable ESC key to quit.
--error-exit-code retval
Set an exit code value for the bsddialog errors.
--esc-exit-code retval
Set an exit code value for the ESC key.
--extra-button
Add a button with "Extra" label.
--extra-exit-code retval
Set an exit code value for the "Extra" button.
--extra-label label
Set label for the "Extra" button.
--left1-button label
Add a button with label.
--left1-exit-code retval
Set an exit code for --left1-button.
--left2-button label
Add a button with label.
--left2-exit-code retval
Set an exit code for --left2-button.
--left3-button label
Add a button with label.
--left3-exit-code retval
Set an exit code for --left3-button.
--help-button
Add a button with "Help" label.
--help-exit-code retval
Set an exit code value for the "Help" button.
--help-label label
Set label for "Help" button.
--help-print-items
Print also the selected items or form values if the "Help" button
is pressed.
--help-print-name
Print the name of the focused item if the "Help" button is
pressed also with --item-bottom-desc.
--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, white space 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 and --passwordbox,
default 2048.
--no-cancel
Do not show "Cancel" button.
--no-descriptions
Do not display items desciption, for Checklist, Menu, Radiolist
or Treeview; mutually exclusive with --no-names.
--no-lines
Do not draw borders and lines.
--no-names
Do not display items name, for Checklist, Menu and Radiolist;
mutually exclusive with --no-descriptions.
--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.
--ok-exit-code retval
Set an exit code value for the "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 white space.
--print-maxsize
Screen size. This option can be used without a dialog.
--print-size
Print dialog height and width at exit.
--print-version
Print version. This option can be used without a dialog.
--quoted
Quote items in output, default only when necessary.
--right1-button label
Add a button with label.
--right1-exit-code retval
Set an exit code for --right1-button.
--right2-button label
Add a button with label.
--right2-exit-code retval
Set an exit code for --right2-button.
--right3-button label
Add a button with label.
--right3-exit-code retval
Set an exit code for --right3-button.
--save-theme file
Save the current theme. This option can be used without a
dialog.
--separate-output
Print selected items separated by a new line and avoid to quote.
--shadow
Show a 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
Enable 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-escape
Enable escapes in text:
"\Z0" black.
"\Z1" red.
"\Z2" green.
"\Z3" yellow.
"\Z4" blue.
"\Z5" magenta.
"\Z6" cyan.
"\Z7" white.
"\Zb" bold.
"\ZB" disable bold.
"\Zd" Half bright.
"\ZD" disable half bright.
"\Zk" Blink.
"\ZK" disable blinking.
"\Zr" reverse foreground and background.
"\ZR" disable reverse.
"\Zs" Highlight.
"\ZS" disable highlighting.
"\Zu" underline.
"\ZU" disable underline.
"\Zn" disable each customization.
--text-unchanged
Disable text modification. By default text is changed before to
be printed in the dialog. 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.
--theme theme
Set theme, possible values: "3d", "blackwhite", "flat".
--time-format format
String accepted by strftime(3) to customize the output of
--timebox.
--timeout-exit-code retval
Set an exit code value for the --pause timeout.
--title title
Dialog title.
Dialogs
The following dialogs are available:
--calendar text rows cols [day month year]
Dialog to select a date.
--checklist text rows cols menurows [name desc status] ...
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 xlabel init yfield xfield
fieldlen maxletters] ...
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 xlabel init yfield
xfield fieldlen maxletters flag] ...
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 miniperc] ...
Dialog to show a main bar to represent mainperc from 0 to 100.
Some mini bar with a minilabel string and a miniperc with a 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 "In Progress", -9 to hide
miniperc, -10 "N/A", -11 "Pending", otherwise "UNKNOWN".
--msgbox text rows cols
Dialog to diplay a message without the "Cancel" button. UP,
DOWN, HOME, END, PAGEUP and PAGEDOWN keys are availble to scroll
the text.
--passwordbox text rows cols [init]
Dialog to get a password, init is the default value.
--passwordform text rows cols formrows [label ylabel xlabel init yfield
xfield fieldlen maxletters] ...
Dialog to get a list of passwords, equivalent to --form except
typed characters are hidden.
--pause text rows cols seconds
Dialog runs until seconds timeout expires or a button is pressed.
--radiolist text rows cols menurows [name desc status] ...
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. UP, DOWN, LEFT, RIGHT, HOME, END, PAGEUP
and PAGEDOWN keys are available to navigate the file, TAB changes
button. "OK" button is renamed "EXIT".
--timebox text rows cols [hour min sec]
Dialog to select a time.
--treeview text rows cols menurows [depth name desc status] ...
Equivalent to Radiolist with --item-depth and --no-name.
--yesno text rows cols
"Yes-No Question", "OK" and "Cancel" buttons are renamed "Yes"
and "No". UP, DOWN, HOME, END, PAGEUP and PAGEDOWN keys are
availble to scroll the text.
ENVIRONMENT
The following environment variables take effect only on startup, other
options can override their setting.
NO_COLOR
If present and not an empty string (regardless of its value)
equivalent to --theme blackwhite.
BSDDIALOG_ERROR, BSDDIALOG_OK, BSDDIALOG_CANCEL, BSDDIALOG_HELP,
BSDDIALOG_EXTRA, BSDDIALOG_TIMEOUT, BSDDIALOG_ESC,
BSDDIALOG_LEFT1, BSDDIALOG_LEFT2, BSDDIALOG_LEFT3,
BSDDIALOG_RIGHT1, BSDDIALOG_RIGHT2, BSDDIALOG_RIGHT3
Set exit codes.
BSDDIALOG_THEMEFILE file
Equivalent to --load-theme file.
FILES
The theme file $HOME/.bsddialog.conf is read on startup if exists.
EXIT STATUS
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 "No" button.
2 "Help" button.
3 "Extra" button.
4 Timeout.
5 ESC key.
6 Left1 generic button.
7 Left2 generic button.
8 Left3 generic button.
9 Right1 generic button.
10 Right2 generic button.
11 Right2 generic button.
EXAMPLES
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 "Saving theme..." 0 0
Load a custom theme:
bsddialog --load-theme mytheme.txt --infobox "Custom theme" 0 0
Checklist:
bsddialog --checklist Checklist 0 0 3 N1 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
bsddialog --bikeshed --datebox Example 0 0
Mixedgauge:
bsddialog --sleep 3 --mixedgauge Example 10 30 60 L1 " -1" 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
COMPATIBILITY
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
--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
SEE ALSO
bsddialog(3), strftime(3), terminfo(5)
HISTORY
The bsddialog utility first appeared in FreeBSD 14.0.
AUTHORS
bsddialog was written by Alfonso Sabato Siciliano
<asiciliano@FreeBSD.org>.
bsddialog provides also 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.
THANKS TO
Baptiste Daroussin <bapt@FreeBSD.org>,
Ed Maste <emaste@FreeBSD.org>,
Juraj Lutter <otis@FreeBSD.org> and
Trenton Schulz for suggestions, help, and testing.
FreeBSD 14.0-CURRENT July 25, 2023 FreeBSD 14.0-CURRENT