Writing Scripts

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

Processes are command strings that you can use to execute Altium Designer commands in scripts.
Components are visual objects on the Tool Palette panel that you can drag and drop onto a script form to manipulate at design time.
A component (or a control) 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 Altium Designer scripting system offers five different script languages:

DelphiScript (*.pas)
EnableBasic (*.bas)
VisualBasic Script (*.vbs)
JavaScript (*.js)
TCL (*.tcl)

The scripting engine itself is written in Embarcadero Delphi, and the Tool Palette panel is based on the Delphi's VCL (Visual Component Library). While DelphiScript is based on Object Pascal, there are some differences between DelphiScript and Object Pascal.

For more detailed information on the differences between DelphiScript and Object Pascal, refer to the DelphiScript Reference document.

A DelphiScript Unit

A quick and basic scripting exercise can be completed by first creating a new project and script file in Altium Designer, as described previously. 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 is a standard DelphiScript ShowMessage function that opens a simple 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 execute the script, invoke the Select Item To Run dialog (DXP » Run Script) and select the script's ShowAMessage procedure from the list.

If there are errors in your script, Altium Designer will prompt you with an error message. The script can be saved by selecting File » Save.

Running a simple HelloWorld script unit from the DXP » 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 menu.

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 button. 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 (that may have paused at an error, for example), 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 functionally similar script can be created using a form unit.

A script form is a window (or in the active sense, a dialog) 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, choose the Add New to Project option and select Delphi Script Form. The script can be saved a renamed using the File » Save As menu.

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 from the Script button at the bottom of the design window. The Object Inspector panel is used to change the color, size, etc of the Form, and insert code in the event handlers associated with the current form.

The Form window's configuration and properties are exposed in the Object Inspector panel, opened via the Script button.

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

The Form tab displays the current form window as shown above, while the Code tab opens the form code for the event handlers and procedures. Use the tabs or the F12 shortcut key to change between the two.

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

The Object Inspector panel shows the values of the properties for the currently focused form or its components. For this form script, change the Name and the Caption properties of the form in the Object Inspector panel to HelloWorldForm and Hello World! respectively, as shown below. These strings match those used in the example event handler and procedure code shown further below.

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

See Scripting System Panels for more information the Object Inspector and Tool Palette panels.

Add and Configure Controls

With the basic form configured, controls can be added to the dialog as required by accessing the Tool Palette panel. To open this choose the Tool Palette option after clicking the Script button at the bottom of the design window.

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 Palette's Component Reference for more details).

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

For the dialog version of the Hello World project there are two buttons on the form: Display and Close. Click TButton (image of an OK button) in the Standard section of the Tool Palette panel as shown above.

Do this twice to place two buttons on the form. One button will be used to display a Hello World! message on separate dialog, and the second button is 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.

Select a component and edit its properties in 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 and its caption to Close. This is to match the example event handler code presented below.

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

Event hander code can be constructed by directly referencing the controls (buttons in this case) on the form. For this example, the Display button will instigate a ShowMessage dialog on top of the existing form, and the Close button action will simply 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 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 (appropriately called RunHelloWorld) in the script to be used as the starting point when calling up the dialog from Altium Designer. 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 if need be, and then executed from the DXP system menu (DXP » 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 simple HelloWorld form script, where the form Display button activates a ShowMessage dialog.

The Object Inspector panel makes it very easy to change the properties and events of a form unit. For example to change the position of the form with respect to the desktop screen or the Altium Designer workspace, use the panel to alter the poScreenCenter value for the form's the 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.

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 dilaog 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 clicked, the global ShowAParametricMessage procedure is called from the HelloWorld script.

A parametric procedure in the HelloWorld script is called form 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.

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

See the 'Scripting Shortcut Keys' section on the Script Editor Tools page for a list of shortcut keys that help to streamline the process of writing and debugging scripts.

Content

Writing Scripts

Contents

Writing Scripts

Script Languages

A DelphiScript Unit

Running the Script

A DelphiScript Form

Add and Configure Controls

Event Handler Code

Calling a Procedure