Technical Reference - System API
Parent page: Altium Designer API Reference
This section of the Altium Designer API documentation provides a detailed reference of the low-level System API interfaces.
System API Reference
The base Object Interfaces and Routines available for scripting in Altium Designer are:
- Client Server Interfaces
- Routines that deal with server processes
- Routines that deal with low level implementation
- Routines and objects exposed from Borland Delphi units (in Helper Functions and Objects section) for the scripting system.
The Altium Designer API includes a large number of interfaces that are exposed to the scripting system, as detailed below.
Altium Designer System API Interfaces
IServerModule Interface |
INotificationHandler Interface |
IDynamicHelpManager Interface |
The above interfaces, and their respective methods and properties, are covered in the following System API documents:
References for the System API
Separate references for other Altium Designer APIs
- Schematic Object Model - refer to the Schematic API Reference
- PCB Object Model - refer to the PCB API Reference
- Integrated Library Object Model - refer to the Integrated Library API Reference
- Workspace Manager Object Model - refer to the Workspace Manager API Reference
System API core interfaces
Client Server API Reference
The Client-Server API reference covers interfaces for Client and Server objects in the Client-Server Object Model part of the Altium Designer API. These objects are also exposed for use by the scripting system.
What are Interfaces?
Each method in the interface is implemented in the corresponding class. Interfaces are declared like classes but cannot be directly instantiated and do not have their own method definitions. Each interface, a class supports is actually a list of pointers to methods. Therefore, each time a method call is made to an interface, the interface actually diverts that call to one of it's pointers to a method, thus giving the object that really implements it, the chance to act.
The Client/Server interfaces exist as long there are associated existing objects in memory, thus when writing a script, you have the responsibility of checking whether the interface you wish to query exists or not before you proceed to invoke the interface's methods.
You can obtain the IClient
interface object by calling the Client
function in a script and execute methods from this function directly for example calling this Client.OpenDocument('Text',FileName);
method is valid.
The empty workspace or the shell of Altium Designer is the top level client window. The client module is represented by its IClient
interface object, and you can have the ability to take a peek into a loaded server’s data structures through this IClient
interface. Servers are represented by its IServerModule
interfaces which are plug in modules in Altium Designer.
Example
Var
ReportDocument : IServerDocument;
Begin
If Client = Nil Then Exit;
// Opens and shows a text file in Altium Designer
ReportDocument := Client.OpenDocument('Text',FileName);
If ReportDocument <> Nil Then
Client.ShowDocument(ReportDocument);
End;
Script Examples
There are Client / Server script examples in the \Examples\Scripts\DXP
folder
Using Client / Server Interfaces
Central to the Altium Designer architecture is the concept of a single client module as the controller collaborating with loaded servers. Each server manages their own documents. This is a big picture view of the Altium Designer– there is one Client executable and several servers as loaded dynamic library linked modules as shown in the diagram below.
Object Interfaces
The IClient
interface represents the Client subsystem of the Altium Designer application and the Client subsystem manages the commands (pre packaged process launchers), process depths and documents of loaded servers. Every server module loaded in Altium Designer is linked to the client subsystem of Altium Designer, so you have access to the specific loaded documents.
The client module maintains a list of loaded servers, that is this module stores many lists of opened server documents, loaded server processes, loaded server resources.
You can obtain the IClient
interface object by calling the Client
function in a script and execute methods from this function directly for example calling this Client.OpenDocument('Text',FileName);
method is valid.
The Client
function returns you the IClient
interface object.
Client Interfaces
ICommandLauncher
(deals with process launchers)IServerDocumentView
(deals with panels or server documents)IProcessControl
(determines the level of stacked processes)IGUIManager
(deals with the User interface, the locations and state of panels)IServerModule
(deals with loaded servers)INotification
(broadcast or dispatch notification messages to servers or to a specified server)
Server Interfaces
The IServerModule
interfaces represent loaded servers in Altium Designer. To obtain the server module and invoke the methods from this module, you can use the ModuleName
property with the name of the server passed in, then if all is well, launch the process for that server. An example is shown below:
Example
If StringsEqual(ServerModule.ModuleName,'TextEdit') Then
Begin
ServerModule.CommandLauncher.LaunchCommand('TextEdit:MoveCursorToTopOfDocument',
Nil,0,ServerDocument.View[0]);
End;
The relationship between a Server, its Documents and Views
An IServerModule
interface has the following interfaces:
ICommandLauncher
(deals with a server’s processes table)IServerView
(represents a view window of the system. The ancestor interface ofIServerDocument
andIServerDosumentView
)IServerDocument
(represents a loaded design document in Altium Designer)IServerDocumentView
(deals with a document view - either the document window or panel window)IExternalForm
(represents Altium Designer -aware Delphi forms - either as a document form or a panel form. These forms are wrapped by theIServerDocumentView
orIServerView
interface object. ThisIExternalForm
interface object has low level methods such as resizing and displaying the form)IProcessControl
(represents the level of stacked processes for the focused server document)INotification
(represents the system notifications from the Client system that are sent to all server modules. Also, documents and associated panels can be synchronized through the use of notifications).
Server Documents and Panels Interfaces
The concept of documents and panels are central to understanding how servers work in Altium Designer. The servers manage their own panels and documents. Altium Designer has access to the currently active panels and documents and manages their the size and position. Basically there are two types of panels — panels associated with documents and standalone panels such as the Messages panel.
Each server loaded in Altium Designer stores its own documents (there can be different document kinds, for example PCB and PCB library documents) and each document has its corresponding panel, for example the PCB panel and the PCB document. In practice, a server has its own document containers, where each container stores its matching document kind. Each document container stores views of documents and associated panels, along with standalone panels if any.
In the Altium Designer screen image above, there are two PCB documents open, with the Projects panel on the left and the PCB panel floating on top of the focused PCB document. Each element has a main interface that is used to represent represent the servers, documents and panels in Altium Designer as shown above.
The Client system within the Altium Designer has access to the active document and panel views directly, therefore a panel’s boundaries and visibility can be set programmatically via the IClient
and its composite IClientGUIManager
interfaces. The Client and the Server module nas its own Command Launcher functionality which is used to execute a server process. This is encapsulated as the ICommandLauncher
interface.
Altium Designer's Workspace manager server has several IServerView
interfaces – Files panel, Projects panel, Messages panel, Navigator panel, Compile Errors panel, Differences panel, To Do panel and so on.
There are three main interfaces that apply to the example screen above: the IServerModule
, IServerView
and IServerDocumentView
interfaces.
IServerModule Interfaces
Each loaded server in Altium Designer is encapsulated by the IServerModule
interface, so from figure above, there is an IServerModule
interface for the PCB editor server, another one for the Work-space Manager server, and so on.
IServerView Interfaces
An IServerView
interface points to a global (standalone) panel that can deal with multiple types of documents, for example the Projects panel. This Projects panel is controlled by the Workspace manager server and is represented by the IServerView
interface.
IServerDocumentView Interfaces
A PCB document has an editor (document) view and three associated panel views (Navigator, PCB List and PCB Inspector panels), where all are represented by the same IServerDocumentView
interface. Therefore in the image above, there are ten IServerDocumentView
interfaces — two representing the PCB documents and the two sets of four PCB panels (the Expression Filter as the List panel, Object Inspector as Inspector panel, the PCB Navigator and the PCB panel). Note that only the PCB panel is displayed but all panels are active in computer’s memory.
Client Server Interfaces
The major interfaces that are used in the client–server architecture within Altium Designer are:
IClient shell and its Interfaces:
ICommandLauncher
(deals with the client’s process launchers table)IProcessLauncher
(deals with launching a server process from the client)IServerDocumentView
(deals with panels or server documents)IProcessControl
(determines the level of stacked processes)IGUIManager
(deals with Altium Designer's user interface, and the locations and state of panels)IServerModule
(deals with a loaded server in Altium Designer)INotification
(Client can broadcast or dispatch notification messages to servers, or to a specified server)
Altium Designer Configuration Interfaces:
- IServerRecord (collects servers information at Altium Designer’s start up – not loaded servers)
- IServerWindowKind (determines which document kinds open in Altium Designer)
- IServerProcess (contains the information of a current server process)
IServerModule Interfaces represent loaded servers
An IServerModule interface has the following interfaces:
ICommandLauncher
interface (deals with a server’s processes table)IServerDocument
interface (represents a loaded design document in Altium Designer)IServerView
interface (represents a panel that can have a view of the Altium Designer system)IServerDocumentView
interface (deals with a document view — either the document window or panel window)IExternalForm
interface (represents the Altium Designer -aware Delphi form, either as a document form or a panel form. These forms are wrapped by theIServerDocumentView
orIServerView
interface objects. ThisIExternalForm
interface object has low-level methods such as resizing and displaying the form)IProcessControl
(represents the level of stacked processes for this focused server document)INotification
interface (receives system notifications from the Client system — all server modules receive these notifications)