Technical Reference - System API

Parent page: Altium NEXUS API Reference

This section of the Altium NEXUS 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 NEXUS 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 NEXUS API includes a large number of interfaces that are exposed to the scripting system, as detailed below.

Altium NEXUS 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 NEXUS 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 NEXUS 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 NEXUS 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 NEXUS.

Example

Var
    ReportDocument : IServerDocument;
Begin
    If Client = Nil Then Exit;
    // Opens and shows a text file in Altium NEXUS
    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 NEXUS 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 NEXUS– 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 NEXUS 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 NEXUS is linked to the client subsystem of Altium NEXUS, 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 NEXUS. 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 NEXUS)
• IServerDocumentView (deals with a document view  - either the document window or panel window)
• IExternalForm (represents Altium NEXUS -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 NEXUS. The servers manage their own panels and documents. Altium NEXUS 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 NEXUS 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 NEXUS 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 NEXUS as shown above.

The Client system within the Altium NEXUS 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 NEXUS'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 NEXUS 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 NEXUS 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 NEXUS's user interface, and the locations and state of panels)
• IServerModule (deals with a loaded server in Altium NEXUS)
• INotification (Client can broadcast or dispatch notification messages to servers, or to a specified server)

Altium NEXUS Configuration Interfaces:

• IServerRecord (collects servers information at Altium NEXUS’s start up – not loaded servers)
• IServerWindowKind (determines which document kinds open in Altium NEXUS)
• 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 NEXUS)
• IServerView interface (represents a panel that can have a view of the Altium NEXUS system)
• IServerDocumentView interface (deals with a document view — either the document window or panel window)
• IExternalForm interface (represents the Altium NEXUS -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)