Xdialog(1)

1Xdialog(1)                         X11/tool                         Xdialog(1)
2
3
4

NAME

6       Xdialog - (c)dialog replacement for X-Windows
7

SYNTAX

9       Xdialog [<common options>] [<transient options>] <box option> ...
10
11       and:
12
13       Xdialog <special option>
14

DESCRIPTION

16       Xdialog is designed to be a drop in replacement for the dialog and cdi‐
17       alog programs (BTW Xdialog may also be used in place  of  gdialog).  It
18       converts  any  terminal  based program into a program with an X-windows
19       interface. The dialogs are easier to see and use, and the  new  widgets
20       adds even more functionality.
21
22       To achieve this, Xdialog uses the Gimp ToolKit (also known as GTK+).
23

OPTIONS

25       The  [<common options>] [<transient options>] <box option> sequence may
26       be repeated several times in the same Xdialog  command  line  (this  is
27       called  dialog  chaining).  The common/transient options may be omitted
28       but there must always be a box option as the last Xdialog option.
29
30       Common options:
31
32       The <common  options>  are  options  applying  to  all  following  <box
33       options>  until  the  same or opposite <common options> are encountered
34       into the Xdialog command line. These options are  mostly  dealing  with
35       menu look, style, placement and behaviour.
36
37       Available common options:
38
39       --wmclass <name>
40
41       --rc-file <gtkrc filename>
42
43       --backtitle <backtitle>
44
45       --title <title>
46
47       --allow-close | --no-close
48
49       --screen-center | --under-mouse | --auto-placement
50
51       --center | --right | --left | --fill
52
53       --no-wrap | --wrap
54
55       --cr-wrap | --no-cr-wrap
56
57       --stderr | --stdout
58
59       --separator <character> | --separate-output
60
61       --buttons-style default|icon|text
62
63       Transient options:
64
65       The  <transient  options>  only apply to the next <box option> into the
66       Xdialog command line. These options are used to tune the widgets  (num‐
67       ber  and  type of buttons, menu icon) or to trigger some of the widgets
68       specific features.
69
70       Available transient options:
71
72       --fixed-font
73
74              This option is for use with --tailbox, --textbox and --editbox.
75
76       --password | --password=1|2
77
78              This option may be repeated 2 or 3 times before --2inputsbox  or
79              --3inputsbox.  It is also possible to specify one (and only one)
80              password field with the --password=1|2 syntax.
81
82       --editable
83
84              This option is for use with --combobox.
85
86       --time-stamp | --date-stamp
87
88              This option is for use with --logbox.
89
90       --reverse
91
92              This option is for use with --logbox.
93
94       --keep-colors
95
96              This option is for use with --logbox.
97
98       --interval <timeout>
99
100              This option may be used with input(s) boxes, combo box, range(s)
101              boxes,  spin(s)  boxes, list boxes, menu box, treeview, calendar
102              and timebox widgets.
103
104       --timeout <timeout> (in seconds)
105
106              This option may be used with all but infobox, gauge and progress
107              widgets.
108
109       --no-tags
110
111              This  option  is for use with --menubox, --checklist and --radi‐
112              olist.
113
114       --item-help
115
116              When  this  option  is  used,  the  <helpN>  parameters  of  the
117              --menubox,  --checklist, --radiolist, --buildlist and --treeview
118              options must  be  specified  (while  they  must  be  omitted  if
119              --item-help is not specified).
120
121       --default-item <tag>
122
123              This option is for use with --menubox.
124
125       --icon <xpm filename>
126
127              This option is for use with any widget accepting a <text> param‐
128              eter.
129
130       --no-ok
131
132              This option is for use with --tailbox and --logbox.
133
134       --no-cancel
135
136              This option may be used with  all  but  --infobox,  --gauge  and
137              --progress.
138
139       --no-buttons
140
141              This  option  may  be  used with --textbox, --tailbox, --logbox,
142              --infobox, --fselect and --dselect.
143
144       --default-no
145
146              This option may be used with all widgets with a "Cancel" or "No"
147              button.  Note  that it is ignored when the --wizard option is in
148              force.
149
150       --wizard
151
152              This option may  be  used  with  all  but  --msgbox,  --infobox,
153              --gauge and --progress.
154
155       --help <help>
156
157              This  option  may  be  used  with all but --infobox, --gauge and
158              --progress.
159
160       --print <printer>
161
162              This option is for use with --tailbox, --textbox and --editbox.
163
164       --check <label> [<status>]
165
166              This option may be used with  all  but  --infobox,  --gauge  and
167              --progress.
168
169       --ok-label <label>
170
171              This  option  may  be used with all widgets with a "OK" or "Yes"
172              button. Note that it is ignored when the --wizard option  is  in
173              force.
174
175       --cancel-label <label>
176
177              This option may be used with all widgets with a "Cancel" or "No"
178              button. Note that it is ignored when the --wizard option  is  in
179              force.
180
181       --beep
182
183              This option may be used with all widgets.
184
185       --beep-after
186
187              This option may be used with all widgets.
188
189       --begin <Yorg> <Xorg>
190
191              This option may be used with all widgets.
192
193       --ignore-eof
194
195              This option may be used with --infobox and --gauge.
196
197       --smooth
198
199              This option is for use with --tailbox and --logbox.
200
201       Box options:
202
203       The <box option> tells to Xdialog which widget must be used and is fol‐
204       lowed by three or more parameters:
205
206              the first parameter is a text string or a filename (this depends
207              on the box option);
208
209              the  second  and  the  third  parameters  are  menu <height> and
210              <width> in characters. These two parameters may be replaced by a
211              single  <XSIZExYSIZE>  parameter, giving the width and height in
212              pixels. When a size of 0 0 (or 0x0) is passed to  Xdialog,  then
213              the  widget  is  auto-sized  by  GTK+.  When a size of -1 -1 (or
214              -1x-1) is passed, then the Xdialog widget is set to the  maximum
215              size  so to fit the screen. It is possible to give the widget an
216              absolute origin on the screen (provided your window manager lets
217              you  do  so), either by using the --begin transient option (when
218              the size is given in characters) or by using a  "-geometry"-like
219              origin (e.g. 400x200+20-30).
220
221              some  box  options  require  additional parameters such as tags,
222              menu items, labels or default values.
223
224       Available box options:
225
226       --yesno        <text> <height> <width>
227
228       --msgbox       <text> <height> <width>
229
230       --infobox      <text> <height> <width> [<timeout>]
231
232       --gauge        <text> <height> <width> [<percent>]
233
234       --progress     <text> <height> <width> [<maxdots> [[-]<msglen>]]
235
236       --inputbox     <text> <height> <width> [<init>]
237
238       --2inputsbox   <text>  <height>  <width>  <label1>   <init1>   <label2>
239       <init2>
240
241       --3inputsbox   <text>   <height>   <width>  <label1>  <init1>  <label2>
242       <init2> <label3> <init3>
243
244       --combobox     <text> <height> <width> <item1> ... <itemN>
245
246       --rangebox     <text>  <height>  <width>  <min   value>   <max   value>
247       [<default value>]
248
249       --2rangesbox   <text>  <height>  <width>  <label1> <min1> <max1> <def1>
250       <label2> <min2> <max2> <def2>
251
252       --3rangesbox   <text> <height> <width> <label1>  <min1>  <max1>  <def1>
253       <label2> <min2> <max2> <def2> <label3> <min3> <max3> <def3>
254
255       --spinbox      <text> <height> <width> <min> <max> <def> <label>
256
257       --2spinsbox    <text>  <height>  <width>  <min1> <max1> <def1> <label1>
258       <min2> <max2> <def2> <label2>
259
260       --3spinsbox    <text> <height> <width> <min1>  <max1>  <def1>  <label1>
261       <min2> <max2> <def2> <label2> <min3> <max3> <def3> <label3>
262
263       --textbox      <file> <height> <width>
264
265       --editbox      <file> <height> <width>
266
267       --tailbox      <file> <height> <width>
268
269       --logbox       <file> <height> <width>
270
271       --menubox      <text>  <height>  <width>  <menu  height> <tag1> <item1>
272       {<help1>}...
273
274       --checklist    <text> <height> <width>  <list  height>  <tag1>  <item1>
275       <status1> {<help1>}...
276
277       --radiolist    <text>  <height>  <width>  <list  height> <tag1> <item1>
278       <status1> {<help1>}...
279
280       --buildlist    <text> <height> <width>  <list  height>  <tag1>  <item1>
281       <status1> {<help1>}...
282
283       --treeview     <text>  <height>  <width>  <list  height> <tag1> <item1>
284       <status1> <item_depth1> {<help1>}...
285
286       --fselect      <file> <height> <width>
287
288       --dselect      <directory> <height> <width>
289
290       --colorsel     <text> <height> <width> [<red> <green> <blue>]
291
292       --fontsel      <font name> <height> <width>
293
294       --calendar     <text> <height> <width> [<day> <month> <year>]
295
296       --timebox      <text> <height> <width> [<hours> <minutes> <seconds>]
297
298       Special options:
299
300       The <special options> take no parameter and are to be used  alone  into
301       the  command  line.  They just make Xdialog to print a string on stderr
302       and to exit immediately (with a 0 exit code).
303
304       Available special options:
305
306       --version           (prints version number to stderr and exits).
307
308       --print-version     (same as above in a cdialog-compatible way).
309
310       --print-maxsize     (prints maximum menu size in characters and exits).
311

DIAGNOSTICS

313       On completion of each box option (i.e. every time a widget  is  closed)
314       Xdialog  sends  any  result  (text,  numbers) as one or more strings to
315       stderr (this can be changed so that the  results  are  sent  to  stdout
316       thanks to a common option).
317
318       When  Xdialog terminates (i.e. when all the <box options> are processed
319       or when an error occurs), the exit code may take the following values:
320
321       0 : OK, Yes or Next button pressed.
322
323       1 : Cancel or No button pressed.
324
325       2 : Help button pressed (when the --help transient option was passed an
326       empty string).
327
328       3 : Previous button pressed (--wizard transient option in force).
329
330       255 : an error (or timeout) occurred, or the box was closed through the
331       window manager (same exit code as  when  the  ESC  key  is  pressed  in
332       (c)dialog).
333
334       Note that when chaining dialogs, the chain is broken and Xdialog termi‐
335       nates as soon as a widget returns a non zero exit code.
336

FILES

338       /usr/bin/Xdialog
339       /usr/share/locale/*/LC_MESSAGES/Xdialog.mo
340       /usr/share/man/man1/Xdialog.1*
341       /usr/share/doc/xdialog-2.3.1/*
342       /usr/share/doc/xdialog-2.3.1/samples/*
343

ENVIRONMENT VARIABLES

345       XDIALOG_HIGH_DIALOG_COMPAT
346
347              When set to 1 or true (case insensitive), this environment vari‐
348              able  turns  the  (c)dialog  high compatibility mode on. The net
349              effect is that:
350
351              - a fixed (monospacing) font is  used  in  all  Xdialog  widgets
352              (including labels, tags, menu/list items and buttons);
353
354              -  the --left common option is used as the default justification
355              option instead of the --center one;
356
357              - the <text> wrapping is always in force (--wrap) and the --fill
358              option is ignored.
359
360              -  the --no-cr-wrap common option is used as the default instead
361              of the --cr-wrap one (but it does not apply to  the  <backtitle>
362              in this case).
363
364              -  regardless of the specified box size, the auto-sizing feature
365              of Xdialog is  forced  when  XDIALOG_FORCE_AUTOSIZE  environment
366              variable is set it to 1 or true. This makes for the sizing prob‐
367              lems of some menus (e.g. when the specified box size is actually
368              too small for the number of specified menu/list entries to fit).
369
370              -  the  Cancel  button  is  not  displayed  into the tailbox and
371              textbox widgets;
372
373              - the infobox widget is turned into a msgbox  unless  the  XDIA‐
374              LOG_INFOBOX_TIMEOUT environment variable is set (in 1/1000s) and
375              greater than 0, in which case an actual infobox  without  button
376              is used;
377
378              -  the  --version  special  option  returns  the  same string as
379              --print-version.
380
381       XDIALOG_FORCE_AUTOSIZE
382       XDIALOG_INFOBOX_TIMEOUT
383
384              See the notes about XDIALOG_HIGH_DIALOG_COMPAT above.
385
386       XDIALOG_NO_GMSGS
387
388              Setting this variable to 1 will prevent the Gdk,  GLib  and  Gtk
389              library from emitting messages via g_log().
390

EXAMPLES

392       Sample  scripts  are available in the /usr/share/doc/xdialog-2.3.1/sam‐
393       ples/ directory.
394       Full HTML doc with screen shots, examples and FAQ is available  in  the
395       /usr/share/doc/xdialog-2.3.1/ directory.
396

AUTHORS

398       Thierry Godefroy <xdialog@free.fr> (from v1.1.0 onwards)
399       Alfred Reynolds <alfred@cyberone.com.au> (v1.0 only)
400