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

The above interfaces, and their respective methods and properties, are covered in the following System API documents:

References for the System API

• Client-Server Interfaces
• System Interfaces
• Types and Constants
• Low-level Routines
• Server Processes

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 of IServerDocument and IServerDosumentView)
• 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 the IServerDocumentView or IServerView interface object. This IExternalForm 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 the IServerDocumentView or IServerView interface objects. This IExternalForm 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)