Running Scripts in Altium Designer
Parent page: Scripting
While the Altium Designer Scripting system provides the means to create sophisticated automated tasks for Altium Designer, the resulting scripts also need to be easily accessible during the design process. For example, a script created to perform a complex set of operations while editing a PCB should be readily available in the PCB Editor itself, where it can be executed with a mouse click or two.
Altium Designer caters for this need by allowing a script to be assigned to a process launcher, and thereby a command that can be assigned to a server Menu, Toolbar and Shortcut.
To briefly recap, when open in the script editor, a script can be executed using the editor's Run command or via the DXP » Run Script menu. This requires the script project to be open in Altium Designer, which is not a convenient approach to accessing a script needed during the PCB design process, for example.
A more suitable method to access a frequently used script is to install the project as a Global Project — DXP » Preferences, Scripting System | Global Projects. In this case the project is automatically loaded when Altium Designer starts, and can be executed at any time via the DXP » Run Script menu.
The ideal way to access a script's functionality however, is where it is integrated into Altium Designer's GUI as a menu or toolbar command. This is normally a two step process; implemeting a script as a Command (with optional shortcut), then assigning the Command to a Menu (static or pop-up) or a Toolbar.
Script as a Command
A script can implemented as a server command by harnessing Altium Designer's built in server processes, or more specifically, the
A command represents a performed action and is supported by a process string via a packaged process launcher. In the case of the the
ScriptingSystem:RunScript process, it includes parameters for pointing to a specific script project file, a constituent script file (
*.pas) and a processes within that script.
Altium Designer processes are directly available via the DXP » Run Process menu, where the
ScriptingSystem:RunScript process can be selected and appropriate parameters added to execute the desired script. In the case of the sample HelloWorld script for example, the entries would be as follows:
ProjectName | ProcName > Process
Therefore, depending on the source path to the script the Parameters string would be similar to:
While still not a particularly convenient way to execute a script during the design process, note that running the script as a process avoids the need to directly open the script or have it loaded as a Global Project. The second and more significant advantage of using the process method to run a script is that it can be implemented as an accessible Altium Designer command.
This is done by customizing Altium Designer's menu system, where a script can be assigned to a command for a nominated server.
Create a Command
To assign the HelloWorld script as a command for the PCB editor for example, open a PCB document and select DXP » Customize from the main menu.
To create a new command, click the New button in the Customizing PCB Editor dialog to open the Edit Command dialog where the server process and script path details can be included, as detailed for the Run Process dialog example above.
The dialog also provides entry fields for a command caption, description, shortcut and associated bitmap image (BMP/GIF; 18 x 18 pixels).
With the details complete and the dialog dismissed (OK) the HelloWorld script becomes available as a Custom command for the PCB Editor.
External Application Command
An external application such as the Microsoft Notepad can be launched from Altium Designer through software control. In this case the command process and parameters entries would be:
Text=Begin RunApplication('notepad.exe'); End;
The server process in this case,
ScriptingSystem:RunScriptText, is literally running a sequence of script statements, rather than opening and running a specific script file as outlined above.
The alternative approach is to create a script with a few equivalent lines of code, then create a conventional
ScriptingSystem:RunScript command entry.
Procedure RunNotepad; Begin RunApplication('notepad.exe'); End;
Note that for both approaches to implementing the external Notepad command it is sufficient to just enter
'notepad.exe' as the parameter for
RunApplication, rather than specify the application's full path and filename. Windows applications such as Calculator and Notepad have their paths already specified by the operating system.
To launch an application from Altium Designer that does not have an inherent Windows path, the application's full path and filename need to be specified (in single quotes, to cater for any white space in the path). So to launch a second copy of Altium Designer for example, the
RunApplication process and parameters would be:
RunApplication('C:\Program Files (x86)\Altium\ADxx\DXP.exe') — where xx represents is the Altium Designer version.
Assigning Menu Commands
With a script implemented as a custom server command via Altium Designer's Customizing function (DXP » Customize) as detailed above, it can be assigned to the server GUI by a simple drag and drop process.
To assign a custom command to the PCB editor's main menu or Toolbar menu for example, open the Customizing PCB Editor dialog, locate the custom command and drag it to the desired menu location. Note that a PCB document needs to be open to provide access to the PCB server menus.
With the customizing dialog closed, the new menu command can be accessed at any time in the PCB editor.
Since the new custom command has been assigned to the PCB Toolbar menu it can be seen under the 'PCB Standard' command category in the Customizing PCB Editor dialog.
To remove a command from a menu, open the custom dialog then drag the menu command icon back into the dialog.
A custom command can be assigned to a menu, at any menu depth, using the same drag and drop process described above.
When the server is in customizing mode the menus remain responsive to the mouse pointer, and will expand and contract accordingly. To place a command into the PCB editor's Reports menu for example, drag the command into the menu and down the list where it can be dropped in a suitable position.
With the customizing dialog closed, the new menu command can be accessed from within the Reports menu.
A command can be assigned to a right-click pop-up menu in the same way as described above, with no restriction imposed by the sub-menu depth.
In this example the command is dragged through the menu path of Help » Popups » Right Mouse Click Free Space and dropped in the sub-menu as shown below.
As assigned, the custom Notepad script command becomes available in the PCB editor when right-clicking in free space.
Direct Script Assignment
As an alternative to creating a reusable custom command from a script then assigning it to menu, a script can be directly applied to a menu as a quick, one-off approach.
This bypasses the creation of a custom command step by directly assigning a loaded script to a menu. Without the existence of a matching custom command, which can be applied to multiple menus, this direct method is a singlular solution for script menu access.
To assign a script directly to a menu, load the script project, open the server's Customizing dialog (DXP » Customize), select [Scripts] in the Categories list, locate the desired script and drag it to a menu position. Click OK to dismiss the Edit Command dialog.
The new menu item will be at its default settings (caption name etc), which can be corrected by right-clicking on the menu entry and selecting Edit from the submenu, to open the Edit Command dialog.
Once configured, the new menu will be available at design time without further need to load the script project, or install it as a Global Project.
Note that this approach to applying a script to a menu automatically creates the required command. This is not a re-assignable custom command, as described in the above methods, but a command created for that direct menu entry.
This can be observed in the actual menu category entry in the Customizing dialog. For the above example, the command can be seen in the 'Reports' category in the Customizing PCB Editor dialog.