A Tour of the Scripting System - Altium

A Tour of the Scripting System

Summary Guide GU0120 (v1.7) April 21, 2008

This guide gives an overview of the Scripting System and what is available in order to write scripts for Altium Designer.

The scripting system in Altium Designer gives you the ability to create and run scripts to automate specific tasks. Altium Designer’s script editor, debugger and scripting panels work together to help you write and debug your scripts easily.

Figure 1: Altium Designer, a Script Code/Form window with Object Inspector and Tool Palette panels.

Scripting allows you to generate custom netlists, add or enhance some functionality in PCB or Schematic editors and more.

Features of the Scripting System The scripting system is composed of two main parts; the editor and the debugger. Scripts can be saved in a script project or in a design project.

Script Projects and Scripts Scripts can be saved in script or design projects. Routines from any script in a project are accessible to other scripts within the same project. There are different script languages available to write scripts in Altium Designer.

Scripting EditorThe scripting editor features a text editor with many options to setup the editing environment and syntax coloring.

Scripting Panels The scripting system features many panels to help you code your script quickly.

GU0120 (v1.7) April 21, 2008 1


Scripting Debugger If your script has an error when it is being executed, an error dialog appears with a concise error message. You have the ability to preview variables in the watches window, trace code and control the execution of the script with the Script Debugger.

Several Scripting Languages Choose one of the scripting languages (DelphiScript, EnableBasic, VB Script, Java Script and TCL) to write and use a script in Altium Designer.

Application Programming Interfaces are supported Altium Designer’s Run Time Library of Application Programming Interfaces and a subset of Borland Delphi’s Run Time Library are accessible in scripts. This means with the APIs, you have the ability to modify a design document and its design objects in Altium Designer.

For more information on using different APIs in scripts, refer to the Using the Altium Designer RTL document.

Using Commands in Scripts Commands or parametric processes (server/client processes) can be used in scripts to execute high level commands such as closing all documents in one go.

Script Examples for Altium Designer To learn more about the scripting system and executing scripts, the example script projects are located in the Examples\Scripts folder of your installation.

For more information on scripts, refer to the Script Examples Gallery Reference.

For tutorials on how to use scripts in Altium Designer, refer to the Getting Started With Scripting and Building Script Projects tutorials.

Scripting Documentation Consult the Scripting Resources from the Knowledge Center panel as shown in the figure below.

Figure 2: Knowledge Center with Tool Palette Panel information.

Navigate to the Scripting resources via Configuring the System » Scripting in Altium Designer from the Knowledge Center panel.

2 GU0120 (v1.7) April 21, 2008


Setting up the Script Editor Invoke the Preferences dialog from the Tools » Editor Preferences menu in the Text Editor / Script Editor. By default, the Preferences dialog opens the General tab of the Text Editors folder.

General Properties of the Script Editor The General tab of the Preferences dialog allows you to set up your editing requirements for scripts, how you find strings, how you tab and indent characters and how you map keys plus a number of advanced options.

Figure 3: Text Editors - General Tab

GU0120 (v1.7) April 21, 2008 3


Color Properties of the Script Editor The Colors in the Preferences dialog allows you to set up the Script Editor for syntax coloring of the scripting language of your choice and set up the color of the elements within the script editor. For example, black for the background, white for the comment keyword and so on.

Figure 4: Text Editors - Colors page.

4 GU0120 (v1.7) April 21, 2008


Display Properties of the Script Editor The Display tab in the Preferences dialog allows you to configure the visual features of scripts such as displaying right margins and line numbers, syntax highlighting and code outlining. You can use the What’s This Help by clicking on the question mark icon in the top right corner of the title bar and then click on a control such as a button or a drop down list to obtain information for that control.

Figure 5: Text Editors - Display page.

GU0120 (v1.7) April 21, 2008 5


Writing Scripts Before we can start writing scripts successfully, we need to understand the following terms:

• 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

• Processes are command strings that you can use to execute Altium Designer commands in your scripts

• Object Interfaces are special object interfaces that you can use to extract and modify data on design documents from your scripts.

Different Script Languages There are five different script languages available in Altium Designer; the script file extension identifies which language is being used: DelphiScript (*.pas) EnableBasic (*.bas), VisualBasic Script (*.vbs), JavaScript (*.js) and TCL (*.tcl).

The scripting engine is written in Borland Delphi, and the Tool Palette panel is based on the Borland 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. Navigate to the Scripting resources via Configuring the System » Scripting in Altium Designer from the Knowledge Center panel.

Projects and Scripts You can store a script in a project of any type in Altium Designer. All scripts in a project are visible, that is, any procedure / function from any script in the same project are accessible to a different script from the same project. Therefore it is important to keep the variable and method names unique in scripts in the same project.

It is advisable to move all the common procedures/functions that are used in different scripts to a one new script within the same project. This allows these procedures and functions in this new common script to be reused easily for different script projects.

Two Script Types

Script Units A script unit is a script document with specific language syntax, for example DelphiScript.

Figure 6: A DelphiScript Unit with DelphiScript code.

Script Forms A script form is a window that can host different kinds of controls such as buttons, memos and list boxes which can have event handlers. A script form has two views represented by the Code and Form tabs – you will notice these tabs at the bottom of this script document.

6 GU0120 (v1.7) April 21, 2008


Figure 7: A DelphiScript Form with a Code and a Form tab.

Using Installed Projects Installed Projects allow scripts from a local project of the same type (DelphiScript, EnableBasic, VBScript and JScript) to routines from “global” scripts in Installed Projects. To add a scripting project in the Installed Projects from the Preferences dialog, click DXP » Preferences and click on the Scripting System item and the Installed Projects list box appears where you can add or delete script projects

Every time you invoke the Select item to Run dialog, these installed script projects (even if they are not loaded in Altium Designer) will appear along with other script projects currently open in the Projects panel.

GU0120 (v1.7) April 21, 2008 7


Figure 8: Installed Projects for global script projects.

Creating New Scripts To create a new script in your project, you can choose a script based on a particular scripting language. The available units and forms are:

• DelphiScript Unit

• DelphiScript Form

• VB Script Unit

• VB Script Form

• Java Script Unit

• Java Script Form

• TCL Script Unit

• Enable Basic Script Unit.

Adding New Scripts to a Script Project You can add new scripts to any design projects including scripting projects (with a *.PrjScr extension). Script projects are used to store a collection of scripts.

To add a new script, first open a script project, right click on this project in the Projects panel, a pop up menu appears. Click on the Add New to Project item and you can add one of the script units or forms to the project.

8 GU0120 (v1.7) April 21, 2008


Figure 9: Adding a script to the Script Project.

Adding New Scripts to a Design Project You can create a new script or attach an existing script to a design project such as a PCB project (*.PrjPCB).

Navigate to the File » New » Script Files menu and choose one of the following script types and then a new script appears in the currently focused project.

Figure 10: Adding a new script to a design project other than a script project

GU0120 (v1.7) April 21, 2008 9


Referencing Different Scripts from the same Script Project A script can have access to any global variables in any script within the same project. A procedure in one script can call another procedure in another script within the same script project.

It is important to keep your global variables to a minimum and have unique names.

Adding Existing Scripts to a Project You can add existing scripts to a script project, to do this right click on a project (*.PrjScr) in the Projects panel, a pop up menu appears, click on the Add Existing to Project item.

The Choose Documents to Add to Project dialog appears. You can multi-select as many scripts you want to add into the script project. For other design projects, change the Files of type to All files so you can choose script files.

Executing a Script in Altium Designer

Running a Script in the Text Editor Scripts are run from the Text Editor when a design document is not required for the script to work with. You can configure the Run command in the Text Editor to point to a script and execute it. Every time you click on the Run button from the Text Editor menu or press the F5 short cut key, the scripting system executes the script pointed to by the Set Project Startup Procedure item.

Figure 11: Assigning a procedure name to the Set Project Startup Procedure menu item.

You can change the start up procedure by clicking on the Set Project Start Up Procedure item in the Run menu which invokes the Select Item to Run dialog. You can then select which procedure of a script to be set.

Figure 12: Choosing a procedure name for the Set Project Startup Procedure menu item

Note, if a script needs to run on top of a design document (in order to use the editor’s API) then this script will not work in the Text Editor. For example a PCB based script that needs to run on a PCB document for example will not work in the Text Editor.

Press the Stop button to stop a script if it is not working.

10 GU0120 (v1.7) April 21, 2008


Running a Script Repeatedly in the Text Editor To run a script repeatedly in the Text Editor, assign the script to the Set Project Startup Procedure item from the Run menu of the Text Editor server. Click on the Run button or press F5 to execute this script. To run a different script, you will need to re-invoke the Set Project Startup Procedure from the Run menu and assign a new script.

Executing a Script on a Design Document in Altium Designer There are three methods available to execute a script. These methods are necessary if you wish to run a script on a server specific document such as PCB or Schematic documents.

• Using the Select Item to Run Dialog to Execute Scripts

• Using the Run Process Dialog to Execute Scripts

• Using the Filter Panel to Execute Scripts

Using the Select Item To Run Dialog to Execute a Script Click on the Run Script item from the DXP menu, the Select Item To Run dialog appears with a list of scripts with their respective procedures (parameter-less procedures/functions only appear).

Figure 13: Select Item to Run dialog allows you to choose and run a script

Note, you can also click on a script unit filename within this Select Item to Run dialog and the functionless/procedureless Begin End block within the script gets executed. See code example below:

DelphiScript unit Var

Begin

//script here with no function/procedure

A := 50;

ShowMessage(IntToStr(A));

End.

Now, only parameter-less functions and procedures for each script of an opened project only appear in the Select Item to Run dialog. It is a good idea to write the functions in scripts so they will appear in this dialog while the other functions with parameters do not appear in this same dialog.

When you are working in an editor such as PCB Editor, you can assign the script to a process launcher and use it to run a specified script easily. See the section, Assigning a Script to the Menu, Toolbar or Key.

Using the Run Process Dialog to Execute a Script Invoke the Run Process dialog from DXP menu and execute the ScriptingSystem:RunScript process in the Process field. Specify the script parameters - the ProjectName parameter which is the path to the project name and the ProcName parameter to execute the specified procedure from a specified script in the Parameters field. You need the following parameters for the ScriptingSystem:RunScript process to execute a specified script.

Process ScriptingSystem:RunScript

Parameters ProjectName (string)

ProcName (string)

GU0120 (v1.7) April 21, 2008 11


Figure 14: Full Parameter list for the Run Process dialog.

For example, to run a DXPVersion script in Altium Designer from the Run Process dialog, we need to have ScriptingSystem:RunProcess in the Process: field and ProjectName = C:\Program Files\Altium Designer \Examples\Scripts\Delphiscript Scripts\Dxp\DXPVersion.PrjScr | ProcName = DXPVersionUnit.pas > DXPVersion in the Parameters: field.

Using the Filter panel to Execute Scripts You can execute scripts with specially defined functions in the Expression (Query) window of the PCB or Schematic Filter panel for Schematic and PCB documents. These scripts need to go in a global project that is installed in the Installed Projects list. These scripts need to have functions that return a boolean value and contain query statements such as IsComponent for PCB, or IsBus for Schematic.

Function HighlightPadsWithZeroHoleSize : Boolean;

Begin

Result := IsComponentPad and (Holesize = 0);

End;

Save the script in a project that is in the Installed Projects list. Type the function name in the PCB Filter panel, and then click the Apply button to execute the function.

Assigning a Script to the Toolbar, Menu or Shortcut Key You can assign a script to a toolbar, menu or shortcut key, making it possible for you to run the script over a current PCB or Schematic document. You will need to specify the full path to a project where the script resides and specify which unit and procedure to execute the script. There are two parameters in this case: the ProjectName and the ProcName. The ProjectName parameter has the full path to the project where the script resides. For the ProcName parameter, you need to specify the script filename and the main procedure in this script. The format is as follows: ProcName = ScriptFileName > ProcedureName. Note the GreaterThan (>) symbol is used between the script file name and the procedure name.

Assigning a Script to the Toolbar 1. Make sure you have a design document open in Altium Designer. As an example, open a PCB document and then double

click on the PCB menu or select DXP » Customize menu, the Customizing PCB Editor dialog appears

12 GU0120 (v1.7) April 21, 2008


Figure 15: The Customizing PCB Editor dialog

2. Click the New button of the Customizing PCB Editor dialog 3. Choose ScriptingSystem:RunScript process in the Process field of the Edit Command dialog

4. Enter ProjectName = C:\Program Files\Altium Designer\Examples\Scripts\DelphiScript Scripts\General\HelloWorld.PrjScr | ProcName = HelloWorldDialog>RunHelloWorld text in the Parameters field of the Edit Command dialog. This points to the HelloWorld dialog script

5. Name this new command in the Caption field. You can also enter text for the Description field and assign a new button image using the BitMap File field. In this case, the Caption name is PCBScript as shown below. Click the OK button

Figure 16: Edit Command dialog – Process and Parameter fields.

6. The new commands appear in the [Custom] category of the Categories list in the Customizing PCB Editor dialog. Click on the [Custom] entry from the Categories list, the PCBScript command appears in the Commands list of this dialog

GU0120 (v1.7) April 21, 2008 13


Figure 17: New scripts are saved in the Custom categories on the left of this dialog

7. Drag and drop the new PCBScript command onto the PCB toolbar from the Customizing PCB Editor dialog. The command appears on the toolbar as shown below.

Figure 18: Dragging a new script to the Toolbar.

8. You can then click on this new command and the HelloWorld dialog appears.

14 GU0120 (v1.7) April 21, 2008


Figure 19: Script dialog appears after clicking on the script icon on the PCB Toolbar

Assigning a Script to a Menu Make sure you have a PCB document open in Altium Designer. As outlined in the Assigning a Script to the Toolbar section, double click on the PCB menu or select DXP » Customize menu, the Customizing PCB Editor dialog appears.

1. Click the New button of the Customizing PCB Editor dialog 2. Choose ScriptingSystem:RunScript process in the Process field of the Edit Command dialog

3. Enter PCBScript as the Command Name in the Caption field 4. Enter ProjectName = C:\Program Files\Altium Designer\Examples\Scripts\DelphiScript

Scripts\General\HelloWorld.PrjScr | ProcName = HelloWorldDialog>RunHelloWorld text in the Parameters field of the Edit Command dialog as an example. This points to the HelloWorld dialog script

5. The new commands appear in the [Custom] category of the Categories list in the Customizing PCB Editor dialog. Click on the [Custom] entry from the Categories list, the PCBScript command appears in the Commands list of this dialog

6. Drag and drop the new PCBScript command onto one of the PCB menus from the Customizing PCB Editor dialog. The command appears on the View menu as shown below.

Figure 20: Dragging a new command (that points to the script) to the Menu.

Assigning a Script to a Shortcut Key You can assign scripts to short cut keys. As outlined in the Assigning a Script to the Toolbar section and as an example, make sure you have a PCB document open in Altium Designer first. Double click on the PCB menu or select DXP » Customize menu, the Customizing PCB Editor dialog appears. 1. Click the New button of the Customizing PCB Editor dialog

GU0120 (v1.7) April 21, 2008 15


2. Choose ScriptingSystem:RunScript process in the Process field of the Edit Command dialog

3. Enter QueryBoard as the Command Name in the Caption field 4. Enter ProjectName = C:\Program Files\Altium Designer\Examples\Scripts\DelphiScript

Scripts\PCB\PCB_Scripts.PrjScr | ProcName = QueryBoard>Query_Board text in the Parameters field of the Edit Command dialog. This points to the Query Board script

5. Assign a short cut key in the Primary and another key for the Alternative fields of the Edit Command dialog. Note, if you attempt to assign a key to the Primary shortcut and this key is already in use, the Currently in use by: field will show which command has already owned this shortcut

Figure 21: The QueryBoard is assigned to two shortcut keys; Shift + Q and Alt +Q.

6. Close this Edit Command dialog to get back to the Customizing PCB Editor dialog with the QueryBoard command in the Commands list. Drag this QueryBoard command to the PCB Shortcuts menu as shown below. You can then use the short cut keys to launch the script.

Figure 22: Dragging the QueryBoard script command to the PCB Shortcuts menu.

Assigning a Script to a Pop up Menu You can assign a script to a pop up menu in one of the editors in Altium Designer. The following example shows how to assign a script to the menu in the PCB Editor.

16 GU0120 (v1.7) April 21, 2008


1. As an example, to execute the QueryBoard script from a pop up menu in the PCB Editor, double click on the PCB menu bar or select DXP » Customize. The Customizing PCB Editor dialog opens, click the New button to invoke the Edit Command dialog. Again make sure there is a PCB document open first (any other document kind will do but the Customizing [ServerName] Editor dialog will reflect the document kind).

2. Insert ScriptingSystem:RunScript in the Process: field, and insert ProjectName = C:\Program Files\Altium Designer\Examples\Scripts\DelphiScript Scripts\PCB\PCB_Scripts.PrjScr | ProcName = QueryBoard>Query_Board in the Parameters: field.

3. Enter Query Board script for the Caption field and Query the board for board settings for the Description field. Click the OK button and this command appears in the [Commands] item within the Categories list of the Customizing PCB Editor dialog.

4. Drag this new command (and the cursor changes to a different cursor) from the list of Commands on the Customizing PCB Editor dialog to the Help menu on the PCB menu, once the Help menu appears, drag to the Popups submenu and again drag further to the Right Mouse Click Free Space or Right Mouse Click Primitive submenu. Drop the command somewhere on this submenu.

Figure 23: Dragging the Query Board Script to the Popups menu item in the Help menu.

Alternatively drop the command in the Right Mouse Click Free Space or Right Mouse Click Primitive entry within the Categories section of the Customizing PCB Editor dialog.

Figure 24: Query board on the pop up menu.

For a tutorial on the customizing the user interface of Altium Designer, refer to the Customizing the Altium Designer Resources document.

GU0120 (v1.7) April 21, 2008 17


Using Altium Designer Object Interfaces in a Script The Altium Designer Run Time Library has Object Interfaces representing Altium Designer objects. These Object Interfaces are available to use in scripts. For example, you can update design objects on Schematic and PCB documents using Schematic Interfaces and PCB Interfaces respectively.

Object Oriented Scripting System All objects in Altium Designer are represented by their object interfaces.

• Objects have Properties. A property is an attribute that you can modify. For example the width property of a track object

• Objects have Methods. A method is something an object can do. Objects can be selected and objects can talk to other objects. For example, the server object has an Open method

• Objects can have Events. Events are actions that user performs while using a dialog in Altium Designer. The Scripting system deals with events using event handlers. An action by the user on the dialog (script dialog) triggers an event handler in your script.

Object Interfaces In scripts, you use an Object Interface that references an existing object rather than creating instances of the objects. All objects of the same type (for example PCB tracks) have the same Object Interfaces; in this case, all track objects in the PCB editor are represented by IPCB_Track interfaces.

Unique Object Interfaces How do we know which object interface is which? Each object interface that represents an existing object has its own object address in memory. In this case, all PCB objects’ addresses are represented by the TPCBObjectHandle type. A PCB object interface has the I_ObjectAddress method.

All Schematic objects’ addresses are represented by the TSchObjectHandle type. A Schematic interface has the Function I_ObjectAddress : TSCHObjectHandle; method.

Accessing to Altium Designer Objects

PCB Objects Invoke the PCBServer function in your script which returns the IPCB_ServerInterface interface. This Object Interface obtains the PCB editor server object, you can then get the current PCB document, extract data from PCB objects and invoke their object’s methods.

Schematic Objects Invoke the SchServer function in your script which returns the ISch_ServerInterface interface. This Object Interface obtains the Schematic editor server object, you can then get the current schematic document, extract data from Schematic objects and invoke Schematic object’s methods.

Workspace Manager Objects The IWorkSpace interface is the main interface representing the WorkSpace Manager object. The IWorkSpace interface deals with projects, documents and objects in the open documents. To use WorkSpace interfaces, the project needs to be compiled first, refreshing all the linkages and nets up to date.

Object Interfaces Conventions and Examples Interface names as a convention have an I character prefixed to their name, for example IPCB_Board represents an interface for an existing PCB document. A PCB interfaces example is shown below.

PCB Object Interfaces Example Var

Board : IPCB_Board;

Via : IPCB_Via;

Begin

18 GU0120 (v1.7) April 21, 2008


// obtains the PCB server and the PCB document

Board := PCBServer.GetCurrentPCBBoard;

If Board = Nil Then Exit;

// Create a Via object using the PCBObjectFactory method.

Via := PCBServer.PCBObjectFactory(eViaObject, eNoDimension, eCreate_Default);

// Setup via object and place on PCB at 7500,7500

Via.X := MilsToCoord(7500);

Via.Y := MilsToCoord(7500);

Via.Size := MilsToCoord(50);

Via.HoleSize := MilsToCoord(20);

// Via is a dual layer object.

Via.LowLayer := eTopLayer;

Via.HighLayer := eBottomLayer;

// Put this via on the Board object (PCB document).

Board.AddPCBObject(Via);

End;

Object Models in Altium Designer Object Models are implemented in Altium Designer so that your scripts have the access to them. For example, you can use Work Space Manager Object Model to compile a PCB project and extract a Protel format netlist. You can use PCB Object Model to massage PCB objects on a PCB document, and so on. You can use any scripting language to access Object Models.

Refer to the Using the Altium Designer RTL guide for details on how to use design objects and their interfaces in your scripts. Navigate to the Scripting resources via Configuring the System » Scripting in Altium Designer from the Knowledge Center panel.

Exploring Example Scripts Check out the scripts in \Examples\Scripts\folder of your installation to see Altium Designer Object Interfaces and functions being used in scripts.

Debugging Scripts The Script Debugger provides you with full featured debugging environment. A script that compiles correctly doesn’t always work as planned. This can be due to errors in logic, invalid assumptions, misplaced grouping operators and typographical errors.

Script Errors The Delphi Script’s debugger permits you to intercept exceptions, trigger break points, evaluate expressions, and more. Script Errors can be one of the following:

• Design Time Errors

• Compile Time Errors

• Run Time Errors

• Logical errors.

GU0120 (v1.7) April 21, 2008 19


Figure 25: This script has an undeclared identifier error. The PCBServer function is misspelt as PCBSrver.

Debugging a Script When you encounter errors in the script, you will debug the script to resolve the errors. The Script Debugger provides ways to find and resolve errors. To exit debugging mode, you can either finish executing the script or stop the script to edit it before re-running this script. The process of executing a script one line at a time is referred to as tracing or script stepping. The Script debugger provides commands related to tracing: stepping into (Run » Step Into) and stepping over (Run » Step Over). This allows you to trace the script and watch certain expressions when you are debugging a script.

Step Into Command

. Figure 26: Various Debugging Commands in the Run menu

The Step Into process executes script one statement at a time. If the statement being executed calls another procedure, stepping into that statement transfers control to the first line in the called procedure. The blue line on a script indicates the current line where the script is up to.

Step Over Command The Step Over process is similar to Step Into, except that if the current statement is a call to another procedure, the entire called procedure is executed without stopping rather than tracing through the called procedure. For example, stepping over the statement, ProcB; in the previous procedure executes procedure ProcB and stops at the next line ProcC; in Procedure ProcA. This is useful if we are certain that the Procedure ProcB is not the cause of our problem and we don’t want to trace through that procedure line by line.

Stopping a Script The Scripting Debugger helps you to identify errors in your scripts. Common errors include errors in logic, invalid assumptions, misplaced grouping operators and typographical errors. An example is shown below with a missing terminating character ; and this is flagged as an error.

Figure 27: An error in the script.

When an error dialog is displayed, close this dialog by clicking the OK button and stop the scripting system by clicking on the Stop button on the menu or pressing the keys, Ctrl+ F3.

There are situations when a script is locked in an infinite loop for example that Altium Designer becomes non-responsive. To overcome this problem, press Ctrl + Pause/Break shortcut keys to break the script’s loop.

Scripting Panels Debugging panels are available for use during scripting: Breakpoints, Call Stack and Watch List Panels. These are accessible through the View Menu (View » Workspace Panels » Script). You can also choose to display these panels by clicking on the Script button on the bottom right of the design window and choosing one of the available items. There are various debugging commands in the Text Editor. There is also the Evaluate dialog which displays the object’s property value during a breakpoint or an error mode.

20 GU0120 (v1.7) April 21, 2008


Figure 28: Various Scripting Panels available.

• The Tool Palette, Object Inspector and the Form Designer all work closely to help you build a user interface for your script

• The Code Explorer, Watch List, Breakpoints and Call Stack panels all work closely to help you debug your script.

Breakpoints Panel By default, script execution pauses each time a breakpoint is encountered. A breakpoint defined on a line in a script is marked by a red line.

A way to get ordered feedback on the errors that may be occurring in your script is to control the script execution. Controlling scripts with breakpoints allow you to execute single lines of code, an entire function or a specified script block.

Breakpoints are stored in the project that the script is associated with.

When you create a breakpoint, it must be on a statement line of script. Any breakpoints set on blank lines, commented lines or other non statements will be ignored and treated as invalid. Breakpoints can be accessed using the Breakpoints Panel so you can easily locate all of your set breakpoints without going through your script to find them.

Figure 29: Breakpoints Panel. You can add new breakpoints by right clicking on the Breakpoints panel and selecting the Add menu item from the pop up menu.

Use the Ctrl+Alt+B short cut keys to show up the Breakpoints panel.

Call Stack Panel The Call Stack panel permits you to inspect the chain of procedure / function invocations that resulted in the execution of the current line of script in the debugger.

Figure 30: Call Stack Panel with the chain of procedures invocations.

Use the Ctrl+Alt+S short cut keys to show up the Call Stack panel.

Code Explorer Panel The Code Explorer panel displays the variables, procedures and functions (along with their parameters) for a currently focused script. This panel serves as a quick reference to what variables and procedures/functions are used in the script.

GU0120 (v1.7) April 21, 2008 21


In the Code Explorer Panel, global variables used in a current script are marked as aqua boxes under the Variables folder, functions used are marked with pink boxes along with yellow flash, procedures used are marked as pink boxes. Variable Parameters used in procedure/functions are marked with pink and blue boxes.

Figure 31: Code Explorer Panel with available variables and procedures and functions.

Watch List Panel Use this handy panel to track the values of values or expressions as you step over or trace into your script code. As you step through your script, the value of the watch expression will change if your script updates any of the variables contained in the watch expression.

Figure 32: Watch List Panel with expressions and their values from the current script.

Use the Ctrl+Alt+W short cut keys to show up the Watch List panel.

Object Inspector Panel The Object Inspector panel is a snapshot of the attributes (properties and events) of the current component on the form or the form itself. You can change an object’s properties and define new event handlers for this object (windowed controls only).

Figure 33: Object Inspector Panel with Properties and Events for the current script form.

22 GU0120 (v1.7) April 21, 2008


Components have three items: Properties, Events and Methods. Properties and Events are displayed for the currently focused component such as a button on the tabs of the Object Inspector panel. The methods are “invisible” but available for use in the scripts. For example, if you wanted to make a button invisible, you invoke the Button’s Hide method in your script.

Figure 34: Tool Palette panel with various components.

Tool Palette Panel A range of controls are available on the Tool Palette panel categorized by different tabs. You can place components on a script form by double clicking the component on the Tool Palette panel or clicking the component once and then clicking on the form where you want the component to appear. To exit component placement mode, click on the Arrow button next to the Categories button.

The Tool Palette panel is equivalent to the Borland Delphi’s Component palette and in fact is a subset of the Borland Delphi’s Component palette.

Tool Palette Tab name

Description

Standard Standard controls and menus

Additional Specialized controls

Win32 Common Window controls such as RichEdit, TrackBar and Coolbar components

System Components and controls for system level access, including timers, multimedia and DDE

Dialogs Commonly used dialogs such as Open dialog, Font dialog and Print dialog components.

Win 3.1 Old style win3.1 components.

Altium Standard Standard controls and menus but with the Windows XP look and feel.

GU0120 (v1.7) April 21, 2008 23


Using Various Scripting Tools The scripting system provides various tools to help you write scripts. You can interactively step through scripts line by line, inspect variables and objects and set breakpoints on one or many lines in the script.

Script Evaluate Feature When your script is stopped due to a breakpoint or an error, you can copy an expression (a script statement) from your script to the Expression field of the Evaluate dialog.

Click the Evaluate button from the Text Editor menu or press the Ctrl+F7 shortcut keys to see the resultant value for this expression. For example type in Pad.Name expression (IPCB_Pad interface has a Name property).

Figure 35: Script in breakpoint mode with the Evaluate dialog.

Scripting System’s Code Completion Feature The Scripting System supports the Code Completion feature. When you type an object interface name from the Altium Designer Run Time Library and a dot after this name, after a brief pause, the list of properties and methods for that object are displayed in a pop up menu. For example, just after the PCBServer function in your script, type in the dot character ‘.’ and after a brief pause, the Code Completion pop-up window appears with a list of properties and methods for this PCBServer function.

Figure 36: Code Completion Pop up.

Use the Ctrl + Space shortcut keys to see available properties or methods for the interface object.

Script Parameters Feature You can use the Script Parameters feature to inspect which parameters are used for a particular function/procedure/method of an object interface.

For example just after the method in your script, type in ‘(‘ and the Code parameters pop-up window appears with a list of parameters for this method.

24 GU0120 (v1.7) April 21, 2008


Figure 37: Script Parameters Pop up.

Use the Shift + Ctrl + Space short cut keys to display the Script parameters pop-up message.

Script Templates Feature You can use the Script Template feature to automatically generate a complete statement for you when you press the Ctrl+J shortcut keys. You can also invoke Script Templates using Tools » Show Code Templates command. A pop-up list of available code templates appears depending on which scripting language is being used.

Select a code template from the list by clicking on your intended statement.

Figure 38: Script Templates popup.

Script Expression ToolTip The Script Expression ToolTip displays data values for the variable that the cursor is hovering over.

Figure 39: Script Expression ToolTip popup.

Script Symbol Insight ToolTip The Symbol Insight ToolTip feature shows the variable type when the cursor is hovering over the variable. This information can also be accessed by pressing the Ctrl key.

Figure 40: Script Symbol Insight ToolTip popup.

Using Bookmarks You can use the Bookmarks in your scripts to jump to a statement quickly. You can define up to 10 bookmarks in your script. Each Bookmark is marked by a dark green box with a number in it. Click on the mouse right-hand button on the script to access the Toggle Bookmarks and Goto Bookmarks menu items from the pop up menu to add or delete bookmarks and jump to a specified bookmark respectively.

Figure 41: Using a bookmark to jump to a statement in the script quickly.

Use the Ctrl + Shift 0..9 short cut keys to toggle a bookmark, and Ctrl + 0..9 shortcut keys to jump to an existing bookmark in the script.

GU0120 (v1.7) April 21, 2008 25


Using the To-Do Items Panel You can use the To-Do panel to store items that need to be completed for a project. You can add To-Do Items and you have the ability to define the information, priority, owner and the category for these items.

Figure 42: You can use this To-Do panel to add to do items for your projects.Ca

Click on the System button on the bottom right of design window, and when the pop up menu appears, choose the To Do menu item to display the To Do Items panel.

Scripting System Shortcut Keys

Display Scripting Panels Ctrl + Alt + B Display the Breakpoints panel

Ctrl + Alt + S Display Call Stack panel Ctrl + Alt + W Display Watch List panel Ctrl + Alt + E Display Code Explorer panel Ctrl + Alt + P Show Tool Palette panel Ctrl + Alt + I Show Object Inspector panel

When Editing Scripts When editing scripts in the Text Editor; the shortcut keys are: F3 Find Next dialog appears

F5 Toggle the existing breakpoint on the current script

F9 Run the current script if this script is defined in the Set Project Startup Procedure from the Run menu, otherwise the Select Item to Run dialog appears prompting you to choose which procedure to execute.

Ctrl + F Find Text dialog appears

Ctrl + H Replace Text dialog appears

Ctrl + F4 Close active document

Alt + F4 Close Altium Designer

Ctrl + TAB Cycle through open documents.

Bookmarks Ctrl + Shift + 0-9 Pressing Ctrl + Shift and one of the number keys (0..9) toggles the indexed bookmark on the gutter of the current line of the script (where the cursor is at). Ctrl + 0 -9 Pressing Ctrl and one of the number keys (0..9) jumps to book mark (0..9) of the script.

26 GU0120 (v1.7) April 21, 2008


When Debugging a Script When debugging scripts in the Debugger, the short cut keys are F5 Pressing the F5 key or clicking on the Hand button from the toolbar toggles the breakpoint on the current line of the script. F7 The Step Into process executes script one statement at a time.

F8 The Step Over process is similar to Step Into, except that if the current statement is a call to another procedure, the entire called procedure is executed without stopping rather than tracing through the called procedure.

F9 When the F9 key / Blue Arrow button is pressed, the script is executed depending on where the cursor is at, for example at the beginning of the script or continuing from the point where it was interrupted due to a breakpoint.

Ctrl+F3 When this Stop key/button is pressed, the debugging of the script is halted.

Ctrl+F7 When the key/button or the Evaluate toolbar button is pressed, the Evaluate dialog appears.

Ctrl+F9 When this Run To Cursor key/button is pressed, whenever the cursor is on the script, the script is executed and then it is paused at where the cursor is located.

Where to Go Next? There are tutorials to bring you up to speed in scripting. There are API documents with different Object models to explore. There are many examples in the \Examples\Scripts folder of your installation.

For more information on scripts examples, refer to the Script Examples Gallery Reference.

For tutorials on how to use scripts in Altium Designer, refer to the Getting Started With Scripting and Building Script Projects tutorials.

For more information on using different APIs in scripts, refer to the Using the Altium Designer RTL document.

GU0120 (v1.7) April 21, 2008 27


Revision History

Date Version No. Revision

01-Dec-2004 1.0 New product release

26-Apr-2005 1.1 Updated for Altium Designer

08-Jul-2005 1.2 Revised

03-Oct-2005 1.3 Changed from technical reference to a guide.

09-Dec-2005 1.4 Updated for Altium Designer 6

07-May-2007 1.5 Revisions made to the text.

11-Feb-2008 1.6 Updated for Altium Designer 6.9.

21-Apr-2008 1.7 Updated Page Size to A4.

Software, hardware, documentation and related materials:

Copyright © 2008 Altium Limited.

All rights reserved. You are permitted to print this document provided that (1) the use of such is for personal use only and will not be copied or posted on any network computer or broadcast in any media, and (2) no modifications of the document is made. Unauthorized duplication, in whole or part, of this document by any means, mechanical or electronic, including translation into another language, except for brief excerpts in published reviews, is prohibited without the express written permission of Altium Limited. Unauthorized duplication of this work may also be prohibited by local statute. Violators may be subject to both criminal and civil penalties, including fines and/or imprisonment. Altium, Altium Designer, Board Insight, Design Explorer, DXP, LiveDesign, NanoBoard, NanoTalk, P-CAD, SimCode, Situs, TASKING, and Topological Autorouting and their respective logos are trademarks or registered trademarks of Altium Limited or its subsidiaries. All other registered or unregistered trademarks referenced herein are the property of their respective owners and no trademark rights to the same are claimed.

28 GU0120 (v1.7) April 21, 2008