What are the System Requirements for the Altium Designer SDK?
To develop software Extensions for Altium Designer using the Altium SDK, you need to have Embarcadero Delphi XE2 or later, the SDK and Altium Designer 13 or later. You can use any recent Delphi edition to build Altium Designer software Extensions; Embarcadero Delphi Starter edition (a low cost option), Professional edition, Enterprise, Architect and the Ultimate edition all work fine with the Altium SDK.
The Altium Designer SDK itself is composed of three main APIs; the DXP – a set of Electronic Data Platform API units, the PCB Editor API and the Schematic API. Note, each API has a set of source code units in Delphi / Object Pascal. Note that C++ and C# versions of the Altium SDK are also available.
Permissions
With the standard Altium SDK installation on Windows 7, the Embarcadero Delphi application may not be able to write directly to the SDK’s \Examples folder, or to Altium Designer's \System folder. The system's default Folder/User Permissions are the issue.
Windows' folder and user permissions could be modified to suit, but the simplest way to work around this is to manually copy the created DLLs and drop them in Altium Designer’s System folder, along with the extension project's configuration files, such as INS and RCS files. See the Setting up your Server Projectsection in the Getting started: Building a Delphi extension document for more information.
DXP Platform
Copy LinkCopied
Can I save a Schematic document in another file format using SDK?
Yes. The available document formats are: Ascii, Orcad, Template, Binary, standard schematic binary, AutoCad DXF and AutoCad DWG for schematic documents. Note that the three strings, Template, Binary and a blank string "" represent the same Altium Designer Schematic Design format.
To save the document into another format, you need to set the documentKind parameter to one of the following format strings:
'ASCII' – ASCII format
'ORCAD' – ORCAD format
'TEMPLATE'
'BINARY' – standard binary format
'AUTOCAD DXF' – DXF format
'AUTOCAD DWG' – DWG format
Is it possible to determine if the project is compiled and whether the compilation is up to date?
For many operations the project needs to be compiled. Without knowing if the project is compiled and wasn’t modified since then, all you can do is compile the project blindly each time before accessing the data. There is a way to avoid this unnecessary compilation.
You can use the DM_NeedsCompile method from the IProject object interface (EDPInterfaces unit) to determine whether the project needs compiling.
The declaration of this function from the IProject interface is: Function IProject.DM_NeedsCompile : LongBool;
Can a server module only be created in the PluginFactory function (as in the SDK samples)?
Is there is any other way? When does Altium Designer call the PluginFactory function? During launch or during a plugin command call from the Altium plugin panel?
You can create your server module anywhere, for example during loading the DLL module (in the Initialization clause).
The Altium Designer application calls the PluginFactory function right after loading the Dynamic Linked Library file (DLL). In this case the PluginFactory function in the Main unit is the best place for creating your server module.
Usually Altium Designer loads a specified server module (calls the PluginFactory function) when it has to launch a command related to this server module. But you can set the "SystemExtension = True" clause in your extension server installation file within the Server End block. In this case, Altium Designer will load your server module on startup automatically.
Can projects from older versions be updated to Altium Designer 13.1?
All of the compatibility issues are concerned with the main unit of a server project prior to Altium Designer, such as DXP Service Pack 2. Certain keywords such as stdcall, NewDocumentInstance, AddCommand methods all need replacing.
The main unit of the server project needs revising with the following items:
Replace AddCommand procedure with RegisterCommand procedure
Comments: Replace AddCommand method with RegisterCommand for the CommandLauncher as an aggregate class of the TServerModule class. The AddCommand method doesn't exist in Altium Designer. Use the RegisterCommand method instead to store a declared command (process) in the server table in Altium Designer.
Replace Stdcall with SafeCall;
Comments: This safecall keyword is used in the COM world and is better protected against failures of importing functions across a boundary such as an EXE to a DLL.
Replace PChar with WideString methods.
Comments: The NewDocumentInstance method of a TServerModule has its parameter signature changed slightly – replace PChars with WideStrings.
How do I execute other processes from my extension?
The MessageRouter_SendCommandToModule function in EDPUtil unit, allows your extension server to run a process from other server. The parameters for this function are Process, Parameters, EditorWindow.
The target window handle specifies the window handle of the target document object for the process to run on. If there is no document supported by the server this parameter should be set to Nil. This function automatically starts the target server if the server is not already started.
Processes can return results using the Parameters parameter. For example the "Client:RunCommonDialog" process runs a dialog and then returns the result through this parameter.
The string 'Action=Document' is assigned to the Parameters parameter and then it is passed in the process string SCH:Zoom and the zoom command is executed on a current schematic document.
How do I add a new Delphi form into my extension Project?
By default, Delphi automatically creates the application's main form in memory by including the following code in the application's project source unit: Application.Create(TForm1,Form1);
These projects are compiled as EXE (executable) files. However server projects are complied as DLLs files thus, the main forms are not auto created at run time. You will have to create the forms dynamically. The procedure to attach a dialog form to your server project is as follows:
Click File » New » VCL form from Delphi and a form is then generated in your server library module (in the project file), and adds the Form clause in the library source's Uses clause.
Make sure the unit associated with the new form is in focus. Add the appropriate Altium Designer APIs, for example EDPClasses to the Uses directive for this new unit.
The next step is to create the dialog at run time (whenever a process is invoked and display the dialog). The processes defined in the commands.pas unit of a server project is the starting point, and inside each process could lead to a function being called from another unit part of this server project. You need to implement the following code snippet to activate the form.
Creation of a dialog example in the commands.pas unit
To obtain the application handle of Altium Designer so that the dialog's owner handle belongs to Altium Designer, you would need to set the Client.ApplicationHandle to the Application.Handle in the ServerFactory function in the main unit of the server project. This dialog will thus adopt Altium Designer's icon and only one same icon appears on the tasking bar.
Result := TCustomizedServerModule.Create(AClient, 'CustomServer');
4
Application.Handle := Client.ApplicationHandle;
5
End;
How do I open a document using a specific path?
Use the OpenDocument and ShowDocument methods of the IClient interface, or the DM_GetDocumentFromPath method from the IWorkspace interface (from the EDPInterfaces unit)
To fetch an active document of a loaded project in Altium Designer, you need to use the DM_FocusedDocument method from the IWorkSpace interface (EDPInterfaces unit).
How do I set my document to be the focused or active document?
Use the SetFocus method from the IServerDocumentView interface (EDPInterfaces unit) or Focus method from the IServerDocument interface.
Note that a document (of IServerDocument type) can have several document views, and in this case, the IServerDocument has a View property which is an indexed list of IServerDocumentViews. You will need to iterate to get the specific document view before you can apply the SetFocus method.
You need the workspace object first, and then invoke the DM_FocusedProject method to get the active project. The GetWorkspace function is from the EDPUtil unit. The IWorkspace interface is from the EDPInterfaces unit.
How can I configure and execute outputs in OutputJob documents?
To get the OutputJob documents from the project you need to iterate all logical documents and find the document containing DocumentKind equal to "OUTPUTJOB".
Follow these steps to execute OutputJob from the SDK:
Find OutputJob file in the project (iterating through the logical documents).
Open this file and make it active.
Run the command depending on the "output container" you want to use.
To iterate PCB objects on a PCB document, you need to fetch the PCB document first, and then set up an iterator with initial conditions (such as layers, object types the iteration method) and then run the iteration process until there are no more objects to be found.
How do I iterate specific PCB objects?
To iterate for specific PCB objects, you need to set the Object Set filter of the object iterator with a PCB type.
You can invoke the Selected property of a PCB design object and get or set the selected boolean value. All PCB objects’ object interfaces are inherited from the IPCB_Primitive interface.
How do I update a PCB object?
When you modify the attributes of a PCB object, you need to invoke the PCB board’s DispatchMessage methods to refresh the PCB object. This is a two step process with PCBM_BeginModify parameter for the DispatchMessage method before the object is being changed and then another DispatchMessage call with the PCBM_EndModify parameter.
How do I add a new PCB object to the PCB document?
You use the PCBObjectFactory method from the PCBServer object to create a new PCB object and add it to the PCB document. To create a track object, you need to specify whether it is used as a dimension or not. The declaration for this PCBObjectFactory method is as follows;
The parameters, AObjectID represents the actual design object, ADimensionKind (basically for tracks and arcs) and ACreationMode which is eCreate_Default by default.
How do I add a new Parameter to a Schematic document?
Is it possible to make this Parameter non-visible to the end user (so having some kind of an internal property), or at least make it read-only (and writable only through SDK or several 'clicks' so that a user does not change or delete it by mistake)?
You can manage parameters for Schematic document but you can't set a parameter as hidden or read-only. Here is an example of how to iterate them and add a new parameter:
Schematic sheets are part of a project, so to have access to a sheet, you need to fetch the workspace and the schematic server handles. The workspace manager object gives you the ability to find the focused document and then check the document type. Once it is a schematic document type, you can then proceed to add, delete or update schematic objects.
Sch_Sheet := ISch_Sheet(Sch_Doc); //this is the focused sheet
17
End;
18
End;
19
End;
How do I iterate schematic objects?
To iterate Schematic objects on a Schematic document, you need to fetch the Schematic document first, and then set up an iterator with initial conditions (such as object types and the iteration method) and then run the iteration process until there are no more objects to be found. Note with iterators, it is possible to look for parent objects only or parents and their child objects on a schematic document.
How do I iterate specific schematic objects?
You set up an interator object invoked from the schematic sheet object, set the iteration depth, specify the object types before starting the iteration.
You can invoke the Selection property of a Schematic design object and Get or Set the selected boolean value. Schematic objects’ object interfaces are inherited from the ISch_GraphicalObject interface.
How do I iterate/update/add parameters to schematic object/document?
Graphical User Interface of Altium Designer
Copy LinkCopied
How do I create menu items in an existing menu and assign my code to be executed?
You need to assign your extension server's process launchers to the new menu items in a target’s menu (the target can be the PCB or the Schematic Editor for example). You need to do three things:
You need to update the resources file (with the RCS file extension) with the Insertion End blocks.
Insert the Updates clause with the name of the target editor (for example the PCB editor has a AdvPCB name) in the project's installation file (with the INS file extension).
Insert the name of your extension server in the ResourceDependencies block of the target editor installation file (the PCB or the Schematic editor’s installation file).
To do this, you need to know the Target ID and Resource reference ID values that indicate where the new menu items should appear in the editor’s menu. These TargetID and RefID0 identifiers can be referenced from the editor’s RCS file in the Altium Designer’s system folder, for example the PCB editor’s AdvPCB.rcs file.
The Process Launcher Tree section in the resources file (with a RCS file extension) defines where the menu items containing the process launchers are going to be attached to in a specific menu.
How do I add my menu item to PCB menu?
You need to update the project resources file (with the RCS file extension) with the Insertion End blocks.
Insert the Updates clause with the ‘AdvPCB’ name within the Server End block in the installation file (with the INS file extension).
Insert the name of your extension project in the ResourceDependencies block in the AdvPCB.ins resources file.
HelpAboutInfo = 'This software is protected by copyright law and international treaties.'
08
Copyright = 'Copyright c Altium Limited 2013'
09
SupportsDDB = True
10
11
ResourceDependencies
12
'AutoPlacer'
13
'CompMake'
14
'HSEdit'
15
'LayerStackupAnalyzer'
16
'Macro'
17
'MakeLib'
18
'PCB3D'
19
'PCBMaker'
20
'PCBMiter'
21
'Placer'
22
'SignalIntegrity'
23
'HelpAdvisor'
24
'OrcadLayoutImporter'
25
'SavePCADPCB'
26
'AutoPlacer'
27
'PinSwapper'
28
'YourPlugInName'
29
End
30
End
How do I create a button and assign this to my extension’s command (process launcher)?
You would need images for such buttons and these bitmaps in 18x18 pixels in size. Copy the button files (with a BMP file extension) into the Altium Designer’s installation ..\System\Buttons folder.
These files are used for the images beside the menu items in a menu of the editor as well as the buttons of a toolbar.
How do I create my own panel?
To add and manage global panel views in your server, you need to build a panel manager object and define its corresponding object interface. This object will manage the global panel. This panel manager object is also exposed as an interface so it can be used in the TServerModule object which represents the Extension.
You will need the Delphi form that represents this panel, and the panel is encapsulated as a private field in the panel manager object as well as in the TServerModule object. To build a global panel view, the global panel view needs to be inherited from the TServerPanelView class, and the global panel form needs to be inherited from the TServerPanelForm class.
The three fields need to be added in the TServerModule class;
The panel form (TServerPanelForm)
The panel view (TServerPanelView)
The panel manager (a standalone class and its interface representation with exposed methods).
Two methods that are added in the TServermodule class;
HandleNotification handler
CreateServerViews method
A property to add in the TServerModule class;
Panel Manager property that represents the panel manager object
TServerPanelForm Object
In the TServerPanelForm constructor, the notification handler is registered with the client module and the self parameter is passed in. The destructor unregisters the notification handler. The HandleNotification method handles whether the panel is changing or not.
TServerPanelView Object
Normally a TServerPanelView object is a direct inheritance from this class and there is no need to add or override methods. These methods are done by the Client system of Altium Designer.
The Panel manager Object
There needs to be an interface representation of the manager within the Panel manager unit, so that the methods needed to manage the global panel are exposed to the system. The interface representation is defined in the manager class, and there is the panel form field as well as the interface methods. When the panel manager is created, the panel form is associated with this manager object so that the panel's form controls can be updated.
TServerModule Object
In the TServerModule constructor, where the server commands are registered, is where to create global panel views and panel managers. The register notification handler needs to be set up here as well. The CreateServerViews method will have the global panel form and the view created with this global panel form. The view is then added to the server module (TServerModule.AddView() method) as well as in the client (Client.AddServerView method). In the ServerModule destructor, the panel manager is set to nil and the notification handler un-registered.
Installation file
The installation file needs to be updated with a new PanelInfo block to reflect the global panel. For example;
How do I create my own editor for files of my type?
You need to do two things to create your own editor to edit its own document types.
1. Server Module and its Documents in the Main.pas file
The main.pas unit is where the server document classes and the server module class are defined and implemented. The server processes are also defined and implemented in this unit, and a corresponding interfaces unit is defined and linked for these server processes. There is the ServerFactory function which is invoked (only once) by the Client module in Altium Designer when its associated graphic documents are being loaded. That is, the Graphic Viewer server is loaded in memory once.
This main.pas unit deals with two classes – the TServerModule and the TServerDocument classes.
The TServerModule class is inherited and expanded into the TGraphicViewerModule class. The TServerDocument is inherited and expanded into the TGraphicDocument class.
The TServerDocument class implements the processes, controls the panels and views plus the file save and load methods. The processes are declared in the main.pas unit and the interfaces implemented in the commands.pas unit.
See the GraphicViewer Main.pas file in \Examples\GraphicViewer\ folder of the SDK installation.
2. You need to specify the EditorWindowKind blocks in your editor’s installation file.
Each document kind is represented by this EditorWindowKind block. You will also need to specify the LoadFilters and SaveFilters sub-blocks within each EditorWindowKind block.
You can check out the Graphic Viewer example from the SDK folder.
If you find an issue, select the text/image and pressCtrl + Enterto send us your feedback.
