Using VBScript Form Components in Altium Designer
Using Components in VBScript Forms
Although Forms and Components are based on Embarcadero Delphi's™ Visual Component Library (VCL), the Altium Designer Delphi-based Tool Palette is still used to drop Controls on a form when using VBScript. Also, event handlers are generated and code is written using the VBScript language, regardless of the Form/Component Delphi roots in Altium Designer.
Components Overview
The scripting system handles two types of components: Visual and Non-visual components. The visual components are used to build the user interface and the non-visual components are used for different tasks, such as the functions provided by the Timer
, OpenDialog
and MainMenu
components. For example, the non-visual Timer
component is used to activate specific code at scheduled intervals and it is never seen by a user. The Button
, Edit
and Memo
components are visual components — they are seen by a user.
Both types of components appear at design time, but non-visual components are not visible at runtime. Components from the Tool Palette panel are object-oriented and have the three following items:
- Properties
- Events
- Methods
A property is a characteristic of an object that influences either the visible behavior or the operations of this object. For example, the Visible
property determines whether this object can be seen in a script form.
An event is an action or occurrence detected by the script. In a script, the programmer writes code for each event handler which is designed to capture a specific event, such as a mouse click.
A method is a procedure that is always associated with an object and defines the behavior of that object.
All script forms have one or more components. Components usually display information or allow a user to perform an action. For example, a Label is used to display static text, an Edit box is used to allow a user to input some data, a Button can be used to initiate actions.
Any combination of components can be placed on a form, allowing a user to interact with them when the script is running (runtime). It's the script programmer's task to decide what happens when a user clicks a button or changes a text in an Edit box.
The Scripting system supplies a range of components for creating simple or complex user interfaces for scripts. All of the components that can be placed on a form can be found in the Tool Palette panel.
To place a component on a form, locate its icon on the Tool Palette panel and double-click it. This action places a component on the active form in its default position, with default width and height. The visual representation of most components is determined by their set of associated properties.
A placed component, in its default position and width-height, can be resized or repositioned using the mouse or through the Object Inspector panel. When a component is dropped onto a form, the Scripting system automatically generates the basic code required to use the component and updates the script form. To get the component on the Form working, all that remains is to set properties, put code in event handlers and use methods as necessary.
Designing Script Forms
A script form is designed to interact with a user within the Altium Designer environment. Designing script forms is the core of visual development in Altium Designer.
Each component that is placed on a script form and every property that's set is stored in a file describing the form (a *.dfm
file) and has a relationship with the associated script code (the *.vbs
file). so for every script form, there is the *.vbs
file and the corresponding *.dfm
file.
When working with a script form and its components, its properties can be accessed and modified using the Object Inspector panel. More than one component can be selected by shift-clicking on the components, or by dragging a selection rectangle around the components on the script form. A script form has a title mapped to the Caption
property in the Object Inspector panel.
Creating a New Script Form
With a script project open, right-click on the project in the Projects panel and select the Add New to Project then the VB Script Form items from the context menus. A new script form is created with the default EditScript1.vbs
name. Alternatively, in a *.PrjPCB
project, select File » New » Script Files » VB Script Form command.
Displaying a Script Form
A script needs to have a routine that displays the form when the script form is executed in Altium Designer. Within this routine, the ShowModal
method is invoked for the form. The form's Visible
property needs to be set to false (unchecked) for the script form's ShowModal
method to work correctly.
ShowModal Example
Sub RunDialog
DialogForm.ShowModal
End Sub
The above ShowModal
example is a simple way of displaying the script form when the RunDialog
dialog from the script is invoked. Note that values can be assigned to the components of the DialogForm
object before the DialogForm.ShowModal
method is invoked.
The ModalResult
example shown below is more complex. Its latter methods are used for buttons in the script form. The script methods cause the dialog to terminate when a user clicks either the OK or Cancel button, which will return mrOk
or mrCancel
respectively from the ShowModal
method.
ModalResult Example
sub bOKButtonClick(Sender)
ModalResult := mrOK
end sub
sub bCancelButtonClick(Sender)
ModalResult := mrCancel
end sub
sub RunShowModalExample
'Form Visible property must be false for ShowModal to work properly.
If Form.ShowModal = mrOk Then ShowMessage("mrOk")
If Form.ShowModal = mrCancel Then ShowMessage("mrCancel")
end sub
The same thing as above could be accomplished by setting the ModalResult
value to mrOk
for the OK button and to mrCancel
for the Cancel button in their event handlers. When a user clicks either button, the dialog box closes. There is no need to call the Close
method, because when the ModalResult
method has been set, the script engine closes the script form automatically.
Note that to set the form's ModalResult
to cancel for when a user presses the Esc key, set the Cancel button's Cancel property to true (checked) in the Object Inspector panel, or insert Sender.Cancel := True
in the form's button CancelButtonClick
event handler.
Accepting User Input
One of the common components that can accept input from a user is the EditBox
component. This EditBox
component has a text field where a user can type in a string of characters. There are also other components that can accept text such as the masked edit component, which is an edit component with a text field input mask. The mask controls, or filters, the input and is stored in a parameter string.
The example below illustrates what occurs when a user clicks on the button after typing text into the edit box. Note that if a user did not type any text into the edit component, the event handler responds with a warning message
sub TScriptForm.ButtonClick(Sender)
If Edit1.Text = "" Then
ShowMessage("Warning - empty input!")
Exit
End
' do something else for the input
End sub
Note that a user can move the input focus on the form using the Tab key or by clicking on another form control.
Responding to Events
When a form or a component is selected by a user, Altium Designer sends a message to the Scripting System which responds to the event notification by calling the appropriate event handler method.
Writing Event Handlers
A script may need to respond to events that might occur to a component at run time. An event is a link between an occurrence in Altium Designer, such as clicking a button, and a piece of code that responds to that occurrence. The responding code is an event handler, which modifies property values and calls methods.
Along with a component's properties, each has a set of event names. A script programmer decides how it will react to a user's actions in Altium Designer. For instance, when a user clicks a button on a form, Altium Designer sends a message to the script and the script reacts to this new event — if the OnClick
event for a button is specified, it gets executed.
All such components also have an event for obtaining and losing focus. However, if the code for OnEnter and OnExit is not specified (OnEnter
- the control has focus; OnExit
- the control loses focus), the event will be ignored by the script.
Component Properties
To see a list of properties for a component, select a component and activate the Properties tab in the Object Inspector panel.
Component Events
To see a list of events a component can react on, select a component and activate the Events tab in the Object Inspector panel. To create an event handling procedure for a component to react to, choose a suitable event and double-click on its name.
For example, select the Button1
component from the Tool Palette panel, drop it on the script form, and double-click next to the OnClick event name. The scripting system will refocus to the Code Editor, where the skeleton code for the OnClick
event will have been created. If a button has a Close
method in its CloseClick
event handler, when the button is clicked its event handler captures the on-click event, and the code inside the event handler is executed. That is, the Close
method closes the script form.
In summary, an event handler is created in a script by selecting a component on the form, or with the Object Inspector panel, and then double-clicking to the right of the desired event (say, OnClick) in the Inspector's Events tab — the appropriate code framework will appear in the script.
Alternatively, by double-clicking on a button, the scripting system will add a handler for an OnClick
event. Other types of components will have completely different default actions.
Component Methods
See the Component Reference for a list of methods for a component, and refer to the Embarcadero Delphi documentation for more detailed information.
Creating Components at Run Time
Components can be directly created and destroyed in a script. Normally the handle of the form does not need to be passed, because the script form takes care of it automatically — instead, pass a Nil
parameter to the component Constructor.
For example, the Open and Save Dialogs can be created and destroyed (the TOpenDialog
and TSaveDialog
classes, as part of the Delphi RTL).