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).