Scripting System Overview and Setup

Old Content - visit altium.com/documentation
Modified by Rob Evans on Feb 15, 2017
Contents

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.


Altium Designer showing Script Code and Form windows with the Object Inspector, Code Explorer and Tool Palette panels. Scripting allows you to generate custom netlists, add or enhance functionality in PCB or Schematic editors and more.

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.

For detailed information on using different APIs in scripts, refer to the Altium Designer API documentation.

 

Scripting Concepts

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 *. PAS file that contains has event handlers and procedures/functions, and a *.DFM file 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.

The Altium Designer Scripting documentation mainly focuses on the DelphiScript and VBScript language sets. The DelphiScript language set is based on Embarcadero Delphi and VBScript is based on Microsoft Scripting technology.

For information on the differences between DelphiScript and Object Pascal (used in Delphi) refer to the DelphiScript reference document.
For more information on VBScript, refer to the Microsoft VBScript documentation.

 

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.

To learn more about the scripting system and executing scripts, see the example script projects that are available for download.
For information on other script examples, refer to the Script Examples Gallery Reference.
For a practical rundown on working script examples in Altium Designer, refer to Writing Scripts and A Script Analysis.

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 DelphiScript Hello World project open in the Projects panel..

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.


The quick and simple way to run a opened example script.

 

Scripting System Setup

Editor Preferences

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.

General Preferences

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.


The Text Editors - General Tab

For detailed information on these preferences see the Text Editors - General reference.

Color Preferences

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 Editors - Colors page.

For detailed information on these preferences see the Text Editors - Colors reference.

Display Preferences

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.


The Text Editors - Display page.

For detailed information on these preferences see the Text Editors - Display reference.

System Preferences

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.


The Scripting System - Global Projects page.

For detailed information on these preferences see the Scripting System - Global Projects reference.

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.


The scripting System - Form Designer page

For detailed information on these preferences see the Scripting System - Form Designer reference.

 

You are reporting an issue with the following selected text and/or image within the active document: