2 dialog - Display dialog boxes in shell script (version 0.3)
3 ===========================================================
5 This is a program that will enable you to present a variety of questions or
6 display messages using dialog boxes from a shell script. Currently, these
7 types of dialog boxes are implemented: yes/no box, menu box, input box,
8 message box, text box, info box, checklist box. The idea of writing this
9 program came from the fact that most questions asked in a shell script (and
10 many interactive programs as well) can be classified into these few types:
13 1) One that requires the user to answer either yes or no.
15 2) One that presents a number of options for the user to choose.
17 3) One that requires the user to input a string.
19 4) One that displays a message and optionally wait for a key press
22 5) One that presents a list of options that can be turned on or off.
25 The program 'dialog' can, say for example, be called in a shell script to
26 present the first type of questions like this:
29 if dialog --yesno <question text> <height> <width>
35 e.g. if dialog --yesno "Do you want to continue?" 7 51
43 I've included a sample shell script for each type of boxes in the directory
44 samples. The program requires ncurses to compile. Running 'dialog' without
45 arguments will display the usage.
52 * Friendly dialog box interface with buttons, etc.
54 * Auto wrap around of question text if it's too long to fit on
57 * "\n" can be inserted in question text to control line breaking
58 explicitly. The real newline character '\n' can also be used.
60 * run-time configruation of color settings and other options using
65 WHAT'S NEW SINCE VERSION 0.21?
66 ------------------------------
68 * some changes for faster screen update.
70 * much more flexible color settings. Can use all 16 colors
71 (8 normal, 8 highlight) of the Linux console.
73 * added run-time configuration using configuration file.
75 * some minor bug fixes and cleanups for menubox, checklist and
80 * some changes for easier porting to other Unix systems (tested
81 on Ultrix, SunOS and HPUX)
90 2. Go to step 3 if your system has ncurses (e.g. Linux).
91 Edit Makefile and remove -DHAVE_NCURSES from DEFS. Also
92 remove rc.c from SRCS and rc.o from OBJS. Change LIBS as
93 appropriate (Usually, it should be '-lcurses -ltermcap').
96 3. Edit Makefile and remove -DBROKEN_WSCRL from DEFS if you
97 are using ncurses 1.8.3 or newer. Menu scrolling should
98 be faster. DON'T REMOVE IT IF YOU ARE NOT USING AT LEAST
99 VERSION 1.8.3 OF NCURSES.
101 4. Edit dialog.h and change USE_SHADOW to FALSE if you don't
102 want shadowed dialog boxes. Also change USE_COLORS to
103 FALSE if you don't want colors. Note that 'dialog' will
104 check if the terminal supports colors, and will use mono
105 settings if it doesn't, so USE_COLORS won't do any harm
106 even if you have a mono display. Also note that USE_SHADOW
107 implies USE_COLORS. These two options can be changed at
108 run-time using the run-time configuration file (see below).
110 5. Edit colors.h to change default color definitions if you
111 don't like the defaults. These are only compiled in defaults,
112 you can change them at run-time using the run-time
115 6. 'make depend; make install' will compile and install the
116 binaries in /usr/local/bin (change BINDIR in Makefile if
117 you want to install elsewhere).
119 7. 'make install.man' will install the man page to
120 /usr/local/man (change MANDIR in Makefile if you want to
123 8. You can then try the sample shell scripts in the samples
124 directory (make sure the environment variable DIALOG is
125 not set, the scripts use it to find the dialog binary, if
126 it's not set, "../src/dialog" will be used).
128 9. Don't forget to mail me (mail address at end of this file)
129 if you find any bugs, have some good color settings to
130 contribute or just want to tell me that you like it, Don't
131 mail me if you don't like it :-)
135 RUN-TIME CONFIGURATION
136 ----------------------
138 1. Create a sample configuration file by typing:
140 "dialog --create-rc <file>"
142 2. At start, 'dialog' determines the settings to use as follows:
144 a) if environment variable DIALOGRC is set, it's value
145 determines the name of the configuration file.
147 b) if the file in (a) can't be found, use the file
148 $HOME/.dialogrc as the configuration file.
150 c) if the file in (b) can't be found, use compiled in
153 3. Edit the sample configuration file and copy it to some place
154 that 'dialog' can find, as stated in step 2 above.
159 Comments and bug reports welcome.
161 - Savio Lam (lam836@cs.cuhk.hk)