.\" The following gives the manual page for "dialog", hacked for the COHERENT
.\" "Lexicon" format by fwb, 4/13/94.  Took the opportunity to clarify some
.\" obscure text, fix minor fluffs in grammar and spelling, and change
.\" spelling and formatting conventions to suit the MWC style.
.\"
.TH dialog "" "" "Command"
.PC "Display dialog boxes from shell scripts"
\fBdialog --clear\fR
.br
\fBdialog --create-rc \fIfile\fR
.br
\fBdialog [\-\-title \fItitle\^\fB] [\-\-clear] \fIbox-options\fR
.PP
The command
.B dialog
lets you use dialogue boxes from within a shell script.
A dialogue box can present a message and accept input from the user.
The user's
input can be in the form of buttons that she selects with the arrow keys;
text that she types into a field; or an item she select from a menu.
At present,
.B dialog
implements the following of dialog boxes:
.DS
.B
	checklist
	info
	input
	menu
	message
	text
	yes/no
.R
.DE
.PP
Each is discussed in detail below.
.SH "Command-line Options"
.B dialog
recognizes the following command-line options:
.IP \fB\-\-clear\fR
Clear the screen upon exit.
.IP "\fB\-\-create-rc \fIfile\fR"
Because
.B dialog
supports run-time configuration, you can use this feature
to dump a sample configuration file into
.IR file .
.IP "\fB\-\-title \fItitle\fR"
Display
.I title
at the top of the dialogue box.
.PP
The following options control the type of box being displayed:
.IP "\fB\-\-yesno \fItext height width\fR"
Create a yes/no dialogue box.
.I height
and
.I width
give, respectively, the height and width of the box, in characters.
.I text
is displayed within the box.
If it is too long to fit within one line,
.B dialog
automatically divides into multiple lines at word breaks.
.I text
string can contain the sub-string `\en', which marks the point at
which you want
.I text
to be broken.
.IP
This dialogue box is useful for asking questions that require
the user to answer either yes or no.
It contains two buttons, labelled
.B Yes
and
.BR No .
The user can switch between them by pressing the
.B <tab>
.BR key ;
by pressing \*(RT, she selects the button that is highlighted.
.B dialog
returns zero if the user selected ``Yes'', one if she selected ``No'', and
255 if she pressed
.K Esc
to abort entry.
.IP "\fB\-\-msgbox \fItext height width\fR"
A message box resembles a yes/no box.
They differ only in that the former has only a single
.B OK
button.
.IP
You can use dialogue box to display a message.
After reading the message, the user presses \*(RT;
.B dialog
then exits.
.B dialog
returns zero to the shell if the user pressed \*(RT; it returns 255 if she
pressed
.K Esc
to abort entry.
.IP "\fB\-\-infobox \fItext height width\fR"
An ``info'' box basically is a message box; however
.B dialog
exits immediately after displaying the message to the user.
It does not clear the screen upon exiting,
so the message remains on the screen until the calling
shell script clears it.
The shell can also call
.B sleep
after it displays the message box, to keep the message on the screen
for a set number of seconds.
.IP
This is useful when you want to inform
the user that some operations are carrying on that may require some
time to finish, or if you wish to warn the user of a problem.
.IP
After it displays an info box,
.B dialog
does not return a meaningful value to the shell.
.IP "\fB\-\-inputbox \fItext height width\fR"
An ``input'' box displays
.I text
and then asks the user to type a reply into a field within the box.
The user can type
.B <backspace>
to correct any errors she makes while typing.
If the input string is too long to fit into the dialogue box,
.B dialog
automatically scrolls the input field.
.IP
The box displays two buttons, one labelled
.B Ok
and the other labelled
.BR Cancel .
The user can jump from the input field to the
buttons by pressing \*(DA.
The user can jump from one button to the other by pressing either the
\*(LA or \*(RA keys, or by pressing the
.B <tab>
key.
To return to the input field, the user must press \*(UA.
.IP
Upon exit,
.B dialog
writes the contents of the input field to the standard error.
It returns zero to the shell if the user pressed the
.B Ok
button; however, it returns one if she pressed the
.B Cancel
button, and it returns 255 if she pressed
.K Esc
to abort entry.
.IP "\fB\-\-textbox \fIfile height width\fR"
A ``text'' box displays the contents of a text file in a
dialogue box.
It is like a simple text-file viewer.
The user can move through the file by pressing the keys \*(UA, \*(DA,
.Kr Page_Up ,
.Kr Page_Down ,
.Kr Home ,
and
.Kr End .
If a line is too long to fit into the box, the user can press the keys
\*(LA or \*(RA
to scroll the text region horizontally.
Forward- and backward-searching functions are also provided.
.IP
Pressing \*(RT selects the
.B Ok
button at the bottom of the box, and ends the viewing session.
.B dialog
returns zero to the shell if the user pressed
.BR Ok ;
it returns 255 if she pressed
.K Esc
to abort viewing.
.IP "\fB\-\-menu \fItext height width menu-height \fB[\fItag item \fB] \fI...\fR"
As its name suggests, a ``menu'' box presents a list of choices,
from which the user can choose one.
Each menu entry consists of a
.I tag
string and an
.I item
string.
The
.I tag
names the entry; this name must be unique among all entries in the menu.
.I item
is a brief description of the option that that entry represents.
The user can move between the menu entries by pressing \*(UA or \*(DA,
the first letter of the
.IR tag ,
or the number keys
.K 1
through
.Kr 9 .
.IP
The menu can display
.I menu-height
entries at one time.
If the menu contains more than that many entries,
.B dialog
scrolls the menu.
.IP
When
.B dialog
exits, it writes
.I tag
of the chosen menu entry to the standard error.
It returns zero to the shell if the user selected a menu entry; it returns
one if she selected the
.B Cancel
button; and it returns 255 if she pressed
.K Esc
to abort input.
.IP "\fB\-\-checklist \fItext height width list-height \fB[\fItag item status \fB] \fI...\fR"
A ``checklist'' box resembles menu box; however, the user
can select more than one item by turning items off or on.
The initial on/off state of each entry is specified by its
.IR status .
.IP
Upon exit,
.B dialog
writes to the standard error all items that the user left turned on.
It returns zero to the shell if the user exited normally; however, it
returns one if the user pressed the
.B Cancel
button; and it returns 255 if she pressed
.K Esc
to abort input.
.SH "Run-Time Configuration"
The following describes how to create a run-time configuration file for
.BR dialog :
.IP \fB1.\fR 0.3i
Create a sample configuration file by typing:
.DM
	dialog --create-rc \fIfile\fR
.DE
.IP
where
.I file
names the file into which you
.B dialog
to write the prototype configuration.
.IP \fB2.\fR
.B dialog
determines the settings to use as follows:
.RS
.IP \fBa.\fR 0.3i
If environment variable
.B DIALOGRC
is set, its value determines the name of the configuration file.
.IP \fBb.\fR
If the file in (a) cannot be opened, it uses the file
.B $HOME/.dialogrc
as the configuration file.
.IP \fBc.\fR
If the file in (b) cannot be opened,
.B dialog
uses the compiled-in defaults.
.RE
.IP \fB3.\fR
Edit the sample configuration file and copy it to a place that
.B dialog
can find, as stated in step 2 above.
.SH Environment
.B dialog
reads the environmental variable
.BR DIALOGRC ,
which names the configuration file to use.
.SH Files
\fB$HOME/.dialogrc\fR \(em Default configuration file
.SH "See Also"
.B
ksh,
libcurses,
sh
.R
.SH Notes
Text files that contain TAB
characters may cause problems with the
.B text
box.
TAB characters in text files must first be expanded to spaces before being
displayed by the text box.
