FreeBSD Manual Pages

home | help
GBSDDIALOG(1)		    General Commands Manual		 GBSDDIALOG(1)

NAME
       gbsddialog -- Gtk+ dialogs

SYNOPSIS
       gbsddialog --help | --version
       gbsddialog   [--option]	 --dialog  text	 rows  cols  [dialog-argument]
		  [--option]
       gbsddialog ...  --dialog1 ... [--and-dialog --dialog2 ...] ...

DESCRIPTION
       The gbsddialog utility builds graphical User Interface dialogs and wid-
       gets.

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

   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 with graphical length fieldlen,
	       maxletters is the maximum input length.	The field can be  cus-
	       tomized,	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 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
	       with  graphical	length	fieldlen  at  the  position yfield and
	       xfield, maxletters is the maximum input length, init is	a  de-
	       fault  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 display 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  de-
	       fault  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.

EXIT STATUS
       The  gbsddialog	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:
	     gbsddialog	--backtitle MESSAGE --title Msgbox --msgbox Message  0
	     0

       Yes-No Question and theme:
	     gbsddialog	--theme	blackwhite --yesno Question 10 30

       Save a custom theme:
	     gbsddialog	--save-theme mytheme.txt --infobox "Saving theme..." 0
	     0

       Load a custom theme:
	     gbsddialog	--load-theme mytheme.txt --infobox "Custom theme" 0 0

       Checklist:
	     gbsddialog	 --checklist  Checklist	0 0 3 N1 D1 off	N2 D2 on N3 D3
	     off

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

       Multi-dialog:
	     gbsddialog	--normal-screen	--begin-y 1 --yesno Continue?  0  0  \
	     --and-dialog --begin-y 10 --infobox Yes 0 0

       Bikeshed:
	     gbsddialog	--bikeshed --inputbox Example 0	0
	     gbsddialog	--bikeshed --datebox Example 0 0

       Mixedgauge:
	     gbsddialog	--sleep	3 --mixedgauge Example 10 30 60	L1 " -1" L2 30

       Mixedgauge script:
	     perc=0
	     while [ $perc -le 100 ]
	     do
		     gbsddialog	--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 | gbsddialog --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 gbsddialog utility was implemented starting in 2023,	and first  re-
       leased in 2024.

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

       gbsddialog was written by
       Pierre Pronchery	<khorben@defora.org>.

       gbsddialog 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 features differ 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.3		       January 27, 2024			 GBSDDIALOG(1)
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=gbsddialog&sektion=1&manpath=FreeBSD+14.3-RELEASE+and+Ports>
home | help
Header And Logo

Peripheral Links

Site Navigation

FreeBSD Manual Pages

Header And Logo

Peripheral Links

Search

Site Navigation

FreeBSD Manual Pages
