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
	       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 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
	       If available set	normal screen mode, see	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 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.

       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 14.quarterly	 May 25, 2024			  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+Ports+14.3.quarterly>
home | help
Header And Logo

Peripheral Links

Site Navigation

FreeBSD Manual Pages

Header And Logo

Peripheral Links

Search

Site Navigation

FreeBSD Manual Pages
