Scripting System Overview and Setup
- Scripting System Features
- Application Programming Interfaces
- Scripting Concepts
- Script Units and Forms
- Altium Designer Script Examples
- Running an Example
- Scripting System Setup
- Editor Preferences
- General Preferences
- Color Preferences
- Display Preferences
- System Preferences
- Global Projects Preferences
- Form Designer Preferences
Parent page: Scripting
The Altium Designer scripting system provides all the tools and features needed to create scripts that automate tasks in Altium Designer.
Altium Designer's script editor, debugger and scripting panels work together to help you write and debug your scripts easily. A script can be run directly from the script editor, or assigned to a menu, toolbar or hot key so it can be applied to the current document (for example a PCB layout) at any time.
Scripting System Features
The scripting system is composed of two main parts; the editor and the debugger. The main features are as follows:
Project access - Scripts can be saved in a script or design project. Routines from any script in a project are accessible to other scripts within the same project.
Scripting Editor - The scripting editor features a dedicated text editor with a range of options to setup the editing environment and syntax coloring.
Scripting Panels - The scripting system features a number of panels that help you code and debug scripts quickly.
Scripting Debugger - If a script has an error when it is being executed, a 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.
- Scripting Languages - Altium Designer scripts can be created in a number of scripting languages: DelphiScript, EnableBasic, VB Script, Java Script and TCL Script.
Application Programming Interfaces
Altium Designer's Application Programming Interfaces (APIs) and a subset of Delphi's Run Time Library are accessible in scripts. Using the APIs in scripts provides the ability to modify an Altium Designer design document and its design objects.
Commands or parametric processes (server/client processes) can be used in scripts to execute high level commands such as closing all documents in one step.
The basic concepts and terms that relate to scripting in Altium Designer are outlined below:
- DXP (Design Explorer) denotes Altium Designer's supporting technology platform.
- The Altium Designer DXP Application Programming Interface (API) offers a collection of sub-APIs and a subset of the Delphi Run Time Library.
- Each API represents an editor in Altium Designer. For example the PCB editor has its PCB API, the Schematic editor has its Schematic API and the Project Manager has its Workspace manager API and so on
- Each API has an Object Model which consist of Object Interfaces. Each Object Interface can consist of Methods and Properties (but no variables).
- The Object Interfaces represent actual design objects in Altium Designer. Object interfaces can be used in scripts (with any language set supported by the scripting system) to extract and modify data from opened design documents in Altium Designer. To deal with PCB documents and objects for example, the PCB Object Model is used in a script, and to deal with Projects and documents in general, the Workspace Manager Object Model would be used.
- Methods of Object Interfaces are the actions an Object Interface can perform.
- Properties of Object Interfaces represent the data contained in the object that is represented by the interface.
- Before a script that uses the API Object Models is run, its target design document needs to be open in Altium Designer.
Script Units and Forms
Script Projects support two script document types – Script Units and Script Forms. Script Units allow you to write standalone procedures and functions. Script Forms allow you to build dialogs with controls and event handlers as well as procedures and functions.
- A Script Form is a form unit that is supported by the script. When a form is active in Altium Designer it represents a dialog window.
- A Script Form has two views – the Script Code view and the Script Form view. The Script Code view contains event handlers and procedures/functions. The Script Form view represents a dialog form (of different types) and has controls and their associated event handlers.
- A Script Form has two associated files. A
*. PASfile that contains has event handlers and procedures/functions, and a
*.DFMfile that has details of the script form itself plus its components and their locations.
- A component is a visual or non visual control object (placed from the Tool Palette panel) that accepts user input, such as a mouse click or a sequence of entered characters. During design, the Object Inspector panel can be used to manipulate components on a Script Form. The components can be used in any Script Form in any language set supported by the Scripting system.
- A component (control) has methods, properties, and events that can be used by a Script Form.
- Methods are the actions an object can perform.
- Properties represent the data contained in the object that can be accessed or modified.
- Events are conditions a component on a Script Form can react to.
- A Script Form has event handlers that process captured conditions, such as when a form button is clicked.
Altium Designer Script Examples
Example and reference scripts are a helpful resource for understanding how object interfaces, methods, processes, properties and components are applied in scripts. They can also be used as the basis for your own script projects.
Running an Example
To quickly run a script example in Altium Designer, first open an example project or an individual script file from one of the example script folders — for example, the simple 'Hello World' project (
HelloWorld.PRJSCR) from the
Scripts\Delphiscript Scripts\General folder.
The project contains two version of the Hello World script, where the second (
HelloWorlDialog.pas) demonstrates the basic use of a Form unit. Double-click a script name to open and inspect the script in the editor — note that a script can be run without it being open in the editor.
To run one of the scripts, select DXP » Run Script from the main menu and 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.
Scripting System Setup
To access the script editor options, open the Preferences dialog from the Tools » Editor Preferences menu in the Text/Script Editor, or through the DXP » Preferences menu. By default, the Preferences dialog opens the General page under the Text Editors folder.
The Text Editors - General page of the Preferences dialog allows you to set up your script editing requirements, such as the string search behavior, how lines are tabbed and indented, how keys are mapped, plus a number of advanced options.
For detailed information on these preferences see the Text Editors - General reference.
The Text Editors - Colors page of the Preferences dialog allows you to configure the Script Editor's syntax coloring for 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.
The Text Editor - Display page of 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.
To access the scripting system options, open the Preferences dialog via the DXP » Preferences menu and navigate to the Scripting System folder.
Global Projects Preferences
The Scripting System - Global Projects page of the Preferences dialog list script projects that are available (installed) in Altium Designer. Script projects can installed, removed or reordered.
Form Designer Preferences
The Scripting System - Form Designer page of the Preferences dialog provides the grid and component designator options for a scripting form document.