The <text> parameter may contain "\n" (line feeds) characters so that a long text can be splitted into several lines (see also the --wrap common option about line wraping). Example:
Xdialog --msgbox "text splitting\ntest..." 0 0
The <file> parameter may be replaced, for all but the fselect and dselect widgets, by "-" so that the input stream is redirected to Xdialog stdin. Example:
echo "hello folks" | Xdialog --textbox "-" 0 0
These two numbers may be replaced by a single <XSIZExYSIZE> parameter (like the one passed in the -geometry option of X) which will represent the size of the Xdialog window in pixels (example: 300x200).
Moreover, the Xdialog widgets may be auto-sized (by GTK+, that alas fails to auto-size properly some widgets) by passing a 0 0 (or 0x0) size parameter to Xdialog.
Examples:
Xdialog --msgbox "test" 6 20 # height of 6 characters and width of 20 characters Xdialog --msgbox "test" 160x96 # width of 160 pixels and height of 96 pixels Xdialog --msgbox "test" 0 0 # auto-sized widget Xdialog --msgbox "test" 0x0 # auto-sized widget
These widgets just display the <text> and wait for the user to press a button. The buttons in the yesno widget are (surprise, surprise !) Yes and No, while a single OK button is used for the msgbox. The yesno widget accepts the --wizard transient option (that may itself be used together with --no-cancel); in this case the Yes and No buttons are replaced by the Previous, Cancel (if --no-cancel is not in force) and Next buttons. The yesno widget also accepts the --default-no transient option
The infobox displays a <text> message and accepts an optional <timeout> parameter (the default is 1000). The infobox vanishes after <timeout>/1000 seconds or when the OK button is pressed (this button may be suppressed by using the --no-buttons transient option).
If a 0 timeout is passed as parameter, then the infobox widget behaves differently:
This widgets displays the <text> and a progress bar (the gauge) which starting position is set according to the <percent> parameter (if any, the default being 0%).
Once set up, it accepts new percentage values (the gauge being updated accordingly) on stdin as well as new <text> enclosed by two "XXX" markers; a newline can be inserted into the new <text> by issuing:
echo "\\n"
between each line sent to Xdialog stdin (i.e. Xdialog must actually receive on stdin a string holding the two "\" and "n" characters, and not just a line feed).
The gauge widget vanishes once the percent value exceeds 100% or when its stdin is put at EOF.
Because this option is wrongly spelled as "guage" in some releases of (c/g)dialog (this is what happens when the programmer is dyslexic ;-) Xdialog also recognizes the "--guage" option as the gauge widget... Of course as you are not dyslexic (are you ?), you should only use --gauge in your own scripts !
The --inputbox widget displays a <text> together with an entry field accepting any string. The string typing into the field may be hidden (entered characters are displayed as "*") thanks to the --password transient option. The entered string is returned (printed to Xdialog output stream) when the OK button is pressed (nothing is returned if the Cancel button is pressed; this button may itself be removed from the widget by using the --no-cancel transient option). An optional <init> string may be passed so to be setup as the default entered string (which will appear into the text entry field when the widget is drawn).
The --2inputsbox and the --3inputsbox widgets allow for two or three entry fields into the same box (see the --password transient option to learn how these fields are affected). A <label> is setup above each field (see the --center, --left and --right common options to learn how the labels justification can be affected); as for the <text> parameter, the <label>s may hold "\n" sequences IOT force text splitting into several lines. The <init> strings cannot be omitted but may perfectly be NULL (empty) strings.
The --rangebox widget displays a <text> together with a horizontal slider which scale ranges from <min value> to <max value>.The initial position of the cursor on the slider is set to <default value> (when the <default value> parameter is omitted, the cursor position is set to the <min value>). The value corresponding to the current cursor position is returned (printed to Xdialog output stream) when the OK button is pressed (nothing is returned if the Cancel button is pressed; this button may itself be removed from the widget by using the --no-cancel transient option).
The --2rangesbox and the --3rangesbox widgets allow for two or three sliders into the same box. Each slider is preceeded by a label. A <label> is setup above each slider (see the --center, --left and --right common options to learn how the labels justification can be affected); as for the <text> parameter, the <label>s may hold "\n" sequences IOT force text splitting into several lines. The <def> values cannot be omitted.
These widgets allow to display a text file contents. If the <file> parameter is replaced with a "-" (minus sign), then the text to be displayed is read from Xdialog stdin. The --editbox allows to edit the text and returns it (i.e. prints it on Xdialog output stream) once the OK button is pressed. These widgets also accept the --fixed-font and --print transient options.
This widgets ressembles to a --textbox (it accepts the same parameters and transient options) but the text is automatically scrolled to the end and is regularly updated (so that any change in the file is reflected in the box). As for the --textbox, if the <file> parameter is replaced with a "-" (minus sign), then the text to be displayed is read from Xdialog stdin.
Compatibility note: The (c)dialog --tailboxbg option is also accepted by Xdialog but it does not turn Xdialog into a background process (use & at the end of the Xdialog command line instead).
This widget presents the <text> together with a menu. For each line in the menu, there must be a <tag> and an <item> parameters. The tag is displayed left (provided that the --no-tags transient option is not in force) and the menu item right. The <menu height> is the number of lines (in characters) to which the menu sub-window should be set (an height of 0 will let GTK+ decide); of course the overall widget <height> must be big enough or the <menu height> will not be taken into account. When the OK button is pressed, the widget prints, onto the Xdialog output stream, the tag corresponding to the last selected menu entry.
Compatibility note: Xdialog also accepts the (c)dialog compatible --menu option for this widget.
These widgets present the <text> together with a list of <item>s each one being prefixed with their corresponding <tag> (provided that the --no-tags transient option is not in force). Each <status> parameter (which value may be "on" or "off") tells to Xdialog if the corresponding <item> must be selected as default. Exactly one item is selected at any time in a radiolist, while the checklist allows for any number of items (0 to all items) to be selected at a time. The tag(s) of the selected item(s) are sent onto the Xdialog output stream when the OK button is pressed. The <list height> is the number of lines (in characters) to which the list sub-window should be set (an height of 0 will let GTK+ decide); of course the overall widget <height> must be big enough or the <list height> will not be taken into account.
This widget presents the <text> together with two list sub-windows and two buttons (Add and Remove). In the left-most sub-window all unselected items are listed (those items either had an "off" <status> or have been Removed from the list by the user). The right-most sub-window presents the list of all selected items (those items either had an "on" <status> or have been Added to the list by the user). IOT Add or Remove items, the user must first highlight them and then press the proper button. The items appear in the order in which they were added/removed and this order is kept when the result is sent to the Xdialog output stream (when the OK button is pressed): the corresponding <tag>s are sent in the exact order in which the associated items appear in the right-most sub-window. The <list height> is the number of lines (in characters) to which the list sub-window should be set (an height of 0 will let GTK+ decide); of course the overall widget <height> must be big enough or the <list height> will not be taken into account.
This widget presents the <text> together with a sub-window holding a tree of the <item>s in the order in which they appear into the Xdialog command line and at the associated <item_depth> (which should range from 1 to 24). Note that from one item to the next, the depth must never increase by more than one while it may decrease by more than one. The <list height> is the number of lines (in characters) to which the list sub-window should be set (an height of 0 will let GTK+ decide); of course the overall widget <height> must be big enough or the <list height> will not be taken into account. When the OK button is pressed, the widget sends the <tag> associated with the last selected item to the Xdialog output stream.
Note: there is a bug in all GTK+ releases (up to and including v1.2.8) that prevents Xdialog to highlight the default selected item (the "on" <status> of this item is actually taken into account but the item can't be highlighted when the widget is drawn).
These widgets make use of the GTK+ file selector. They allow to select a filename (for the fselect widget) or a directory name (for the dselect widget). The <file> (for fselect) and <directory> (for dselect) parameters are used as the default selection. Using the --no-buttons transient option prevents the New directory, Delete file and Rename file buttons to be displayed in the file selector. The --help transient option is allowed and makes a help button to appear, even if --no-buttons was specified. Note that the --backtitle and --buttons-style common options are ignored by these two widgets. The widgets return the user-selected file/directory name once the OK button is pressed.
This widget displays the <text> together with a calendar showing the month holding the date defined by the <day> (1 to 31) <month>, (1 to 12) and <year> (1970 and over) parameters (if any of this parameter is 0, then the current date is used). The user may then browse the calendar and choose another date. Once the OK button is pressed, the widget returns the user-selected date (in the form DD/MM/YYYY).
This widget displays the <text> together with the current time into three "spin buttons" (hours, minutes and seconds). The user may change the time displayed and the widget returns the user-set time (in the form HH:MM:SS) once the OK button is pressed.