As was briefly explained last time, all dialog box commands can optionally include an identifier. For illustrative purposes, I've used the form .Identifier or DialogName.Identifier in all of the following examples. However, in your own macros, you do not actually have to use the words "DialogName" or ".Identifier." "DialogName" should be whatever the name of your dialog is, as given as the first half of the relevant Dim statement following End Dialog. (Thus, Dim GetNewText As Dialog1 means you would use GetNewText instead of DialogName.) "Identifier" can be any word or combination of letters and numbers you can think of, as long as it is preceded by a period and is not the same as any other identifier in the same dialog box.

A dialog box with some plain text and an "OK" 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 numbers that indicate coordinates relative to the dialog window (0,0 is the upper left corner of the dialog window); dx, dy are numbers that indicate 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 is an optional identifier you can use later on in the macro to reference whether this button was pushed or not by using DialogName.Identifier. Clicking on a button, any button, automatically closes the dialog window and sends any results to the macro. This was stated earlier, but it bears repeating: 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 continue on to the rest of the macro!

ButtonGroup .Identifier

ButtonGroup defines a set of buttons for use by the dialog. Later on the macro, DialogName.Identifier 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", .Identifier

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.Identifier will equal 0 if the box is unchecked and 1 if it is checked.
Apples

ComboBox x, y, dx, dy, text$, .Identifier
DropComboBox x, y, dx, dy, text$, .Identifier

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.]

apples oranges pears

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 appearing 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.Identifier will be a string containing the selection or whatever the user typed.

DropListBox x, y, dx, dy, text$, .Identifier

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.

apples oranges pears

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 appearing 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.Identifier 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$, .Identifier

A ListBox gives the user a selection of choices, which looks something like this:

apples oranges pears

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.

  text$ = "apples" & Chr(9) & "oranges" & Chr(9) & "pears"

  text$(0) = "apples"
  text$(1) = "oranges"
  text$(2) = "pears"

After the dialog box has been closed, DialogName.Identifier will reflect the choice made--DialogName.Identifier equals 0 if the first is chosen, it equals 1 if the second is chosen, 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$, .Identifier

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, this code fragment

  OptionGroup .Identifier
    OptionButton 16, 12, 46, 12, "&Grapes"
    OptionButton 16, 28, 67, 8, "Grape&fruit"

will display something roughly like this

Grapes
Grapefruit

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 on this web page.]

OptionGroup .Identifier

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.Identifier 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$, .Identifier

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, .Identifier

Creates a box in which users can type in whatever they want. Later statements in the macro can reference the entered text by using DialogName.Identifier. 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.