DelphiScript

Dieser Abschnitt beschreibt die DelphiScript-Sprache, die von der Altium Designer Scripting Engine verwendet wird, und enthält Referenzdetails zu den unterstützten Anweisungen, Funktionen und Erweiterungen. Dabei handelt es sich um spezielle Prozeduren, die zur direkten Steuerung von und Kommunikation mit Altium Designer verwendet werden.

Außerdem in dieser Referenz:

• Unterschiede zwischen DelphiScript und Delphi
• DelphiScript-Schlüsselwörter
• DelphiScript-Anweisungen und -Operatoren
• DelphiScript-Funktionen
• DelphiScript-Formulare und -Komponenten

Die DelphiScript-Sprache

Diese DelphiScript-Referenz setzt voraus, dass Sie mit grundlegenden Programmierkonzepten sowie mit der grundlegenden Bedienung von Altium Designer vertraut sind. Das Skriptsystem unterstützt die DelphiScript-Sprache, die Embarcadero Delphi™ sehr ähnlich ist.

Der wesentliche Unterschied besteht darin, dass DelphiScript eine typfreie bzw. untypisierte Skriptsprache ist. Das bedeutet, dass Sie keine Records oder Klassen definieren und keine Pointer als Parameter an Funktionen übergeben können. Variablen können innerhalb von Skripten dennoch zur besseren Lesbarkeit deklariert werden.

Diese Seite und die zugehörigen Unterseiten enthalten Referenzmaterial zu Schnittstellen, Komponenten, globalen Routinen, Typen und Variablen, aus denen die DelphiScript-Skriptsprache besteht.

Zentrale DelphiScript-Elemente

Objekte

In DelphiScript besteht ein Objekt aus Methoden und in vielen Fällen auch aus Eigenschaften und Ereignissen. Eigenschaften repräsentieren die im Objekt enthaltenen Daten, Methoden sind die Aktionen, die das Objekt ausführen kann, und Ereignisse sind Bedingungen, auf die das Objekt reagieren kann. Alle Objekte leiten sich vom Objekt der obersten Ebene des Typs TObject ab (und erben davon).

Objektschnittstellen

Eine Objektschnittstelle besteht aus Methoden und in vielen Fällen auch aus Eigenschaften, kann jedoch keine Datenfelder haben. Eine Schnittstelle repräsentiert ein vorhandenes Objekt, und jede Schnittstelle besitzt eine GUID, die sie eindeutig kennzeichnet. Eigenschaften repräsentieren die im Objekt enthaltenen Daten, dem die Schnittstelle zugeordnet ist. Methoden sind die Aktionen, die das Objekt (dem die Schnittstelle zugeordnet ist) ausführen kann.

Komponenten

Komponenten sind visuelle Objekte aus dem Tool Palette panel, die zur Entwurfszeit bearbeitet werden können. Alle Komponenten leiten sich von der Systemklasse TComponent in der Embarcadero Delphi Visual Component Library (VCL) ab.

Routinen

Globale Routinen sind die Prozeduren und Funktionen des Skriptsystems. Diese Routinen sind nicht Teil einer Klasse, können jedoch entweder direkt oder innerhalb von Klassenmethoden in einem Skript aufgerufen werden.

Typen

Die Variablentypen werden als Rückgabetypen und Parametertypen für Schnittstellenmethoden und -eigenschaften, Objektmethoden, Eigenschaften und Ereignisse sowie globale Routinen verwendet. In vielen Fällen sind Typen in den Abschnitten zu Aufzählungstypen der API-Dokumentation dokumentiert.

Altium Designer und die Delphi RTL

Das Skriptsystem unterstützt eine Teilmenge der Embarcadero Delphi Run Time Library (RTL) und der Altium Designer API.

DelphiScript-Quelldateien

In Altium Designer ist ein Skriptprojekt so organisiert, dass Skriptdokumente (Skript-Units und Skript-Formulare) gespeichert werden. Sie können das Skript über einen Menüeintrag, eine Symbolleistenschaltfläche oder über den Dialog Select Item To Run ausführen, der im Hauptmenü von Altium Designer verfügbar ist.

PRJSCR-, PAS- und DFM-Dateien

Skripte sind in Projekten mit der Erweiterung *.PRJSCR organisiert. Jedes Projekt besteht aus Dateien mit der Erweiterung *.pas. Dateien können entweder Skript-Units oder Skript-Formulare sein — beachten Sie, dass jedes Formular eine Skriptdatei mit der Erweiterung *.pas und eine zugehörige Formulardatei mit der Erweiterung *.dfm besitzt. Ein Skript-Formular ist ein grafisches Fenster (Dialog), das über Altium Designer ausgeführt wird und verschiedene für den Benutzer zugängliche Steuerelemente enthält.

Es ist möglich, Skripte verschiedenen Projekten zuzuordnen, und es wird dringend empfohlen, Skripte in verschiedenen Projekten zu organisieren, um die Anzahl der Skripte sowie ihrer Prozeduren/Funktionen besser verwalten zu können.

Beispielskripte

Die Sammlung von Skriptbeispielen veranschaulicht die grundlegenden Funktionen der DelphiScript-Programmierung anhand einfacher Skripte zur Verwendung in Altium Designer.

Speicherort und Zweck einer Auswahl der Beispielskripte sind unten aufgeführt:

• Scripts\DelphiScript Scripts\DXP Ordner - Demonstriert die Client- und System-API
• Scripts\DelphiScript Scripts\PCB-Ordner - Demonstriert die PCB-API
• Scripts\DelphiScript Scripts\Processes Ordner - Demonstriert Server-Prozesse
• Scripts\DelphiScript Scripts\General Ordner - Demonstriert DelphiScript-Schlüsselwörter
• Scripts\DelphiScript Scripts\Sch Ordner - Demonstriert die Schaltplan-API
• Scripts\DelphiScript Scripts\WSM Ordner - Demonstriert die Workspace Manager API

DelphiScript-Skripte schreiben

Benennungskonventionen für DelphiScript

Im Allgemeinen gibt es keine Einschränkungen für die Namen, die Prozeduren, Funktionen, Variablen und Konstanten gegeben werden, solange sie die folgenden Regeln einhalten:

• Der Name kann die Buchstaben A bis Z, a bis z, das Unterstrichzeichen "_" und die Ziffern 0 bis 9 enthalten.
• Der Name muss mit einem Buchstaben beginnen.
• Der Name darf kein DelphiScript-Schlüsselwort, keine Direktive und kein reserviertes Wort sein.
• Namen werden bei der Interpretation nicht zwischen Groß- und Kleinschreibung unterschieden. Sowohl Groß- als auch Kleinbuchstaben können bei der Benennung einer Funktion, Unterroutine, Variablen oder Konstante verwendet werden; der Interpreter unterscheidet jedoch nicht zwischen Groß- und Kleinbuchstaben. Namen, die sich nur durch die Groß-/Kleinschreibung unterscheiden, werden in DelphiScript als derselbe Name behandelt.

In einer DelphiScript-Datei werden Funktionen und Prozeduren mithilfe der Blöcke Procedure-Begin-End oder Function-Begin-End deklariert. Beide Anweisungsblöcke erfordern, dass der Prozedur oder Funktion ein Name gegeben wird. DelphiScript ermöglicht es Ihnen, benannte Variablen und Konstanten zu erstellen, um Werte zu speichern, die im aktuellen Skript verwendet werden.

Kommentare einfügen

In einem Skript sind Kommentare nicht ausführbare Codezeilen, die zum Nutzen des Programmierers eingefügt werden. Kommentare können praktisch überall in einem Skript eingefügt werden.

Jeder Text nach // oder eingeschlossen von (* *) oder {} wird von DelphiScript ignoriert.

//This whole line is a comment

{This whole line is a comment}

{
These lines are comments
These lines are comments
}

(* This whole line is a comment *)
 
(*
These lines are comments
These lines are comments
*)

Kommentare können auch in derselben Zeile wie ausführbarer Code eingefügt werden. Zum Beispiel wird alles nach dem Semikolon in der folgenden Codezeile als Kommentar behandelt.

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

Lokale und globale Variablen

Da alle Skripte lokale und globale Variablen haben, ist es sehr wichtig, in Skripten innerhalb eines Skriptprojekts eindeutige Variablennamen zu verwenden. Wenn die Variablen outside irgendwelchen Prozeduren und Funktionen definiert werden, sind sie global und können von jeder Skript-Unit im selben Projekt aus aufgerufen werden.

Wenn Variablen inside einer Prozedur oder Funktion definiert werden, sind diese lokalen Variablen außerhalb dieser Prozeduren/Funktionen nicht zugänglich.

Example of Local and Global Variables in a Script:

// Note: The Uses keyword is not needed.

{ The global variable from UnitA script (see below) is available to this Script Unit,
  as long UnitA is in the same project as this Script Unit. }

Const
  GlobalVariableFromThisUnit='Global Variable from this unit';

Procedure TestLocal;
var
  Local;
Begin
  Local := 'Local Variable';
  ShowMessage(Local);
End;

Procedure TestGlobal;
Begin
  //ShowMessage(Local); // This line produces an error because the 'Local' variable is not global.
  ShowMessage(GlobalVariableFromThisUnit);
  // A variable from UnitA can be accessed without the Uses keyword.
  ShowMessage(GlobalVariableFromUnitA);
End;

UnitA script:

Const
  GlobalVariableFromUnitA = 'Global Variable from Unit A';

Benannte Variablen verwenden

In einem Skript werden benannte Variablen oder Konstanten erstellt, um Werte zu speichern, die während der Programmausführung verwendet werden. Alle Variablen in einem Skript sind immer vom Typ Variant. Typecasting findet keine Anwendung, daher werden Typen in Variablendeklarationen ignoriert und können weggelassen werden. Die folgenden Deklarationen sind daher korrekt:

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

Eine Zeile aufteilen

Jede Codeanweisung wird mit dem Zeichen ; als Semikolon abgeschlossen, um das Ende der Anweisung anzuzeigen. DelphiScript erlaubt es Ihnen, eine Anweisung über mehrere Codezeilen zu schreiben und eine lange Anweisung in zwei oder mehr Zeilen aufzuteilen. Die einzige Einschränkung beim Aufteilen von Programmanweisungen auf verschiedene Zeilen besteht darin, dass ein String-Literal nicht über mehrere Zeilen reichen darf.

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!'

DelphiScript setzt praktisch keine Grenze für die Länge einer einzelnen Codezeile in einem Skript, aber aus Gründen der Lesbarkeit und der einfacheren Fehlersuche ist es empfehlenswert, die Länge von Codezeilen so zu begrenzen, dass sie auf dem Bildschirm oder in gedruckter Form leicht gelesen werden können.

Wenn eine Codezeile sehr lang ist, können Sie diese Zeile in mehrere Zeilen aufteilen, und dieser Code wird vom DelphiScript-Interpreter so behandelt, als wäre er in einer einzigen Zeile geschrieben.

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;

Groß-/Kleinschreibung

Die zum Schreiben von Skripten verwendete DelphiScript-Sprache unterscheidet nicht zwischen Groß- und Kleinschreibung — das heißt, alle Schlüsselwörter, Anweisungen, Variablennamen sowie Funktions- und Prozedurnamen können ohne Beachtung von Groß- oder Kleinbuchstaben geschrieben werden. Groß- und Kleinbuchstaben gelten als gleichwertig.

Zum Beispiel ist der Variablenname myVar gleichbedeutend mit myvar und MYVAR. DelphiScript behandelt alle diese Namen als dieselbe Variable.

Die einzige Ausnahme hiervon sind Literal-Strings, wie etwa der Titel-String einer Dialogdefinition oder der Wert einer String-Variablen. Diese Strings behalten Unterschiede in der Groß-/Kleinschreibung bei.

Das Leerzeichen

Ein Leerzeichen wird verwendet, um Schlüsselwörter in einer Skriptanweisung zu trennen. DelphiScript ignoriert jedoch zusätzliche Leerzeichen in einer Anweisung.

Zum Beispiel:

X   = 5
// is equivalent to
X =5

Sie können Leerzeichen verwenden, um Ihr Skript besser lesbar zu machen.

Funktionen und Prozeduren in einem Skript

Der DelphiScript-Interpreter erlaubt zwei Arten von Methoden (Prozeduren): Prozeduren und Funktionen. Der einzige Unterschied zwischen einer Funktion und einer Prozedur besteht darin, dass eine Funktion einen Wert zurückgibt.

Ein Skript kann mindestens eine Prozedur haben, die den Hauptprogrammcode definiert. Sie können jedoch auch andere Prozeduren und Funktionen definieren, die von Ihrem Code aufgerufen werden können.

Wie bei Embarcadero Delphi werden Prozeduren und Funktionen innerhalb eines Anweisungsblocks Begin-End definiert. Um eine Funktion oder Prozedur aufzurufen, fügen Sie den Namen der Funktion oder Prozedur in eine Anweisung ein, genauso wie bei der Verwendung der integrierten DelphiScript-Funktionen und -Prozeduren. Wenn die Funktion oder Prozedur Parameter erfordert, müssen diese in die aufrufende Anweisung aufgenommen werden. Sowohl Funktionen als auch Prozeduren können so definiert werden, dass sie Parameter akzeptieren, aber nur Funktionen können so definiert werden, dass sie einen Wert an die aufrufende Anweisung zurückgeben.

Funktionen und Prozeduren können bei ihrer Definition beliebig benannt werden, solange der Name den Standard-Benennungskonventionen von DelphiScript entspricht.

Typical DelphiScript Procedure:

Procedure CreateSchObjects;
Begin
  If SchServer = Nil Then Exit;
  SchDoc := SchServer.GetCurrentSchDocument;
 
  If SchDoc = Nil Then Exit;
  PlaceSchematicObjects;
  SchDoc.GraphicallyInvalidate;
End;

Typical DelphiScript Function:

Function BooleanToString(AValue : Boolean) : String;
Begin
  If (AValue) Then Result := 'True'
  Else   Result := 'False';
End;

Der Name einer Funktion kann nicht verwendet werden, um ihren Rückgabewert festzulegen. Stattdessen muss das Schlüsselwort Result verwendet werden.

Var, Begin-End global block:

Var
  A, B, C;
Begin
  B := 10;
  C := 20;
  A := B + C;
  ShowMessage(IntToStr(A));
End;

Scripting-Tipps

Referenzieren von Skripten in einem Skriptprojekt

Der Code in einem Skript kann eine Prozedur in einem anderen Skript innerhalb desselben Skriptprojekts aufrufen. Auf jede globale Variable in jedem Skript kann innerhalb desselben Projekts zugegriffen werden.

Lokale und globale Variablen

Da Skripte lokale und globale Variablen haben, ist es wichtig, in Skripten innerhalb eines Skriptprojekts eindeutige Variablennamen zu verwenden. Wenn die Variablen außerhalb von Prozeduren und Funktionen definiert sind, sind sie global und können von jeder Unit im selben Projekt verwendet werden. Wenn Variablen innerhalb einer Prozedur oder Funktion definiert sind, sind diese lokalen Variablen außerhalb dieser Prozeduren/Funktionen nicht zugänglich.

Es wird empfohlen, Skripte ähnlicher Art in einem Projekt zusammenzufassen und die Anzahl der Skripte in einem Projekt auf eine überschaubare Größe zu begrenzen — das Nachverfolgen globaler Variablen in vielen Skripten kann problematisch werden. Es ist nicht zwingend erforderlich, Skripte in einem Skriptprojekt zu speichern, da Skripte auch in anderen Projekttypen abgelegt werden können.

Eindeutige Bezeichner und Variablen

Bei der Verwendung von Skriptformularen stellen Sie sicher, dass alle Skriptformulare eindeutige Formularnamen haben. Es ist möglich, dass alle Skriptformulare im selben Skriptprojekt beispielsweise form1 heißen. In diesem Fall gerät das Skriptsystem in Konflikt, wenn beim Ausführen eines Skriptformulars das richtige Formular angezeigt werden soll.

Ein Skriptformularname kann mit Object Inspector geändert werden. Der Name wird sowohl in den Dateien der Skript-Unit als auch des Skriptformulars automatisch geändert.

Parameterlose Prozeduren und Funktionen

Skripte sollten so geschrieben werden, dass die Prozeduren, die zum Ausführen des Skripts aufgerufen werden müssen, nur im Dialogfeld Select Items to Run dialog angezeigt werden. Um zu verhindern, dass andere Prozeduren/Funktionen im Dialogfeld Select Items to Run erscheinen, kann neben dem Methodennamen ein Parameter (Dummy : Integer) eingefügt werden. Siehe das folgende Beispiel.

// This function is prevented from appearing in the Select Items to Run dialog.
Function TSineWaveform.CreateShape(Dummy : Integer);
Begin
    //Do something
End;
{..................................................}
 
{..................................................}
Procedure TSineWaveform.bCloseClick(Sender: TObject);
var
  I : integer;
Begin
     //Doing something
Close;
End;
{..................................................}
 
{..................................................}
procedure DrawSine;
Begin
    SineWaveform.showmodal;
End;

DelphiScript-Fehlercodes