=============================================================================== IMPORTANT NOTICE: ~~~~~~~~~~~~~~~~~ This file is NO MORE MAINTAINED and is kept for historical reasons only. It is therefore no more in sync with recent Xdialog releases (v1.5.0 and later). Please, read the nice HTML documentation instead ! =============================================================================== This Xdialog written by Cyberone Internet. Xdialog is designed to be a drop in replacement for the cdialog program. It converts any terminal based program into a program with an X-windows interface. The dialogs are easier to see and use and the treeview adds an extra dimension to the way menus can be displayed. If you have any problems/bugs contact alfred@cyberone.com.au and I will try to help. Please read the INSTALL file for installation instructions. Commands - Xdialog functions exactly as cdialog does, and it accepts the same command line parameters. It also has an added treeview mode which can be very handy. Here is the command line arguments it accepts: Usage: Xdialog <Common options> <Box options> Common options: [--backtitle <backtitle>] - the menubar title [--title <title>] - Another part of the title [--password ] - make input to the screen '*' (ala password entry screens) Box options: --yesno <text> <height> <width> --msgbox <text> <height> <width> --infobox <text> <height> <width> --inputbox <text> <height> <width> [<init>] --textbox <file> <height> <width> --menu <text> <height> <width> <menu height> <tag1> <item1>... --checklist <text> <height> <width> <list height> <tag1> <item1> <status1>... --radiolist <text> <height> <width> <list height> <tag1> <item1> <status1>... --treeview <text> <height> <width> <list height> <tag1> <item1> <status1> <item_depth1>... --guage <text> <height> <width> <percent> --tailbox <file> <height> <width> --tailboxbg <file> <height> <width> The only thing of note here is the treeview depth. This is the number of levels in the tree entry should be, and it should *never* increase by more than 1 at a time (decreasing by more than 1 is fine). ------------------------------------------------------------------------------------- Xdialog v1.4.6, 15/12/00: Bug fixes and further development by Thierry Godefroy <xdialog@free.fr> (web site: http://xdialog.free.fr): 1.- Bug fixes: ~~~~~~~~~ - The <height> and <width> parameters are now actually taken into account. They must be specified in "lines" (12 pixels high each) and "characters" (8 pixels wide each). The 8x12 character size may be changed at compile time only by defining XSIZE_MULT and/or YSIZE_MULT in the CPPFLAGS line of the src/Makefile (e.g. CPPFLAGS = -DXSIZE_MULT=10 -DYSIZE_MULT=18). These two parameters may also be replaced by a single <XSIZExYSIZE> parameter that will specify the size in pixels (this size will be rounded to the next "character" boundary). Passing 0 0 (or 0x0) to Xdialog for its window size will make it to auto-size. - The <text> is now actually displayed by checklist, radiolist, menu, etc... - The treeview options is debugged and now takes parameters in the order in which they are documented (it used to mess up the tags, the status and the item names). Note that the "<status>" ("on" or "off") although taken into account for the item tag returned as default, does not hilight the "on" item (because of what looks like a GTK+ bug...). - The <tag>s are now displayed before the <item>s in checklist and radiolist (same behaviour as with "(c)dialog"). But as hidding them may be useful too, I added the transient "--no-tags" option, which may also be used with the "menubox" widget. 2.- Changes and improvements: ~~~~~~~~~~~~~~~~~~~~~~~~ - It is now possible to chain dialogs in a single Xdialog command line. The chain is broken as soon as a "cancel" button is pressed or the box is closed (see the "chain" example script in the "samples" directory). Note though that in this case no parameter can be defaulted in the <Box options>. - Distinction has been made between "common options" (that will affect all the following "box options" until the same or opposite "common options" are encountered in the command line) and "transient options" that only apply to the next "box option" in the command line. The "--passwd" option has been made a "transient option". - The <file> parameter of "--textbox", "--editbox" and "--tailbox(bg)" may be replaced by a minus sign ("-"). In this case stdin is used as the input file, which allow to pipe data to Xdialog. - The infobox now accepts an optional <timeout> parameter (the default is 1000 and will make the infobox to vanish after one second) and no more waits forever for the "OK" button to be pressed (this makes infobox behave much more closer to the "(c)dialog" infobox). When timeout is set to 0, then infobox behaves differently: - The "OK" button is replaced by a "Cancel" button (unless the --no-button option is given, in which case no button will be set up). - It accepts messages from stdin (much in the same way as the gauge widget). These messages may be "XXXX" (in which case the infobox is closed) or new <text> enclosed by "XXX" markers; as for the gauge widget, newlines can be inserted into the <text> (see below). - It waits until the "Cancel" button is pressed, or the "XXXX" message is received, or the stdin put at EOF. - The "guage" widget has been properly renamed into "gauge" (but "guage" is still recognized for compatibility reasons). It does now behave much like the dialog gauge (it accepts percentage values on stdin as well as new <text> enclosed by two "XXX" markers; a newline can be inserted into the new <text> by isuing echo "\\n" between each line). Note that the <percent> parameter (which represents the initial gauge position) is now optional and defaults to 0. - "--menu" has been renamed as "--menubox" but you still may use "--menu" because abreviated options are allowed. - The tailbox widget is displayed as soon as Xdialog is invoked (it used to appear only once 1024 characters were read from the input file). - A new "--fselect" box option is implemented (GTK file selector). Using the "--no-button" transient option with "--fselect" prevents the "New directory", "Delete file" and "Rename file" buttons to be displayed in the file selector. The "--help" option is allowed and makes a help button to appear even if the "--no-buttons" option was specified. Note that the --backtitle option is ignored by fselect. - A new "--dselect" box option is implemented (GTK directory selector). This box has the same behaviour as the file selector (see above). - A new "--editbox" option is implemented. It takes the same parameters as the textbox but allows to edit the text and returns the edited text (after "OK" is pressed) on Xdialog output stream (i.e. stderr unless "--stdout" is in force). - A new "--rangebox" option is implemented. It takes a <text> parameter together with a <min value>, a <max value> and an optional <default value> and displays the text together with a horizontal slider allowing to set a value that will be returned (printed to Xdialog output stream) by Xdialog. When the <default value> parameter is omitted, the default value is set to the <min value>. - A new "--calendar" option is implemented. It takes a <text> parameter together with <day> (1 to 31) <month>, (1 to 12) and <year> (1970 and more) parameters and returns the user-selected date (in the form DD/MM/YYYY). any of <day>, <month> or <year> parameter may be given a value of 0 so that the current day, month or year is used as default. - A new "--timebox" option is implemented. It takes a <text> parameter and returns the user-set time (in the form HH:MM:SS). - "--left", "--right", "--center", "--wrap" and "--no-wrap" common options have been added so to instruct Xdialog to justify the text left, right or centered and/or to wrap (or not) long lines (line wrapping also apply to the "back-title" line). Default is --center --no-wrap. - "--fixed-font" transient option added. This allows to use a monospacing font in the text area of tailbox, textbox and editbox widgets. - "--screen-center" (default), "--under-mouse" and "--auto-placement" common options added so to control the Xdialog widgets placement. - If the back-title line is empty (no --backtitle option in the command line), then it will not be displayed (Xdialog v1.0 used to display a "Cyberone -" line in this case). - "--no-cancel" and "--no-buttons" options added. The "--no-cancel" option allows to suppress the "Cancel" button from all but the infobox, gauge and fselect widgets. The "--no-buttons" option allows to suppress all the "OK", the "Cancel", the "Help" and the "Print" buttons from the tailbox(bg), textbox and infobox widgets, as well as the "New directory", "Delete file" and "Rename file" buttons from the fselect widget. Note that these options are transient ones and only apply to the next <Box option> listed in the command line. - A new "--help" transient option has been added. This option is to be followed by the help text that will be displayed (in a msgbox) when the "Help" button is chosen. All widgets but the "gauge" and "fselect" ones got the help feature implemented. The <help> text following "--help" may hold "\n" (as for the <text> parameter) so to force help text line splitting. - A new "--print" transient option has been added. It makes a "Print" button to appear in textbox, editbox and tailbox widgets (provided that the --no-button option was not specified). Hitting the button will make Xdialog to issue a printing command defined at compile time, defaulting to "lpr -P <printer> /tmp/Xdialog.tmp". The <printer> parameter (that must follow the "--print" option) gives the name of the printer to use. The "/tmp/Xdialog.tmp" file is a temporary file used by Xdialog and is deleted when Xdialog terminates. To see what printing command is used by your version of Xdialog, just invoke "Xdialog" (without parameter) and look at the last lines in the displayed usage. - A new "--buttons-style" common option has been added. It must be followed by a parameter (the style name, case sensitive !) which must be either "default" (both icon and text in each button), "icon" (icon only in each button) or "text" (text only in each button). - New "--stderr" and "--stdout" options added. The default behaviour of Xdialog is to mimic (c)dialog and send all its results to stderr. This may sometimes be inapropriate and you may want to get separate output (one for the true errors/warnings and one for the result). This is why the "--stdout" common option was implemented: it makes Xdialog to output all the widgets results to stdout instead of stderr. The "--stderr" common option is there so that you can revert to the default stderr output in a chained dialogs command line. - New "--wmclass" common option added. This option allows to set the window manager class name for Xdialog so that its window may be differenciated and decorated differently from other applications windows. This, of course, will depend on your window manager features... This also allows to use different decorations for different scripts using Xdialog. The --wmclass option must be followed by a <name> (the wmclass name of Xdialog then becomes <name>/<name>). - New "--rc-file" common option added. This allows to change the GTK+ theme for the following box options into the Xdialog command line. This option must be followed by the name of a file in the gtkrc format. - New "--icon" transient option added. This option must be followed by the filename of an icon (in XPM format only). This icon will be displayed on the left of the <text> (provided the following box option accepts such a <text> parameter). If the filename does not corresponds to a XPM image, the option will be ignored. - New "--version" special option added. This option makes Xdialog to prints its version number to stderr and to exit. This is useful to check from a script if the installed version of Xdialog is able to use some of the latest widgets that have been implemented since Xdialog exists... - When the Xdialog window is closed via the window manager, an exit code of 255 is now returned (same exit code as for the (c)dialog ESC event). 255 is also returned when an error occured (bad options or parameters, GUI initialisation failure) in Xdialog. Two new common options have been implemented: "--no-close" that prevents the dialogs to be closed with the window manager close button and "--allow-close" allowing to revert to default behaviour of allowing the window manager to close the dialogs. - The Xdialog usage while still printed to stderr is now also displayed into a textbox. - Xdialog may be compiled so to use french buttons labels (by passing the --with-french-labels options to the "configure" script). 3.- Distribution changes: ~~~~~~~~~~~~~~~~~~~~ - Examples of how to use Xdialog are given into the "samples" directory (many of these examples are adapted from the "cdialog" ones). - Xdialog.spec added into the tarball. - Added a FAQ. The new usage for Xdialog v1.4.6 is therefore: Usage: Xdialog <Common options> <Transient options> <Box options> Common options: [--wmclass <name>] [--rc-file <gtkrc filename>] [--backtitle <backtitle>] [--title <title>] [--allow-close | --no-close] [--screen-center | --under-mouse | --auto-placement] [--center | --right | --left] [--no-wrap | --wrap] [--stderr | --stdout] [--buttons-style default|icon|text] Transient options: [--fixed-font] [--password] [--no-tags] [--icon <xpm filename>] [--no-cancel] [--no-buttons] [--help <help>] [--print <printer>] (1) Box options: --yesno <text> <height> <width> --msgbox <text> <height> <width> --infobox <text> <height> <width> [<timeout>] --inputbox <text> <height> <width> [<init>] --rangebox <text> <height> <width> <min value> <max value> [<default value>] --textbox <file> <height> <width> --editbox <file> <height> <width> --menubox <text> <height> <width> <menu height (1)> <tag1> <item1>... --checklist <text> <height> <width> <list height (1)> <tag1> <item1> <status1>... --radiolist <text> <height> <width> <list height (1)> <tag1> <item1> <status1>... --treeview <text> <height> <width> <list height (1)> <tag1> <item1> <status1> <item_depth1>... --gauge <text> <height> <width> [<percent>] --tailbox <file> <height> <width> --tailboxbg <file> <height> <width> --fselect <file> <height> <width> --dselect <directory> <height> <width> --calendar <text> <height> <width> <day> <month> <year> --timebox <text> <height> <width> Special option: --version (prints version number to stderr and exits). (1) this parameter is actually ignored by Xdialog and kept for backward compatibility only.
