FreeBSD Manual Pages

home | help
BSDDIALOG(1)		     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 an-
     other 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
	     Set alternate screen mode if the terminal and curses(3) provide it.
	     If enabled bsddialog draws to the alternate screen and restores the
	     main screen after exit.  See "smcup" in 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, Mixed-
	     form, Passwordform, Radiolist and Treeview to display at the bottom
	     screen side.

     --item-depth
	     Specify a margin for items, available for Checklist, Menu and Radi-
	     olist.

     --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,  de-
	     fault 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; mutu-
	     ally 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
	     Set normal screen mode.  bsddialog does not  restore  the	previous
	     screen after exit.  See "rmcup" in 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 press-
	     ing 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.

   Keys
     The following keys are available at runtime:

     Ctrl-l  Redraw the dialog.

     F1      See --hfile and --hmsg.

     SPACE   Select menu item.

     UP DOWN LEFT RIGHT - + HOME END PAGEUP PAGEDOWN Ctrl-p Ctrl-n TAB
	     Navigate elements and set value, depending on the dialog.

   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 er-
	     ror.  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 po-
	     sition yfield and xfield.	fieldlen is the field width, if negative
	     is readonly and the width is the absolute value, if 0 the field be-
	     comes readonly and its value is the init width.  The field input is
	     not printed to output if it is readonly.  maxletters is the maximum
	     input  length,  if is 0 its value is fieldlen.  init is the default
	     value in the field.  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  immedi-
	     ately.

     --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 equiva-
	     lent to ENTER.  An item has a name and a desc.  The name of the se-
	     lected item is printed to standard error.	menurows is the  graphi-
	     cal 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 at the po-
	     sition yfield and xfield.	fieldlen is the field width, if negative
	     is readonly and the width is the absolute value, if 0 the field be-
	     comes readonly and its value is the init width.  The field input is
	     not printed to output if fieldlen is  less  than  or  equal  to  0.
	     maxletters  is  the  maximum  input  length,  if  is 0 its value is
	     fieldlen.	init is the default value in the field.  flag  can  cus-
	     tomize  field:  0	normal,  1  hide  typed  characters, 2 readonly.
	     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.

     --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.

     --textbox file rows cols
	     Opens and prints file.  TAB changes button.  Extra keys 0, h, l, k,
	     j are available to navigate  the  text.   "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".

ENVIRONMENT
     The following environment variables take effect only on startup, other  op-
     tions can override their setting.

     NO_COLOR
	     If present and not an empty string (regardless of its value) equiv-
	     alent 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 Right3 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  op-
     tions 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.

     Keys: Ctrl-l, F1.

     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 ports 15.quarterly	  June 22, 2025 		    BSDDIALOG(1)
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=bsddialog&sektion=1&manpath=FreeBSD+15.1-RELEASE+and+Ports.quarterly>
home | help
Header And Logo

Peripheral Links

Site Navigation

FreeBSD Manual Pages

Header And Logo

Peripheral Links

Search

Site Navigation

FreeBSD Manual Pages
