JScript

Parent Page: Scripting Languages

This reference describes the JavaScript (JScript for short) scripting language used in Altium Designer. It provides details of the JScript Scripting statements, functions and extensions that are supported in the scripting system.

Also in this reference:

The JScript language

The Altium Designer scripting system supports the JScript language (along with other scripting languages) which is derived from the Microsoft Active Scripting system. The JScript Scripting can also deal with Altium Designer Object Models and Visual Components.

All scripting languages supported in Altium Designer are typeless or untyped, which means you cannot define records or classes and pass pointers as parameters to functions. In this guide it is assumed that you are familiar with basic programming concepts and as well as the basic operation of the Altium Designer software.

JScript example

 function DisplayDate(){    var d, s = "Today's date is: ";  //Declare variables.    d = new Date();                  //Create Date object.    s += (d.getMonth() + 1) + "/";   //Get month    s += d.getDate() + "/";          //Get day    s += d.getYear();                //Get year.    showmessage(s);                  //Show date. }

Altium Designer and the Delphi RTL

The Scripting system also supports a subset of the Embarcadero Delphi™ Run Time Library (RTL) and the Altium Designer scripting API.

JScript scripts can access several Object Models in Altium Designer. For example, the PCB Object Model can be used in JScripts to deal with PCB objects on a PCB document, or the Workspace Manager Object Model to work with Projects and their documents to extract netlist data.

Server Processes

A script can can be used to execute Altium Designer server processes.

JScript source files

A script project is organized to store script documents (script units and script forms). A script can be executed from a menu item, toolbar button or from the Run Script dialog from the system menu.

PRJSCR, JS and DFM files

Scripts are organized into projects with a *.PRJSCR extension. Each JScript project consists of files with a *.js extension. Files can be either script units or script forms — each form has a script file with *.js extension and a corresponding form with a *.dfm extension). A script form is a graphical window (dialog) that hosts different controls that run on top of Altium Designer.

It is possible to attach scripts to different projects, and it's highly recommended to organize scripts into different projects to manage the number of scripts and their procedures / functions. Scripts (script units and script forms) consist of functions/procedures that can be called within Altium Designer.

JScript examples

The simple examples included in this reference illustrate the basic features of JScript programming in Altium Designer.

The JScripts can use script forms, script units, functions and objects from the Altium Designer scripting API, and a subset of functions and objects from the Embarcadero Delphi RTL that are exposed in the scripting system.

Writing JScript scripts

This section covers the basic concepts of writing JScripts in Altium Designer.

JScript naming conventions

JScript is a case sensitive language, which means the keywords, variables, function names and other identifiers must be typed with consistent capitalization of letters.

Example

 function Displaymessage //valid function. Function Displaymessage // invalid function statement a = 60 // A = 45 // a and A are two different variables with different memory locations! 

Local and Global Variables

Since all scripts have local and global variables, it is very important to have unique variable names in scripts within a script project. If the variables are defined outside any procedures and functions, they are global and can be accessed by any unit in the same project.

If variables are defined inside a procedure or function, then these local variables are not accessible outside these procedures/functions.

Example of local and global variables in a script

 // Variables from UnitA script are available to this unit script, // as long UnitA is in the same project as this Unit script. var     GlobalVariableFromThisUnit="Global Variable from this unit";  function TestLocal() { var     Local;      // can we access a variable from UnitA without the Uses      Local = "Local Variable";      ShowMessage(Local); }  function TestGlobal {     //ShowMessage(Local); // produces an error.     ShowMessage(GlobalVariableFromThisUnit);     ShowMessage(GlobalVariableFromUnitA); }

Unit A script

 Var     GlobalVariableFromUnitA = "Global Variable from Unit A"; 

Functions

The function statement defines a JScript function. The block of the function is defined by the curly brackets {}. The syntax for a function is:

function functionname ([arg1 [, arg2[..., argn]]] {statements}

Example

 function DisplayMessage() {     var          Message = "Hello World";     Showmessage(Message); } 

Returning results in a function

The return statement is used to specify the value returned by a function.
Example

 function square (x){     return x * x; } 

Parameters and arguments

The function declaration normally has a list of parameters. In scripts, variables are considered typeless, and the scripting system automatically works out what the variable types are. The value used in place of the parameter when a procedure call is made is called an argument.

It is important to note that functions with parameters will not appear on the Select Item To Run dialog

Example of a function with a parameter

 function DisplayName (sName) {     ShowMessage("My Name is " +  sName); } 

Including Comments in scripts

JScript supports both C++ and C style comments. Any text between a // and the end of a line is a comment.

Any text between the characters /* and */ is a comment.

 //This whole line is a comment  /* This whole line is a comment */  /* This whole line is a comment This whole line is a comment This whole line is a comment */

Comments can also be included on the same line as executed code. For example, everything after the semi colon in the following code line is treated as a comment, as it as preceded by //.

 ShowMessage("Hello World"); //Display Message 

Splitting a line of script

Each code statement is terminated with the semi-colon " ; " character to indicate the end of this statement. JScript allows a statement to be written on several lines of code, such as splitting a long instruction on two or more lines. The only restriction in splitting programming statements on different lines is that a string literal may not span several lines.

For example:

 X.AddPoint( 25, 100); X.AddPoint( 0, 75); // is equivalent to: X.AddPoint( 25, 100); X.AddPoint( 0, 75);

...however;

 "Hello World!" // is not equivalent to: "Hello World!"

JScript does not put any practical limit on the length of a single line of code in a script, however for the sake of readability and ease of debugging, it is good practice to limit the length of code lines so that they can easily be read on screen or in printed form.

If a line of code is very long it can be broken into multiple lines, and this code will be treated by the JScript interpreter as if it were written on a single line.

Unformatted code example

 If Not (PcbApi_ChooseRectangleByCorners(BoardHandle,"Choose first corner","Choose final corner",x1,y1,x2,y2)) Then Exit; 

Formatted code example

 If Not (PcbApi_ChooseRectangleByCorners(BoardHandle,                                         "Choose first corner",                                         "Choose final corner",                                         x1,y1,x2,y2)) Then Exit; 

Using Altium Designer Object Models

The biggest feature of the scripting system is that the Interfaces of Altium Designer objects are available to use in scripts. For example, you have the ability to massage design objects on Schematic and PCB documents through the use of Schematic Interfaces and PCB Interfaces.

Normally in scripts, there is no need to instantiate an interface. The interface representing an existing Altium Designer object is extracted, and from this interface the embedded or aggregate interface objects can be extracted to get or set their property values.

By convention, Interface names are prefixed by an I character — for example IPCB_Board represents an interface for an existing PCB document in Altium Designer. For access to a schematic document, the SchServer function is invoked first.

Example

 // Checks if the current document is a Schematic document if SchServer != Null {     CurrentSheet = SchServer.GetCurrentSchDocument;     if (CurrentSheet != Null {         // statements     } } 

To access to a PCB document, the PCBServer function is invoked first.

Creating a PCB object example

 function ViaCreation() { var Board; //IPCB_Board; var Via;   //IPCB_Via;     Board = PCBServer.GetCurrentPCBBoard;     if (Board != Null)     {         /* Create a Via object */         Via           = PCBServer.PCBObjectFactory(eViaObject, eNoDimension, eCreate_Default);         Via.X         = MilsToCoord(7500);         Via.Y         = MilsToCoord(7500);         Via.Size      = MilsToCoord(50);         Via.HoleSize  = MilsToCoord(20);         Via.LowLayer  = eTopLayer;         Via.HighLayer = eBottomLayer;         /* Put this via in the Board object*/         Board.AddPCBObject(Via);     } } 

Altium Designer Objects, Interfaces, functions and types can be accessed in scripts from the following:

• Client API
• PCB Server API
• Schematic Server API
• Work Space Manager Server API
• Nexus API
• DXP RTL functions
• Parametric processes.

Reserved Words in JScript

The scripting system supports the JScript language which is derived from the Microsoft Active Scripting language technology.

The following words are reserved in JScript and cannot be used for variable names.
B,C
abstract, boolean, break, byte, case, catch, class, const, continue
D,E
debugger, default, delete, do, else, enum, export, extends
F, G
false, final, finally, for, function, goto
I
if, implements, import, in, instanceof, int, interface, long
N, R, S
native, new, null, return, short, static, super, switch, synchronized
T, V
this, throw, throws, transient, true, try, typeof, var, void, volatile
W
while, with