Contact our corporate or local offices directly.
Parent page: DelphiScript
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.
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.
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.
See the Using Sets in DelphiScript entry for more information
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 to set the return value within a function block. For example:
Function Foo : String; Begin Result := 'Foo Foo'; End;
Nested routines are supported, but variables of the top-level function can't be used from the nested one.
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.
Type TVertices = Array [1..50] Of TLocation; Var NewVertices : TVertices;
Var NewVertices : Array [1..50] of TLocation;
Open Array declaration is not supported.
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;
New classes cannot be defined in DelphiScript, but you can use existing DelphiScript classes and instantiate them. For example the
TStringList classes can be created and used in your scripts.
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;
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.
Raise(Format('Invalid value : %d', [Height]));
Try, Finally and Raise keywords.
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.
The Set operator
In is not supported. The
InSet operator can be used to check whether a value is a member of a 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);
[...] set constructors are not supported — use the
MkSet function to create a Set:
Font.Style := MkSet(fsBold, fsItalic);
@ operators are not supported.
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.
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.
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).
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
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:
Check the scripts in the downloadable scripts collection to see Altium Designer Object Interfaces and functions, plus Delphi objects and functions being used in scripts.
Refer to the main Scripting documentation for information on writing scripts for Altium Designer.
Refer to the Using the Altium Designer API guide for details on how to use design objects and their interfaces in your scripts.
Refer to the Altium Designer API Reference for information on the range of Altium Designer APIs and their Interface Objects for scripts.
Contact our corporate or local offices directly.