Server configuration files

Created: August 04, 2013 | Updated: March 06, 2024

Related documents

Extension server configuration files allow Altium Designer to determine an extension's system capabilities and configuration when Altium Designer is started. This document provides full details on the configuration and deployment of a software extension DLL (such as a document editor or a simple add-on server) in Altium Designer.

The configuration file set

The main configuration files for software extensions are resources files, installation files and tool location files. Which files are included in an extension project will depend on its capabilities and how the extension interfaces with Altium Designer.

Extension configuration files

Resources file (.rcs)
Installation file (.ins)
Tools Layout file (.tlt)
Button files (typically .bmp)
Icons files (.ico)

Configuration files generally reside in an \Installation folder within the main project folder, while image, icon and reference files are in respective sub folders - for example \Installation\Buttons for the button images.

A simpler project such as an Add-on extension (one that 'adds on' to an existing document editor) may only include an Installation configuration file to implement its commands in Altium Designer. Other types of extension servers can be developed and deployed in Altium Designer, such as model editors and output generators. These types of extension projects may include:

Server Implementation models files
Output Generator or Implementation configuration files

Resources file

Within the Altium Designer environment, operations are initiated by a user via the menus, toolbars and hot keys. So in terms of an extension, menus, toolbars and keyboard hotkey lists are known as resources in this environment. Behind each resource item, such as a toolbar icon or menu item, there is a pre-packaged process launcher that activates a command when its resource item is selected.

Processes and Process launchers for a extension are exposed in Altium Designer by its Installation and Resource files. Thus when an extension is installed, the MyExtension.dll, MyExtension.rcs and MyExtension.ins files co-exist in the C:\ProgramData\Altium\Altium Designer {GUID}\Extensions\MyExtension folder.

A resources file is an ASCII text file containing process launcher blocks and user interface elements. A resources file is used to assign process launchers to the user interface of the server, and has a .RCS extension. Key shortcuts, menu items and toolbar buttons can be assigned. In essence, when Altium Designer starts it first loads the default resources from all servers in its \Extensions folder (as outlined above) and updates the Extension Registry (ExtensionsRegistry.xml) to implement the extensions at a system level.

The structure of a Resources file

Process launchers can be linked to three different resource items: menu items, toolbar buttons and shortcut keys. A process launcher can be a parametric process and when a process launcher is linked to a user interface element in Altium Designer such as a menu item - this called a command. Process launchers are stored in a Resources file and processes (commands) are stored in an Installation file.

The structure of a resources file has two sections:

The first section has a list of defined process launchers.
The second section has a list of process launcher trees.

The second section is where menus, toolbars and key tables can be defined for the extension server, and which process launchers can be linked to which elements of the user interface for this server. You can include comments in a resources file using double backslash as a prefix for the comment string.

Note that when building a resources script, every Process Launcher Name entry must be unique. This is because when a server is activated in Altium Designer it loads the server-specific resources and will overwrite any duplicate entries it encounters.

Process Launchers section

The Resources file process launchers section has a list of process launcher statements that consist of PL End blocks, and within each block, there are PLName, Command, Params, Caption, Image, ShortCut and Description identifiers.

Each process launcher is referenced by a PLServerName: ProcessName string. These process launchers are then used in the next section of the resources file, which are linked to a specific menu item, toolbar button or hot key.

A process launcher statement:

PL
PLName: Process
Command = 'Server: Process'
Params = 'Parameter1 = Value1\|Parameter2=Value2'
Caption = 'text'
Image ='Name.BMP'
ShortCut1 = ''
Description = ''
End

Process Launcher statement table:

Process Launcher Identifier	Description
PL	PL represents the Process Launcher block. The block ends with the terminator string, End.
PLName: Process	Each process launcher block has a unique PLName: Process string which represents the name of the server and its process. This string represents the unique name of the process assigned to the process launcher. An example is PLSch:Undo. If a process is parametric, you can have different process launchers for each parametric process.
Command = Server: Process	The Command clause represents the actual server process. A Server: Process string assigned to the Command clause is identified from one of the Command Name clauses in a server installation file. The PLName: Process string is the name of the PL End block and the Command along with the Params clauses identify the specific process launcher.
Params ='Parameter1 = value1 \| .. ParameterN = Value N'	Assign multiple parameters for the server process. Note that there can be separate process launchers and different Params clauses for the same server process in different Process Launcher blocks.
Caption	The definition of a caption for a process launcher based menu item. A '&' character can be used in the caption string which denotes a hot key / accelerator key and the character after the & character is underlined. For example the caption string, &File ends up as File on the File menu.
Image	The path to a bitmap image for a process launcher based toolbar item or menu item. Images are stored in the `\Buttons` folder of the Altium Designer installation and each button image needs to be 18 x 18 pixels in size.
ShortCut1	An accelerator key short cut for the menu item.
ShortCut2	A second accelerator key short cut for the same menu item.
Description	A text message used as a tool tip and for the status bar of Altium Designer.
PLRepeat	The PLRepeat identifier is needed to define a range of repeated commands. Note that the PLName: Process identifier, Symbol1, BeginIndex1, EndIndex1 identifiers needed to define the range of repeated similar commands.
End	A terminator string which denotes the end of a process launcher block.

An example of Process Launcher block

PL
PLSch:Undo
Command='Sch:Undo'
Caption='&Undo '
Image='UNDO.BMP'
Shortcut1='Ctrl+Z'
Shortcut2='Alt+Backspace'
Description='Undo'
End

Process Launcher Trees section

The second section of the resources file contains Process Launcher Trees. Each tree specifies one of the three resources - menus, toolbars and hot key tables. You can also have sub trees within a tree (representing sub menus of a menu for example). The same process launchers can be assigned to multiple process launcher identifiers (PLID). Within each tree, a Link clause points to a process launcher and must have a unique link name.

Altium Designer maintains a table of process launchers for the user interface resources for all active servers. Therefore each link to a process launcher clause needs have a unique Link identifier. A process launcher's shortcut is active if it is in any available process launcher trees.

Process launchers have shortcuts (two) so there is no need to have a hot key table to retain the short cuts themselves. However, the hot key tables can make sure that the shortcut will work even if a process launcher (command) is not in the menu or in any visible toolbars - without the shortcut tables its shortcut will not work. So in the file's PL section there is another tree category which is basically a list of process launchers that may (or may not) be in other available process launcher trees, but for which we want the shortcuts to work. Conceptually, hot key tables are really just invisible toolbars.

The examples below show how Process Launcher Trees are constructed for three different types of resources in Altium Designer.

A basic process launcher tree
Tree NameOfUniqueTreeResource Caption = '' TopLevel = Boolean
TreeCopy NameOfTree_N OriginalID = NameOfTreeToCopy IDSuffix = '' End
Separator Name End
Link NameOfUniqueResourceItem PLID=PLName: Process End
End

This basic process launcher tree will include the required elements, however there is the ability to copy an existing Process Launcher tree from another extension server's resources into your server resources. This is useful in situations where an extension's resources rely on the resources of a document editor, such as the PCB or Schematic editor for example.

Process Launcher Tree table:

Process Launcher Tree Identifier	Description
Tree	Denotes the starting block of a process launcher tree.
NameOfUniqueTreeResource	To build a new process launcher tree for the specified server - this tree needs to have a unique name.
Caption	The caption string that appears for a menu item.
TopLevel	Describes the top level of a menu hierarchy, and the use of sub-trees to define sub menus.
Popup	Denotes a pop up menu floating on top of an active document in Altium Designer. A unique character must be assigned for each pop up menu. The Popup identifier is part of the Tree clause. When the key associated with the pop up menu is pressed, this pop up menu appears at the location of the mouse cursor. A pop up menu can be the same as the existing menu, so for example, the user has two options of going to the File menu on the menu bar. Pressing F for the pop up menu will activate the File menu with the same menu items as the File menu.
TreeCopy	Copies an existing process launcher tree from a primary server resources file (for example PCB resources). This feature can be used to maintain the latest common user interface elements, for example the File and Edit menu items. Future Altium Designer updates can change the structure of menus, therefore an extension server that employs the TreeCopy clause is assured of the same user interface as the primary server. However the IDSuffix identifier must be used to ensure that each Link identifier is unique, and the OriginalID identifier is needed to identify the original process launcher to copy.
Separator	The Separator identifier inserts a blank a line between a process launcher and the next process launcher in a menu or toolbar.
Link	Links the specified process launcher to a user interface element. Each Link statement must have a unique identifier. since Altium Designer maintains a table of process launchers for all active servers.
IDSuffix	The IDSuffix is used when an existing Process Launcher Tree needs to be copied from another server's resources. This copied Tree will have the IDSuffix identifier appended to the Process Launcher Tree IDs. Note again that every Link identifier within a Link clause has to be unique, since Altium Designer maintains a table of process launchers for every server loaded.
PLID	The PLID identifier which references the particular process launcher from the process launchers section in a resources file.
LinkRepeat	This LinkRepeat clause is used within a tree or a sub tree and the following Symbol, BeginIndex and EndIndex subclauses are used to define a range of similar Process Launchers.
OriginalId
BeginIndex	The BeginIndex denotes the beginning of the range of repeated similar process launchers. The LinkRepeat clause is used within a tree or a sub tree and the following Symbol, BeginIndex and EndIndex subclauses are used to define a range of similar Process Launchers.
EndIndex	The EndIndex denotes the end of the range of repeated, similar process launchers. The LinkRepeat clause is used within a tree or a sub tree, and its following Symbol, BeginIndex and EndIndex subclauses are used to define a range of similar Process Launchers.
End	Terminating string for Tree, TreeCopy, and Link clauses.

Process Launchers Tree examples

Menu Tree snippet
Tree MNPCB_AutoRoute10 Caption='&Auto Route' Popup='A'
Link MNPCB_AutoRoute20 PLID='PLPCB:AutorouteAll' End
End

For menus, 'MN' is used as a short-hand for the menu Tree identifier, and for menu items, MN is used as a short-hand as in the identifier for each menu item. Notice a Popup='A' identifier is at the end of the Tree clause.

Toolbar Tree snippet
Tree TLFindSelections Caption='Find Selections' TopLevel=True
Link TBPCB_FindSelections20 PLID='PLPCB:JumpFirstSelection' End
End

For toolbar trees, 'TL' is used as a short-hand for the Toolbar Tree identifier, and for toolbar items, TB is used as as a short-hand as in the identifier for each Toolbar Button. Since there can be sub-trees within a tree, the TopLevel needs to be set to true for the outer most tree, and for sub trees, the TopLevel set to false or the the TopLevel identifiers omitted.

Keys Tree snippet
Tree HTPCBHotKeys Caption='PCB Shortcuts' TopLevel=True
Link HKPCBHotKeys20 PLID='PLPCB: PopupZoomIn' End
End

For key tables, 'HT' is used as a shorthand for the Keys Tree identifier, and for key items, HK is used as a short-hand in the identifier for each key button.

To understand how these three types of resource trees are defined in a resources file, Altium Designer's AdvPCB.RCS can be examined. AdvPCB.RCS is the PCB Editor's resources file in the \System folder of the Altium Designer installation.

Menu example in AdvPCB.rcs:

//..........................................................................
//********\* Top Level Autoroute Menu
//..........................................................................
Tree MNPCB_AutoRoute10 Caption='&Auto Route' Popup='A'
Link MNPCB_AutoRoute20 PLID='PLPCB:AutorouteAll' End
Separator MNPCB_AutoRoute30 End
Link MNPCB_AutoRoute40 PLID='PLPCB:AutorouteNet' End
Separator MNPCB_AutoRoute90 End
Tree MNPCB_Fanout Caption='&Fanout'
Link MNPCB_Fanout20 PLID='PLPCB:FanoutAll' End
Link MNPCB_Fanout30 PLID='PLPCB:FanoutPowerPlaneNets' End
Separator MNPCB_Fanout50 End
Link MNPCB_Fanout60 PLID='PLPCB:FanoutNet' End
Link MNPCB_Fanout70 PLID='PLPCB:FanoutConnection' End
End
Separator MNPCB_AutoRoute95 End
Link MNPCB_AutoRoute100 PLID='PLPCB:AutorouteSetup' End
Link MNPCB_AutoRoute110 PLID='PLPCB:AutorouteStop' End
End
Toolbar example:
Tree TLFindSelections Caption='Find Selections' TopLevel=True
Link TBPCB_FindSelections20 PLID='PLPCB:JumpFirstSelection' End
Link TBPCB_FindSelections30 PLID='PLPCB:JumpPreviousSelection' End
Link TBPCB_FindSelections40 PLID='PLPCB:JumpNextSelection' End
Link TBPCB_FindSelections50 PLID='PLPCB:JumpLastSelection' End
Separator TBPCB_FindSelections60 End
Link TBPCB_FindSelections70 PLID='PLPCB:JumpFirstGroup' End
Link TBPCB_FindSelections80 PLID='PLPCB:JumpPreviousGroup' End
Link TBPCB_FindSelections90 PLID='PLPCB:JumpNextGroup' End
Link TBPCB_FindSelections100 PLID='PLPCB:JumpLastGroup' End
End
Hot key Table example
Tree HTPCBHotKeys Caption='PCB Shortcuts' TopLevel=True
Tree HTPCBHotKeys Caption='PCB Shortcuts'
Link HKPCBHotKeys20 PLID='PLPCB: PopupZoomIn' End
Link HKPCBHotKeys30 PLID='PLPCB: PopupZoomOut' End
Link HKPCBHotKeys40 PLID='PLPCB:ViewZoomOut' End
Link HKPCBHotKeys50 PLID='PLPCB:ViewZoomIn' End
Link HKPCBHotKeys60 PLID='PLPCB:ViewFitDocument' End
Link HKPCBHotKeys70 PLID='PLPCB:ToggleElectricalGrid' End
Link HKPCBHotKeys80 PLID='PLPCB:Redo' End
Link HKPCBHotKeys90 PLID='PLPCB:Undo' End
Link HKPCBHotKeys110 PLID='PLPCB: PopupSnapGridOther' End
Link HKPCBHotKeys120 PLID='PLPCB:MeasureDistance' End
End
End

Customizing a Resources file

When you install an extension server in Altium Designer, the system automatically looks for the resources script file (RCS) of your server. Note that the resources, such as menus, toolbars, and keyboard hot keys are defined from the server's installation file (INS).

The EditorBars identifiers in this installation file specify the server's toolbars, hot key tables and menu bars. Refer to the Server's Installation File section for more information on installation files. The actual implementation of the resources is defined in the server's resources file with an .RCS extension. The resources filename must have the same name as the server filename.

Inserting new Process Launchers from a supporting extension

To update the resources of a target software extension (the PCB editor for example), you need to define the resources in the supporting extension's resources script, and then insert an Updates clause in the supporting extension's installation file. To insert a process launcher, an Insertion - End block is defined in the supporting resources file. Process launchers can only be inserted one at a time, that is, one Menu tree, one Toolbar or a key assignment at a time. Therefore to do a multiple process launcher insertion, multiple Insertion blocks are required.

TargetID
The TargetID identifier identifies which Process Launcher tree to link from the primary resources file. For example the identifier can point to the menu.

RefID0
The RefID0 (with a numerical 0 value) identifier refers to which reference menu item the new resource item is to be inserted. This process is similar for toolbar buttons and hot keys except that trees are not normally used within an insertion body. Only links to process launchers are needed - for example the RefID0 identifier can point to the menu item.

Basically, the Insertion structure is as follows:

Insertion UniqueNameOfResource TargetID= InsertType= RefID=
Link ResourceItem PLID= End
End

The next three generic examples show how to link a process launcher to three different user interface elements (the hotkey, toolbar or menu item).

Inserting a menu item based process launcher:

Insertion NameOfMenuTree TargetID='NameOfMenuTreeFromServer' InsertType=After RefID0='ReferenceMenuItemFromServer'
Tree PopUp Caption='CaptionText to appear on menu item'
Link MenuItem1 PLID='PLName: Process' End
Link MenuItem2 PLID='PLName: Process' End
Separator MenuItem3
Link MenuItem4 PLID='PLName: Process' End
End
End

Inserting a toolbar based process launcher:

Insertion UniqueToolBarName TargetID='ToolbarName' InsertType=After RefID0='ToolBarItemName'
Link UniqueToolBarItemName PLID='PLName: Process' End
End

Inserting a hot key based process launcher:

Insertion UniqueHotKeyName TargetID='HotKeyTreeNameFromServer' InsertType=After RefID0='HotKeyItemNameFromServer'
Link UniqueHotKeyItemName PLID='PLName: Process' End
End

However when inserting multiple toolbar buttons, multiple inserts are needed. Note that different RefID0 clauses must be assigned for each insert, or otherwise the previous user interface element will be overwritten with the current RefID0 insertion.

User Interface elements of a server can be deleted using the Deletion identifier instead of the Insertion identifier, and multiple RefID identifiers can be used to identify which process launchers to delete.

Adding a New Toolbar to the Target

To implement a new toolbar that contains commands (process launchers) from the Add-on project example, and have these commands appear in a target extension (for example a new toolbar on the PCB editor workspace), an Updates clause needs to be inserted with the name of the target server identifier in the supporting server installation file (addon.ins for example) and the resources defined in the supporting resources file (addon.rcs for example).

An EditorBar clause then needs to be inserted in the target installation file (advpcb.ins for example), an EditorWindowKind clause identified (if more than one document kind is supported) along with the name of the new resource and which resource type (Menu, Toolbar, HotKey). The ResourceDependencies block may also need to be updated with the name of the supporting server (Addon for example).

Finally, a tool locations file can be created to define where the toolbar appears and whether it should be docked or configured as a floating toolbar. See Tools Locations File section for details.

Updating the target server with the Updates clause in Addon.INS installation file example:

ClientInsFile 0.0
Server
EditorName = 'AddOn'
EditorExePath = 'AddOn.DLL'
EditorDescription = 'A demonstratory AddOn module'
Version = 'Version 8.4.03.3664'
Date = '31-Dec-2004'
HelpAboutInfo = 'This software is protected by copyright law and international treaties.'
CopyRight = 'Copyright © Altium Limited 2005'
Updates = 'AdvPCB'
End
 
Command Name = 'CountPads' LongSummary 'Find how many pads on a PCB document' End
Command Name = 'RunAPCBProcess' LongSummary 'Invoke a PCB process'
End

Resources example

Refer to the extension's resources file in the SDK's \Examples\AddOn Complete folder example. This extension server adds several process launchers in the PCB editor.

Addon.rcs resources file

PL
PLAddon:CountPadsAndShowDialog
Command='Addon:CountPads'
Caption='&Count...'
Image='Pad1.bmp'
Shortcut1='d'
Shortcut2=''
Params='Display=False'
Description='Count pads'
End
 
PL
PLAddon:CountPadsAndShowDocument
Command='Addon:CountPads'
Caption='&Count...'
Image='Pad2.bmp'
Shortcut1='t'
Shortcut2=''
Params='Display=True'
Description='Count pads'
End
 
PL
PLAddon:RunAPCBProcess
Command='Addon:RunAPCBProcess'
Caption='&RunAPCBCProcess...'
Image=''
Shortcut1='r'
Shortcut2=''
Params=''
Description='Runs a PCB Process'
End
 
// Inserts three addon processes in the PCB's View menu
Insertion \_AddOnMenu TargetID='MNPCB_View10' RefID0='MNPCB_View140'
Tree AddonMenuTree Caption='&Addon Menu'
Link AddonMenu1 PLID='PLAddon:CountPadsAndShowDialog' End
Link AddonMenu2 PLID='PLAddon:CountPadsAndShowDocument' End
Separator AddonSeparator1 End
Link AddonMenu3 PLID='PLAddon:RunAPCBProcess' End
End
End
 
// Inserts two toolbar buttons on a new floating toolbar
Tree TLAddon Caption = 'Addon Tools'
Link TBAddon_Item1 PLID= 'PLAddon:CountPadsAndShowDialog' End
Separator TBAddon_Item2 End
Link TBAddon_Item3 PLID = 'PLAddon:CountPadsAndShowDocument' End
End

From this resources script, three process launchers are defined. The AdvPCB.RCS file can be consulted for reference to find the TargetID and RefID values of the PCB resources. Two button image files need to go in the \Buttons folder of the installation so that the buttons to appear on the new toolbar on a PCB document.

To summarize the process of adding an extension's process launcher in an editor:

Define the process launchers and the process launcher trees in the resources file for this server to insert new commands in the PCB or Schematic editor. The AdvSch.RCS or AdvPCB.RCS file in the \System folder provide a reference source for the Target and RefID numbers.
Add a Updates 'NameOfEditor' statement (the trarget server) in the extension project's installation file.

See the Altium DXP Developer documentation for the direct way to edit and update an extension server's existing configuration files.

Installation File

A software extension's installation file is an ASCII text file containing server processes, resource types, file save/load kinds and settings.

Note that the processes and process launchers of an extension server are exposed in Altium Designer by its Installation and Resource files. Thus the .DLL, .RCS and .INS files co-exist in the installation folder.

Every software extension has its own installation file (*.INS) that is based on the same file name as extension itself. In this way Altium Designer knows to register that extension based on the installation file data.

The structure of an Installation file

When building an editor, the types of documents and resources need to be specified (for example the Schematic Editor has two document types - the schematic sheets and schematic libraries). The installation file is one of the places that can define the document kinds. The system's text-based configuration files specify the document type association to the document extension so the DXP application knows which server to invoke when a specific document type is being generated and opened.

To do this, the system FileFilters and FileExtensions text files need to be updated to specify the document type associated with the document extension. See the SDK's GraphicViewer example project for an application of file filters.

A skeleton Installation file:

ClientInsFile 1.0
Server
EditorName = <Description>
EditorExePath = <DLL FileName>
EditorDescription = <Description>
Version = <Version>
Date = <Day-Month-Year>
HelpAboutInfo = <Description>
CopyRight = <Description>
 
StartupBitmap = <BMP Filename>
Updates = <ServerName>
 
ResourceDependencies
<SupportingServer Name1>
<SupportingServer NameN>
End
End
 
EditorWindowKind
Name = <NameString>
NewWindowCaption = <NewWindowCaptionString>
NewWindowExtension = <NewWindowExtensionString>
WindowKindDescription = <WindowKindDescriptionString>
IconName = <IconNameString>
 
EditorBar Name = <Name> BarType = <Menu,HotKeyTable,Toolbar> End
 
EditorClasses
End
 
LoadFilters
<File Format Name> <FileExtension>
End
 
SaveFilters
<File Format Name> <FileExtension>
End
End
 
PanelInfo
Name = <NameString>
Category = <CategoryString>
BitMap = <Bitmap>
Hotkey = <HotKey>
ButtonVisible = <Boolean>
CanDockVertical = <Boolean>
CanDockHorizontal= <Boolean>
DocumentKinds
<DocumentKinds>
End
ProjectTypes
<ProjectTypes>
End
End
 
Options Page
OptionsPage
Caption = <CaptionName>
FormName = <FormName>
OrderIndex = <Integer>
End
End
 
Command Name= <ProcessName> LongSummary = <Description> End
Command Name= <ProcessName> LongSummary = <Description> End
Command Name= <ProcessName> LongSummary = <Description> End

Installation clauses table:

Installation clauses	Description
Server Block
EditorName = <Description>	A string to define the name of the server
EditorExePath = <DLL FileName>	A string to define the path name of the server
EditorDescription = <Description>	A string to define the description of the editor.
Version = <Version>	A string to define the version of the server, based on Altium Designer's version build - Check DXP's About dialog for its Build Number.
Date= <Day-Month-Year>	A string to define when this server was built or distributed.
HelpAboutInfo = <Description>	A string to define what the server is all about.
CopyRight = <Description>	A string to define the copyright information for the server.
StartupBitmap = <BMP Filename>	Each time the server is started a bitmap can be displayed to denote that the server is loading, if StartupBitmap is true. This is useful for servers that have large and complex data-structures that might take a while to load in Altium Designer.
ResourcesDependencies block
ResourceDependencies = <Supporting ServerName>	This is when a server A updates Server B resources, which means that server A adds resources to a Server B. So whenever Altium Designer loads the resources for B, server A resources are loaded afterwards. This is needed for 'copy of process launcher trees' (treecopy) and is needed if the server B defines a process launcher tree which server A is copying, Altium Designer will load the resource for server B first before server A resources are loaded. A specific example is when a target server like the PCB editor links in a process launcher from an extension server in the PCB resources file, where there needs to be a ResourcesDependency clause with the extension's name with in the PCB's installation file.
Updates <Target Editor Server>	The supporting server needs to have the updates clause in its installation file, which dictates that new process launchers are to be linked in the target server user interface for that target server document. For example the HoleSize extension server has the Updates clause assigned to AdvPCB as the target server to have the HoleSize process launchers linked in.
EditorWindowKind block
EditorWindowKind <DocumentType> <BlankDocumentTitle> <DocumentExtension> <Description> <ResourcesIconFileName> END	This EditorWindowKind denotes the type of document. <DocumentType> Denotes the document type, such as SCH, SCHLIB, PCB, and PCBLIB. <BlankDocumentTitle> The document title on the titlebar for the document when document is visible in Altium Designer. <DocumentExtension> The document filename's extension. <Description> Description for this document. <ResourcesIconFileName> Icon for the tab of this document.
EditorBar Name = <DocumentType> <Tree Id> <Resource Type>	There are three types of editor bars - menus, toolbars and hotkeys. DocumentType: Document kind string, for example PCB documents, 'PCB' Sch Library documents, 'SCHLIB' etc. TreeId: one of the resource name identifiers from the resources file/tool locations file. Resource Type: Menu, Toolbar and HotKeyTable
PanelInfo block
PanelInfo <PanelName> <DocumentType> <Bitmap> <HotKey> <Button Visible> <Dock Vertical> <Dock Horizontal> <DocumentKinds> <ProjectTypes>	This PanelInfo clause denotes a panel supported by the server. <PanelName> Denotes the name of this panel <DocumentType> Denotes the document type, such as SCH, SCHLIB, PCB, and PCBLIB. <Bitmap> Denotes the bitmap related to this panel. True / False <HotKey> Denotes the hot key to toggle the display status of this panel. True / False <ButtonVisibility> Denotes whether the panel's button is to be visible or not. True / False. <Dock Vertical> Denotes whether the panel can be docked vertically. True / False <Dock Horizontal> Denotes whether the panel canbe docked horizontally. True / False DocumentKinds End blocks. <ProjectTypes> blocks
Commands block
Command Name = <ProcessName> LongSummary = <Description> HelpFilename <HLPFilename> END	The CommandName clause contains a server process definition that is supported by this server.

Installation file example

Every Server has its own installation file with an INS extension. The installation and server files have the same filenames so that Altium Designer knows that a server exists and can be registered.

When building a document editor, its types of documents and resources need to be specified by the EditorFileLoadKind and EditorFileSaveKind clauses in the installation file. When dealing with an extension's specific document types, Altium Designer's FileExtensions and FileFilters text files (in the \System folder) need to be updated to suit. See the AdvSch.ins installation file below to examine how installation clauses are used.

AdvSch.INS Schematic Installation File:

ClientInsFile 1.0
 
Server
EditorName = 'Sch'
EditorExePath = 'AdvSch.dll'
EditorDescription = 'Schematic Capture'
Version = 'Version 8.4.03.3664'
Date = '20-July-2005'
HelpAboutInfo = 'This software is protected by copyright law and international treaties.'
Copyright = 'Copyright © Altium Limited 2005'
StartupBitmap = 'Startup_Schematic.bmp'
 
ResourceDependencies
'Sim'
'LoadPCADSCH'
'Macro'
'SavePCADSCH'
'SchDwgUtility'
'SignalIntegrity'
'EditVHDL'
End
End
 
EditorWindowKind
Name = 'Sch'
NewWindowCaption = 'Sheet'
NewWindowExtention = 'SchDoc'
WindowKindDescription = 'Schematic Document'
IconName = 'SCH'
 
EditorBar Name = 'MNSchematicMenu' BarType = Menu End
EditorBar Name = 'HTSchematicHotKeys' BarType = HotkeyTable End
EditorBar Name = 'TLSchematicTools' BarType = Toolbar End
EditorBar Name = 'TLSimulationSources' BarType = Toolbar End
EditorBar Name = 'TLAdvSimTools' BarType = Toolbar End
EditorBar Name = 'TLSignalIntegrity' BarType = Toolbar End
EditorBar Name = 'TLFormatting' BarType = Toolbar End
EditorBar Name = 'TLFocusedProject' BarType = Toolbar End
EditorBar Name = 'TLSchUtilities' BarType = Toolbar End
EditorBar Name = 'TLWiringTools' BarType = Toolbar End
EditorBar Name = 'TBNavigation' BarType = Toolbar End
EditorBar Name = 'TBLayout' BarType = Toolbar End
 
EditorClasses
'PCBSource'
'FPGASource'
'CoreSource'
End
 
LoadFilters
'Advanced Schematic binary files (*.schdoc)'
'Advanced Schematic binary files (*.sch)'
'Advanced Schematic ascii files (*.schdoc)'
'Protel DOS Schematic files (*.s??)'
'Orcad SDT Schematic files (*.sch)'
End
 
SaveFilters
'Advanced Schematic binary (*.schdoc)'
'Advanced Schematic ascii (*.schdoc)'
'Schematic binary 4.0 (*.sch)'
'Orcad SDT Schematic (*.sch)'
'Advanced Schematic template (*.schdot)'
'Export AutoCAD Files (.dwg;.dxf)'
End
End
 
PanelInfo
Name = 'SchLibraryPanel'
Category = 'S&CH'
Bitmap = ''
Hotkey = 'B'
ButtonVisible = True
CanDockVertical = True
CanDockHorizontal = False
End
 
Command Name = 'AddComponentPart' LongSummary = 'Add a new part to the currently displayed component 'End
Command Name = 'AddRemoveLibraryInSchEditor' LongSummary = 'Add and remove libraries from the schematic editor library list' End

The AdvSch.INS file above is a trimmed down installation file to show the main features. Note that there is a ResourceDependency clause that instructs other supporting servers to update the Schematic server's user interface.

ToolBar Locations file

For an Editor that has toolbars and panels, the locations of these toolbars and panels are stored in the toolbar locations file, servername.tlt. When a design document is loaded, Altium Designer reads in the tools locations file and updates the toolbar and panel locations for this associated server, on the first occasion only.

Altium Designer loads a server's toolbar and panel layouts defaults from its toolbar locations file (.TLT). It then applies its own UserTools.TLT file, which override the defaults (if any) and updates the new toolbar locations (if any) - Altium Designer's TLT file can be found in the the ..\*UserName\AppData\Roaming\AD{xxx} folder (Windows 7).

Within the ToolsLayout block there can be any number of BarLayout and FrameLayout blocks. The BarLayout blocks define the toolbars, and the FrameLayout blocks define the panels associated within and for each frame - you can have only one active panel.

A skeleton tools layout file:

ToolsLayout
    BarLayout
        BarName= < Name >
        BarState= < State >
        BarDockSite= < DockSite >
        BarDockRow= < DockRow >
        BarDockOffset= < NoOfPixels >
        BarFloatLeft= < NoOfPixels >
        BarFloatTop= < NoOfPixels >
        BarFloatWidth= < NoOfPixels >
        BarActive= < Boolean >
        BarHotkey= < Key >
        BarDocumentKind = < Server Document Name >
    End
    FrameLayout
        FrameState= < State >
        FrameDockSite= < DockSite >
        FrameDockedWidth= < NoOfPixels >
        FrameDockedHeight= < NoOfPixels >
        FrameFloatLeft= < NoOfPixels >
        FrameFloatTop= < NoOfPixels >
        FrameFloatWidth= < NoOfPixels >
        FrameFloatHeight= < NoOfPixels >
        SectionLayout
        SectionSplitRatio=50
        SectionSplitType=Horizontal
            ActivePanels
                <Name Of Document Kind> <NameOfPanel>
            End
            PanelLayout
                PanelName= < Name >
                PanelVisible= < Boolean >
                PanelFloatWidth= < NoOfPixels >
                PanelFloatHeight= < NoOfPixels >
                PanelCanDockHorizontally= < Boolean >
                PanelCanDockVertically= < Boolean >
                PanelHotkey= < Key >
                PanelButtonVisible= < Boolean >
            End
    End
End

Toolbar layout identifiers

The table below defines the tools layout structure for toolbars and panels. The toolbars and panels can be defined as floating and set in locations relative to the top left corner of the monitor's screen.

Within this structure, BarLayout and FrameLayout blocks can be defined. Within the FrameLayout block, PanelLayout blocks and ActivePanel blocks can be defined.

Tools Layout identifiers table:

Tools Identifier	Description
ToolsLayout	The top level identifier that outlines the tools layout block. Blocks are terminated with the End identifier.
BarLayout	The location of a toolbar. This can be defined as a floating or as a docked toolbar.
FrameLayout	Within a FrameLayout, PanelLayout and ActivePanels blocks can be defined.
SectionLayout	A section layout represents the layout of a frame section. A frame section is the surface in which several panels are 'stacked' on top of each other within the frame.
PanelLayout	The settings of a server panel.
ActivePanels	Used to specify which panels will be active within the FrameLayout block. The ActivePanels clause applies when that panel is docked in a frame that has other panels - this panel is then focused.
End	The terminating identifier for the ToolsLayout block, BarLayout block, FrameLayout block, PanelLayout block and ActivePanels block.

FrameLayout identifiers table for a FrameLayout - End block:

FrameLayout Identifiers	Description
FrameState	The state of the frame; FrameStateFloating, FrameStateDocked, Unpinned
FrameDockSite	Where the panel is to be docked. Only applies if the FrameState identifier is assigned to the FrameStateDocked value (see above). This DockSite identifier has the following parameters; DockSiteNone, DockSiteTop, DockSiteLeft
FrameDockedWidth	The width of the docked frame in pixels relative to the monitor screen's 0,0.
FrameDockedHeight	The height of the docked frame in pixels relative to the monitor screen's 0,0.
FrameFloatLeft	Specifies in pixels where the floating frame is relative to the monitor screen's 0,0.
FrameFloatTop	Specifies in pixels where the floating frame is relative to the monitor screen's 0,0.
FrameFloatWidth	Specifies the width of the floating frame relative to the monitor screen's 0,0.
FrameFloatHeight	Specifies the height of the floating frame relative to the monitor screen's 0,0.

PanelLayout identifiers table for a PanelLayout - End block:

PanelLayout Identifiers	Description
PanelName	The unique name of a server panel.
PanelVisible	Boolean value. Set the panel visibility at start up.
PanelFloatWidth	Specifies in pixels where the floating panel is relative to the top-left corner of the monitor screen.
PanelFloatHeight	Specifies in pixels where the floating panel is relative to the top-left corner of the monitor screen.
PanelCanDockHorizontally	Boolean value. Set if the panel can be docked horizontally.
PanelCanDockVertically	Boolean value. Set if the panel can be docked vertically.
PanelHotkey	Assign a hot key character for this panel.
PanelButtonVisible	Boolean value. Set whether the panel button will appear in the Altium Designer status bar along with other panel buttons.

ActivePanels identifiers table for an ActivePanels - End block:

ActivePanels Identifiers	Description
< Name of server >	A string containing the name of a document kind.
< Name of panel >	A string containing the name of the active panel of this server within the FrameLayout block.

BarLayout identifiers table for a BarLayout - End block:

Bar Layout Identifiers	Description
BarName	The unique name of this toolbar. This toolbar is also defined by the EditorBar clause in the server installation file.
BarState	The state of the toolbar; BarStateFloating, BarStateDocked.
BarDockSite	Where the toolbar is to be docked. Only applies if the BarState identifier is assigned to the BarStateDocked value. This DockSite identifier has the following parameters; DockSiteNone, DockSiteTop, DockSiteLeft, DockSiteRight, DockSiteBottom values.
BarDockRow	Specifies where docking is to take place from three row docking options (0,1,2).
BarDockOffset	Specifies in pixels a positional offset from where the toolbar is docked from the left.
BarFloatLeft	Specifies in pixels where the toolbar is relative to the top-left corner of Altium Designer.
BarFloatTop	Specifies in pixels where the toolbar is relative to the top-left corner of Altium Designer.
BarFloatWidth	Specifies the width of the toolbar, if floating.
BarActive	Boolean value. Enable or disable the toolbar.
BarHotKey	Assign a hot key for this toolbar.
BarDocumentKind	Specify which document the toolbar is to be associated with - 'PCB' for PCB documents and 'SCH' for Schematic documents.

Inserting a new Toolbar in the PCB Editor

As an example, to place a new toolbar in a target extension server that has the supporting extension's process launchers:

A new tool locations file needs to be defined for this supporting server with the BarLayout block.
The supporting server's resources file needs to be updated to include a Toolbar process launchers tree block.
An Updates clause needs to be added in the supporting extension server's installation file to include the new toolbar for the PCB workspace.

The target extension's installation file will also need to be modified by adding the EditorBar clause to the existing list within the EditorWindowKind block. The ResourceDependencies block needs to have the supporting server name entry added at the end, for example 'AddOn'.

In this case, the new toolbar (TLAddon) is called with process launchers defined in the Add-on project's resource file, and the installation file with addition of the Updates and EditorBar clauses. The complete source code files are in the SDK's ..\Examples\Addon Complete folder.

It is essential that the name given to a new toolbar is unique, and the same name is used for the clauses in the server installation file, the tool locations file and the resources file.

Addon.rcs resources file (Addon.rcs):

PL
PLAddon:CountPadsAndShowDialog
Command='Addon:CountPads'
Caption='&Pad Count on Dialog...'
Image='Pad1.bmp'
Shortcut1='d'
Shortcut2=''
Params='Display=False'
Description='Display pad count in a dialog.'
End
 
PL
PLAddon:CountPadsAndShowDocument
Command='Addon:CountPads'
Caption='&Pad Count on Document...'
Image='Pad2.bmp'
Shortcut1='t'
Shortcut2=''
Params='Display=True'
Description='Display pad count in a text document.'
End

// two tool bar buttons added to the new toolbar
Tree TLAddon Caption='Addon Tools' TopLevel=True
Link TBAddon_Item1 PLID='PLAddon:CountPadsAndShowDialog' End
Separator TBAddon_Item2 End
Link TBAddon_Item3 PLID='PLAddon:CountPadsAndShowDocument' End
End

In this resources file, two tool buttons are linked to two existing process launchers. The nominated toolbar name, TLAddon, is also used in the tool locations file below.

Addon Tool Locations File (Addon.tlt):

ToolsLayout
BarLayout
BarName='TLAddon'
BarState=BarStateFloating
BarDockSite=DockSiteNone
BarDockRow=0
BarDockOffset=563
BarFloatLeft=299
BarFloatTop=201
BarFloatWidth=46
BarActive=True
BarDocumentKind = PCB
End
End

The tool locations file is defined for the supporting server so that the new toolbar is set to floating, and its location and size set in the PCB workspace.

Addon Installation File (Addon.ins):

ClientInsFile 1.0
 
Server
EditorName = 'AddOn'
EditorExePath = 'AddOn.DLL'
EditorDescription = 'Demonstratory AddOn module'
Version = 'Version 8.3.03.3231'
Date = '23-Apr-2005'
HelpAboutInfo = 'This software is protected by copyright law and international treaties.'
Copyright = 'Copyright © Altium Limited 2005'
Updates = 'ADVPCB'
End
 
EditorWindowKind
Name = 'Pcb'
EditorBar Name = 'TLAddon' BarType = Toolbar End
End
 
Command Name = 'CountPads' LongSummary = 'Find how many pads' End
Command Name = 'RunAPCBProcess' LongSummary = 'Invoke a PCB process' End

Note that the EditorBar clause includes the unique name of the toolbar (TLAddon) and the type of resource item (toolbar, hotkeytable or menu).

Extension Toolbar and Panel locations

Altium Designer retains the location information for toolbars and panels. For an extension, when its panels and toolbars are rearranged and Altium Designer shut down, the new panel/toolbar locations are written out to the UserTools.TLT file in the ..\*username*\AppData\AD{xxx} folder or its equivalent. These positional values will override the extension's defaults when its toolbars and panels are next opened in Altium Designer.

Printer-friendly version

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