Contact our corporate or local offices directly.
Parent page: VBScript
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.
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
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
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:
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.
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
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.
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.
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.
Sub RunDialog DialogForm.ShowModal End Sub
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.
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
mrCancel respectively from the
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.
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.
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.
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.
To see a list of properties for a component, select a component and activate the Properties tab in the Object Inspector panel.
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.
See the Component Reference for a list of methods for a component, and refer to the Embarcadero Delphi documentation for more detailed information.
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
TSaveDialog classes, as part of the Delphi RTL).
Contact our corporate or local offices directly.