Scripting Language Elements
BlueZone Basic has support for custom dialogs. The syntax is similar to the syntax used in Microsoft Word Basic. The dialog syntax is not part of Microsoft Visual Basic or Microsoft Visual Basic For Applications (VBA). BlueZone Basic has complete support for dialogs. The type of dialogs supported are outlined below.
BlueZone Basic supports the standard Windows dialog box controls. This section introduces the controls available for custom dialog boxes and provides guidelines for using them.
The Dialog Box syntax begins with the statement Begin Dialog. The first two parameters of this statement are optional. If they are left off the dialog will automatically be centered.
Begin Dialog DialogName1 240, 184, "Test Dialog"
Begin Dialog DialogName1 60, 60,240, 184, "Test Dialog"
Every custom dialog box must contain at least one command button - an OK button or a Cancel button. BlueZone Basic includes separate dialog box definition statements for each of these two types of buttons.
Sub Main
Begin Dialog ButtonSample 16,32,180,96,"OK and Cancel"
OKButton 132,8,40,14
CancelButton 132,28,40,14
End Dialog
Dim Dlg1 As ButtonSample
Button = Dialog (Dlg1)
End Sub
You can use a list box, drop-down list box, or combo box to present a list of items from which the user can select. A drop-down list box saves space (it can drop down to cover other dialog box controls temporarily). A combo box allows the user either to select an item from the list or type in a new item. The items displayed in a list box, drop-down list box, or combo box are stored in an array that is defined before the instructions that define the dialog box.
The following screen shot is was created by the sample code below:
Sample Code:
Sub Main
Dim MyList$ (5)
MyList (0) = "line Item 1"
MyList (1) = "line Item 2"
MyList (2) = "line Item 3"
MyList (3) = "line Item 4"
MyList (4) = "line Item 5"
MyList (5) = "line Item 6"
Begin Dialog BoxSample 16,35,256,89,"List Box, Combo Box, and Drop-Down _
List Box"
OKButton 204,24,40,14
CancelButton 204,44,40,14
ListBox 12,24,48,40, MyList$( ),.Lstbox
DropListBox 124,24,72,40, MyList$( ),.DrpList
ComboBox 68,24,48,40, MyList$( ),.CmboBox
Text 12,12,32,8,"List Box:"
Text 124,12,68,8,"Drop-Down List Box:"
Text 68,12,44,8,"Combo Box:"
End Dialog
Dim Dlg1 As BoxSample
Button = Dialog ( Dlg1 )
End Sub
You use a check box to make a yes or no or on or off choice. For example, you could use a check box to display or hide a toolbar in your application.
Sub Main
Begin Dialog CheckSample15,32,149,96,"Check Boxes"
OKButton 92,8,40,14
CancelButton 92,32,40,14
CheckBox 12,8,45,8,"CheckBox",.CheckBox1
CheckBox 12,24,45,8,"CheckBox",.CheckBox2
CheckBox 12,40,45,8,"CheckBox",.CheckBox3
CheckBox 12,56,45,8,"CheckBox",.CheckBox4
End Dialog
Dim Dlg1 As CheckSample
Button = Dialog ( Dlg1 )
End Sub
A text box control is a box in which the user can enter text while the dialog box is displayed. By default, a text box holds a single line of text. BlueZone Basic supports single and multi-line text boxes. The last parameter of the TextBox function contains a variable to set the TextBox style.
The following screen shot is was created by the sample code below:
Sample code:
Sub Main
Begin Dialog TextBoxSample 16,30,180,96,"Text Boxes and Text"
OKButton 132,20,40,14
CancelButton 132,44,40,14
Text 8,8,32,8,"Text Box:"
TextBox 8,20,100,12,.TextBox1
Text 8,44,84,8,"Multiline Text Box:"
TextBox 8,56,100,32,.TextBox2
End Dialog
Dim Dlg1 As TextBoxSample
Button = Dialog ( Dlg1 )
End Sub
The following is an additional example of how to implement a Multi-line Text Box.
'==========================================================
' This sample shows how to implement a Multi-line Text Box
'==========================================================
' Try these different styles or-ed together as the last
' parameter of the TextBox changes the text box style.
' A 1 in the last parameter position defaults to a Multiline,
' Wantreturn, AutoVScroll text box.
Const ES_LEFT = &h0000&
Const ES_CENTER = &h0001&
Const ES_RIGHT = &h0002&
Const ES_MULTILINE = &h0004&
Const ES_UPPERCASE = &h0008&
Const ES_LOWERCASE = &h0010&
Const ES_PASSWORD = &h0020&
Const ES_AUTOVSCROLL = &h0040&
Const ES_AUTOHSCROLL = &h0080&
Const ES_NOHIDESEL = &h0100&
Const ES_OEMCONVERT = &h0400&
Const ES_READONLY = &h0800&
Const ES_WANTRETURN = &h1000&
Const ES_NUMBER = &h2000&
Sub Multiline
Begin Dialog DialogType 60, 60, 140, 185, "Multiline text Dialog", _
.DlgFunc
TextBox 10, 10, 120, 150, .joe, ES_MULTILINE Or _
ES_AUTOVSCROLL Or _
ES_WANTRETURN ' Indicates Multiline TextBox.
'TextBox 10, 10, 120, 150, .joe, 1 ' Indicates Multiline TextBox.
CancelButton 25, 168, 40, 12
OKButton 75, 168, 40, 12
End Dialog
Dim Dlg1 As DialogType
Dlg1.joe = "The quick brown fox jumped over the lazy dog"
' Dialog returns -1 for OK, 0 for Cancel.
Button = Dialog( Dlg1 )
'MsgBox "button: " & button
If button = 0 Then Exit Sub
MsgBox "TextBox: "& Dlg1.joe
End Sub
You can have option buttons to allow the user to choose one option from several. Typically, you would use a group box to surround a group of option buttons, but you can also use a group box to set off a group of check boxes or any related group of controls.
The following screen shot is was created by the sample code below:
Sample code:
Sub Main
Begin Dialog GroupSample 31,32,185,96,"Option Button and Check Box"
OKButton 28,68,40,14
CancelButton 120,68,40,14
GroupBox 12,12,72,48,"GroupBox",.GroupBox1
GroupBox 100,12,72,48,"GroupBox",.GroupBox2
OptionGroup .OptionGroup1
OptionButton 16,24,54,8,"OptionButton",.OptionButton1
OptionButton 16,40,54,8,"OptionButton",.OptionButton2
CheckBox 108,24,45,8,"CheckBox",.CheckBox1
CheckBox 108,40,45,8,"CheckBox",.CheckBox2
End Dialog
Dim Dlg1 As GroupSample
Button = Dialog (Dlg1)
End Sub
BlueZone Basic supports the dialog function. This function is a user-defined function that can be called while a custom dialog box is displayed. The dialog function makes nested dialog boxes possible and receives messages from the dialog box while it is still active.
When the function dialog() is called in BlueZone Basic, it displays the dialog box, and calls the dialog function for that dialog. BlueZone Basic calls the dialog function to see if there are any commands to execute. Typical commands that might be used are disabling or hiding a control. By default, all dialog box controls are enabled. If you want a control to be hidden you must explicitly make it disabled during initialization. After initialization BlueZone Basic displays the dialog box. When an action is taken by the user, BlueZone Basic calls the dialog function and passes values to the function that indicate the kind of action to take and the control that was acted upon.
The dialog box and its function are connected in the dialog definition. A function name argument is added to the Begin Dialog instruction, and matches the name of the dialog function located in your BlueZone Basic program.
Begin Dialog UserDialog1 60,60, 260, 188, "3", .BlueZone Basic
A dialog function needs an identifier for each dialog box control that it acts on. The dialog function uses string identifiers. String identifiers are the same as the identifiers used in the dialog record.
CheckBox 8, 56, 203, 16, "Check to display controls",. Chk1
The controls identifier and label are different. An identifier begins with a period and is the last parameter in a dialog box control instruction. In the sample code above Check to display controls is the label and Chk1 is the identifier.
The syntax for the dialog function is as follows:
Function FunctionName( ControlID$, Action%, SuppValue% )
Statement Block
FunctionName = ReturnValue
End Function
NOTE
All parameters
in the dialog function are required.
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.
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 ( i.e. a button is pushed, checkbox is checked etc...) 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.
|
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. |
|
Statement or Function |
Action or Result |
|
DlgControlId |
Returns the numeric equivalent of Identifier$, the string identifier for a dialog box control. |
|
DlgEnable, DlgEnable() |
The DlgEnable statement is used to enable or disable a dialog box control. When a control is disabled, it is visible in the dialog box, but is dimmed and not functional. DlgEnable() is used to determine whether or not the control is enabled. |
|
DlgFocus, DlgFocus() |
The DlgFocus statement is used to set the focus on a dialog box control. (When a dialog box control has the focus, it is highlighted.) DlgFocus() returns the identifier of the control that has the focus. |
|
DlgListBoxArray, DlgListBoxArray() |
The DlgListBoxArray statement is used to fill a list box or combo box with the elements of an array. It can be used to change the contents of a list box or combo box while the dialog box is displayed. DlgListBoxArray() returns an item in an array and the number of items in the array. |
|
DlgSetPicture |
The DlgSetPicture statement is used in a dialog function to set the graphic displayed by a picture control. |
|
DlgText, DlgText |
The DlgText statement is used to set the text or text label for a dialog box control. TheDlgText() function returns the label of a control. |
|
DlgValue, DlgValue() |
The DlgValue statement is used to select or clear a dialog box control. Then DlgValue() function returns the setting of a control. |
|
DlgVisible, DlgVisible() |
The DlgVisible statement is used to hide or show a dialog box control. The DlgVisible() function is used to determine whether a control is visible or hidden. |
DlgControlId(Identifier)
Used within a dialog function to return the numeric identifier for the dialog box control specified by Identifier, the string identifier of the dialog box control. Numeric identifiers are numbers, starting at 0 (zero) , that correspond to the positions of the dialog box control instructions within a dialog box definition. For example, consider the following instruction in a dialog box definition:
CheckBox 90, 50, 30, 12, &Update, .MyCheckBox
The instruction DlgControlId(MyCheckBox) returns 0 (zero) if the CheckBox instruction is the first instruction in the dialog box definition, 1 if it is the second, and so on.
In most cases, your dialog functions will perform actions based on the string identifier of the control that was selected.
DlgFocus Identifier
DlgFocus()
The DlgFocus statement is used within a dialog function to set the focus on the dialog box control identified by Identifier while the dialog box is displayed. When a dialog box control has the focus, it is active and responds to keyboard input. For example, if a text box has the focus, any text you type appears in that text box.
The DlgFocus() function returns the string identifier for the dialog box control that currently has the focus.
Example:
This example sets the focus on the control MyControl1 when the dialog box is initially displayed. (The main subroutine that contains the dialog box definition is not shown.)
Function MyDlgFunction( identifier, action, suppvalue )
Select Case action
Case 1 ' The dialog box is displayed
DlgFocus MyControl1
Case 2 ' Statements that perform actions based on which control
' is selected.
End Select
End Function
DlgListBoxArray Identifier, ArrayVariable()
DlgListBoxArray(Identifier, ArrayVariable())
The DlgListBoxArray statement is used within a dialog function to fill a ListBox, DropListBox, or ComboBox with the contents of ArrayVariable() while the dialog box is displayed.
The DlgListBoxArray() function fills ArrayVariable() with the contents of the ListBox, DropListBox, or ComboBox specified by Identifier and returns the number of entries in the ListBox, DropListBox, or ComboBox. The ArrayVariable() parameter is optional (and currently not implemented) with the DlgListBoxArray() function; if ArrayVariable() is omitted, DlgListBoxArray() returns the number of entries in the specified control.
DlgSetPicture Identifier, PictureName
The DlgSetPicture function is used to set the graphic displayed by a picture control in a dialog.
The Identifier is a string or numeric representing the dialog box. The PictureName is a string that identifies the picture to be displayed.
DlgValue Identifier, Value
DlgValue(Identifier)
The DlgValue statement is used in a dialog function to select or clear a dialog box control by setting the numeric value associated with the control specified by Identifier. For example, DlgValue MyCheckBox, 1 selects a check box, DlgValue MyCHeckBox, 0 clears a check box, and DlgValue MyCheckBox, -1 fills the check box with gray. An error occurs if Identifier specifies a dialog box control such as a text box or an option button that cannot be set with a numeric value.
The following dialog function uses a Select Case control structure to check the value of Action. The SuppValue is ignored in this function.
' This sample file outlines dialog capabilities, including nesting
' dialog boxes.
Sub Main
Begin Dialog UserDialog1 60,60, 260, 188, "3", .DlgFunc
Text 8,10,73,13, "Text Label:"
TextBox 8, 26, 160, 18, .FText
CheckBox 8, 56, 203, 16, "Check to display controls",. Chk1
GroupBox 8, 79, 230, 70, "This is a group box:", .Group
CheckBox 18,100,189,16, "Check to change button text", .Chk2
PushButton 18, 118, 159, 16, "File History", .History
OKButton 177, 8, 58, 21
CancelButton 177, 32, 58, 21
End Dialog
Dim Dlg1 As UserDialog1
x = Dialog( Dlg1 )
End Sub
Function DlgFunc( ControlID$, Action%, SuppValue%)
Begin Dialog UserDialog2 160,160, 260, 188, "3", .DlgFunc
Text 8,10,73,13, "New dialog Label:"
TextBox 8, 26, 160, 18, .FText
CheckBox 8, 56, 203, 16, "New CheckBox",. ch1
CheckBox 18,100,189,16, "Additional CheckBox", .ch2
PushButton 18, 118, 159, 16, "Push Button", .but1
OKButton 177, 8, 58, 21
CancelButton 177, 32, 58, 21
End Dialog
Dim Dlg2 As UserDialog2
Dlg2.FText = "Your default string goes here"
Select Case Action%
Case 1
DlgEnable "Group", 0
DlgVisible "Chk2", 0
DlgVisible "History", 0
Case 2
If ControlID$ = "Chk1" Then
DlgEnable "Group"
DlgVisible "Chk2"
DlgVisible "History"
End If
If ControlID$ = "Chk2" Then
DlgText "History", "Push to display nested dialog"
End If
If ControlID$ = "History" Then
DlgEnable =1
x = Dialog( Dlg2 )
End If
Case Else
End Select
DlgEnable =1
End Function