Penguin
Recent Changes
Annotated edit history of dialog(1) version 1, including all changes. View license author blame.
Rev Author # Line
1 perry 1 DIALOG
2 !!!DIALOG
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 OPTIONS
7 RUN-TIME CONFIGURATION
8 ENVIRONMENT
9 FILES
10 DIAGNOSTICS
11 BUGS
12 AUTHOR
13 ----
14 !!NAME
15
16
17 dialog - display dialog boxes from shell scripts
18 !!SYNOPSIS
19
20
21 __dialog --clear
22 dialog --create-rc__ ''file''__
23 dialog --print-maxsize
24 dialog__ ''common-options box-options''
25 !!DESCRIPTION
26
27
28 __Dialog__ is a program that will let you to present a
29 variety of questions or display messages using dialog boxes
30 from a shell script. These types of dialog boxes are
31 implemented (though not all are necessarily compiled into
32 __dialog__):
33
34
35 __calendar__, __checklist__, __fselect__,
36 __gauge__, __infobox__, __inputbox__, __menu__,
37 __msgbox__ (message), __password__, __radiolist__,
38 __tailbox__, __tailboxbg__, __textbox__,
39 __timebox__, and __yesno__ (yes/no).
40
41
42 You can put more than one dialog box into a
43 script:
44
45
46 -
47
48
49 Use the __--and-widget__ token to force Dialog to proceed
50 to the next dialog unless you have pressed ESC to cancel,
51 or
52
53
54 -
55
56
57 Simply add the tokens for the next dialog box, making a
58 chain. Dialog stops chaining when the return code from a
59 dialog is nonzero, e.g., Cancel or No.
60 !!OPTIONS
61
62
63 __Common Options__
64
65
66 __--aspect__ ''ratio''
67
68
69 This gives you some control over the box dimensions when
70 using auto sizing (specifying 0 for height and width). It
71 represents width / height. The default is 9, which means 9
72 characters wide to every 1 line high.
73
74
75 __--backtitle__ ''backtitle''
76
77
78 Specifies a ''backtitle'' string to be displayed on the
79 backdrop, at the top of the screen.
80
81
82 __--beep__
83
84
85 Sound the audible alarm each time the screen is
86 refreshed.
87
88
89 __--beep-after__
90
91
92 Beep if input is interrupted, e.g., by a
93 control/C.
94
95
96 __--begin__ ''y x''
97
98
99 Specify the position of the upper left corner of a dialog
100 box on the screen.
101
102
103 __--cancel-label__ ''string''
104
105
106 Override the label used for
107
108
109 __--clear__
110
111
112 The screen will be cleared to the __screen attribute__ on
113 exit. This may be used alone, without other
114 options.
115
116
117 __--cr-wrap__
118
119
120 Interpret embedded newlines in the dialog text as a newline
121 on the screen. Otherwise, __dialog__ will only wrap lines
122 where needed to fit inside the text box. Even though you can
123 control line breaks with this, __dialog__ will still wrap
124 any lines that are too long for the width of the box.
125 Without cr-wrap, the layout of your text may be formatted to
126 look nice in the source code of your script without
127 affecting the way it will look in the dialog.
128
129
130 __--create-rc__ ''file''
131
132
133 When __dialog__ supports run-time configuration, this can
134 be used to dump a sample configuration file to the file
135 specified by ''file''.
136
137
138 __--defaultno__
139
140
141 Make the default value of the __yes/no__ box a
142 __No__.
143
144
145 __--default-item__ ''string''
146
147
148 Set the default item in a menu box. Normally the first item
149 in the box is the default.
150
151
152 __--help__
153
154
155 Prints the help message to standard error. The help message
156 is printed if no options are given.
157
158
159 __--help-button__
160
161
162 Show a help-button after ok/cancel buttons.
163
164
165 __--help-label__ ''string''
166
167
168 Override the label used for
169
170
171 __--ignore__
172
173
174 Ignore options that __dialog__ does not recognize. Some
175 well-known ones such as __--icon__
176 __
177
178
179 __--item-help__
180
181
182 Interpret the tags data for checklist, radiolist and
183 menuboxes adding a column which is displayed in the bottom
184 line of the screen, for the currently selected
185 item.
186
187
188 __--max-input__ ''size''
189
190
191 Limit input strings to the given size. If not specified, the
192 limit is 2000.
193
194
195 __--no-kill__
196
197
198 Tells __dialog__ to put the __tailboxbg__ box in the
199 background, printing its process id to standard error.
200 SIGHUP is disabled for the background process.
201
202
203 __--no-cancel__
204
205
206 __--nocancel__
207
208
209 Suppress the
210
211
212 __--no-shadow__
213
214
215 Suppress shadows that would be drawn to the right and bottom
216 of each dialog box.
217
218
219 __--ok-label__ ''string''
220
221
222 Override the label used for
223
224
225 __--print-maxsize__
226
227
228 Print the maximum size of dialog boxes, i.e., the screen
229 size, to the standard error. This may be used alone, without
230 other options.
231
232
233 __--print-size__
234
235
236 Prints the size of each dialog box to standard
237 error.
238
239
240 __--print-version__
241
242
243 Prints __dialog__'s version to standard error. This may
244 be used alone, without other options.
245
246
247 __--separate-output__
248
249
250 For checklist widgets, output result one line at a time,
251 with no quoting. This facilitates parsing by another
252 program.
253
254
255 __--separate-widget__ ''string''
256
257
258 Specify a string that will separate the output on standard
259 error from each widget. This is used to simplify parsing the
260 result of a dialog with several widgets. If this option is
261 not given, the default separator string is a tab
262 character.
263
264
265 __--shadow__
266
267
268 Draw a shadow to the right and bottom of each dialog
269 box.
270
271
272 __--size-err__
273
274
275 Check the resulting size of a dialog box before trying to
276 use it, printing the resulting size if it is larger than the
277 screen. (This option is obsolete, since all new-window calls
278 are checked).
279
280
281 __--sleep__ ''secs''
282
283
284 Sleep (delay) for the given number of seconds after
285 processing a dialog box.
286
287
288 __--stderr__
289
290
291 Direct output to the standard error. This is the default,
292 since curses normally writes screen updates to the standard
293 output.
294
295
296 __--stdout__
297
298
299 Direct output to the standard output.
300
301
302 __--tab-correct__
303
304
305 Convert each tab character to one or more spaces. Otherwise,
306 tabs are rendered according to the curses library's
307 interpretation.
308
309
310 __--tab-len__ ''n''
311
312
313 Specify the number of spaces that a tab character occupies
314 if the --tab-correct__
315 __
316
317
318 __--timeout__ ''secs''
319
320
321 Timeout (exit with error code) if no user response within
322 the given number of seconds.
323
324
325 __--title__ ''title''
326
327
328 Specifies a ''title'' string to be displayed at the top
329 of the dialog box.
330
331
332 __--trim__
333
334
335 eliminate leading blanks, trim literal newlines and repeated
336 blanks from message text.
337
338
339 __--version__
340
341
342 Same as --print-version____
343
344
345 __Box Options__
346
347
348 All dialog boxes have at least three
349 parameters:
350
351
352 ''text''
353
354
355 the caption or contents of the box.
356
357
358 ''height''
359
360
361 the height of the dialog box.
362
363
364 ''width''
365
366
367 the width of the dialog box.
368
369
370 Other parameters depend on the box type.
371
372
373 __--calendar__ ''text height width day month
374 year''
375
376
377 A __calendar__ box displays month, day and year in
378 separately adjustable windows. If the values for day, month
379 or year are missing or negative, the current date's
380 corresponding values are used. You can increment or
381 decrement any of those using the left-, up-, right- and
382 down-arrows. Use tab or backtab to move between windows. If
383 the year is given as zero, the current date is used as an
384 initial value. On exit, the date is printed in the form
385 day/month/year.
386
387
388 __--checklist__ ''text height width list-height'' [[
389 ''tag item status'' ] ''...''
390
391
392 A __checklist__ box is similar to a __menu__ box;
393 there are multiple entries presented in the form of a menu.
394 Instead of choosing one entry among the entries, each entry
395 can be turned on or off by the user. The initial on/off
396 state of each entry is specified by ''status''. On exit,
397 a list of the ''tag'' strings of those entries that are
398 turned on will be printed on ''stderr''.
399
400
401 __--fselect__ ''filepath height width''
402
403
404 The file-selection dialog displays a text-entry window in
405 which you can type a filename (or directory), and above that
406 two windows with directory names and filenames.
407
408
409 Here __filepath__ can be a filepath in which case the
410 file and directory windows will display the contents of the
411 path and the text-entry window will contain the preselected
412 filename.
413
414
415 Use tab or arrow keys to move between the windows. Within
416 the directory or filename windows, use the up/down arrow
417 keys to scroll the current selection. Use the space-bar to
418 copy the current selection into the text-entry
419 window.
420
421
422 Typing any printable characters switches focus to the
423 text-entry window, entering that character as well as
424 scrolling the directory and filename windows to the closest
425 match.
426
427
428 Use a carriage return or the
429
430
431 __--gauge__ ''text height width
432 [[percent]''
433
434
435 A __gauge__ box displays a meter along the bottom of the
436 box. The meter indicates the percentage. New percentages are
437 read from standard input, one integer per line. The meter is
438 updated to reflect each new percentage. If stdin is XXX,
439 then subsequent lines up to another XXX are used for a new
440 prompt. The gauge exits when EOF is reached on
441 stdin.
442
443
444 The ''percent'' value denotes the initial percentage
445 shown in the meter. If not specified, it is
446 zero.
447
448
449 __--infobox__ ''text height width''
450
451
452 An __info__ box is basically a __message__ box.
453 However, in this case, __dialog__ will exit immediately
454 after displaying the message to the user. The screen is not
455 cleared when __dialog__ exits, so that the message will
456 remain on the screen until the calling shell script clears
457 it later. This is useful when you want to inform the user
458 that some operations are carrying on that may require some
459 time to finish.
460
461
462 __--inputbox__ ''text height width
463 [[init]''
464
465
466 An __input__ box is useful when you want to ask questions
467 that require the user to input a string as the answer. If
468 init is supplied it is used to initialize the input string.
469 When entering the string, the ''BACKSPACE'' key can be
470 used to correct typing errors. If the input string is longer
471 than can fit in the dialog box, the input field will be
472 scrolled. On exit, the input string will be printed on
473 ''stderr''.
474
475
476 __--menu__ ''text height width menu-height'' [[ ''tag
477 item'' ] ''...''
478
479
480 As its name suggests, a __menu__ box is a dialog box that
481 can be used to present a list of choices in the form of a
482 menu for the user to choose. Choices are displayed in the
483 order given. Each menu entry consists of a ''tag'' string
484 and an ''item'' string. The ''tag'' gives the entry a
485 name to distinguish it from the other entries in the menu.
486 The ''item'' is a short description of the option that
487 the entry represents. The user can move between the menu
488 entries by pressing the ''UP/DOWN'' keys, the first
489 letter of the ''tag'' as a hot-key, or the number keys
490 ''1-9''. There are ''menu-height'' entries displayed
491 in the menu at one time, but the menu will be scrolled if
492 there are more entries than that. When __dialog__ exits,
493 the ''tag'' of the chosen menu entry will be printed on
494 ''stderr''. If the __--help-button__ option is given,
495 the corresponding help text will be printed if the user
496 selects the help button.
497
498
499 __--msgbox__ ''text height width''
500
501
502 A __message__ box is very similar to a __yes/no__ box.
503 The only difference between a __message__ box and a
504 __yes/no__ box is that a __message__ box has only a
505 single __OK__ button. You can use this dialog box to
506 display any message you like. After reading the message, the
507 user can press the ''ENTER'' key so that __dialog__
508 will exit and the calling shell script can continue its
509 operation.
510
511
512 __--passwordbox__ ''text height width
513 [[init]''
514
515
516 A __password__ box is similar to an input box, except
517 that the text the user enters is not displayed. This is
518 useful when prompting for passwords or other sensitive
519 information. Be aware that if anything is passed in
520 __
521
522
523 __--radiolist__ ''text height width list-height'' [[
524 ''tag item status'' ] ''...''
525
526
527 A __radiolist__ box is similar to a __menu__ box. The
528 only difference is that you can indicate which entry is
529 currently selected, by setting its ''status'' to
530 ''on''.
531
532
533 __--tailbox file height width__
534
535
536 Display text from a file in a dialog box, as in a
537
538
539 __--tailboxbg file height width__
540
541
542 Display text from a file in a dialog box as a background
543 task, as in a
544
545
546 Dialog treats the background task specially if there are
547 other widgets (__--and-widget__) on the screen
548 concurrently. Until those widgets are closed (e.g., an
549 __ENTER''.
550 Once the non-tailboxbg widgets are closed, dialog forks a
551 copy of itself into the background, and prints its process
552 id if the __--no-kill__ option is given.
553
554
555 NOTE: Older versions of dialog forked immediately and
556 attempted to update the screen individually. Besides being
557 bad for performance, it was unworkable. Some older scripts
558 may not work properly with the polled scheme.
559
560
561 __--textbox file height width__
562
563
564 A __text__ box lets you display the contents of a text
565 file in a dialog box. It is like a simple text file viewer.
566 The user can move through the file by using the
567 ''UP/DOWN'', ''PGUP/PGDN'' and ''HOME/END'' keys
568 available on most keyboards. If the lines are too long to be
569 displayed in the box, the ''LEFT/RIGHT'' keys can be used
570 to scroll the text region horizontally. For more
571 convenience, forward and backward searching functions are
572 also provided.
573
574
575 __--timebox__ ''text height [[width hour minute
576 second]''
577
578
579 A dialog is displayed which allows you to select hour,
580 minute and second. If the values for hour, minute or second
581 are missing or negative, the current date's corresponding
582 values are used. You can increment or decrement any of those
583 using the left-, up-, right- and down-arrows. Use tab or
584 backtab to move between windows. On exit, the result is
585 printed in the form hour:minute:second.
586
587
588 __--yesno__ ''text height width''
589
590
591 A __yes/no__ dialog box of size ''height'' rows by
592 ''width'' columns will be displayed. The string specified
593 by ''text'' is displayed inside the dialog box. If this
594 string is too long to fit in one line, it will be
595 automatically divided into multiple lines at appropriate
596 places. The ''text'' string can also contain the
597 sub-string '''' or newline characters
598 ''`n'' to control line breaking explicitly. This dialog
599 box is useful for asking questions that require the user to
600 answer either yes or no. The dialog box has a __Yes__
601 button and a __No__ button, in which the user can switch
602 between by pressing the ''TAB'' key.
603 !!RUN-TIME CONFIGURATION
604
605
606 1.
607
608
609 Create a sample configuration file by typing:
610
611
612
613
614 2.
615
616
617 At start, __dialog__ determines the settings to use as
618 follows:
619
620
621 a)
622
623
624 if environment variable __DIALOGRC__ is set, its value
625 determines the name of the configuration file.
626
627
628 b)
629
630
631 if the file in (a) is not found, use the file
632 ''$HOME/.dialogrc'' as the configuration
633 file.
634
635
636 c)
637
638
639 if the file in (b) is not found, try using the GLOBALRC file
640 determined at compile-time, i.e.,
641 ''/etc/dialogrc''.
642
643
644 d)
645
646
647 if the file in (c) is not found, use compiled in
648 defaults.
649
650
651 3.
652
653
654 Edit the sample configuration file and copy it to some place
655 that __dialog__ can find, as stated in step 2
656 above.
657 !!ENVIRONMENT
658
659
660 __DIALOGRC__
661
662
663 Define this variable if you want to specify the name of the
664 configuration file to use.
665
666
667 __DIALOG_CANCEL__
668
669
670 __DIALOG_ERROR__
671
672
673 __DIALOG_ESC__
674
675
676 __DIALOG_OK__
677
678
679 Define any of these variables to change the exit code on
680 Cancel (1), error (-1), ESC (255) or Ok (0). Normally shell
681 scripts cannot distinguish between -1 and 255.
682 !!FILES
683
684
685 ''$HOME/.dialogrc''
686
687
688 default configuration file
689 !!DIAGNOSTICS
690
691
692 Exit status is subject to being overridden by environment
693 variables. Normally they are:
694
695
696 0
697
698
699 if __dialog__ is exited by pressing the __Yes__ or
700 __OK__ button.
701
702
703 1
704
705
706 if the __No__ or __Cancel__ button is
707 pressed.
708
709
710 -1
711
712
713 if errors occur inside __dialog__ or __dialog__ is
714 exited by pressing the ''ESC'' key.
715 !!BUGS
716
717
718 Perhaps.
719 !!AUTHOR
720
721
722 Savio Lam (lam836@cs.cuhk.hk) - version 0.3,
723
724
725 Stuart Herbert (S.Herbert@sheffield.ac.uk) - patch for
726 version 0.4
727
728
729 Pako (demarco_p@abramo.it) - version 0.9a,
730
731
732 Thomas Dickey (updates for 0.9b)
733 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.