DelphiScript

Cette section décrit le langage DelphiScript utilisé par le moteur de script d’Altium Designer et fournit des informations de référence sur les instructions, fonctions et extensions prises en charge. Il s’agit de procédures spéciales utilisées pour contrôler et communiquer directement avec Altium Designer.

Également dans cette référence :

• Différences entre DelphiScript et Delphi
• Mots-clés DelphiScript
• Instructions et opérateurs DelphiScript
• Fonctions DelphiScript
• Formulaires et composants DelphiScript

Le langage DelphiScript

Cette référence DelphiScript suppose que vous connaissez les concepts de base de la programmation ainsi que le fonctionnement de base d’Altium Designer. Le système de script prend en charge le langage DelphiScript, qui est très similaire à Embarcadero Delphi™.

La principale différence est que DelphiScript est un langage de script sans type, ou non typé, ce qui signifie que vous ne pouvez pas définir d’enregistrements ni de classes, ni passer des pointeurs comme paramètres à des fonctions. Les variables peuvent néanmoins être déclarées dans les scripts pour améliorer la lisibilité.

Cette page et les sous-pages associées contiennent des informations de référence sur les interfaces, composants, routines globales, types et variables qui constituent le langage de script DelphiScript.

Éléments clés de DelphiScript

Objets

Dans DelphiScript, un objet se compose de méthodes et, dans de nombreux cas, de propriétés et d’événements. Les propriétés représentent les données contenues dans l’objet, les méthodes sont les actions que l’objet peut exécuter, et les événements sont les conditions auxquelles l’objet peut réagir. Tous les objets descendent (et héritent) de l’objet de niveau supérieur de type TObject.

Interfaces d’objet

Une interface d’objet se compose de méthodes et, dans de nombreux cas, de propriétés, mais ne peut pas avoir de champs de données. Une interface représente un objet existant, et chaque interface possède un GUID qui l’identifie de manière unique. Les propriétés représentent les données contenues dans l’objet auquel l’interface est associée. Les méthodes sont les actions que l’objet (auquel l’interface est associée) peut exécuter.

Composants

Les composants sont des objets visuels du panneau Tool Palette qui peuvent être manipulés au moment de la conception. Tous les composants dérivent de la classe système TComponent dans la Visual Component Library (VCL) d’Embarcadero Delphi.

Routines

Les routines globales sont les procédures et fonctions du système de script. Ces routines ne font pas partie d’une classe, mais peuvent être appelées soit directement, soit depuis des méthodes de classe dans un script.

Types

Les types de variables sont utilisés comme types de retour et types de paramètres pour les méthodes et propriétés d’interface, les méthodes, propriétés et événements d’objet, ainsi que les routines globales. Dans de nombreux cas, les types sont documentés dans les sections sur les types énumérés de la documentation API.

Altium Designer et la RTL Delphi

Le système de script prend en charge un sous-ensemble de la Run Time Library (RTL) d’Embarcadero Delphi ainsi que l’API d’Altium Designer.

Fichiers source DelphiScript

Dans Altium Designer, un projet de script est organisé pour stocker des documents de script (unités de script et formulaires de script). Vous pouvez exécuter le script depuis un élément de menu, un bouton de barre d’outils ou depuis la boîte de dialogue Select Item To Run disponible dans le menu principal d’Altium Designer.

Fichiers PRJSCR, PAS et DFM

Les scripts sont organisés en projets avec une extension *.PRJSCR. Chaque projet se compose de fichiers avec une extension *.pas. Les fichiers peuvent être soit des unités de script, soit des formulaires de script — notez que chaque formulaire possède un fichier de script avec une extension *.pas et un fichier de formulaire correspondant avec une extension *.dfm. Un formulaire de script est une fenêtre graphique (boîte de dialogue) qui s’exécute au-dessus d’Altium Designer et héberge différents contrôles accessibles à l’utilisateur.

Il est possible d’attacher des scripts à différents projets, et il est fortement recommandé d’organiser les scripts dans différents projets afin de gérer le nombre de scripts ainsi que leurs procédures/fonctions.

Exemples de scripts

La collection d’exemples de scripts illustre les fonctionnalités de base de la programmation DelphiScript à l’aide de scripts simples destinés à être utilisés dans Altium Designer.

L’emplacement et l’objectif d’une sélection d’exemples de scripts sont indiqués ci-dessous :

• Scripts\DelphiScript Scripts\DXPdossier - illustre l’API Client et l’API système
• Scripts\DelphiScript Scripts\PCdossier B - illustre l’API PCB
• Scripts\DelphiScript Scripts\Processesdossier - illustre les processus serveur
• Scripts\DelphiScript Scripts\Generaldossier - illustre les mots-clés DelphiScript
• Scripts\DelphiScript Scripts\Schdossier - illustre l’API Schématique
• Scripts\DelphiScript Scripts\WSMdossier - illustre l’API Workspace Manager

Écriture de scripts DelphiScript

Conventions de nommage DelphiScript

En général, il n’existe aucune restriction concernant les noms donnés aux procédures, fonctions, variables et constantes, tant qu’ils respectent les règles suivantes :

• Le nom peut contenir les lettres A à Z, a à z, le caractère de soulignement « _ » et les chiffres de 0 à 9.
• Le nom doit commencer par une lettre.
• Le nom ne peut pas être un mot-clé DelphiScript, une directive ou un mot réservé.
• Les noms ne sont pas sensibles à la casse lors de l’interprétation. Les majuscules comme les minuscules peuvent être utilisées pour nommer une fonction, une sous-routine, une variable ou une constante ; toutefois, l’interpréteur ne fera pas la distinction entre caractères majuscules et minuscules. Les noms identiques à l’exception de la casse seront traités comme un seul et même nom en DelphiScript.

Dans un fichier DelphiScript, les fonctions et procédures sont déclarées à l’aide des blocs Procedure-Begin-End ou Function-Begin-End. Ces deux blocs d’instructions exigent qu’un nom soit donné à la procédure ou à la fonction. DelphiScript vous permet de créer des variables et constantes nommées pour contenir les valeurs utilisées dans le script en cours.

Ajout de commentaires

Dans un script, les commentaires sont des lignes de code non exécutables incluses pour le bénéfice du programmeur. Des commentaires peuvent être insérés pratiquement n’importe où dans un script.

Tout texte suivant // ou encadré par (* *) ou {} est ignoré par DelphiScript.

//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
*)

Les commentaires peuvent également être inclus sur la même ligne que du code exécuté. Par exemple, tout ce qui suit le point-virgule dans la ligne de code suivante est traité comme un commentaire.

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

Variables locales et globales

Étant donné que tous les scripts ont des variables locales et globales, il est très important d’avoir des noms de variables uniques dans les scripts d’un même projet de script. Si les variables sont définies outside toute procédure ou fonction, elles sont globales et peuvent être accessibles depuis n’importe quelle unité de script du même projet.

Si les variables sont définies inside une procédure ou une fonction, alors ces variables locales ne sont pas accessibles en dehors de ces procédures/fonctions.

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

Utilisation de variables nommées

Dans un script, des variables ou constantes nommées sont créées pour stocker des valeurs à utiliser pendant l’exécution du programme. Toutes les variables d’un script sont toujours de type Variant. Le transtypage ne s’applique pas ; les types dans les déclarations de variables sont donc ignorés et peuvent être omis. Les déclarations suivantes sont donc correctes :

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

Fractionnement d’une ligne

Chaque instruction de code se termine par le caractère ; point-virgule pour indiquer la fin de l’instruction. DelphiScript vous permet d’écrire une instruction sur plusieurs lignes de code, en divisant une instruction longue en deux lignes ou plus. La seule restriction concernant le fractionnement des instructions de programmation sur différentes lignes est qu’un littéral de chaîne ne peut pas s’étendre sur plusieurs lignes.DelphiScript n’impose aucune limite pratique à la longueur d’une seule ligne de code dans un script, mais, pour des raisons de lisibilité et de facilité de débogage, il est recommandé de limiter la longueur des lignes de code afin qu’elles puissent être facilement lues à l’écran ou sous forme imprimée.

Si une ligne de code est très longue, vous pouvez la scinder en plusieurs lignes, et ce code sera traité par l’interpréteur DelphiScript comme s’il avait été écrit sur une seule ligne.

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;

Sensibilité à la casse

Le langage DelphiScript utilisé pour écrire des scripts n’est pas sensible à la casse — c’est-à-dire que tous les mots-clés, instructions, noms de variables, noms de fonctions et de procédures peuvent être écrits sans tenir compte de l’utilisation de majuscules ou de minuscules. Les caractères majuscules et minuscules sont considérés comme équivalents.

Par exemple, le nom de variable myVar est équivalent à myvar et MYVAR. DelphiScript traite tous ces noms comme une seule et même variable.

La seule exception concerne les chaînes littérales, telles que la chaîne de titre d’une définition de boîte de dialogue ou la valeur d’une variable chaîne. Ces chaînes conservent les différences de casse.

Le caractère espace

Un espace est utilisé pour séparer les mots-clés dans une instruction de script. Cependant, DelphiScript ignore tout espace blanc supplémentaire dans une instruction.

Par exemple :

X   = 5
// is equivalent to
X =5

Vous pouvez utiliser les espaces blancs pour rendre votre script plus lisible.

Fonctions et procédures dans un script

L’interpréteur DelphiScript autorise deux types de méthodes (procédures) : les procédures et les fonctions. La seule différence entre une fonction et une procédure est qu’une fonction renvoie une valeur.

Un script peut comporter au moins une procédure qui définit le code principal du programme. Vous pouvez toutefois définir d’autres procédures et fonctions pouvant être appelées par votre code.

Comme avec Embarcadero Delphi, les procédures et fonctions sont définies dans un bloc d’instructions Begin-End. Pour invoquer ou appeler une fonction ou une procédure, incluez le nom de la fonction ou de la procédure dans une instruction, de la même manière que lorsque vous utilisez les fonctions et procédures DelphiScript intégrées. Si la fonction ou la procédure nécessite des paramètres, ceux-ci doivent être inclus dans l’instruction d’appel. Les fonctions comme les procédures peuvent être définies pour accepter des paramètres, mais seules les fonctions peuvent être définies pour renvoyer une valeur à l’instruction appelante.

Tout nom peut être attribué aux fonctions et procédures lors de leur définition, à condition qu’il soit conforme aux conventions de nommage standard de DelphiScript.

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;

Le nom d’une fonction ne peut pas être utilisé pour définir sa valeur de retour. Le mot-clé Result doit être utilisé à la place.

Var, Begin-End global block:

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

Conseils de script

Référencement des scripts dans un projet de script

Le code d’un script peut appeler une procédure dans un autre script du même projet de script. Toute variable globale de n’importe quel script est accessible dans le même projet.

Variables locales et globales

Comme les scripts comportent des variables locales et globales, il est important d’avoir des noms de variables uniques dans les scripts d’un projet de script. Si les variables sont définies en dehors de toute procédure ou fonction, elles sont globales et peuvent être accessibles depuis n’importe quelle unité du même projet. Si les variables sont définies à l’intérieur d’une procédure ou d’une fonction, alors ces variables locales ne sont pas accessibles en dehors de ces procédures/fonctions.

Il est recommandé de regrouper dans un projet les scripts de nature similaire et de maintenir le nombre de scripts d’un projet à une taille gérable — le suivi des variables globales dans de nombreux scripts peut devenir problématique. Il n’est pas obligatoire de stocker les scripts dans un projet de script, car ils peuvent être placés dans d’autres types de projets.

Identifiants et variables uniques

Lors de l’utilisation de formulaires de script, assurez-vous que tous les formulaires de script ont des noms de formulaire uniques. Il est possible d’avoir tous les formulaires de script nommés form1 (par exemple) dans le même projet de script. Dans ce cas, le système de script entre en conflit lorsqu’il tente d’afficher le formulaire correct lors de l’exécution d’un formulaire de script.

Le nom d’un formulaire de script peut être modifié à l’aide de Object Inspector. Le nom sera automatiquement modifié à la fois dans les fichiers d’unité de script et de formulaire de script.

Procédures et fonctions sans paramètre

Les scripts doivent être écrits de sorte que les procédures devant être invoquées pour exécuter le script n’apparaissent que dans la boîte de dialogue Select Items to Run dialog. Pour empêcher d’autres procédures/fonctions d’apparaître dans la boîte de dialogue Select Items to Run, un paramètre (Dummy : Integer) peut être inséré à côté du nom de la méthode. Voir l’exemple ci-dessous.

// 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;

Codes d’erreur DelphiScript