Integrating an extension in Altium Designer

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.

Extending the server functions

This section looks at three methods that extend the AddOn extension server:

• Executing a PCB command from within the extension server.
• Adding its process launchers in the PCB editor.
• Adding a new floating toolbar with the server's process launchers.

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 *.tlt file:

Addon project files	Description
Addon.dll	The AddOn extension server object.
Addon.ins	The server installation file which defines the processes, types of documents and toolbars/menus/hotkeys used by this server.
Addon.rcs	The server's resources file which defines the process launchers for the graphical user interface in Altium Designer.
Addon.tlt	The server's tool layout file which defines the locations of toolbars and panels (optional).

Server files

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.

Setting up the processes in the PCB Editor

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.

The AddOn project's menu items in the GUI. Also note the new toolbar buttons positioned to the right of Help, in the main Menu.

Modifying the configuration files that update the PCB Editor GUI

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.ins installation file
• Addon.rcs resources file
• The new Addon.tlt tools locations file (see below)
• The main server (the PCB editor) AdvPCB.ins installation file.

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.

Resources file and its sections

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:

• PL
• The unique name (prefixed with a PL string) of the Process launcher linked to the server command string
• Command
• Caption
• Image
• ShortCut1
• ShortCut2
• Params
• Description

• End

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:

• Tree
• The unique name of the process launcher tree
• TargetId
• RefIDn where n is a numerical value, 0..N
• Popup
• Link
• Separator
• End

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.

TargetID
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.

RefID0
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.

Inserting new Menu Items in an existing menu

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;

• Update the AddOn project's resources file with Insertion–End blocks (AddOn.rcs).
• Insert the Updates clause with the name of the target PCB editor in the installation file (AddOn.ins).
• Insert the name of the extension server in the ResourceDependencies block in the target PCB editor's installation file (AdvPCB.ins).

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 6.8.0.14549'
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.

Adding a Toolbar to the PCB Editor's Workspace

To place a new toolbar in a PCB Editor's workspace that has the extension's process launchers, the step are as follows;

• Define a new BarLayout block for the toolbar and panel locations file.
• Update the resources file with a Tree End block that point to the server processes.
• Insert Name and EditorBar clauses within an EditorWindowKind block in the installation file.
• Insert the name of the extension server in the ResourceDependencies block in the PCB Editor's installation file.

The new toolbar, floating in the design workspace.

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 DXP.RCS, DXP.RAF and 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.

Updating the Target Installation file

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

Updating the Installation file

Here the 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 6.3.0.6689'
    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.

Updating the Resources File

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.

Defining a new Tools Layout 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 sum up

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;

• The supporting server's INS,TLT and RCS files
• The target server's INS file - that is, the appropriate *.ins file in Altium Designer's \System folder

You can refer to the AddOn example in the \Examples\Addon Complete\ folder.