Forms and Components

Old Content - visit altium.com/documentation

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

FnName

 

Name of the function. Must be the same as that defined in the Begin Dialog statement.

ControlID$

 

String containing the control identifier for the control that initiated the function call.

Action%

 

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.

SuppVal%

 

Integer. The value depends on the type of control (See below)

ReturnVal%

 

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
You are reporting an issue with the following selected text and/or image within the active document:
ALTIUM DESIGNER FREE TRIAL
Altium Designer Free Trial
Let’s get started. First off, are you or your organization already using Altium Designer?

If would like to speak with a representative, please contact your local Altium office.
Copyright © 2019 Altium Limited

In that case, why do you need an evaluation license?

If would like to speak with a representative, please contact your local Altium office.
Copyright © 2019 Altium Limited

Got it. You actually don’t need an evaluation license for that.

Click the button below to download the latest Altium Designer installer.

Download Altium Designer Installer

If would like to speak with a representative, please contact your local Altium office.
Copyright © 2019 Altium Limited

Please fill out the form below to get a quote for a new seat of Altium Designer.

By clicking “Get Your Free Trial”, you are agreeing to our Privacy Policy.
You may receive communications from Altium and can change your notification preferences at any time.

If you are on Altium Subscription, you don’t need an evaluation license.

If you are not an active Altium Subscription member, please fill out the form below to get your free trial.

By clicking “Get Your Free Trial”, you are agreeing to our Privacy Policy.
You may receive communications from Altium and can change your notification preferences at any time.

Why are you looking to evaluate Altium Designer?

If would like to speak with a representative, please contact your local Altium office.
Copyright © 2019 Altium Limited

You came to the right place! Please fill out the form below to get your free trial started.

By clicking “Get Your Free Trial”, you are agreeing to our Privacy Policy.
You may receive communications from Altium and can change your notification preferences at any time.

Sounds exciting! Did you know we offer special discounted student licenses? For more information, click here.

In the meantime, feel free to request a free trial by filling out the form below.

By clicking “Get Your Free Trial”, you are agreeing to our Privacy Policy.
You may receive communications from Altium and can change your notification preferences at any time.

Got it. You can download a free Altium Designer Viewer license which is valid for a 6 months.

Please fill out the form below to request one.

By clicking “Get Your Free Trial”, you are agreeing to our Privacy Policy.
You may receive communications from Altium and can change your notification preferences at any time.

That’s great! Making things is awesome. We have the perfect program for you.

Upverter is a free community-driven platform designed specifically to meet the needs of makers like you.

Click here to give it a try!

If would like to speak with a representative, please contact your local Altium office.
Copyright © 2019 Altium Limited

Got it. You can download a free Altium Designer Viewer license which is valid for a 6 months.

Please fill out the form below to request one.

By clicking “Get Your Free Trial”, you are agreeing to our Privacy Policy.
You may receive communications from Altium and can change your notification preferences at any time.