Writing Scripts

 

Writing Scripts

There are a number of essential concepts and terms that apply to writing scripts:

  • Processes are command strings that you can use to execute commands in scripts.
  • Components are visual control objects on the Tool Palette panel that you can drag and drop onto a script form to manipulate the design.
  • A component that is placed on a script form has methods, properties, and events.
  • Object Interfaces are special object interfaces that you can use to extract and modify data on design documents from your scripts.

Script Languages

The default scripting language is set to DelphiScript (*.pas). The scripting engine itself is written in Embarcadero Delphi, and the Tool Palette panel is based on the Delphi's VCL (Visual Component Library).

  • You can open and run existing scripts written in VBScript and JavaScript (Jscript). In order to be able to create new scripts written in VBScript, you must enable the Legacy.Scripts.SupportOldLanguages option in the Advanced Settings dialog.
  • Documentation for scripting API can be found here: Scripting API Objects. Please note that this documentation was last updated for an older version of Altium Designer. While many of the principles and approaches will remain the same, be aware that interfaces, objects, methods, properties, and the like will have changed since then, and will not reflect the entirety of those found in later versions of the software.

A DelphiScript Unit

A quick and basic scripting exercise can be completed by first creating a new project and script file. Assuming the project and script file are set to the DelphiScript language, a simple 'Hello World' script can be entered as below.

Procedure ShowAMessage;
Var
 DefaultMessage;
Begin
 DefaultMessage := 'Hello World!';
 ShowMessage(DefaultMessage);
End;
When a document is edited, an asterisk appears next to the script document, and the icon on the Projects panel changes to red. When a script code line is edited, a red block appears in the line's left margin, indicating that the line has changed.

Within the procedure, there is a standard DelphiScript ShowMessage function that opens a dialog with the "Hello World" message, as defined by the DefaultMessage variable.

Since all variables are of the variant type in scripts, there is no need to define the DefaultMessage variable type in the script.

Running the Script

To run one of the scripts, select File » Run Script from the main menus then choose an available script procedure from the Select Item To Run dialog. When a version is run, a dialog will open to display the message.

Running a simple HelloWorld script unit from the File » Run Script menu.
Running a simple HelloWorld script unit from the File » Run Script menu.

This script has a procedure with no parameters. Only procedures or functions that don't have parameters appear in the Select Item To Run dialog. Procedures that require passed parameters are called from within the script (or from another script), but not from an external system such as the Select Item To Run dialog where parameters are not passed.

A script can also be executed using the editor's Run command, accessed by the Run button (), the F9 shortcut key, or by selecting Run » Run from the main menus.

Along with the Run command itself, the dropdown Run menu offers a range of script control and debugging commands.Along with the Run command itself, the dropdown Run menu offers a range of script control and debugging commands.

When the Run command is selected for the first time, the Select Item to Run dialog will open allowing you to specify a script's main procedure (ShowAMessage in this case). Once set, the script is easy to run repeatedly from the editor using the Run command. Use the Run » Set Project Startup Procedure to change the setting to a different procedure, or close and reopen the script project to clear the setting.

To stop a running script, use the Stop button (), select Run » Stop from the main menu, or use the Ctrl+F3 shortcut.

A DelphiScript Form

Expanding on the HelloWorld project created above, a similar script can be created using a form unit.

A Script Form is a dialog window that can host a range of controls such as buttons, memos, and list boxes. It has event handlers that respond when a control has generated an event, such as when a button is clicked.

To create the new script form, right-click on the project name from the Projects panel, choose the Add New to Project option, and select Script Form. The script can be saved and renamed using File » Save As from the main menus.

With a new script project established, add a new script to the project. With a new script project established, add a new script to the project.

The script form creates two files: a *.dfm file that defines the form window elements and handles, and a *.pas file that hosts the form's event handlers and procedures or functions.

To see and edit the property values for the currently focused form or its components, open the Object Inspector panel. The Object Inspector panel is used to change the properties of the form and insert code in the event handlers associated with the current form.

The Script Form's window configuration and properties are demonstrated in the Object Inspector panel.
The Script Form's window configuration and properties are demonstrated in the Object Inspector panel.

Note that the Script Form offers two tabs at the bottom of the document: the Code and Form tabs.

The Code tab contains the event handlers and procedures as shown above, while the Form tab represents the dialog and has controls and associated event handlers. Use the tabs or the F12 shortcut key to change between the two.

The terms 'dialog' and 'script form' are descriptively equivalent in this guide. The 'form' term refers to the window that is being designed in real-time in the scripting system, and a 'dialog' is an active form in the software that is waiting for user feedback and takes action when a dialog button or a control has been clicked.

The Object Inspector panel enables you to interrogate and edit the properties and events of components in the active script form. Clicking on a single component on the active script form in the design editor window will select the component and display attributes associated to it in the Object Inspector panel. Alternatively, use the drop-down field at the top of the panel to choose from a list of all components currently placed on the active form. The form itself is also included.

Use the Object Inspector panel to configure the form dialog and its action. 
Use the Object Inspector panel to configure the form dialog and its action.

The information is displayed over two tabs – Properties and Events:

  • The Properties tab of the panel lists all property attributes for the selected component. The exact list of attributes available will depend on the particular type of component currently under inspection. A property is a characteristic of an object that influences either its visible behavior or its operations. For example, the Visible property (in the Behavior sub-category) determines whether or not the object is displayed on the script form on which it is placed. The properties of a component can be modified as required. Click inside the field to the right of a property and either type directly, toggle a check box or select an entry from a drop-down, as appropriate.
  • The Events tab of the panel provides a list of all events that the currently selected component can react upon. Once again, the exact list of events available will depend on the particular type of component currently under inspection. When an event occurs, such as a button on a form being clicked, the script will take the appropriate action, providing a handling procedure for the event has been defined in the code. This type of procedure is referred to as an event handler.

The skeletal basis for an event handler can be added to the code of the script document from within the Object Inspector panel. Simply select the component you wish to define an event for, choose the particular type of event and then double-click inside the field to the right of the event. A name is created for the event and used in the definition of the name for the event handling procedure - FormName.EventName. The skeleton code for the event handling procedure is then added to the main script code, which is made the active tab in the design space. The 'filling' of the event handling procedure can then be coded to provide the desired response when the event occurs and is detected by the running script.

The bottom section of the panel provides a summary description of the currently selected property or event, where available.

Multiple components may be selected and edited simultaneously. Those properties/events that are common to all components in the selection will be displayed in the panel. Properties/events that have differing values between components will be displayed as blank. Simply edit the properties and/or events as required - the changes made will be conveyed instantly to each component in the selection. For example, you may wish to change the text used on multiple buttons to a particular font. Select all buttons and change the properties listed under the Font category as required - all buttons will be updated to display their text using the same font.

For this form script, change the Caption properties of the form in the Object Inspector panel from HelloWorldForm to Hello World!. These strings match those used in the example event handler and procedure code shown further below.

For more detailed information with respect to components and their properties, methods and events, refer to the Component Categories page.

Add and Configure Controls

With the basic form configured, controls can be added to the dialog as required by accessing the Tool Palette panel. The Tool Palette, based on the Delphi's Visual Component Library, is a component palette that offers a wide range of window controls that are organized as component categories (see the Scripting Graphical Components and  Component Categories pages for more details).

The Tool Palette panel sections can be expanded and collapsed using the region heading tabs.
The Tool Palette panel sections can be expanded and collapsed using the region heading tabs.

Use the controls at the top of the panel, the category names, and the right-click menu to configure the presentation of controls in the panel: expand/collapse categories, change the presentation of palette items, etc.

All components used in the panel descend from TComponent in the Borland Delphi Visual Component Library.

For the dialog version of the 'Hello World' project, there are two buttons on the form - Display and Close. Click TButton in the Standard region of the Tool Palette panel.

Do this twice to place two buttons on the form. One button will be used to display a 'Hello World!' message in a separate dialog, and the second button will be used to close the main dialog.

Components can be placed on a script form by double-clicking the component on the Tool Palette panel, or by clicking the component once and then clicking on the form where you want the component to appear.

All components in the panel have associated Properties, Methods, and Events, where:

  • Property is a characteristic of an object that influences either its visible behavior or its operations. For example, the Visible property determines whether an object can be seen on a script form.
  • Method is a procedure that is always associated with an object and defines the behavior of that object.
  • 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.

The properties and events of a component can be interrogated and modified after placement using the Object Inspector panel.

Using the Object Inspector panel, the two-button configurations can be changed from their default names and captions.

Configure the first button name to bDisplay and its caption to Display. Configure the second button name to bClose and its caption to Close. This is to match the example event handler code presented below.

Select a component and edit its properties in the Object Inspector panel.
Select a component and edit its properties in the Object Inspector panel.

The comments box at the bottom of the Object Inspector panel provides a description of the highlighted property.

Event handler code can be constructed by directly referencing the controls on the form. In this example, the Display button will instigate a ShowMessage dialog on top of the existing form, and the Close button action will close this form.

Event Handler Code

Double-clicking on the Display button will open the form in Code view and create the skeleton code for its event handler. Alternatively, select the button and then the Events tab in the Object Inspector panel. Double-clicking on the OnClick event in the panel will open the code view as above. Within the Code view, the ShowMessage statement can be included in the event handler as shown in the listing below.

Procedure THelloWorldForm.bDisplayClick(Sender: TObject);
Begin
 ShowMessage('Hello World!');
End;
To view pre-defined event handlers for any component on your script form, select the component, then click on the Events tab in the Object Inspector panel.
Similarly, the event handler for the Close button can be defined by generating an OnClick event that applies the Close (form) statement:
Procedure THelloWorldForm.bCloseClick(Sender: TObject);
Begin
 Close;
End;

With the event handlers defined, there needs to be a procedure in the script to be used as the starting point when calling up the dialog from the software. This is added at the end of the code script.

Note that the form name is HelloWorldForm and the procedure name in RunHelloWorld — it's important to have unique form names in the same script to avoid form name clashes.

Procedure RunHelloWorld;
Begin
 HelloWorldForm.ShowModal;
End;

The script can be saved and then run from the main menus (File» Run Script) by running the RunHelloWorld procedure item under the HelloWorldDialog entry.

Alternatively, the procedure can be assigned to the Run command/button () via the Run » Set Startup Project Procedure menu.

Running a HelloWorld form script, where the form Display button activates a ShowMessage dialog.
Running a HelloWorld form script, where the form Display button activates a ShowMessage dialog.

The Object Inspector panel makes it easy to change the properties and events of a form unit. For example, to change the position of the form in the workspace, use the panel to alter the poScreenCenter value for the form's position property. The dialog will now be placed at the center of the desktop screen when the script is run.

A reference version of the Hello World project scripts can be found in the Scripts\Delphiscript Scripts\General folder of the downloadable script collection. Keep in mind that these are legacy reference designs, and are not updated.

Calling a Procedure

As mentioned above, any script (using the same language set) within a project has access to global variables and procedures, so a procedure in one script can call another procedure in a different script in the project.

This can be demonstrated by the additional ShowAParametricMessage code section in the HelloWorld example project:

Procedure ShowAParametricMessage(S : String);
Var
    DefaultMessage;
Begin
    DefaultMessage := 'Hello World!';

    If S = '' Then ShowMessage(DefaultMessage)
              Else ShowMessage(S);
End;

This establishes a string variable 'S' that can be passed to the ShowAParametricMessage procedure.

The passed string will be displayed using the ShowMessage dialog function, whereas a simple If-Then-Else method causes a default 'Hello World!' message to display if the string is empty.

To see this in action, open the example project (HelloWorld.PrjScr) and add the grey highlighted line into the HelloWorldDialog script (not the HelloWorld script), as shown below.

...
Procedure THelloWorldForm.bDisplayClick(Sender: TObject);
Begin
    Showmessage('Hello World!');
End;

Procedure THelloWorldForm.bCloseClick(Sender: TObject);
Begin
    ShowAParametricMessage('Goodbye World');
    close;
End;

Procedure RunHelloWorld;
Begin
    HelloWorldForm.ShowModal;
End;
...

When the HelloWorldDialog script is run and the Close button is clicked, the global ShowAParametricMessage procedure is called from the HelloWorld script.

A parametric procedure in the HelloWorld script is called from the HelloWorldDialog script.
A parametric procedure in the HelloWorld script is called from the HelloWorldDialog script.

The call passes 'Goodbye World' message string to the ShowAParametricMessage procedure, so this message is displayed when the Close button is clicked, prior to the form closing.

The script call shown above inserts a specified message in the HelloWoldDialog form close procedure.
The script call shown above inserts a specified message in the HelloWoldDialog form close procedure.

If the passed string parameter is empty, ShowAParametricMessage(''), the default 'Hello World!' message is displayed as defined in the ShowAParametricMessage procedure.

For a list of shortcut keys that help to streamline the process of writing and debugging scripts, refer to the Script Editor Tools page.

Browsing Script Identifiers using the Code Explorer Panel

The Code Explorer panel provides a visual summary of all identifiers (variables, functions, and procedures) that are used in the active script document.

The Code Explorer panel
The Code Explorer panel

The identifier information that appears in the panel is grouped under the following top-level folders:

  • Procedures & Functions – includes all procedures and functions declared in the active script document. For each procedure/function, any parameters passed to the procedure/function or variables local to it are also listed.

  • Variables – includes all global variables declared in the active script document.

If local variables are declared for a procedure/function, they will appear listed in a variables sub-folder, under that procedure/function. Unique icons are used to distinguish between the various identifiers:

Procedure

Function

Procedure/function parameter

Variable (local or global)

Double-clicking on an entry in the panel (or selecting it and pressing the Enter key) will jump to the corresponding area of code in the design space.

If you find an issue, select the text/image and pressCtrl + Enterto send us your feedback.
Note

The features available depend on your Altium product access level. Compare features included in the various levels of Altium Designer Software Subscription and functionality delivered through applications provided by the Altium 365 platform.

If you don’t see a discussed feature in your software, contact Altium Sales to find out more.

Content