Dialog function syntax

The syntax for the dialog function is as follows:

Function FunctionName( ControlID$, Action%, SuppValue% )
   Statement Block
   FunctionName = ReturnValue
End Function

A dialog function returns a value when the user chooses a command button. BlueZone Basic acts on the value returned. The default is to return 0 (zero) and close the dialog box. If a non zero is assigned the dialog box remains open. By keeping the dialog box open, the dialog function allows the user to do more than one command from the same dialog box.

Note

All parameters in the dialog function are required.

Parameters

ControlID$

Receives the identifier of the dialog box control.

Action

Identifies the action that calls the dialog function. There are six possibilities, BlueZone Basic supports the first 4:

Action 1

The value passed before the dialog becomes visible.

Action 2

The value passed when an action is taken (for example, a button is pushed, check box is checked, and other actions). The controlID$ is the same as the identifier for the control that was chosen.

Action 3

Corresponds to a change in a text box or combo box. This value is passed when a control loses the focus (for example, when the user presses the TAB key to move to a different control) or after the user clicks an item in the list of a combo box (an Action value of 2 is passed first). Note that if the contents of the text box or combo box do not change, an Action value of 3 is not passed. When Action is 3, ControlID$ corresponds to the identifier for the text box or combo box whose contents were changed.

Action 4

Corresponds to a change of focus. When Action is 4, ControlID$ corresponds to the identifier of the control that is gaining the focus. SuppValue corresponds to the numeric identifier for the control that lost the focus. A Dialog function cannot display a message box or dialog box in response to an Action value of 4.

SuppValue

Receives supplemental information about a change in a dialog box control. The information SuppValue receives depends on which control calls the dialog function. The following SuppValue values are passed when Action is 2 or 3.

Table 5: Passed SuppValue values

Control	SuppValue passed
ListBox, DropListBox, or ComboBox	Number of the item selected where 0 (zero) is the first item in the list box, 1 is the second item, and so on.
CheckBox	1 if selected, 0 (zero) if cleared.
OptionButton	Number of the option button selected, where 0 (zero) is the first option button within a group, 1 is the second option button, and so on.
TextBox	Number of characters in the text box.
ComboBox	If Action is 3, number of characters in the combo box.
CommandButton	A value identifying the button chosen. This value is not often used, since the same information is available from the ControlID$ value.