Using the WorkSpace Manager API

Now reading version 20. For the latest, read: Using the WorkSpace Manager API for version 22
 

Parent page: Using the Altium Designer API

Please note that this documentation was last updated for an older version of Altium Designer. While many of the principles and approaches will remain the same, be aware that interfaces, objects, methods, properties, and the like will have changed since then, and will not reflect the entirety of those found in later versions of the software.

Using the Workspace Manager Interfaces

The Workspace Manager is a system extensions server which is always running when Altium Designer is loaded in memory. The Workspace Manager provides project functionality of grouping of files and provides a bridge between source documents (such as Schematic documents) and its corresponding primary implementation documents (such as PCB documents).

This Workspace Manager provides information on how a project is structured, information on nets and its associated net aware objects of source and implementation documents.

This Workspace Manager also provides you with the ability to manipulate the contents of a design project in Altium Designer.

The document interfaces in the Workspace Manager can refer to documents which may not be open in Altium Designer, whereas the IServerDocument interfaces only references loaded documents in Altium Designer. To have access to data within the Workspace Manager, you need to have access to the IWorkSpace interface object which references the workspace manager.

Simplified Workspace Manager Object hierarchy

IWorkspace
  IProject
    IDocument
        ISheetSymbol
        IComponent
        IBus

Main Workspace Manager Interfaces

  • The IDMObject interface is the ancestor interface used for many Workspace interfaces.
  • The IWorkSpace interface is the top level interface and contains many interfaces within. For example the IWorkSpace interface has a DM_OpenProject function which returns a currently open or currently focussed IProject interface.
  • The IProject interface represents the current project in Altium Designer.
  • The IPart interface represents a part of a multi-part component. This component is represented by this IComponent interface.
  • The IDocument interface represents a document in Altium Designer.
  • The IComponentMappings interface is used for the Signal Integrity models mapping to Schematic components.
  • The IECO interface represents the Engineering Change Order system in PCB and Schematic editors.
  • The INet interface is a container storing Net aware objects (which are INetItem interfaces) that have the same net property. So there are INet interfaces representing nets on a document.
  • The INetItem interface is the parent interface for the Cross interface. Pin, Port, Netlabel, Sheet entry and Power Object Interfaces are direct representations of the INetItem interface so these objects can be part of a net.

GetWorkspace function

The Function GetWorkspace : IWorkspace; returns the Workspace Manager interface object within your server project. With this interface, you can extract extra information about a project and its associated documents and their design objects on them.

Using the GetWorkSpace function in a DelphiScript

Var
    i        : Integer;
    Document : IDocument;
    Project  : IProject;
Begin
    Project := GetWorkspace.DM_FocusedProject;
    If Project = Nil Then Exit;
    For i := 0 To Project.DM_LogicalDocumentCount - 1 Do
    Begin
        Document := Project.DM_LogicalDocuments(i);
        ShowMessage(Document.DM_DocumentKind);
    End;
End;

Compiling a Project

A project needs to be compiled first so you can have access to the most current data which provides a snapshot of the latest status of a design project. There are two ways you can compile the project which are shown below.

Compile with Project.DM_Compile example

Procedure CompileProject;
Begin
    Project := GetWorkspace.DM_FocusedProject;
    If Project = Nil Then Exit;
    Project.DM_Compile;
    FileName := Project.DM_ProjectFullPath;
End;

Compile example using the MessageRouter_SendCommandToModule call

GetMem(P, 4048);
SetState_Parameter(P,'Action','Compile');
SetState_Parameter(P,'ObjectKind', 'Project');
MessageRouter_SendCommandToModule('WorkspaceManager:Compile',P,4048,Nil);
FreeMem(P);

For detailed information on Workspace Manager API, refer to the Technical Reference - Workspace Manager API document.
See the script examples in the Scripts\DelphiScript Scripts\DXP\ folder.

Nets of design documents

Schematic Design documents that have components and wires contain connectivity information which is captured in nets. A net is composed of connections and each connection is linked by a node as a pin. Nets are connected pins and a valid net has more than 1 pin.

To obtain connectivity information, we use the WorkSpace Manager API to fetch net information. Open a project with valid schematics and then going through each schematic, the net count is obtained and for each net, the pin count is obtained and we have pins at our disposal. With pin interfaces, we can fetch pin designator, pin number and so on.

The design project needs to be compiled first, the documents (IDocument interfaces) are obtained and then the Nets (INet interfaces) are obtained. For each net, IPin interfaces are again obtained.

Fetch Nets example using the INet interface

//net information is stored in the NetList TStringList container
For i := 0 To Document.DM_NetCount - 1 Do
        WriteNet(Document.DM_Nets(i));
 
Procedure WriteNet(Net : INet);
Var
    I       : Integer;
    Pin     : IPin;
    PinDsgn : String;
    PinNo   : String;
Begin
    If Net.DM_PinCount >= 2 Then
    Begin
        NetList.Add('(');
        NetList.Add(Net.DM_CalculatedNetName);
        For i := 0 To Net.DM_PinCount - 1 Do
        Begin
            Pin := Net.DM_Pins(i);
            PinDsgn := Pin.DM_PhysicalPartDesignator;
            PinNo   := Pin.DM_PinNumber;
            NetList.Add(PinDsgn + '-' + PinNo);
        End;
        NetList.Add(')');
    End;
End;

PCB Design documents also have net information, but these nets are captured in IPCB_Net interfaces. Refer to the Technical Reference - PCB API document for more information.
See the script examples in the Scripts\DelphiScript Scripts\WSM\ folder.

If you find an issue, select the text/image and pressCtrl + Enterto send us your feedback.
Note

The features available depend on your Altium product access level. Compare features included in the various levels of Altium Designer Software Subscription and functionality delivered through applications provided by the Altium 365 platform.

If you don’t see a discussed feature in your software, contact Altium Sales to find out more.

Content