A dialog box with some plain text and an "Ok" and a "Cancel" button is
the equivalent of a MsgBox. A dialog box with a box for typing data, an
"Ok" button and a "Cancel" button is the equivalent of an InputBox. For
fancier applications, there are several commands that can be included
between the Begin Dialog and End Dialog statements in order to get various
"controls" (like the control knobs and buttons on a radio): boxes,
buttons, text, and the like.
Button x, y, dx, dy, "Text", [.identifier]
PushButton x, y, dx, dy, "Text", [.identifier]
Button and PushButton are synonymous. X, y are coordinates relative
to the dialog window (0,0 is the upper left corner of the dialog window);
dx, dy are the width and height of the button. Otherwise, the four sizing
controls work the same as they do for the Begin Dialog statement. "Text"
is the word(s) that appear on the button, and .identifier (or any other
unique word or combination of characters you can think of; always preceded
by a dot) is an optional identifier you can use later on in the macro to
reference whether this button was pushed or not. Clicking on a button,
any button, automatically closes the dialog window and sends any results
to the macro. Every dialog box must contain at least one button, be it
an OkButton, a CancelButton, or a user-defined Button or PushButton;
otherwise there is no way for the user to exit the dialog box and have the
macro continue!
ButtonGroup .bg
ButtonGroup defines a set of buttons for use by the dialog. Later on
the macro, DialogName.GroupName (in this case .bg) will identify with a
number which button in the group was pushed. The first button in the group
is identified as "1", the second as "2", and so forth.
CancelButton x, y, dx, dy
This creates a "Cancel" button. x, y, dx, and dy work the same as for
Button (and, for that matter, all commands that use such location and
sizing controls inside of a Begin Dialog...End Dialog block.) As
mentioned in the discussion of the Dialog statement above, clicking the
Cancel button either returns a -1 or an error, depending on which format
of the Dialog command is used.
Caption "text"
Caption text$
If you didn't specify one in the Begin Dialog statement, Caption
allows you to set the text in the blue bar at the very top of your dialog
box. As with most instances of strings in commands, you can use plain
text in quotes or use a string which was given a value earlier in the
macro. Thus, the two above forms of the command are equivalent.
CheckBox x, y, dx, dy, "text", .id
This command creates a box which can be checked and un-checked.
Unlike OptionButtons, checking one CheckBox has no effect on any other
checkboxes in the dialog window. DialogName.id will equal 0 if the box is
unchecked and 1 if it is checked.
Apples
ComboBox x, y, dx, dy text$, .id
DropComboBox x, y, dx, dy, text$, .id
These two commands are synonymous. A ComboBox combines a TextBox with
a DropListBox to create a list of choices from which the user can choose
or type in their own; text$ must be defined earlier in the macro, exactly
the way a ListBox works. If the user clicks in the box, a cursor appears
and the user can type anything, just as for a TextBox. [Note: Due to the
limitations of HTML, it is not possible to type anything in the following
box.]
If the user clicks the down arrow, the box drops down. Selecting an item
closes the box back down to normal, with the newly selected item appearning
in the box. The user may then click in the box and edit the selection as
desired. After the dialog window has been closed, DialogName.id will be a
string containing the selection or whatever the user typed.
DropListBox x, y, dx, dy, text$, .id
This is virtually identical to a normal ListBox, except that, unless
the user is active in selecting something from the box, only the selected
item is shown (the first item is the default selection). Note that text$
must be defined earlier, exactly as for a ListBox.
If the user clicks anywhere in the box or on the down arrow, the box
drops down. Selecting a different item or clicking on the arrow box closes
the box back down to normal, with whichever item was highlighted appearning
in the box. Also, if the box is "active", pressing the first letter of an
item brings that item directly into the box. After the dialog window has
been closed, DialogName.id will reflect the choice made--choosing the first
returns a "0", choosing the second returns a "1", and so forth.
GroupBox x, y, dx, dy, text$
This command allows you to draw a line around a section of your dialog
window. If text$ is null (""), then it is a solid line all the way
around; otherwise, the contents of text$ are displayed as part of the top
border of the box formed by the line.
ListBox x, y, dx, dy, text$, .id
A ListBox gives the user a selection of choices, which looks
something
like this:
In this case, "apples", being the first item in the list, is
pre-selected. If the user clicks on another selection or uses the down
arrow on the keyboard to highlight a different one, then the selection box
highlights the new selection. Also, if the box is "active", pressing the
first letter of an item highlights that item.
The text$ element must be defined earlier in the program, and is
usually made up of each element you wish to list, separated by a tab--that
is, chr(9)--or in an array explicitly made up of strings. For the above
example, a line would be needed before the ListBox command along the lines
of either of the following sets of statements.
After the dialog box has been closed, DialogName.id will reflect the
choice made--if the first is chosen, DialogName.id equals 0, if the second
is chosen, it equals 2, and so forth.
OkButton x, y, dx, dy
This command creates an Ok Button. Otherwise, it is functionally
identical to the CancelButton command, except that it does not
automatically generate an error.
OptionButton x, y, dx, dy, text$, .id
Both ListBoxes and OptionButtons allow users to select between a
limited number of choices. Where ListBox does so via a single command, in
which the selected choice is highlighted, OptionButtons are "radio"
buttons, which fill in when they are selected, making all other
OptionButtons blank. OptionButton can only be used after the OptionGroup
command. Each choice requires its own OptionButton command, and if you
are using OptionButtons, at least two must be used. If you want a user to
be able to select an option by typing a letter, put an ampersand before
that letter in text$. For example, the code fragment
In this case, when the macro is running, pressing "f" will change the
selection to "Grapefruit". [Note: Due to the limitations of HTML, this
ability is not possible here.]
OptionGroup .id
OptionGroup defines a group of OptionButton statements; it tells the
computer can tell which radio buttons are linked together, so that it is
possible to have multiple sets of radio buttons in the same window.
DialogName.id will equal 0 if the selection defined by the first
OptionButton statement is selected, 1 if the second is selected, and so
forth.
StaticComboBox x, y, dx, dy, text$, .id
This command is identical to a DropComboBox, except that the list of
choices is always visible.
Text x, y, dx, dy, "text"
The indicated text is printed in the dialog box, beginning at the point
indicated by x & y. Dx and dy are the width and height of the text to be
inserted, and work the same as other dialog statements do.
TextBox x, y, dx, dy, .id
Creates a box in which users can type in whatever they want. Later
statements in the macro can reference it using MacroName.id, where .id is
whatever idenfier you chose for the TextBox. There is no way to use the
TextBox command itself to limit the number of characters typed in, or the
type of letters (such as letters versus numbers), but applying Left$,
Right$, and the like to the inputted text may achieve this effect. The
inputted text is always a string, even if numbers are typed, so the Val
command may be required to change an inputted number from a string value
to a numerical value.
Continue on to part 3 of the lesson...
Return to part 1 of the lesson.
Return to Lesson #11.
Return to Main page.