Delphi - DelphiScript differences

Old Content - visit altium.com/documentation

Parent page: DelphiScript

Differences between DelphiScript and Delphi

This section covers the essential differences between the DelphiScript scripting language and Embarcadero's Delphi programming language, and how this applies to the Altium Designer API.

The Altium Designer scripting system uses untyped DelphiScript language so there are no data types in scripts. Although you can declare variables and their types, and specify the types for functions/procedures or method parameters for readability, DelphiScript will convert undeclared variables when a script is being executed. So for example, you cannot define records or classes.

Delphi Script Variables

All variables in a script are of Variant type, and Types in a variable declaration are ignored and can be skipped. So these three declarations are correct:

Var
a : Integer;
 
Var
b : Integer;
 
Var
  c, d;

Types of parameters in a procedure/function declaration are also ignored and can be skipped. For example, this code is correct:

Function Sum(a, b) : Integer;
Begin
  Result := a + b;
End;

In general, variants can be used to store any data type and perform numerous operations and type conversions. A variant is type-checked and computed at run time. The compiler won't provide a warning of possible errors in the code, which can be caught only with extensive testing. On the whole, the code portions that use variants can be considered to be interpreted code, because many operations cannot be resolved until run time. This can affect the speed of the code.

The result of this is that once a variant variable has been declared and has obtained a variant value, it can be copied to any compatible - or incompatible - data type:

Var
V;
Begin
  // variable V can be assigned values of several different types:
  V := 10;
  V := 'Hello, World';
  V := 45.55;
End;

If an incompatible data type has been assigned to a variable the DelphiScript interpreter performs a conversion where possible. Otherwise, a run-time error is issued. In practice, a variant stores type information along with the data so DelphiScript is slower than the equivalent Embarcadero Delphi compiled code.

Sets in scripts

DelphiScript does not have Set types and does not support Set operators, unlike the Delphi language which does have Set types and supports Set operators.

To use Sets in DelphiScript scripts, use the built-in functions that manipulate sets in a script.

Internal Functions or Procedures

When considering using Functions and Procedures inside a Function or Procedure, the recommended approach is to write standalone functions/procedures — although recursive procedures/functions are permitted.

The following function snippet is not recommended:

Function A
Function B
Begin
// blah
End;
Begin
B;
End;

Recommended function structure:

Function B
Begin
// blah
End;

Function A
Begin
B;
End;

Result Keyword

Use the Result keyword to set the return value within a function block. For example:

Function Foo : String;
Begin
Result := 'Foo Foo';
End;

Nested Routines

Nested routines are supported, but variables of the top level function can't be used from the nested one.

Array Elements

The Type of array elements is ignored and can be skipped, so these two declarations are equal:

Var
x : array [1..2] of double;

Var
x : array [1..2];

Note that you cannot declare array types, but you can declare arrays to variables.

Illegal example:

Type
TVertices = Array [1..50] Of TLocation;
Var
NewVertices : TVertices;

Legal example:

Var
NewVertices : Array [1..50] of TLocation;

Open Array Declaration

The Open Array declaration is not supported.

Case Keyword

The Case keyword can be used for any type. So the following is valid:


Case UserName of
'Alex', 'John' : IsAdministrator := true;
'Peter' : IsAdministrator := false;
Else
Raise('Unknown user');
End;

Class Declarations

New classes cannot be defined in DelphiScript, but you can use existing DelphiScript classes and instantiate them. For example the TList and TStringList classes can be created and used in your scripts.
See also
TList
TStringList

CreateObject Function

The CreateObject function can be used to create objects that will be implicitly freed when no longer used.

So instead of:

Procedure Proc;
Var
  l;
Begin
    l := TList.Create;
  Try
    // do something with l
  Finally
  L.Free;
End;

...you can write:

Procedure Proc;
Var
  l;
Begin
  l := CreateObject(TList);
  // Do something with l
End;

See also
CreateObject function.

Raise Exceptions

The Raise keyword can be used without parameters to re-raise the last exception. Raise can also be used with a string parameter to raise the exception with the specified message string. The Exception objects are not supported in DelphiScript, because the On keyword is not supported.

Example:

Raise(Format('Invalid value : %d', [Height]));

See also
Try, Finally and Raise keywords.

ThreadVar

In Delphiscript, the Threadvar keyword is treated as Var. Note that in Embarcadero Delphi, the variables declared using the Threadvar keyword have distinct values in each thread.

Set Operators

The Set operator In is not supported. The InSet operator can be used to check whether a value is a member of set. For example:

If InSet(fsBold, Font.Style) then
ShowMessage('Bold');

Note that Delphi set operators +, -, *, <=, >= do not work correctly. The built in Delphiscript functions MkSet, MkSetRange, SetUnion, SetDifference, SetIntersection, SubSet and InSet are used instead:

ASet := BSet + CSet; \\ should be changed to
ASet := SetUnion(BSet, CSet);

The [...] set constructors are not supported — use the MkSet function to create a Set:

Font.Style := MkSet(fsBold, fsItalic); 

See also
MkSet keyword
MkSetRange keyword
InSet keyword
SetDifference keyword
SetIntersection keyword
SetUnion keyword
SubSet keyword
InSet keyword

Operators

The ^ and @ operators are not supported.

Directives

The following directives are not supported (note that some are obsolete, and are also not supported by Embarcadero Delphi): absolute, abstract, assembler, automated, cdecl, contains, default, dispid, dynamic, export, external, far, implements, index, message, name, near, nodefault, overload, override, package, pascal, private protected, public, published, read, readonly, register, reintroduce, requires, resident, safecall, stdcall, stored, virtual, write, writeonly.

Also note that the in directive in the Uses clause is ignored.

Ignored Keywords

The interface, implementation, program and unit keywords are ignored in DelphiScript. The scripts can contain them but they have no effect — however these keywords can enhance the readability of scripts.

Unsupported Keywords

The following keywords are not supported in DelphiScript:

  • as, asm, class, dispinterface, exports, finalization, inherited, initialization, inline, interface, is, library, object, out, property, record, resourcestring, set, supports, type.

The following Delphi RTL functions aren't supported in DelphiScript:

  • Abort, Addr, Assert, Dec, FillChar, Finalize, Hi, High, Inc, Initialize, Lo, Low, New, Ptr, SetString, SizeOf, Str, UniqueString, VarArrayRedim, VarArrayRef, VarCast, VarClear, VarCopy.

The functions from the Delphi's Windows unit (the windows.pas file) are not supported (for example the RGB function is not supported).

Using the Altium Designer API in scripts

You cannot create your own records or classes types using DelphiScript and instantiate them in a script, however you can use certain classes from the Altium Designer API. For example, the TStringList and TList classes can be instantiated and used as containers of data storage (usually of the same type) to meet the needs of a script.

The API's Object Interfaces that represent Altium Designer objects are available to use in scripts. For example, you have the ability to update design objects on Schematic and PCB documents through the use of Schematic object interfaces and PCB objects interfaces.

As a convention, interface names have an 'I' added in front of the name. For example IPCB_Board represents an interface for an existing PCB document.

PCB Interfaces in a script example:

Procedure ViaCreation;
Var
  Board : IPCB_Board;
  Via : IPCB_Via;
Begin
  Board := PCBServer.GetCurrentPCBBoard;
  If Board = Nil Then Exit;
 
  (\* 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);
End;

The following APIs can be used in Scripts:

  • Certain Embarcadero Delphi™ functions and classes, and DelphiScript extensions
  • Client API
  • PCB Server API
  • Schematic Server API
  • Workspace Manager Server API
  • Integrated Library API
  • Nexus (FPGA) API
  • Altium Designer API functions
  • Parametric processes

More information

You are reporting an issue with the following selected text and/or image within the active document:
ALTIUM DESIGNER FREE TRIAL
Altium Designer Free Trial
Let’s get started. First off, are you or your organization already using Altium Designer?

If would like to speak with a representative, please contact your local Altium office.
Copyright © 2019 Altium Limited

In that case, why do you need an evaluation license?

If would like to speak with a representative, please contact your local Altium office.
Copyright © 2019 Altium Limited

Got it. You actually don’t need an evaluation license for that.

Click the button below to download the latest Altium Designer installer.

Download Altium Designer Installer

If would like to speak with a representative, please contact your local Altium office.
Copyright © 2019 Altium Limited

Please fill out the form below to get a quote for a new seat of Altium Designer.

By clicking “Get Your Free Trial”, you are agreeing to our Privacy Policy.
You may receive communications from Altium and can change your notification preferences at any time.

If you are on Altium Subscription, you don’t need an evaluation license.

If you are not an active Altium Subscription member, please fill out the form below to get your free trial.

By clicking “Get Your Free Trial”, you are agreeing to our Privacy Policy.
You may receive communications from Altium and can change your notification preferences at any time.

Why are you looking to evaluate Altium Designer?

If would like to speak with a representative, please contact your local Altium office.
Copyright © 2019 Altium Limited

You came to the right place! Please fill out the form below to get your free trial started.

By clicking “Get Your Free Trial”, you are agreeing to our Privacy Policy.
You may receive communications from Altium and can change your notification preferences at any time.

Sounds exciting! Did you know we offer special discounted student licenses? For more information, click here.

In the meantime, feel free to request a free trial by filling out the form below.

By clicking “Get Your Free Trial”, you are agreeing to our Privacy Policy.
You may receive communications from Altium and can change your notification preferences at any time.

Got it. You can download a free Altium Designer Viewer license which is valid for a 6 months.

Please fill out the form below to request one.

By clicking “Get Your Free Trial”, you are agreeing to our Privacy Policy.
You may receive communications from Altium and can change your notification preferences at any time.

That’s great! Making things is awesome. We have the perfect program for you.

Upverter is a free community-driven platform designed specifically to meet the needs of makers like you.

Click here to give it a try!

If would like to speak with a representative, please contact your local Altium office.
Copyright © 2019 Altium Limited

Got it. You can download a free Altium Designer Viewer license which is valid for a 6 months.

Please fill out the form below to request one.

By clicking “Get Your Free Trial”, you are agreeing to our Privacy Policy.
You may receive communications from Altium and can change your notification preferences at any time.