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

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

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

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  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 gbsddialog utility was implemented starting in 2023, and first released
     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 ports 15.quarterly	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+15.1-RELEASE+and+Ports.quarterly>

home | help