Forms and Components
Contents
Parent page: EnableBasic
Enable Basic provides a simple approach to providing Dialogs (Forms) and their associated Controls (Components) for a script's user interface.
Creating Custom Dialogs
Enable Basic includes support for the use of custom dialogs within a script. A dialog is essentially a window that includes various controls that a user can manipulate. In Enable Basic, you define a dialog is defined by including control definition statements in a Begin Dialog...End Dialog statement block.
The following code fragment shows a simple dialog definition that just includes an OK button, a Cancel button and a single checkbox:
Begin Dialog ButtonSample 162,129, 180, 96, "Simple dialog" OKButton 84,76,40,14 CancelButton 132,76,40,14 CheckBox 64,28,48,16, "Click me", .CheckBox_1 End Dialog In the above code, the Begin Dialog statement includes the name of dialog, ButtonSample, and the text that will appear on the title bar of the dialog, "Simple dialog".
Dimension
To display a dialog that has been defined using the Begin Dialog...End Dialog statement block, first declare an object variable in which to store the various dialog control values using the Dim statement. The following code fragment dimensions a variable, myDlg, to hold the values of the ButtonSample dialog defined above:
Dim myDlg As ButtonSample
After the dialog is displayed and the user clicks on a button to exit the dialog, the values of the dialog controls (in this case .CheckBox_1) will be stored in the variable myDlg.
Display
To display a dialog, use the Dialog function. This function displays the dialog associated with the given object variable, and returns a number that corresponds to the button that the user clicks to close the dialog. The following code fragment displays the dialog declared above:
WhichButton = Dialog(myDlg)
...where WhichButton is a variable used to store the return value.
Interrogate
Once the dialog has been displayed and closed by the user, the object variable can be interrogated to determine the values of the dialog controls when the it was closed. For example, the following code fragment displays the value of the checkbox once the dialog is closed.
MsgBox myDlg.CheckBox_1
Reference
Note how the checkbox control value is referenced. Any control that returns a value can be referenced using the syntax:
DlgVar.CtrlIdentifier
...where DlgVar is the object variable associated with the dialog and CtrlIdentifier is the control identifier set in the control definition statement.
Note that every custom dialog box must contain at least one control button: OKButton , CancelButton or PushButton .
Linking a Function to a Dialog
Enable Basic gives you the ability to link a function to a user-defined dialog. The linked function is then called when the dialog is displayed and each time the user performs an action in the dialog, such as changing the value of a control.
The ability to link a function to a dialog makes it possible to create nested dialogs and to process messages from a dialog without closing it.
A dialog-linked function is called:
- When the dialog is first initialized
- Each time the user changes the value of or uses a dialog control.
To link a function to a dialog, include the name of the function, preceded by the period " . " character, in the Begin Dialog statement. The following code fragment shows a dialog definition statement that links the function myDlgFunction to the dialog:
Begin Dialog UserDialog1 60,60, 260, 188, "A dialog", .myDlgFunction
Once a function is linked to a dialog in a Begin Dialog statement, the function must then be defined using a Function...End Function statement block.
Each time the linked function is called, three parameters are passed to it;
- The first is a string containing the name of the control that was changed or activated to invoke the function call.
- The second is an integer value that indicates whether the function is being called during the dialog initialization (a value of 1), or whether the function call is a response to action taken in the dialog (a value of 2).
- The third parameter is an integer that supplies supplemental information about the control that initiated the function call. For example, if a checkbox is changed, the supplemental value represents the state of the checkbox: 1 for checked, 0 for not checked
The dialog linked function must therefore be declared using the following syntax:
Function FunctionName(ControlID$, Action%, SuppValue%) As Integer
The function returns an integer value indicating whether the dialog should remain open after the function has executed. A return value of 0 (the default) indicates that the dialog should close. Any other value indicates the dialog should remain open.
Dialog Linked Function example
Sub Main Begin Dialog UserDialog1 60,60, 165, 120, "MyDlg 1", .DlgFunction GroupBox 8,45,150,50, "This is a group box:", .GroupBox1 CheckBox 8,21,148,16, "Check to display more controls", .Chk1 PushButton 30,66,100,16, "Open Second Dlg", .SecDlgBut OKButton 84,104,26,12 CancelButton 124,104,26,12 End Dialog Dim Dlg1 As UserDialog1 If Dialog( Dlg1 ) = -1 Then MsgBox "You pressed the OK button" Else MsgBox "You pressed the Cancel button" End If End Sub ' Define the linked function Function DlgFunction( ControlID$, Action%, SuppValue%) As Integer Begin Dialog USERDIALOG2 150,150, 155, 100, "MyDlg 2", .DlgFunction Text 8,6,101,16, "This is a secondary dialog" PushButton 35,23,80,16, "Display message", .PushBut1 CancelButton 112,84,26,12 CheckBox 8,48,136,20, "Keep dialog open after button press", .CheckBoxKeepOpen End Dialog Dim Dlg2 As UserDialog2 Select Case Action% Case 1 ' Executed when dialog initializes DlgEnable "GroupBox1", 0 DlgVisible "SecDlgBut", 0 Case 2 ' Executed each time a control is changed If ControlID$ = "Chk1" Then DlgEnable "GroupBox1" DlgVisible "SecDlgBut" ElseIf ControlID$ = "SecDlgBut" Then DlgFunction = 1 x = Dialog( Dlg2 ) ElseIf ControlID$ = "PushBut1" Then If Dlg2.CheckBoxKeepOpen = 1 Then DlgFunction = 1 ' Keeps dialog open Else DlgFunction = 0 ' Closes dialog End If MsgBox "You pushed me!" Else DlgFunction = 0 End If End Select End Function Dialog-linked function syntax
Syntax
Function FnName(ControlID$, Action%, SuppVal%) As Integer
...statement block...
[FunctionName = ReturnValue%]
End Function
Parameters
|
| Name of the function. Must be the same as that defined in the | |
|
| String containing the control identifier for the control that initiated the function call. | |
|
| Integer. Is 1 if the function is being called during dialog initialization. Is 2 if the function is being called in response to a user action in the dialog. | |
|
| Integer. The value depends on the type of control (See below) | |
|
| Integer representing the return value of the function. A dialog-linked function returns a value when the user chooses a command button. Enable Basic acts on the value returned. If the value is 0 (zero), the calling dialog is closed when the function has executed. If a non-zero value is returned, the dialog remains open. |
By returning a non-zero value from the function you can keep the dialog open. This allows you to execute more than one command from the same dialog.
Values for SuppVal%
| Control | Values for SuppVal% |
|---|---|
| CheckBox | 0 if cleared, 1 if checked. |
| OptionButton | Number of the option button selected, where 0 (zero) is the first option button within a group. |
| OKButton | 1 |
| CancelButton | 2 |
| other controls | Not applicable. |
Begin Dialog...End Dialog
Description
Encloses the definition of a user-created dialog box. Statements enclosed by the Begin Dialog...End Dialog structure define the controls that appear in the dialog.
Syntax
Begin Dialog DlgName, PosX, PosY, Width, Height, dlgTitle$ [, .dlgFtnIdentifier]
...
dialog box controls definition procedures
...
End Dialog
Parameters
DlgName - the object variable used to reference the dialog within the program. DlgName must follow standard function naming conventions.
PosX, PosY - a number or numerical expression representing the position of the top-left corner of the dialog. The position is measured in pixels from the top-left corner of the Altium Designer window.
Width - a number or numerical expression representing the width of the dialog in pixels.
Height - a number or numerical expression representing the height of the dialog in pixels
dlgTitle$ - a string or string expression representing the text to be displayed in the title bar of the dialog.
.dlgFtnIdentifier - optional identifier which defines a function to be executed whenever a change is made to the dialog by the user. .dlgFunctionIdentifier is the name of a valid function preceded by the period character.
Notes
If the optional .dlgFtnIdentifier parameter is used, you must define a function of the same name (less the initial period character) that will be executed whenever the dialog is opened or any control within the dialog is changed by the user. This dialog function is typically used to test and act upon the state of the dialog controls before the user closes the dialog. For example, the dialog function could enable or disable certain dialog controls when a particular option is selected.
Example
This example creates a dialog called DialogName1 with the title of "ASC - Hello".
Sub Main () ' Define the dialog box. Begin Dialog DialogName1 60, 60, 160, 70, "ASC - Hello" TEXT 10, 10, 28, 12, "Name:" TEXTBOX 42, 10, 108, 12, .nameStr TEXTBOX 42, 24, 108, 12, .descStr CHECKBOX 42, 38, 48, 12, "&CHECKME", .checkInt OKBUTTON 42, 54, 40, 12 End Dialog ' Dimension an object to represent the dialog. Dim Dlg1 As DialogName1 Dlg1.checkInt = 1 ' Check the checkbox. Dialog Dlg1 ' Display the dialog. End Sub
Dialog Controls
CancelButton
Description
Used in a dialog definition for placing a Cancel button in a user-defined dialog box.
Syntax
CancelButton PosX, PosY, Width, Height
Parameters
PosX, Pos Y - numbers or numeric expressions representing the position of the top-left corner of the button expressed in pixels relative to the top-left corner of the dialog box.
Width - a number or numeric expression representing the width of the button in pixels.
Height - a number or numeric expression representing the height of the button in pixels.
Notes
This procedure is only used as part of a dialog definition.
CheckBox
Description
This procedure is used as part of a dialog box definition to create a check box object.
Syntax
CheckBox PositionX, PositionY, Width, Height, Caption$, .Identifier
Parameters
PosX, PosY - a numerical expression defining the x and y position of the checkbox in pixels relative to the top right of the dialog box.
Width - a numerical expression defining the width of the checkbox in pixels. This width includes the title text area.
Height - a numerical expression defining the height of the checkbox in pixels. This height includes the title text area.
Caption$ - string expression that defines the text associated with the check box.
.Identifier - name used as the identifier for the checkbox control. The name must start with the period character.
Notes
The .Identifier parameter is used to set or test the value of the check box. If the check box is checked, the .Indetifier parameter returns a value of 1. If it is not checked, it returns a value of 0.
Example
This example creates a checkbox in a dialog called "ASC - Hello". Before the dialog is displayed, the checkbox identifier is set to 1 indicating that the box is checked.
Sub Main () ' Define the dialog box. Begin Dialog DialogName1 60, 60, 160, 70, "ASC - Hello" TEXT 10, 10, 28, 12, "Name:" TEXTBOX 42, 10, 108, 12, .nameStr TEXTBOX 42, 24, 108, 12, .descStr CHECKBOX 42, 38, 48, 12, "&CHECKME", .checkInt OKBUTTON 42, 54, 40, 12 End Dialog ' Dimension an object to represent the dialog. Dim Dlg1 As DialogName1 Dlg1.checkInt = 1 ' Check the checkbox. Dialog Dlg1 ' Display the dialog. End Sub ComboBox
Description
Used in a dialog definition for placing a Combo box in a user-defined dialog box.
Syntax
ComboBox PosX, PosY, Width, Height, ArrayVar(), .Identifier
Parameters
PosX,Pos Y - numbers or numeric expressions representing the position of the top-left corner of the box expressed in pixels relative to the top-left corner of the dialog box.
Width - a number or numeric expression representing the width of the box in pixels.
Height - a number or numeric expression representing the height of the box in pixels.
ArrayVar() - a valid array used as the source for the combo box value list.
.Identifier - name used as the identifier for the control. The name must start with the period character.
Notes
A combo box is a combination of a text entry box and a list box. The control presents a list of options for the user to choose from, but also allows the user to enter text directly.
The array named in the parameter ArrayVar() is the source of the combo box list.
The .Identifier parameter is used to reference the text value of control. If myDlg is the object variable declared to contain the dialog box values, the text value of the combo box is contained in myDlg.Identifier.
Example
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.
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, "Dialog Example" 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 Dlg1.CmboBox = MyList$(0) Button = Dialog(Dlg1) If Button = -1 Then Msg$ = "List Box = " & MyList$(Dlg1.Lstbox) & Chr(10) Msg$ = Msg$ & "Drop List Box = " & MyList$(Dlg1.DrpList) & Chr(10) Msg$ = Msg$ & "Combo Box = " & Dlg1.CmboBox & Chr(10) MsgBox Msg$ End If End Sub Dialog
Description
The first listed syntax displays the dialog defined by DialogRecord. The function version (the second listed syntax) displays the dialog defined by DialogRecord and returns a number corresponding to the pushbutton the user presses.
Syntax
Dialog DialogRecord
Var = Dialog(DialogRecord)
Parameters
DialogRecord - the name of the dialog to display. DialogRecord must be defined in a preceding Dim statement.
Var - a variable to hold the returned button value.
Notes
Use the Begin Dialog ... End Dialog syntax to define the dialog box. Use the Dim procedure to dimension an object to represent the dialog. The variable used in the Dim procedure is the calling name of the dialog, DialogRecord.
The function form of Dialog returns an Integer data type which represents the control button pressed to close the dialog. Returned value for button pressed:
OK button -1
Cancel button 0
Other command button: The first PushButton defined in the dialog definition returns the number 1, the second the number 2, etc.
Example
The following example defines a dialog with a text input box and three buttons: an OK button, a Cancel button and a general control pushbutton. The procedure displays the dialog and, when the user presses a button, displays the text typed into the text input box and which control button was pressed.
Sub Main () Dim WhichButton% ' Define the dialog box. Begin Dialog DialogName1 58,60, 161, 65, "Press a button" Text 2,2,64,12, "Type your name:" TextBox 6,14,148,12, .nameStr Text 16,32,124,12, "And then press a button..." OKButton 16,48,40,12 CancelButton 60,48,36,12 PushButton 100,48,40,12, "Push me", .PushButton_1 End Dialog ' End of dialog definition Dim Dlg1 As DialogName1 WhichButton% = Dialog(Dlg1) ' Display the dialog and return ' the button pressed MsgBox "Your name is " & Dlg1.nameStr _ & " and you pressed button " & WhichButton% End Sub DlgEnable
Description
This procedure is used in a dialog-linked function to enable or disable a particular control on a dialog box.
Syntax
DlgEnable CtrlName$[, Value]
Parameters
CtrlName$ - string or string expression that is the name of a control on a dialog box.
Value - optional integer used to determine whether the control is enabled or disabled. If Value is 1 then the control is enabled. If Value is 0 then the control is disabled. If Value is omitted then the status of the control is toggled.
Notes
The CtrlName$ parameter is derived from the control identifier used in the dialog definition statements. CtrlName$ is the control's identifier less the initial period character. For example, if a dialog definition contains the check box definition statement:
CheckBox 8, 46, 100, 12, "A CheckBox", .checkbox1
...then the control identifier is .checkbox1 and the CtrlName$ parameter used to identify the control in the DlgEnable statement would be "checkbox1".
When a control is disabled, it is 'grayed' out in the dialog and unavailable for user input.
DlgText
Description
This procedure is used in a dialog-linked function to set or change the text label of a dialog control.
Syntax
DlgText CtrlName$, Value$
Parameters
CtrlName$ - a string expression that is the name of a control on a dialog box.
Value$ - a string expression that contains the text to assign to the control label.
Notes
The CtrlName$ parameter is derived from the control identifier used in the dialog definition statements. CtrlName$ is the control's identifier less the initial period character. For example, if a dialog definition contains the check box definition statement:
CheckBox 8, 46, 100, 12, "A CheckBox", .checkbox1
...then the control identifier is .checkbox1 and the CtrlName$ parameter used to identify the control in the DlgText statement would be "checkbox1".
This statement only affects the text label associated with a control. To set the text value of a TextBox control, use a variable assignment statement of the form:
myDlg.TextBox1 = "Default text"
DlgVisible
Description
This procedure is used in a dialog-linked function to hide or make visible a particular control on a dialog box.
Syntax
DlgVisible CtrlName$[, Value]
Parameters
CtrlName$ - string or string expression that is the name of a control on a dialog box.
Value - optional integer used to determine whether the control is visible or hidden. If Value is 1 then the control is visible. If Value is 0 then the control is hidden. If Value is omitted then the status of the control is toggled.
Notes
The CtrlName$ parameter is derived from the control identifier used in the dialog definition statements. CtrlName$ is the control's identifier less the initial period character. For example, if a dialog definition contains the check box definition statement:
CheckBox 8, 46, 100, 12, "A CheckBox", .checkbox1
...then the control identifier is .checkbox1 and the CtrlName$ parameter used to identify the control in the DlgVisible statement would be "checkbox1".
When a control is hidden it is not displayed in the dialog and is not accessible for user input.
DropListBox
Description
Used in a dialog definition for placing a drop-down list box in a user-defined dialog box.
Syntax
DropListBox PosX, PosY, Width, Height, ArrayVar(), .Identifier
Parameters
PosX, Pos Y - numeric expressions representing the position of the top-left corner of the box expressed in pixels relative to the top-left corner of the dialog box.
Width - numeric expression representing the width of the box in pixels.
Height - numeric expression representing the height of the box in pixels.
ArrayVar() - a valid array used as the source for the box value list.
.Identifier - name used as the identifier for the control. The name must start with the period character.
Notes
A drop list box has a data display box with an arrow button at the side. Clicking the arrow expands the box to show a list of values that the user can choose from. The selected item is displayed in the display box. Unlike a Combo box, only values from the list can be chosen. The user cannot directly enter text into a drop list box.
The array named in the parameter ArrayVar() is the source of the displayed list. The default value displayed is the first array item.
The .Identifier parameter is used to reference the value of control. If myDlg is the object variable declared to contain the dialog box values, the value of the drop list box is contained in myDlg.Identifier.
The value of a drop list box is the index value of the array element chosen, not the element itself.
Example
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.
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, "Dialog Example" 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 Dlg1.CmboBox = MyList$(0) Button = Dialog(Dlg1) If Button = -1 Then Msg$ = "List Box = " & MyList$(Dlg1.Lstbox) & Chr(10) Msg$ = Msg$ & "Drop List Box = " & MyList$(Dlg1.DrpList) & Chr(10) Msg$ = Msg$ & "Combo Box = " & Dlg1.CmboBox & Chr(10) MsgBox Msg$ End If End Sub GroupBox
Description
Used in a dialog definition for placing a box around a group of controls in a user-defined dialog box.
Syntax
GroupBox PosX, PosY, Width, Height, Caption$, .Identifier
Parameters
PosX, PosY - numeric expressions representing the position of the top-left corner of the box expressed in pixels relative to the top-left corner of the dialog box.
Width - numeric expression representing the width of the box in pixels.
Height - a numeric expression representing the height of the box in pixels.
Caption$ - a string expression containing the title to appear on the box.
.Identifier - optional name used as the identifier for the control. The name must start with the period character.
Notes
This procedure is only used as part of a dialog definition. The group box has no inherent value and cannot be altered by the user.
The use of the .Identifier parameter is optional. You may want to include this if you wish to, for example, enable or disable the group box in a dialog-linked function.
Example
You can use option buttons to allow the user to choose one option from several options. 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.
Sub Main Begin Dialog GroupSample 31, 32, 185, 96, "Groups Example" OKButton 28, 68, 40, 14 CancelButton 120, 68, 40, 14 GroupBox 12, 8, 72, 52, "GroupBox", .GroupBox1 GroupBox 100, 12, 72, 48, "GroupBox", .GroupBox2 OptionGroup .OptionGroup1 OptionButton 16, 24, 54, 8, "0ption 1" OptionButton 16, 40, 54, 8, "0ption 2" CheckBox 108, 24, 45, 8, "CheckBox 1", .CheckBox1 CheckBox 108, 40, 45, 8, "CheckBox 2", .CheckBox2 End Dialog Dim Dlg1 As GroupSample If Dialog ( Dlg1 ) Then Select Case Dlg1.OptionGroup1 Case 0 MsgBox "Option 1 was selected" Case 1 MsgBox "Option 2 was selected" End Select End If End Sub ListBox
Description
Used in a dialog definition for placing a list box in a user-defined dialog box.
Syntax
ListBox PosX, PosY, Width, Height, ArrayVar(), .Identifier
Parameters
PosX, Pos Y - numeric expressions representing the position of the top-left corner of the box expressed in pixels relative to the top-left corner of the dialog box.
Width - a numeric expression representing the width of the box in pixels.
Height - a numeric expression representing the height of the box in pixels.
ArrayVar() - a valid array used as the source for the box value list.
.Identifier - name used as the identifier for the control. The name must start with the period character.
Notes
A list box presents the user with a list of items from which to choose. The selected item is highlighted. The user cannot directly enter text into a list box.
The array named in the parameter ArrayVar() is the source of the displayed list. The default value highlighted is the first array item.
The .Identifier parameter is used to reference the value of control. If myDlg is the object variable declared to contain the dialog box values, the value of the list box is contained in myDlg.Identifier.
Note that the value of a list box is the index value of the array element chosen, not the element itself.
Example
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.
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, "Dialog Example" 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 Dlg1.CmboBox = MyList$(0) Button = Dialog(Dlg1) If Button = -1 Then Msg$ = "List Box = " & MyList$(Dlg1.Lstbox) & Chr(10) Msg$ = Msg$ & "Drop List Box = " & MyList$(Dlg1.DrpList) & Chr(10) Msg$ = Msg$ & "Combo Box = " & Dlg1.CmboBox & Chr(10) MsgBox Msg$ End If End Sub OKButton
Description
Used in a dialog definition for placing an OK button in a user-defined dialog box.
Syntax
OKButton PosX, PosY, Width, Height
Parameters
PosX, Pos Y - numeric expressions representing the position of the top-left corner of the button expressed in pixels relative to the top-left corner of the dialog box.
Width - a numeric expression representing the width of the button in pixels.
Height - a numeric expression representing the height of the button in pixels.
Notes
This procedure is only used as part of a dialog definition.
Example
This example creates a dialog called DialogName1 with the title of "ASC - Hello".
Sub Main () ' Define the dialog box. Begin Dialog DialogName1 60, 60, 160, 70, "ASC - Hello" TEXT 10, 10, 28, 12, "Name:" TEXTBOX 42, 10, 108, 12, .nameStr TEXTBOX 42, 24, 108, 12, .descStr CHECKBOX 42, 38, 48, 12, "&CHECKME", .checkInt OKBUTTON 42, 54, 40, 12 End Dialog ' Dimension an object to represent the dialog. Dim Dlg1 As DialogName1 Dlg1.checkInt = 1 ' Check the checkbox. Dialog Dlg1 ' Display the dialog. End Sub OptionButton
Description
This procedure is used as part of a dialog box definition to create an option or radio button object.
Syntax
OptionButton PosX, PosY, Width, Height, Caption$[, .Identifier]
Parameters
PosX, PosY - a numerical expression defining the x and y position of the control in pixels relative to the top right of the dialog box.
Width - a numerical expression defining the width of the control in pixels. This width includes the title text area.
Height - a numerical expression defining the height of the control in pixels. This height includes the title text area.
Caption$ - string expression that defines the text label associated with the control.
.Identifier - name used as the identifier for the control. The name must start with the period character.
Notes
Option buttons are usually used in groups to present a series of options from which the user can pick only one.
A group of OptionButton statements in a dialog definition must be preceded by an OptionGroup statement, which assigns the group that the option buttons belong to. To determine which option in a group is checked, you query the option group identifier, which returns the number of the option button which is checked. The first option button defined after the OptionGroup statement is button 0, the second is button 1, etc. Checking one option button unchecks all other option buttons in the same group.
The .Identifier parameter is optional, but should be included if you wish to refer to the control in a dialog-linked function.
Example
You can use option buttons to allow the user to choose one option from several options. 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.
Sub Main Begin Dialog GroupSample 31, 32, 185, 96, "Groups Example" OKButton 28, 68, 40, 14 CancelButton 120, 68, 40, 14 GroupBox 12, 8, 72, 52, "GroupBox", .GroupBox1 GroupBox 100, 12, 72, 48, "GroupBox", .GroupBox2 OptionGroup .OptionGroup1 OptionButton 16, 24, 54, 8, "0ption 1" OptionButton 16, 40, 54, 8, "0ption 2" CheckBox 108, 24, 45, 8, "CheckBox 1", .CheckBox1 CheckBox 108, 40, 45, 8, "CheckBox 2", .CheckBox2 End Dialog Dim Dlg1 As GroupSample If Dialog ( Dlg1 ) Then Select Case Dlg1.OptionGroup1 Case 0 MsgBox "Option 1 was selected" Case 1 MsgBox "Option 2 was selected" End Select End If End Sub OptionGroup
Description
Precedes a set of OptionButton statements in a dialog definition block to define an option button group.
Syntax
OptionGroup .Identifier
...option button definition statements..
Parameters
.Identifier - name used as the identifier for the option button group. The name must start with the period character.
Notes
This statement is only used within a dialog box definition. It gives a name to a group of option or radio buttons which are placed immediately after it in the dialog definition.
The .Identifier parameter is used to reference the selected option in the group within the dialog object variable. For example, if myDlg is dimensioned as the variable to hold the value of the dialog controls, then a reference of the form:
myDlg.Identifier
...will set or return an integer representing the number of the option button in the group which is checked. The first option button defined after the OptionGroup statement in the dialog definition is 0, the second is 1, etc.
Example
You can use option buttons to allow the user to choose one option from several options. 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.
Sub Main Begin Dialog GroupSample 31, 32, 185, 96, "Groups Example" OKButton 28, 68, 40, 14 CancelButton 120, 68, 40, 14 GroupBox 12, 8, 72, 52, "GroupBox", .GroupBox1 GroupBox 100, 12, 72, 48, "GroupBox", .GroupBox2 OptionGroup .OptionGroup1 OptionButton 16, 24, 54, 8, "0ption 1" OptionButton 16, 40, 54, 8, "0ption 2" CheckBox 108, 24, 45, 8, "CheckBox 1", .CheckBox1 CheckBox 108, 40, 45, 8, "CheckBox 2", .CheckBox2 End Dialog Dim Dlg1 As GroupSample If Dialog ( Dlg1 ) Then Select Case Dlg1.OptionGroup1 Case 0 MsgBox "Option 1 was selected" Case 1 MsgBox "Option 2 was selected" End Select End If End Sub PushButton
Description
Used in a dialog definition for placing a general-purpose pushbutton or control button in a user-defined dialog box.
Syntax
PushButton PosX, PosY, Width, Height, Caption$, .Identifier
Parameters
PosX, Pos Y - numeric expressions representing the position of the top-left corner of the button expressed in pixels relative to the top-left corner of the dialog box.
Width - a numeric expression representing the width of the button in pixels.
Height - a numeric expression representing the height of the button in pixels.
Caption$ - a string expression containing the text to appear on the button.
.Identifier - name used as the identifier for the pushbutton control. The name must start with the period character.
Notes
This procedure is only used as part of a dialog definition.
Text
Description
This procedure is used within a dialog box definition to create a text field for titles and labels.
Syntax
Text PosX, PosY, Width, Height, Label$
Parameters
PosX, Pos Y - numeric expressions representing the position of the top-left corner of the control expressed in pixels relative to the top-left corner of the dialog box.
Width - a numeric expression representing the width of the control in pixels.
Height - a numeric expression representing the height of the control in pixels.
Label$ - a string expression that contains the text displayed.
Notes
Text placed in a dialog with this procedure is fixed and cannot be altered by the user. This statement is only used within a dialog definition.
Example
This example creates a dialog called DialogName1 with the title of "ASC - Hello".
Sub Main () ' Define the dialog box. Begin Dialog DialogName1 60, 60, 160, 70, "ASC - Hello" TEXT 10, 10, 28, 12, "Name:" TEXTBOX 42, 10, 108, 12, .nameStr TEXTBOX 42, 24, 108, 12, .descStr CHECKBOX 42, 38, 48, 12, "&CHECKME", .checkInt OKBUTTON 42, 54, 40, 12 End Dialog ' Dimension an object to represent the dialog. Dim Dlg1 As DialogName1 Dlg1.checkInt = 1 ' Check the checkbox. Dialog Dlg1 ' Display the dialog. End Sub TextBox
Description
This procedure is used within a dialog box definition to create a text box for data entry.
Syntax
TextBox PosX, PosY, Width, Height, .Identifier
Parameters
PosX, Pos Y - numbers or numeric expressions representing the position of the top-left corner of the control expressed in pixels relative to the top-left corner of the dialog box.
Width - a number or numeric expression representing the width of the control in pixels.
Height - a number or numeric expression representing the height of the control in pixels.
.Identifier - the identifier for the control. The identifier must begin with the period "." character.
Notes
A TextBox control has no inherent label associated with it. Use the Text statement to create a label if necessary.
The .Identifier parameter is used to return or set the text value of the TextBox. For example, if the object variable Dlg1 has be dimensioned to hold the values for the dialog box, then the statement Dlg1.Identifier = "my text" sets the text in TextBox. Similarly, A$ = Dlg1.Identifier returns the current text in the TextBox.
Example
This example creates a dialog called DialogName1 with the title of "ASC - Hello".
Sub Main () ' Define the dialog box. Begin Dialog DialogName1 60, 60, 160, 70, "ASC - Hello" TEXT 10, 10, 28, 12, "Name:" TEXTBOX 42, 10, 108, 12, .nameStr TEXTBOX 42, 24, 108, 12, .descStr CHECKBOX 42, 38, 48, 12, "&CHECKME", .checkInt OKBUTTON 42, 54, 40, 12 End Dialog ' Dimension an object to represent the dialog. Dim Dlg1 As DialogName1 Dlg1.checkInt = 1 ' Check the checkbox. Dialog Dlg1 ' Display the dialog. End Sub