Differences between DelphiScript and Delphi
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.
See the Using Sets in DelphiScript entry for more information
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 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);
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
- Altium Designer API functions
- Parametric processes
More Information
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.