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 Menu, Toolbar and Shortcut.
When opened in the script editor, a script can be executed using the editor's Run » Run command from the main menus (shortcut: F9). The current script referenced by the Run » Set Project Startup Procedure command will be run.
If the Set Project Startup Procedure command has not been set, the Select Item To Run dialog will appear prompting you to choose which script and its procedure to execute.
If a script has errors, the script will be stopped and you can use various debugging commands to resolve the errors and try running again.
The Run command 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. Alternatively, the Select Item To Run dialog (File » Run Script) allows you to browse to a script on your local hard drive or a connected Workspace or select a script that is open in the Projects panel and then run the desired process. The script remains loaded for the current session.
Executing a script using the script process launcher via the Select Item to Run dialog.
- Grid - lists the available script projects (*.PrjScr) and associated source documents. Select the desired script item from the list, then click OK to run the script.
- Browse - click to open a drop-down in which you can select to browse:
- From File - click to browse and select the desired script item from the standard Windows Open dialog.
- From Server - click to browse and select the desired script item from the Choose item dialog (an iteration of the Explorer panel).
- Copy script parameters - right-click over the desired script item to capture the correct parameters. This will copy the entire path, process name, and procedure to the clipboard.
If there are errors present in the script, after clicking OK in the Select Item To Run dialog an error dialog will open alerting you to the fact an error is present. The dialog will give information about the error and the source script document will be opened and the offending line of script highlighted. Close this dialog by clicking the OK button and stop the scripting system by selecting the Run » Stop command from the main menus (shortcut: Ctrl+F3).
The error dialog will only flag the first scripting error encountered. There may be more existing, which will be found by subsequent attempts to run the script.
A more suitable method to access a frequently used script is to install the project as a Global Project from the Scripting System – Global Projects page of the Preferences dialog. In this case, the project is automatically loaded when Altium Designer starts, and can be executed at any time via the File » Run Script command.
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; implementing 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 be implemented as an application 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
ScriptingSystem:RunScript process, it includes parameters for pointing to a specific script project file, a constituent script file (
*.pas) and a process within that script. When suitably arranged, these elements constitute a command string.
The advantage of this approach is 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 – that is, a sub-application such as the file system or a design document editor.
Create a Command
To assign the HelloWorld script as a command for the PCB editor, for example, first open a PCB document (and hence the editor) and select View » Tools » Customize from the main menu to open the Customizing PCB Editor dialog. The dialog also can be accessed by right-clicking on a menu bar or toolbar then choosing Customize from the drop-down menu or by double-clicking in a blank area (away from any commands) of a menu bar or toolbar.
To create a new command, click the dialog's New button to open the Edit Command dialog where the server process and script path details can be included – ensure that the
[Scripts] category is not selected when creating a command from a script.
The dialog's Action entries take the form:
Depending on the source path to the script, the Parameters string would be similar to:
For a script project hosted in a Workspace, the path, and therefore the command’s parameters entry, must point to the correct Workspace location – which is based on the Workspace Script’s GUID reference. So this reference link must be obtained before attempting to create the new script command entry. To capture the correct parameters for a script installed from the Workspace, open the Select Item To Run dialog (File » Run Script), right-click on the desired procedure in the script and choose the Copy script parameters command from the context menu. This will copy the entire path, process name and procedure to the clipboard.
Select the required process/procedure in the Workspace script project, then copy the script's parameters.
The Edit Command dialog also provides entry fields for a command caption, description, shortcut and associated bitmap image (BMP/GIF/PNG; 18 x 18 pixels). These settings are saved with the command and apply to all instances where it is inserted in menus, toolbars and pop-ups – as described in the Assigning Menu Commands section below.
The required parameters can be copied from the actual script entry under the
[Scripts] category in the Customize PCB Editor dialog if the script is currently loaded. To temporarily load the script, browse to and open it via the File » Run Script command. Once copied, ensure that the Categories entry is no longer set to
[Scripts] before creating the command with the New button.
► See example image
With the details complete and the edit dialog dismissed (), the HelloWorld script becomes available as a Custom command (under
[Custom]) for the PCB Editor.
Note that commands are implemented on a server basis, so a Custom command that has been created for the PCB Editor (as above) will not be available for other functions, such as the Schematic Editor or the Scripting System.
Executing a Script using the RunScriptFile Process
A DelphiScript unit script from Altium Designer (with a
*.pas extension) can be executed using the
RunScriptFile process. Note, only DelphiScript unit scripts can be used – not these scripts that have forms. In this case, the dialog's Action entries take the form:
Depending on the source path to the script file, the Parameters string would be similar to:
Executing a Script using the RunScriptText Process
This process can be used to execute a series of commands within the
Begin End; block. In this case, the dialog's Action entries take the form:
For example, an external application such as 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 software 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.
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\Altium\xx\X2.EXE') – where xx represents Altium Designer version folder name.
Commands can be edited, duplicated and removed directly from the customizing dialog (in this case the Customizing PCB Editor dialog) using the buttons at the bottom of the dialog.
Assigning Menu Commands
With a script implemented as a custom server command via Altium Designer's Customizing function (View » Toolbars » Customize) as detailed above, it can be assigned to the server GUI by a simple drag and drop process.
► See also Customizing the Design Space
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 editor menus. With the customizing dialog closed, the new menu command can be accessed at any time in the PCB editor.
A custom command can be dragged to the required menu location.
A command may also be added using the Insert Link option
from the menu's right-click options.
Since the new custom command has been assigned to the PCB Active Bar in this example, it can be seen under the
PCB Active Bar command category in the Customizing PCB Editor dialog.
When assigned to a menu, the custom script command will appear under that menu's category in the customizing dialog.
To remove a command from a menu, open the custom dialog then drag the menu command icon back into the dialog.
Removing a command assigned to the Toolbar.
When in customizing mode, commands assigned to a menu can also be edited and deleted by right-clicking on the menu command itself.
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 – here, Notepad – can be accessed from within the Reports menu.
Active menus during customization allow a custom command to be dragged into a drop-down 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 PCB 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.
A custom command assigned to a right-click sub-menu
Direct Script Assignment
As an alternative to creating a reusable custom command from a script then assigning it to a 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 as a fully configured command to multiple menus, this direct method is a singular solution for script menu access. As such, the various command settings, such as its Caption, Description, Image and Shortcuts only apply to the assigned instance.
To assign a script directly to a menu, load the script project, open the server's Customizing dialog (View » Toolbars » Customize), select [Scripts] in the Categories list, locate the desired script and drag it to a menu position. Click to dismiss the Edit Command dialog.
A script, rather than a command, can also be assigned directly to a menu.
As with all menu placements, if the new menu item is still at its default settings (caption name, shortcut etc), these can be corrected by right-clicking on the menu entry and selecting Edit from the submenu. This opens the Edit Command dialog where suitable settings can be entered.
In Customizing mode, right click on a menu to access its parameters.
Once configured, the new menu will be available at design time without further need to explicitly 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, fully configured 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 individually configured command can be seen in the
Reports category in the Customizing PCB Editor dialog.
When directly applying a script to a menu, the matching command is created for just that menu entry.