PCB-Related API

Overview

Creating Objects

Tracks

The following code shows how to create a track (a straight line, curved ones are called arcs) on a PCB.

Arcs

The following code shows how to create an arc (a curved line) on a PCB.

User Input

The following functions belonging to the IPCB_Board object request input from the user:

Get The User To Select A Position

The following code prompt the user to select a position on the PCB. The position (as x and y co-ordinates) the user clicks can then be used in proceeding code.

Get The User To Select Objects

To prompt the user to select objects, use the function GetObjectAtCursor(); on a PCB board ( IPCB_Board) object. It’s syntax is:

where objectSet is a list of all object types that the user can select (think of it as a mask), layerSet is a list of all layers that objects can be selected on (yet again, a mask), and statusBarText is the text you want to display in the status bar while the user selects the objects.

The TObjectSet variable is normally made by calling the function MkSet(), which makes a set from the passed in object(s) (this only required when scripting in Delphi, as Delphi doesn’t natively support sets). The objects you can pass into MkSet() are part of the TObjectID enumeration and include:

The example below requests the user to select a component from an layer.

Check That A PCB Board Is Selected

You commonly need to check that when a script is run, the active window is the right thing for the script to act on. The following code shows how to check if a PCB board file is loaded (.Pcb), and it feature at the start of lots of the other code examples. If a PCB board is not currently selected, the script quietly exits.

Creating PCB Regions (The Contour Method)

You can create PCB regions (which are similar to polygons, but have slightly different properties/behaviours) using contours.

Define The Objects

Define the following objects after the var  keyword and before the begin  keyword.

To Generate An Arc Section Of A Region

Use the following function to create an arc an add it to the contour (which will be used once all the segments have been added to generate the region).

Make Aclockwise  be true if going clockwise, false if going clockwise.

The Generate A Straight Section Of A Region

Use the following function to create a line segment and add it to a contour (which will be used once all the segments have been added to generate the region). Note that it is slightly simpler to add a line segment to a contour than an arc, basically because for a line all you have to do is define the start and end points.

How To Finally Add The Region To The PCB

Once you have defined a region by using the contour object, you can add it to the PCB with the following code. This assumes

Creating PCB Polygons (The PolySegment Method)

You can create polygons on a PCB by using the IPCB_Polygon and TPolySegment classes.

Here is an example that will create a rather large, square polygon on the top layer of your PCB.

To Update The PCB Window

Use the Client object to update the PCB window. This will update the PCB to show any changes that have been made to it by preceeding code (it is not updated automatically). It is useful to call this at the end of a script to update the PCB and show the user the changes that have been made. If you don’t call this, the the user will only see the changes once this method is called by another process.

Undo

With specifically calling the functions PCBServer.PreProcess and PCBServer.PostProcess, you will lose undo/redo functionality when/after running altium scripts.

Make sure that you call PCBServer.PreProcess and PCBServer.PostProcess after doing any action that would change the PCB in anyway. If you are losing Undo functionality, it is likely due to the fact you are calling PreProcess without calling PostProcess. Essentially, any action done on the PCB between these two function calls is counted as one ‘Undo’. The code below shows how to use these two functions correctly.

You can get the following error when trying to save if you haven’t called PCBServer.PostProcess and equal number of times as PCBServer.PostProcess. So far, if this does occur, I haven’t worked out how to save the document (all changes since last save are lost!).

pcb-script-bug-a-command-is-currently-active-and-save-cannot-be-completed-at-this-time-png You might get this error in Altium when trying to save because you have run a script which hasn't called PSBServer.PostProcess an equal number of times as PCBServer.PostProcess.

Updating Component  Links

You can open the “Edit Component Links” window by running the following commands (VBscript):

Note that this does not update the component links automatically, but just opens the “Edit Component Links” window.

Zoom

You can change the zoom on a PCB by using the following commands (VBscipt):

PCB Layer Info

You can get the currently selected PCB layer with the code:

 On a valid IPCB_Board object.

You can use the LayerToString() and StringToLayer() functions to convert a PCB layer object into a human readable string and back again. For example, if the PCB was currently on the top copper layer, you could do the following:

 

PCB Components

PCB Components have a child object called Name, which refers the the designator.

The Name Object

The confusing thing is, while the parameter Width refers to it’s width, the parameter Size refers to the designator height.