Contact our corporate or local offices directly.
Beyond the concept of simply calling an installed extension project in Altium Designer using the Run Process function (as covered in the Altium C++ SDK page), its capabilities can be extended so that it functions as an integrated feature within Altium Designer.
This is done by introducing additional server configuration files and modifying the existing files to implement suitable process launchers, menu items and toolbars. In effect, this process links the new resources into Altium Designer, or more specifically for the AddOn example project, into the PCB Editor itself.
To recap, an extension server such as the AddOn example project for the PCB editor, has a set of processes. These process identifiers are stored in an installation file (with an .ins extension) and the functionality implemented in server source files. The commands linked to Altium Designer's GUI are the packaged process launchers which wrap around server processes and their parameters, if any.
Note that a command in Altium Designer is a specific server process launcher linked to a menu item, a toolbar button or a hot key - one of the three resources. These process launchers are defined in the server resources file (with a .rcs extension). Each process launcher is composed of a server process string, parameters and bitmap file names. You can find the example's source files in the SDK installation's
..\Examples\Addon Complete\ folder.
This section looks at three methods that extend the AddOn extension server:
Once the three methods are completed to enhance the project, the following physical files will be included to interface with (plug in to) Altium Designer – note the addition of a
|Addon project files||Description|
The AddOn extension server object.
The server installation file which defines the processes, types of documents and toolbars/menus/hotkeys used by this server.
The server's resources file which defines the process launchers for the graphical user interface in Altium Designer.
The server's tool layout file which defines the locations of toolbars and panels (optional).
The complete AddOn project is composed of at least four files – the server file (DLL) representing the functionality of the server itself, the resources file (RCS) which contains the process launchers and the structure of the server's user interface, the installation file (INS) with server settings and command names, and optionally, the toolbar locations file (TLT) representing the locations of panels for this server. Extending the AddOn project requires that the two new files, the resources and toolbar files, be modified or created.
Files for the resources and toolbar locations will be defined so that commands (as process launchers) can appear in the PCB editor's menu, and a floating toolbar containing two buttons will also appear in the PCB Editor's work space. The full code is not provided here, but the completed files can be found in the
\SDK\CPP\Examples\Addon Complete folder. This may not include an
Addon.tlt file, however you can find an example in the Tools Layout File section below.
You can execute a server process from Altium Designer's Run Process dialog to launch the AddOn extension, but there is a better way. The commands can be invoked in the PCB Editor from a toolbar button, a menu item or a hot key. These extension server processes are linked to the new resource items in the PCB editor.
In practice, the Add-on extension will add its process launchers in the PCB editor when the server is loaded in Altium Designer. What follows shows how to add new menu items in the PCB menu and their respective menu key shortcuts, and a new toolbar with two buttons.
To add new resource items that link to the AddOn server's processes in the PCB Editor, these following server files need to be updated:
Addon.tlttools locations file (see below)
For reference, you can find the final project files in the SDK Examples folder.
These files are essential to the process that inserts three new menu items in the PCB editor's View menu interface and two toolbar buttons on a new floating toolbar. The toolbar will need new buttons, and their bitmaps (18x18 pixels in size) are added to the
\System\Buttons\ folder in the Altium Designer installation. The same bitmaps are used for the images beside the menu items.
Each time the Altium Designer is started it loads and processes all the servers and their installation, toolbar locations and resources files. When a PCB editor is loaded for example, the default PCB resources are also loaded and set up in Altium Designer, and then the resources for any other PCB extension (AutoPlace, MakeLib, etc) are processed and set up, changing the PCB menus and other PCB resource items as dictated by the server extensions.
To register the AddOn project's resources, the AdvPCB installation file needs to be updated to include the user interface details from the server, so that its user interface elements can be inserted in the PCB Editor user interface (see later).
The following section looks at a server resources file which defines GUI elements in Altium Designer.
A resources file (with a RCS extension) is made up of two sections: Process Launcher definitions and Process Launcher Trees definitions.
Process Launchers resource section
A process launcher is a command linked to a user interface element such as a menu item, hotkey and toolbar in Altium Designer. The process launchers section in the resources file has a list of process launcher blocks. Each process launcher block denoted by a PL–End clause that needs to have a unique name.
A PL–End block has the following identifiers:
These process launchers are then used in the process launcher trees section of the resources file. These process launcher trees map to menu items, toolbar buttons or a hot keys in Altium Designer.
Example of a process launcher (PL–End block) - this maps the CountPads process to menus and buttons.
PL PLAddon:CountPadsAndShowDialog Command='Addon:CountPads' Caption='&Pad Count on Dialog...' Image='Pad1.bmp' Shortcut1='d' Shortcut2='' Params='Display=False' Description='Display pad count in a dialog.' End
This process launcher (above) defines a process launcher called Addon:CountPads, has a Caption called Pad Count on Dialog, has a image for the menu item and a short cut key; 'd'. Note: To set up hot keys for the menu items, you need to define the key character in the Shortcut1 clause and an alternative key character in the Shortcut2 clause in Process Launcher (PL) block.
Process Launcher Trees section
The process launcher trees section of the resources file provides a list of trees that represent each top-level user interface element (a hot key, a toolbar, or a menu) such as the File menu. Within each process launcher tree, you define the links for specific process launchers to sub user interface elements (say, sub menus) under that top level user interface element (say, a main menu), such as the Save As menu item. In this case for example, the three AddOon extension commands appear under the View » AddOn menu.
A Process Launcher Tree–End clause has the following identifiers:
Within a tree block, there are links and separators. In Altium Designer a separator inserts a line between a menu item/toolbar button and the next menu item/toolbar button. For the links, they must have unique link identifiers to process launchers within each process launcher tree block.
Example process launcher tree block - this defines the three menu items:
... Tree MNAddonMenuTree Caption='&Addon Menu' Popup='1' Link AddonMenu1 PLID='PLAddon:CountPadsAndShowDialog' End Link AddonMenu2 PLID='PLAddon:CountPadsAndShowDocument' End Separator AddonSeparator1 End Link AddonMenu3 PLID='PLAddon:RunAPCBProcess' End End
This process launcher tree block defines three menu items that will appear on a PCB menu.
Note: To enable pop up menus, you need to insert a Popup identifier with a key value at the end of the Tree clause (here,
Popup='1'). Therefore, to add a new menu item in the PCB editor you need to insert an Insertion–End block, and within this block a Tree–End block with defined Links to specific extension process launchers.
You also need to specify the TargetId and RefID0 values so the PCB editor knows where to attach the commands to.
The TargetID clause identifies which top level user interface element to link from the main server resources file. An example is the PCB's View menu. See the Insertion–End block code below.
The RefID0 clause refers to which existing user interface element (for example the menu item within the menu) for the new resource item to be inserted after or before. See the Insertion–End block code below. This process is similar for toolbar buttons and hot keys, except that you only need links to process launchers rather than trees within an insertion body.
To place new menu items in a target's menu (such as the PCB Editor) that has the server's process launchers, you need to;
Example Insertion–End block - this inserts the three process menu items.
// Inserts two new addon processes in the PCB's View menu Insertion MNAddOnMenu TargetID='MNPCB_View10' RefID0='MNPCB_View80' Tree MNAddonMenuTree Caption='&Addon Menu' Popup='1' Link AddonMenu1 PLID='PLAddon:CountPadsAndShowDialog' End Link AddonMenu2 PLID='PLAddon:CountPadsAndShowDocument' End Separator AddonSeparator1 End Link AddonMenu3 PLID='PLAddon:RunAPCBProcess' End End End
To do this, you need to know the Target ID and the Resource reference ID values that describe where the new menu items should appear in the PCB menu. You will need to look for the appropriate values in the
AdvPCB.rcs file in Altium Designer's
\System folder for the TargetId and RefID0 identifiers to refer to.
The fully completed file for the AddOn extension is as follows. At a later stage, an Insertion–End block for a Toolbar will be added.
Addon.rcs resources file
PL PLAddon:CountPadsAndShowDialog Command='Addon:CountPads' Caption='&Pad Count on Dialog...' Image='Pad1.bmp' Shortcut1='d' Shortcut2='' Params='Display=False' Description='Display pad count in a dialog.' End PL PLAddon:CountPadsAndShowDocument Command='Addon:CountPads' Caption='&Pad Count on Document...' Image='Pad2.bmp' Shortcut1='t' Shortcut2='' Params='Display=True' Description='Display pad count in a text document.' End PL PLAddon:RunAPCBProcess Command='Addon:RunAPCBProcess' Caption='&Run a PCB Process...' Image='' Shortcut1='r' Shortcut2='' Params='' Description='Runs a PCB Process\!' End // Inserts two new addon processes in the PCB's View menu Insertion MNAddOnMenu TargetID='MNPCB_View10' RefID0='MNPCB_View80' Tree MNAddonMenuTree Caption='&Addon Menu' Popup='1' Link AddonMenu1 PLID='PLAddon:CountPadsAndShowDialog' End Link AddonMenu2 PLID='PLAddon:CountPadsAndShowDocument' End Separator AddonSeparator1 End Link AddonMenu3 PLID='PLAddon:RunAPCBProcess' End End End
From this resources file three process launcher blocks are defined along with their commands, plus a caption to appear on a menu, accelerator key short cuts, the path to a bitmap that will appear on a toolbar and a menu item, any parameters for parametric commands, and finally, a description for this process launcher as a tool tip or on the status bar of the Altium Designer.
The Process Launcher Tree section in the resources file defines where the three new menu items containing the CountPads and RunAPCBProcess process launchers, with their short cut keys, are going to appear in the PCB | View menu.
The PCB editor needs to be informed that the AddOn extension wishes to add three process launchers in the PCB View menu. To do this, insert the Updates clause and the 'ADVPCB' identifier (including the single quotes) in the
Addon.ins file as shown below. The Updates keyword basically tells Altium Designer to update the target server (the PCB editor in this case) immediately.
Installation file (AddOn.ins) with Updates clause added
ClientInsFile 1.0 Server EditorName = 'AddOn' EditorExePath = 'AddOn.DLL' EditorDescription = 'Demonstratory AddOn module' Version = 'Version 18.104.22.16849' Date = '07-Aug-2008' HelpAboutInfo = 'This software is protected by copyright law and international treaties.' Copyright = 'Copyright © Altium Limited 2013' Updates = 'ADVPCB' End Command Name = 'CountPads' LongSummary = 'Find how many pads on a PCB document' End Command Name = 'RunAPCBProcess' LongSummary = 'Invoke a PCB process' End
Save all the files and re-compile the project. Don't forget to update the resources file, installation file and the server module (DLL) in Altium Designer's
\System folder. Once you have copied the files to this folder and have Altium Designer up and running with a PCB document open, you can then invoke a command from the AddOn extension via one of the three new menu items in the PCB's View menu.
To place a new toolbar in a PCB Editor's workspace that has the extension's process launchers, the step are as follows;
The figure above is a screen shot depicting the AddOn extension's toolbar floating on the PCB work-space. The first step is to define the resources file for the project that define the process launchers for the new floating toolbar on the PCB workspace (specifically, only when PCB type documents are open). For this exercise the floating toolbar will be called TLAddon.
Next, the new tool layout file is defined with a TLT extension and the server's installation file is updated. Note that the toolbar name in the server resources file will also be used in the tool locations file and in the installation file.
It is imperative to delete the
UserTools.TLT files to remove the User Interface customizations when you are experimenting with Altium Designer's GUI. Altium Designer will recreate these files, but it may be prudent to back up the existing files first.
Where the extension server inserts a new toolbar in the PCB workspace, the
AdvPCB.INS file needs to be modified in the ResourceDependencies block - if it has not already been done in the previous steps above.
The AdvPCB installation file is updated to include the user interface details for the AddOn extension, so that its user interface elements can be inserted in the PCB Editor user interface. The
Adv.INS file is also in the
\System folder of the Altium Designer installation.
AdvPCB installation file (AdvPCB.ins) snippet: Addon server resources reference inserted
ClientInsFile 1.0 Server EditorName = 'PCB' <SNIP> ResourceDependencies 'AutoPlacer' <SNIP> 'PinSwapper' 'AddOn' End End
EditorWindowKind block needs to be inserted within the supporting server INS file with the following format;
EditorBar Name = NameOfAddon BarType = ResourceType (Toolbar, Menu, HotKeyTable) End
Then a new Tree block is defined with links to toolbar buttons in the project's resources file. Finally a BarLayout block for the toolbar in the TLT file (don't forget to specify the BarName and BarDocumentKind clauses).
Installation file (addon.ins): Toolbar included
ClientInsFile 1.0 Server EditorName = 'AddOn' EditorExePath = 'AddOn.DLL' EditorDescription = 'Demonstratory AddOn module' Version = 'Version 22.214.171.12489' Date = '29-Dec-2012' HelpAboutInfo = 'This software is protected by copyright and international treaties.' Copyright = 'Copyright © Altium Limited 2012' Updates = 'ADVPCB' End EditorWindowKind Name = 'Pcb' EditorBar Name = 'TLAddon' BarType = Toolbar End End Command Name = 'CountPads' LongSummary = 'Find how many pads on a PCB document' End Command Name = 'RunAPCBProcess' LongSummary = 'Invoke a PCB process' End
The Updates clause tells the Altium Designer to update the PCB Server (AdvPCB) to update its resources. The format of the Updates clause is: Updates 'NameOfTargetServer'
In this case, we wish to update the PCB Editor, thus the ADVPCB string is used.
To reiterate, an extension server's resources file (with a RCS extension) is a text file with a list of process launchers. Each process launcher is enclosed in a PL-End block consisting of a command string, a bitmap and parameters etc. The name of the toolbar in the tool locations file correspond to the name in the Editor.
Resources file (addon.rcs): With Toolbar Tree block added
PL PLAddon:CountPadsAndShowDialog Command='Addon:CountPads' Caption='&Pad Count on Dialog...' Image='Pad1.bmp' Shortcut1='t' Shortcut2='' Params='Display=False' Description='Display pad count in a dialog.' End PL PLAddon:CountPadsAndShowDocument Command='Addon:CountPads' Caption='&Pad Count on Document...' Image='Pad2.bmp' Shortcut1='d' Shortcut2='' Params='Display=True' Description='Display pad count in a text document.' End PL PLAddon:RunAPCBProcess Command='Addon:RunAPCBProcess' Caption='&Run a PCB Process...' Image='' Shortcut1='r' Shortcut2='' Params='' Description='Runs a PCB Process\!' End // Inserts two addon processes in the PCB's View menu Insertion MNAddOnMenu TargetID='MNPCB_View10' RefID0='MNPCB_View80' Tree MNAddonMenuTree Caption='&Addon Menu' Link AddonMenu1 PLID='PLAddon:CountPadsAndShowDialog' End Link AddonMenu2 PLID='PLAddon:CountPadsAndShowDocument' End Separator AddonSeparator1 End Link AddonMenu3 PLID='PLAddon:RunAPCBProcess' End End End // Inserts two toolbar buttons on a new floating toolbar Tree TLAddon Caption='Addon Tools' TopLevel=True Link TBAddon_Item1 PLID='PLAddon:CountPadsAndShowDialog' End Separator TBAddon_Item2 End Link TBAddon_Item3 PLID='PLAddon:CountPadsAndShowDocument' End End
Within the last Tree block, the two Link identifiers (all links are unique) are linked to two process launchers on a new toolbar with two button bitmaps. This toolbar has the TLAddon name.
The toolbar name in the server resources file will also be used in the tool locations file and in the installation file.
A tools layout file (with a TLT extension) is a text file with information for each menu / panel / hotkey / toolbar, which defines (for example) whether it is docked, floating, the size of the menu, panel, toolbar etc. The bar names in the tools layout file correspond to the entries in the server resources file. For example, to add a new toolbar for the AddOn extension in the PCB workspace, you would need to define a layout file.
Tools layout file (addon.tlt)
ToolsLayout BarLayout BarName='TLAddon' BarState=BarStateFloating BarDockSite=DockSiteNone BarDockOffset=563 BarFloatLeft=307 BarFloatTop=137 BarFloatWidth=51 BarActive=True BarDocumentKind=PCB End End
The tools layout file is defined so that the new toolbar is set to floating, and the location and size of the toolbar is set in the PCB workspace. Make sure that the BarName is set to TLAddon and it corresponds to the TLAddon entry in the corresponding resources file. The BarState identifier is set to BarStateFloating and the BarDocumentKind identifier is set to PCB.
To add menu items to the PCB Editor for example, you need to have Insertion clauses in the resources file with TargetID and RefID0 referencing user interface element IDs in the PCB Editor's server resources file.
To add the toolbar to a PCB Editor, there are four files to update;
*.insfile in Altium Designer's
You can refer to the AddOn example in the
\Examples\Addon Complete\ folder.
See Server configuration files for more details on implementing and modifying server extension configuration files.
For an overall look at developing and deploying extension servers using the Altium Designer SDK see An Overview of the Altium SDK.
Contact our corporate or local offices directly.