Getting started: Building a Delphi extension

Note: This document subject to updates to support Altium's latest technology.

This document guides you in the process of developing an Extension server for the PCB Editor, and how to update the Altium Designer's PCB Editor's menus automatically. See An Overview of the Altium SDK document for an introduction to the SDK.

The Altium Designer software integration platform (also called the DXP software technology platform, or DXP platform for short) is based on the client-server architecture. The DXP platform allows software extensions to work together and behave as a single design application, and provides you with an integrated and customizable user interface. This integrated platform provides developers a ready-built environment to develop modules that extend or enhance the existing functionality of Altium Designer.

The Altium Designer SDK provides a set of source units and source code examples that allow you to develop software extension modules. Altium Designer has a range of built in software products that provide specialized functionality such as the PCB editor and the Integrated Library server. Other software extensions can be developed as add-ons to enhance the functionality of an Altium Designer server that has an Application Programming Interface (API) such as PCB API. You can also port your existing Altium Designer scripts to a server extension, mainly to lock the code and to speed up the functionality.

This document shows how to develop an extension that adds on to the PCB Editor in Altium Designer using the Altium SDK, and contains four main parts:

• Introduction to Altium Designer's Client/Server architecture and software technologies
• Building and running an example project
• Exploring and developing the PCB Editor extension project
• Building and plugging the extension server into Altium Designer
• Extending the server's functionality

This document assumes you are familiar with using the Embarcadero Delphi™ development tool and its Visual Component Library, and understand Delphi programming techniques such as using Object Pascal and Object Interfaces.

Client / Server Architecture

Altium Designer consists of the DXP platform as the client module which hosts extension server applications. A server here is basically a Dynamic Link Library (DLL) module installed in Altium Designer that has the algorithms and data structures needed to provide specific services or functionality. It can also be called a server module (or just server) within Altium Designer's client-server architecture.

The PCB and Schematic editors are examples of servers. These servers harness Altium Designer's interface elements for communication between the user and the computer.

The figure above shows the conceptual bridge within the Altium Designer application, where the client side consists of the DXP platform module. On the other side of the bridge, the server side consists of the Workspace Manager system module, the Schematic Editor module, PCB editor, additional software extensions, and so on. The WorkSpace Manager module is a system server, while the Hole Size Editor for the PCB Editor, for example, is an add-on extension that uses the PCB Editor's Application Programming Interface so that it can deal with the PCB objects on a PCB document.

Providing services in Altium Designer

In Altium Designer, a extension module (as a server) provides its specialized services in the Altium Designer environment, and interfaces to the system's Graphical User Interface (GUI) through commands.

A command can be thought of as the software executing a sequence of tasks. This task can be as simple as redrawing the screen on the monitor, or it may be more complex like generating a Bill of Materials (BOM) report. Commands are the basic units of Altium Designer's GUI. A command is a packaged process launcher which is linked to a resource item in Altium Designer, for example the PCB's View » Area menu item is a PCB command which has a PCB:Zoom process launcher.

A process launcher is linked to a resource item in Altium Designer and can be assigned to a key, toolbar button or a menu item. When you launch a command, a process launcher is invoked. Basically, each server has its own list of processes. These processes with their parameters are packed as process launchers that are linked to commands in the Altium Designer's GUI. Whenever a command is invoked through the GUI, the process launcher is routed to the appropriate server. This server then interprets the process launcher as a process string with parameters.

To have a server function in Altium Designer, this server needs to have the APIs linked in and several configuration files such as the server installation file (with an INS extension). The APIs provide the necessary protocols for the server to interact within the Altium Designer environment, and the server installation file provides a list of available server processes of the server.

Altium Designer SDK

The Altium Designer SDK contains API source files, which when compiled and bundled, allow your server to work in Altium Designer. The files can be found in the installation's \SDK\Source Code folder.

When you want to use a particular function, you need to add the corresponding unit in the Uses clause of your server code project. For example, using the MessageRouter_SendCommandToModule procedure, you need to add the SDK's EPDUtil source unit in the Uses clause. Otherwise the Embarcadero Delphi compiler will report an Undeclared identifier error message in the Message window. You can check out the files in the \SDK\Source Code folder to see the variable and object declarations/interfaces.

Altium Designer Object Interfaces

An Object Interface that represents a design object in Altium Designer will have methods and properties listed (note that some interfaces will only have methods listed);

• A method is a procedure or function that is invoked from its interface. Methods of Object Interfaces are the actions an Object Interface can perform.
• A property of an object interface is like a variable; you get or set a value in a property, but some properties are read only properties, so they can only return values and cannot be set. Properties of object interfaces represent the data contained in the object that is represented by the interface.

For example the IDispPCB_Component interface from the PCB API has a Height property and two associated methods. Note that the IDispPCB_Component declaration comes from the PCB API in the Altium Designer SDK.

IDispPCB_Component interface declaration:

IDispPCB_Component = DispInterface;
....
Function GetState_Height : Integer;
Procedure SetState_Height (Value : Integer);
Property Height : IntegerRead GetState_Height Write SetState_Height;
....
End;

Object Model Hierarchy

A parent object interface can have child object interfaces and in turn, child object interfaces can act as parent object interfaces and have child object interfaces and so on. This forms an Object Model Hierarchy. For example, in the EDP SDK, the IWorkspace Object Interface is the top level interface representing the Workspace manager in Altium Designer. Projects are part of the Workspace Manager, therefore an IProject interface is a child interface from the parent IWorkspace interface.

Design objects such as sheet symbols, components and buses are child objects of the document object (represented by the IDocument interface). This is illustrated in a simple hierarchy example below:

IWorkspace
IProject
IDocument
ISheetSymbol
IComponent
IBus

A relationship exists between objects in Altium Designer and the object Interfaces supported by the various APIs from the Altium Designer SDK.

• Projects and the corresponding documents are managed by the Workspace Manager.
• A project open in Altium Designer is represented by the IProject object interface.
• The documents from this project are represented by the IDocumentinterfaces.

The PCB documents and PCB design objects are managed by the PCB Editor and its PCB Object Model. The PCB document open is represented by its IPCB_Board interface and the design objects (for example, a pad object and a track object) are represented by IPCB_Pad and IPCB_Track interfaces.

Altium Designer APIs

The Altium Designer SDK has a DXP Platform API and several software product APIs:

• Client API
• Integrated Library API
• WorkSpace Manager API
• Schematic API
• PCB API

Figure 2 below is an illustration of the relationship between objects in the Altium Designer application and the object interfaces supported by the Altium Designer SDK. This shows the PCB and Workspace Object Interfaces in Altium Designer, where the projects and the corresponding documents are managed by the Workspace Manager. An open project in Altium Designer is represented by the IProject object interface, and the documents from this project are represented by the IDocument interfaces.

Figure 2: The PCB and Workspace Object Interfaces in Altium Designer.

Furthermore, the PCB documents have PCB objects which are accessed by the PCB API. The open PCB document open is also represented by its IPCB_Board interface and design objects, for example the pad object and the track object are represented by IPCB_Pad and IPCB_Track interfaces respectively. The PCB API provides PCB interfaces to use in scripts and server module projects. The PCB API allows a programmer to modify PCB objects and their attributes from a PCB document.

PCBServer Function

When you need to work with PCB design objects in Altium Designer the starting point is to invoke the PCBServer function. With the IPCB_ServerInterface interface returned (see the EDPInterfaces_PCB source unit), you can extract all other derived PCB interfaces that are exposed in the IPCB_ServerInterface interface. For example to get an access to the current PCB document, you would invoke the GetCurrentPCBBoard method from the IPCB_ServerInterface interface object from your server code.

• To use PCB interfaces, you need to obtain the IPCB_ServerInterface object by invoking the PCBServer function. The IPCB_ServerInterface interface is the gateway to other PCB object interfaces.
• The IPCB_Board interface points to an existing PCB document in Altium Designer.

GetCurrentPCBBoard Example
Var
  TheServer : IPCB_ServerInterface;
  TheBoard : IPCB_Board;
  TheFileName : String;
Begin
  TheServer := PCBServer;
  If TheServer = Nil Then Exit;
  TheBoard := PCBBoard.GetCurrentPCBBoard;
  If TheBoard = Nil The Exit;
  TheFileName := TheBoard.FileName;
End;

For detailed information on PCB API, refer to the Delphi SDK Reference.

Building and running an SDK example project in Altium Designer

A good place to start in developing your own software extensions for Altium Designer with the SDK is to examine and build one of the example projects provided with the SDK.

This section shows you how to build an example add-on extension server that uses the PCB API to interact with an opened PCB design document in Altium Designer, where it counts the number of pad objects on the document. This extension displays the number of pads in a dialog or in a text document in Altium Designer.

When installed in Altium Designer and fully configured, the add-on extension will add three new menu items to the PCB menu, along with two new buttons on a new floating toolbar. To build and run the example, you will need a copy of Embarcadero Delphi development tool (XE2 or better).

Setting up your Server Project

To start the process, open the Embarcadero Delphi tool and navigate to the \SDK\Examples\AddOn Complete folder (depending on where your copy of the SDK is installed on your computer). The folder should contain, amongst others, the files listed in the table further below. Note that the Delphi project files will be located in the \SDK\AddOn Complete\D2010 folder.

To build a server DLL that will interact with Altium Designer, Delphi must be able to find the Altium Designer SDK API files build the project. These are located in the SDK installation's \Source Code folder. The search and file output paths need to be defined in Delphi's compiler options.

With the AddOn project loaded in Delphi (File » Open Project), click Project » Options from the Delphi menu to open the Project Options dialog. Select the Debug option from the Build Configuration pull down menu, then populate or edit the following fields:

Output directory:

This is where the compiler will generate the Add-on project DLL. Set to ..\ so the DLL will be generated in the project root folder.

Unit output directory:

This is where the compiler generates the compiled unit files (*.dcu), which are linked to create a single executable. Set to ..\dcu so they collect in a single folder within the project.

Search path:

The location of the source unit files, which should include the SDK source files. To add the SDK API units, click in the Search Path field then use the navigator button (at the right) to open the Search Path dialog. Use the path browse button to select the SDK source code folder for your installation. Click Add to include the path, then OK to close the dialog. Note that Delphi's inherent $(BDS)\lib source path (and possibly others) is inherited from the Base Configuration compiler settings.

Figure 3: Setting the path to the API in the Project Options dialog in the Embarcadero Delphi application.

Figure 4: Adding the SDK source file units to Delphi's search path.

The project Source Code

A extension server as a dynamic library linking (DLL) module is constructed from Altium Designer API files (units). The files used for this Add-on project, as described in the tables below, are stored in the project folder.

The units that make up the project are stored in a Delphi project folder (for the SDK examples, the \AddOn Complete\D2010 folder):

Addon source and configuration files are stored in the Server Project folder (\AddOn Complete):

Since a server DLL is a library module, there is an Exports directive which exposes the some of the functionality from the server into the Altium Designer (see listing for the Add-on example project below).
In this case, a PlugInFactory routine from the server project, when instantiated, is exposed in the DXP platform. This routine is defined in the main.pas unit. It takes in the IClient object interface which represents the DXP platform, and this same routine creates a single unique server module which stays in memory until Altium Designer is closed down.

Code Listing 1: AddOn.dpr

Library AddOn;
uses
  Main in '..\Main.pas',
  Commands in '..\Commands.pas',
  DisplayForm in '..\DisplayForm.pas' {ReportDialog};
{$R *.res}
Exports
    PluginFactory;
End

Code Listing 2 (below) refers to the main.pas unit for the Add-on example. This unit is where the server module is instantiated and interfacing takes place in Altium Designer. The main.pas unit defines the TServerModule object, which is the main object representing the Add-on server. The methods and fields of the TServerModule class in the EDPClasses unit are from \SDK\Source Code folder.

Code Listing 2: Main.pas

Unit Main;
Interface
Uses
  EDPInterfaces;
{................................................................................}
Function PluginFactory (AClient : IClient) : IServerModule; Safecall;
{................................................................................}
Implementation
Uses
    Forms,
    Commands,
    EDPClasses;
 
{................................................................................}
// The addon server methods and fields are inherited from the
// TServerModule class in EDPClasses unit.
Type
  TAddOn = Class(TServerModule)
  Protected
    Function NewDocumentInstance(Const AKind, AFileName : Widestring) : IServerDocument; Override;
    Procedure InitializeCommands; Override;
  End;
{.................................................................................}
{.................................................................................}
//This where instance of new document is created.
//In this example it returns nil, because no custom types of documents are introduced here.
Function TAddOn.NewDocumentInstance(Const AKind, AFileName : Widestring) : IServerDocument;
Begin
    Result := Nil;
End;
{.................................................................................}
{.................................................................................}
// This is where Commands (process launchers) are initialized and stored.
Procedure TAddOn.InitializeCommands;
Begin
    FCommandLauncher.RegisterCommand('CountPads'     , @Command_CountPads);
    FCommandLauncher.RegisterCommand('RunAPCBProcess', @Command_RunAPCBProcess);
End;
{..................................................................................}
{..................................................................................}
// This is where a server module is created from the PluginFactory call.
// The new server module sets up the command launcher table which stores commands (processes).
Function PluginFactory (AClient : IClient) : IServerModule; Safecall;
Begin
    // name of addon server passed in
    // the installation file with INS extension needs to have the same name
    Result := TAddOn.Create(AClient, 'AddOn');
End;

Basically, the main.pas unit deals with the creation of an server module and sets up the server processes table (commands table). The PluginFactory procedure also passes the name of the Add-on server module to Altium Designer.

Server Processes and Server Configuration Files

Server Processes are internal commands provided by a server which are used as the elements for process launchers that link to menus, toolbars and short cut keys in Altium Designer. So behind each menu item, toolbar button and hotkey is a process launcher, which is a wrapper around a server process, and a set of parameters and display information such as a caption string.

When you select a menu item, press a hot key or click on a toolbar button, the Altium Designer system launches the command (its packaged process launcher) by passing the server process identifier string and its parameters (if any) to the appropriate server, which then executes the action on the active document. Therefore, server processes are implemented as server process launchers which are linked to menu items, toolbar buttons and shortcut keys in Altium Designer and then are called commands. Server processes are implemented in the Commands.pas unit of a server project as outlined in the Code Listing 3 below.

An extension server module has a set of server processes and their server process identifiers are stored in an ASCII installation file (which ends with an INS extension). Again, these server processes are wrapped as process launchers that can link to three different user interface element (resources) types. The layout of user interface elements such as the structure of menu items are defined in the resources file (which ends with a RCS extension). The module itself is a dynamic linked library (with a DLL extension) with the appropriate elements from the Altium Designer SDK.

In practice a typical extension would have three files – here, the addon.dll, the resources file addon.rcs, and the installation file addon.ins.

You just drop your extension server file (with a DLL extension), its installation file (with an INS extension) and its resources file (with a RCS extension) in Altium Designer installation's \System folder. Altium Designer will then automatically register this new server and its processes or internal commands will ready to use when Altium Designer is activated.

When Altium Designer starts, it reads the server installation files from the \System folder and then stores the list of servers and their processes in an internal command table. When a command is executed (such as clicking on a tool bar button), Altium Designer checks where this button is linked to, and with the server name and its command name it then routes the command or the process launcher to the appropriate server. The server responds by executing this command if the routed command can be matched to the commands table supported by the server module.

Code listing 3: Command examples from the Add-on Commands.pas unit

Unit Commands;
Interface
{......................................................................}
Procedure Command_CountPads       (View : IServerDocumentView; Parameters : WideString);
Procedure Command_RunAPCBProcess  (View : IServerDocumentView; Parameters : WideString);
{......................................................................}
 
Implementation
 
Procedure Command_CountPads(View : IServerDocumentView; Parameters : WideString);
Var
    S : TDynamicString;
Begin
    // Check the parameters passed in
    GetState_Parameter(Parameters,'DISPLAY',S);
    // If Display = True then post results on a text document otherwise post on a dialog.
    If UpperCase(S) = 'TRUE' Then
        CountPadObjects(True)
    Else
        CountPadObjects(False);
End;
 
Procedure Command_RunAPCBProcess(View : IServerDocumentView; Parameters : WideString);
Var
    _PCBServer : IPCB_ServerInterface;
Begin
    // Check if PCB document exists. If not stop the server.
    _PCBServer := PCBServer;
    If _PCBServer = Nil Then
        Exit;
    RunCommand('PCB:BoardInformation','');
End;

From the code listing 3 above, the server processes (internal commands) are declared and implemented.

• All command signatures have the View : IServerDocumentView and Parameters : WideString parameters. The View parameter represents an opened server document in Altium Designer, and the Parameters parameter represents the parameters passed by the command supported by the server in the Altium Designer.
• The InitializeCommands procedure in the main.pas unit must match the command procedure signatures in this Commands.pas unit (in this case, CountPads and RunAPCBProcess).
• The installation file with an INS extension must also match the commands defined in the commands.pas unit, and the server module name as defined in the main.pas unit must match the EditorName string in the installation file that has the line EditorName = 'AddOn'.

To Sum Up

• A software extension is supported by its set of server processes which are implemented as commands in Altium Designer.
• The commands in Altium Designer's user interface (UI) are linked to the process launchers from the internal servers' processes tables.
• A process launcher is composed of a name, process, bitmap filename, a caption string and so on. Each process launcher is identified by a unique process identifier which includes the server name and the server process name, separated by a colon, (for example PCB:BoardInformation).
• The list of server processes is defined by the server installation file (with an INS extension).
• The layout of graphical user interface is defined in the server resources file (with a RCS extension).

Building and plugging the project into Altium Designer

With the server project loaded in the Delphi development tool, execute the Build command from the Project » Build Addon menu. A dynamic library link file is then generated. Check in the directory where the source code and the output files have been generated.

As noted previously, you just drop your server file (with a DLL extension), its installation file (INS extension) and the resources file (RCS extension) in the Altium Designer \System folder. Altium Designer will automatically register this new server, and its processes (internal commands) are then ready to use in Altium Designer.

Executing the process in Altium Designer

To start a process manually in Altium Designer, execute the Run Process command from the DXP System menu. In the Run Process dialog that opens, use the Browse button to select the Add-on extension from the list (AddOn:CountPads), click OK, then click OK again to run the Add-on process.

Exploring and developing the extension for the PCB Editor 

This section covers the anatomy of the Add-on project, which counts the number of pads on a current PCB document. A parametric process is implemented in this extension to display the number of pads on a dialog or on a text document.

Since this extension server has been developed to work with a PCB document, it applies (amongst others) these PCB API units in the Uses clause: EDPTypes_PCB, EDPClasses_PCB and EDPInterfaces_PCB units. The PCB Interfaces allow you to write code that is implementation independent. Refer to the Delphi SDK Reference and Delphi documentation for more details on object interfaces.

The stages of the server development are described here by looking at all code snippets first and then putting all of them together in a code listing. Ultimately, the configuration files for the Add-on server are developed so a floating toolbar can be specified with the project's process launchers in the PCB editor's work-space

First up is the commands.pas unit which deals with the server processes (internal commands).

Code Snippet 1: The Uses clause entries in command.pas

Uses
    SysUtils,
    Classes,
    Windows,
    Dialogs,
    EDPParam,           // Contains all the functions for server parametric process processing.
    EDPUtil,            // Contains EDP utility functions.
    EDPTypes,           // Contains types used for the Client, Server and Workspace.
    EDPClasses,         // Contains base classes for Client, Server and Workspace interfaces.
    EDPInterfaces,      // Contains Client, Server and Workspace interfaces.
    EDPTypes_PCB,       // Contains types used for PCB.
    EDPClasses_PCB,     // Contains base classes for PCB interfaces.
    EDPInterfaces_PCB;  // Contains PCB interfaces.

Searching PCB objects on a PCB document

Note the CountPadObjects procedure that's defined in the commands.pas unit (Code Snippet 2, below). This routine counts the pad objects on the current PCB document using an object search mechanism called an iterator.

The CountPadObjects procedure counts the pad objects on a currently focused document using the PCB API. The database system of the PCB editor stores objects such as pads, vias, tracks etc. So to have access to the objects in the PCB database that represents the current PCB document from an extension server, we use an iterator derived from the PCB Board object (IPCB_Board interface).

Code Snippet 2: The CountPadObjects procedure in commands.pas

Procedure CountPadObjects(DisplayOnText : Boolean);
Var
    Board           : IPCB_Board;
    Pad             : IPCB_Primitive;
    Iterator        : IPCB_BoardIterator;
    PadNumber       : Integer;
    PadNumberString : String;
    PCBFileName     : String;
    _PCBServer      : IPCB_ServerInterface;
Begin
    PadNumber       := 0;
    _PCBServer := PCBServer;
    If _PCBServer = Nil Then
        Exit;
 
    // retrieve the interface representing the PCB document
    Board := _PCBServer.GetCurrentPCBBoard;
    If Board = Nil Then
        Exit;
 
    // Obtain PCB document filename and path, then change the file extension.
    PCBFileName := Board.FileName;
 
 
    // retrieve the board iterator
    Iterator        := Board.BoardIterator_Create;
    Iterator.AddFilter_ObjectSet([ePadObject]);
    Iterator.AddFilter_LayerSet_2(cAllLayers);
    Iterator.AddFilter_Method(eProcessAll);
 
 
    // search and count pads
    Pad := Iterator.FirstPCBObject;
    While (Pad <> Nil) Do
    Begin
        PadNumber := PadNumber + 1;
        Pad := Iterator.NextPCBObject;
    End;
    Board.BoardIterator_Destroy(Iterator);
    // Convert the integer type to a string type.
    PadNumberString := IntToStr(PadNumber);
    If DisplayOnText Then
    Begin
        // Display the results onto a text document
        ExportResultsToTextEditor(PCBFilename,PadNumberString);
    End
    Else
    Begin
        // Display the results on a dialog
        DisplayResultsOnDialog(PadNumberString);
    End;
End;

An iterator is a compact method of accessing PCB objects without creating a mirror database across the PCB API. So the iterator is issued once to set up the search mechanism, and the interface representing the pad object found is always issued with a unique value every time a pad object is found. If this pad interface is zero, it implies that there are no more pads to find in the database. This is shown in Code Snippet 3 below.

Code Snippet 3: Iterator (within above Procedure) in commands.pas

// retrieve the board iterator
    Iterator        := Board.BoardIterator_Create;
    Iterator.AddFilter_ObjectSet([ePadObject]);
    Iterator.AddFilter_LayerSet_2(cAllLayers);
    Iterator.AddFilter_Method(eProcessAll);
    // search and count pads
    Pad := Iterator.FirstPCBObject;
    While (Pad <> Nil) Do
    Begin
        PadNumber := PadNumber + 1;
        Pad := Iterator.NextPCBObject;
    End;
    Board.BoardIterator_Destroy(Iterator););

Once the last pad object is found, the Board Iterator object is no longer needed and is therefore destroyed.

Server Processes and Parameters

A parametric server process allows the information that a server process needs to be passed when the server process is called. The ability to pass server process parameters allows direct control over the operation of a server process.

A parametric server process is a process with multiple parameters (a multiple name and value block) which could be used to dictate the course of this process. This method can be used instead of having multiple processes to do similar tasks in Altium Designer.  The parameters format for the Parameters variable, as part of the server process procedure that normally has the Command_NameOfProcess format, is composed of two identifiers as a block; the parameter name and the parameter value. Each block is separated by the Pipe symbol.

A typical Parameters block will look like this:

DocumentName1=4Port.PCB | DocumentName2=MyDesign.PCB | DocumentName3=Report.TXT 

From this example, the GetState_Parameter function processes the Parameters parameter to match the parameter value (which has the following format, DocumentName1, DocumentName2 etc) and returns the result (Value only which contains the actual document name), if any, into the value. It continues until there are no more DocumentName parameters. This function is not destructive; that is, the original Parameters parameter is not altered.

The routines that massage server parametric processes are defined in the EDPParam unit as part of the Altium Designer SDK. A process procedure is defined in the commands unit, and you can add your logic in this unit to interpret and extract required values of names from the Parameters variable.

In Code Snippet 4 (in the Commands.pas unit of a server project) the Command_CountPadObjects is the entry point where Altium Designer registers a server-specific process in its command launcher table. The pad count is displayed in a text document or on a dialog depending on the value of the Display parameter for the CountPads server process.

Code Snippet 4: Altium Designer to Add-on server entry point in commands.pas

Procedure Command_CountPads(View : IServerDocumentView; Parameters : WideString);
Var
  S : TDynamicString;
Begin
  // Check the parameters passed in by Altium Designer
  GetState_Parameter(Parameters,'DISPLAY',S);
 
  // If Display = True then post results on a text document otherwise post on a dialog.
  If UpperCase(S) = 'TRUE' Then
    CountPadObjects(True)
  Else
    CountPadObjects(False);
End;

If the server process has the Display = True parameter, then the procedure call is made to bring up the text editor so the pad count results will be displayed in a new text document. It will be saved as a text file with the same name as the PCB document, but with a .TXT extension, in the folder that holds the current PCB document. See Code Snippet 5 below.

Alternatively, if the Display=False condition is met, a dialog box is called to display the number of pads found - see Code Snippet 6. The parameter comes from the Command_CountPads procedure in the main.pas unit.

Code Snippet 5: Export to text procedure in commands.pas

Procedure ExportResultsToTextEditor(APCBFileName : TDynamicString; PadCount : TDynamicString);
Var
    NewPCBFileName : TDynamicString;
    FilePath       : TDynamicString;
    Report         : TStringList;
    ReportDocument : IServerDocument;
Begin
    FilePath       := ExtractFilePath(APCBFileName);
    If FilePath = '' Then
        FilePath   := ExtractFilePath(GetTemporaryFileName);
 
    NewPCBFileName := ExtractFileName(APCBFileName);
    NewPCBFileName := ChangeFileExt(NewPCBFileName,'.txt');
    NewPCBFileName := Filepath + NewPCBFileName;;
 
    Report := TStringList.Create;
    Report.Add(DateToStr(Date));
    Report.Add('-------------------------------------------------------------');
    Report.Add('There are ' + PadCount + ' pad(s) on this' + ExtractFileName(APCBFilename) + ' document.');
    Report.SaveToFile(NewPCBFileName);
    Report.Free;
 
    // open and display the textfile
    ReportDocument := Client.OpenDocument('Text',PChar(NewPCBFilename));
    If ReportDocument <> Nil Then
    Client.ShowDocument(ReportDocument);
End;

The ExportResultsToTextEditor procedure will create and open a new text document and display the number of pads found using the TStringsList class provided by Delphi's Classes unit.

Code Snippet 6: Display on dialog procedure in Commands.pas

Procedure DisplayResultsOnDialog(PadCount : TDynamicString);
Var
  DisplayForm : TDialog;
Begin
  DisplayForm := TDialog.Create(Application);
  DisplayForm.Label1.Caption := PadCount;
  DisplayForm.ShowModal;
  DisplayForm.Free;
End;

Here, the DisplayForm variable is declared and defined in the DisplayForm unit. The result is a simple dialog with a close button. The Altium Designer application handle needs be passed to this dialog, so this dialog appears as part of Altium Designer.

Code snippet 7: Server module creation function in main.pas

// The new server module sets up the command launcher table which stores commands (processes).
Function PluginFactory (AClient : IClient) : IServerModule; Safecall;
Begin
    // name of addon server passed in
    // the installation file with INS extension needs to have the same name
    Result := TAddOn.Create(AClient, 'AddOn');
End;

To see the final code for the Commands unit, refer to the complete Commands.pas file in the \SDK\Addon Complete\ folder.

You can use the example files, or copy and paste the above command code snippets into the commands.pas unit of your server project and update the InitializeCommands procedure (Code snippet 7, above) in the main.pas unit. You will also need the DisplayForm (pas/dfm) unit before you can compile the project. These files (and others) can be found in the \SDK\Addon Complete\ folder.

Compile the server project by selecting Build from Delphi's Project menu (Project » Build).

Server Installation File

The next step is to create or edit the server installation file, Addon.ins, which should reflect the server processes declared and defined in the commands.pas and main.pas units of the Add-on server project. The Command Name clauses need to include the commands defined in the other units (for example, CountPads).

Installation file: AddOn.ins

Installable Server File: Addon.ins
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 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

Executing the CountPads Command

Copy all the relevant files to Altium Designer's \System folder, then run Altium Designer and load a PCB document that has a number pad objects.

In the DXP System menu, click the Run Process button

Running a process from the DXP System menu in Altium Designer

In the Run Process dialog, click Browse and select the Add-on extension. Select the AddOn:CountPads process, click OK, then click the button again to run the Add-on's process. The Add-on extension checks for the presence of a PCB document, then it counts the number of pads on this document. The number of pad objects found is displayed or written out to a text document.

An easier way to debug your server project

To revise the code, the Add-on server needs to be stopped first by closing Altium Designer. The project source can then be revised in Delphi and the project re-compiled. Make sure the updated DLL file is copied into Altium Designer's system folder if it was generated in a folder other than the default \System\ folder.

There is, however, an easier method; you can execute Altium Designer from Delphi using the Run menu within Delphi. For this approach, you need to set the compiler so that the DLL is generated in Altium Designer's \System folder, and set the compiler break points.

To set the DLL output path for the compiler debugging setup, open the Project Options dialog from Delphi's Run » Parameters menu. Use the Browse button to specify the Host application path to the Altium Designer application (the executable) for debugging your server.

Setting up the path to Altium Designer in the Host Application field

Then set the Output directory field on the Directories/Conditionals page of the Project Options dialog to the default \System path, or where your Altium Designer system is installed (see below).
.

Setting the DLL output directory for debugging the server

With the paths defined, breakpoints can then be set in your server code and run in Altium Designer from Delphi IDE, allowing you to step into the server code whenever the breakpoint is encountered.

Recommended Debug compiler settings are shown in the figure below. These are found in the Compiling page under Delphi Compiler section in the Project Options dialog.

Setting the debugging compiler options in Delphi for extension server projects

Extending the server project

A extension server, in this case the add-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.

As a reminder, 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 filenames.

This section explores three methods that extend the Add-on extension project:

• Executing a PCB command from within the Add-on project
• Adding the project's process launchers in the PCB editor
• Adding a new floating toolbar with the project's process launchers

Once the three methods are completed to enhance the Add-on project, the following physical files will be included to plug into Altium Designer:

Server project files

The complete Add-on extension 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 functionality requires that the two new files, the resources and toolbar files, be included.

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 (with the exception of the Addon.tlt file, for some SDK installations) can be found in the \SDK\Examples\Addon Complete folder.

Executing a PCB process from the extension

The Add-on server itself can invoke and execute different server processes when running in Altium Designer.

Here, another command procedure is included in the Add-on project; the first command procedure is CountPads which counts pads from the current PCB document, and the second process, RunAPCBProcess runs the PCB Server's BoardInformation process. In order to invoke the PCB editor's BoardInformation process from the extension server, the source units of the project (Main.pas, Commands.pas and AddOn.ins) are expanded as follows.

Refer to the snippets below in which you can copy and paste into your own server project, or use the files from the \SDK\Examples\AddOn Complete folder.

Main Unit
In the main.pas unit, the InitializeCommands procedure include the new Command_RunAPCBProcess procedure for the RunAPCBProcess process.

Command initialization in the main.pas unit:

Procedure TAddOn.InitializeCommands;
Begin
    FCommandLauncher.RegisterCommand('CountPads' , @Command_CountPads);
    FCommandLauncher.RegisterCommand('RunAPCBProcess', @Command_RunAPCBProcess);
End;

Commands Unit

Two parts in the Commands.pas unit have entries for the new command; the Command_RunAPCBBProcess procedure in the Interface section, and the Command_RunAPCBProcess procedure the Implementation section.

Interface section in the commands.pas unit:

Procedure Command_CountPads       (View : IServerDocumentView; Parameters : WideString);
Procedure Command_RunAPCBProcess  (View : IServerDocumentView; Parameters : WideString);

Implementation section in the commands.pas unit:

Procedure Command_RunAPCBProcess(View : IServerDocumentView; Parameters : WideString);
Var
    _PCBServer : IPCB_ServerInterface;
Begin
    // Check if PCB document exists. If not stop the server.
    _PCBServer := PCBServer;
    If _PCBServer = Nil Then
        Exit;
    RunCommand('PCB:BoardInformation','');
End;

Finally, in the server installation file, another Command Name clause is added for this RunAPCBProcess command.

Complete Addon Installation file (Addon.ins)

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 law and international treaties.'
    Copyright         = 'Copyright © Altium Limited 2012'
    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

Note that later, a toolbar definition will be added.

Save all the files and recompile the Add-on project. Don't forget to copy the latest server installation and server module files into the System folder within the Altium Designer installation.

Setting up the project's Processes in the PCB Editor

You can execute a server process from Altium Designer's Run Process dialog to launch the Add-on 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 server will add its process launchers in the PCB editor when the extension 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 Add-on server's menu items in the GUI. Also note the new toolbar buttons positioned to the right of Help, in the main Menu.

Modifying the server configuration files that update the PCB Editor GUI

To add new resource items that link to the Add-on extension's processes in the PCB Editor, these server files need to be updated: Addon.ins installation file, Addon.rcs resources file, the new Addon.tlt tools locations file (see below), and 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 extensions (AutoPlace, MakeLib, etc) are processed and set up, changing the PCB menus and other PCB resource items as dictated by the extension servers.

To register the Add-on project's resources, the AdvPCB installation file needs to be updated to include the user interface details from the extension 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 Add-on 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 Add-on server 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 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 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 full resources file for the Add-on extension is as follows. Later, an Insertion–End block for a toolbar will be added.

Complete 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 Add-on server 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.

Add-on project Installation file (AddOn.ins): 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 Add-on extension 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 Add-on extension via one of the three new menu items in the PCB's View menu.

Adding new Toolbars to the PCB Editor's Workspace

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

• Define a new BarLayout block for the Add-on server's 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 Add-on extension's toolbar

The figure above is a screen shot depicting the Add-on' projects toolbar floating on the PCB work-space. The first step is to define the resources file for the Add-on server 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 floating toolbar will be called TLAddon.

Next, the new addon's tool layout file is defined with a TLT extension and the project'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 the Altium Designer's graphical user interface. 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 Add-on extension 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 from the Add-on server, 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 project 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 addon resources file. Finally a BarLayout block for the toolbar in the project TLT file (don't forget to specify the BarName and BarDocumentKind clauses).

Add-on example 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 Server Resources File

An extension server 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.

Add-on project resources file (addon.rcs): Add toolbar Tree block

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 extension in the PCB workspace, you would need to define a layout file for the extension server.

Add-on project 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 for the Add-on server 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 project's 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 from an extension server for example, you need to have Insertion clauses in the project's resources file with TargetID and RefID0 referencing user interface element IDs in the PCB Editor's server resources file.

To add an extension server's toolbar to a PCB Editor for example, 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)

Refer to the Add-on extension example in the \Examples\Addon Complete\ folder.

Further information

Refer to the Delphi SDK How-to FAQ and Delphi SDK Reference documents for more information on developing and deploying extension servers using the Altium Designer SDK.

To explore the supplied SDK examples, take a look at various software extension projects in the \SDK\Examples folder of Altium Designer SDK installation.