Skip site navigation (1)Skip section navigation (2)

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  op-
       tion  --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
	       Set alternate screen mode if the	terminal and curses(3) provide
	       it.  If enabled bsddialog draws to the alternate	screen and re-
	       stores 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 auto-
	       sizing; 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" but-
	       ton 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	other-
	       wise.

       --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,	 Radi-
	       olist 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
	       Set  normal screen mode.	 bsddialog does	not restore the	previ-
	       ous screen after	exit.  See "rmcup" in terminfo(5).

       --output-fd fd
	       Print input from	user interface to the specified	file  descrip-
	       tor.

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

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

   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 stan-
	       dard 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.	fieldlen is the	 field	width,
	       if negative is readonly and the width is	the absolute value, if
	       0  the  field becomes 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
	       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 at
	       the position yfield and xfield.	fieldlen is the	 field	width,
	       if negative is readonly and the width is	the absolute value, if
	       0  the  field becomes 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	customize field: 0 normal, 1 hide typed	 char-
	       acters,	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  de-
	       fault 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 re-
	       named "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
       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 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
       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.

       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	15.0			 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.0-RELEASE+and+Ports>

home | help