DelphiScript

Questa sezione descrive il linguaggio DelphiScript utilizzato dal motore di scripting di Altium Designer e fornisce dettagli di riferimento sulle istruzioni, funzioni ed estensioni supportate. Si tratta di procedure speciali utilizzate per controllare e comunicare direttamente con Altium Designer.

Inoltre, in questo riferimento:

• Differenze tra DelphiScript e Delphi
• Parole chiave di DelphiScript
• Istruzioni e operatori di DelphiScript
• Funzioni di DelphiScript
• Form e componenti di DelphiScript

Il linguaggio DelphiScript

Questo riferimento su DelphiScript presuppone che tu abbia familiarità con i concetti base della programmazione, nonché con il funzionamento di base di Altium Designer. Il sistema di scripting supporta il linguaggio DelphiScript, che è molto simile a Embarcadero Delphi™.

La differenza principale è che DelphiScript è un linguaggio di scripting senza tipi o non tipizzato, il che significa che non è possibile definire record o classi né passare puntatori come parametri alle funzioni. Le variabili possono comunque essere dichiarate negli script per migliorarne la leggibilità.

Questa pagina e le relative sottopagine contengono materiale di riferimento su interfacce, componenti, routine globali, tipi e variabili che costituiscono il linguaggio di scripting DelphiScript.

Elementi chiave di Delphiscript

Oggetti

In DelphiScript, un oggetto è costituito da metodi e, in molti casi, proprietà ed eventi. Le proprietà rappresentano i dati contenuti nell'oggetto, i metodi sono le azioni che l'oggetto può eseguire e gli eventi sono condizioni alle quali l'oggetto può reagire. Tutti gli oggetti derivano (ed ereditano) dall'oggetto di livello superiore di tipo TObject.

Interfacce oggetto

Un'interfaccia oggetto è costituita da metodi e, in molti casi, proprietà, ma non può avere campi dati. Un'interfaccia rappresenta un oggetto esistente e ogni interfaccia ha un GUID che la identifica in modo univoco. Le proprietà rappresentano i dati contenuti nell'oggetto a cui l'interfaccia è associata. I metodi sono le azioni che l'oggetto (a cui l'interfaccia è associata) può eseguire.

Componenti

I componenti sono oggetti visivi del pannello Tool Palette che possono essere manipolati in fase di progettazione. Tutti i componenti derivano dalla classe di sistema TComponent nella Visual Component Library (VCL) di Embarcadero Delphi.

Routine

Le routine globali sono le procedure e le funzioni del sistema di scripting. Queste routine non fanno parte di una classe, ma possono essere chiamate direttamente oppure dall'interno dei metodi di classe in uno script.

Tipi

I tipi di variabile vengono utilizzati come tipi di ritorno e tipi di parametro per metodi e proprietà delle interfacce, metodi, proprietà ed eventi degli oggetti e routine globali. In molti casi, i tipi sono documentati nelle sezioni dedicate ai tipi enumerati nella documentazione API.

Altium Designer e la RTL di Delphi

Il sistema di scripting supporta un sottoinsieme della Run Time Library (RTL) di Embarcadero Delphi e dell'API di Altium Designer.

File sorgente DelphiScript

In Altium Designer, un progetto di script è organizzato per archiviare documenti di script (Unit di script e Form di script). È possibile eseguire lo script da una voce di menu, da un pulsante della barra degli strumenti oppure dalla finestra di dialogo Select Item To Run disponibile nel menu principale di Altium Designer.

File PRJSCR, PAS e DFM

Gli script sono organizzati in progetti con estensione *.PRJSCR. Ogni progetto è costituito da file con estensione *.pas. I file possono essere Unit di script oppure Form di script — nota che ogni Form ha un file di script con estensione *.pas e un file Form corrispondente con estensione *.dfm. Una Form di script è una finestra grafica (finestra di dialogo) che viene eseguita sopra Altium Designer e ospita diversi controlli accessibili all'utente.

È possibile collegare script a progetti diversi ed è fortemente consigliato organizzare gli script in progetti differenti per gestire il numero di script e le relative procedure/funzioni.

Script di esempio

La raccolta di script di esempio illustra le funzionalità di base della programmazione DelphiScript utilizzando script semplici da usare in Altium Designer.

Di seguito sono elencati la posizione e lo scopo di una selezione degli script di esempio:

• Scripts\DelphiScript Scripts\DXP cartella - Dimostra l'API Client e di sistema
• Scripts\DelphiScript Scripts\PCCartella B - Dimostra l'API PCB
• Scripts\DelphiScript Scripts\Processes cartella - Dimostra i processi del server
• Scripts\DelphiScript Scripts\General cartella - Dimostra le parole chiave di DelphiScript
• Scripts\DelphiScript Scripts\Sch cartella - Dimostra l'API Schematic
• Scripts\DelphiScript Scripts\WSM cartella - Dimostra l'API Workspace Manager

Scrittura di script DelphiScript

Convenzioni di denominazione DelphiScript

In generale, non ci sono restrizioni sui nomi assegnati a procedure, funzioni, variabili e costanti, purché rispettino le seguenti regole:

• Il nome può contenere le lettere da A a Z, da a a z, il carattere di sottolineatura "_" e le cifre da 0 a 9.
• Il nome deve iniziare con una lettera.
• Il nome non può essere una parola chiave, una direttiva o una parola riservata di DelphiScript.
• I nomi non sono sensibili alle maiuscole/minuscole durante l'interpretazione. È possibile usare sia maiuscole sia minuscole quando si assegna un nome a una funzione, sottoprocedura, variabile o costante; tuttavia, l'interprete non distinguerà tra caratteri maiuscoli e minuscoli. I nomi identici che differiscono solo per l'uso delle maiuscole/minuscole saranno trattati come lo stesso nome in DelphiScript.

In un file DelphiScript, le funzioni e le procedure vengono dichiarate utilizzando i blocchi Procedure-Begin-End o Function-Begin-End. Entrambi questi blocchi di istruzioni richiedono che venga assegnato un nome alla procedura o alla funzione. DelphiScript consente di creare variabili e costanti con nome per contenere i valori utilizzati nello script corrente.

Inclusione di commenti

In uno script, i commenti sono righe di codice non eseguibili incluse a beneficio del programmatore. I commenti possono essere inseriti praticamente ovunque in uno script.

Qualsiasi testo che segue // o racchiuso tra (* *) o {} viene ignorato da 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
*)

I commenti possono anche essere inclusi sulla stessa riga del codice eseguito. Ad esempio, tutto ciò che segue il punto e virgola nella seguente riga di codice viene trattato come commento.

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

Variabili locali e globali

Poiché tutti gli script hanno variabili locali e globali, è molto importante avere nomi di variabili univoci negli script all'interno di un progetto di script. Se le variabili sono definite outside qualsiasi procedura e funzione, sono globali e possono essere accessibili da qualsiasi unità di script nello stesso progetto.

Se le variabili sono definite inside una procedura o funzione, allora queste variabili locali non sono accessibili al di fuori di tali procedure/funzioni.

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

Uso di variabili con nome

In uno script, vengono create variabili o costanti con nome per memorizzare valori da utilizzare durante l'esecuzione del programma. Tutte le variabili in uno script sono sempre di tipo Variant. Il typecasting non si applica, quindi i tipi nelle dichiarazioni di variabile vengono ignorati e possono essere omessi. Queste dichiarazioni sono quindi corrette:

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

Suddivisione di una riga

Ogni istruzione di codice termina con il carattere ; punto e virgola per indicare la fine dell'istruzione. DelphiScript consente di scrivere un'istruzione su più righe di codice, suddividendo un'istruzione lunga in due o più righe. L'unica restrizione nella suddivisione delle istruzioni di programmazione su righe diverse è che una stringa letterale non può estendersi su più righe.

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 non impone alcun limite pratico alla lunghezza di una singola riga di codice in uno script, ma per motivi di leggibilità e facilità di debug è buona pratica limitare la lunghezza delle righe di codice in modo che possano essere lette facilmente sullo schermo o in forma stampata.

Se una riga di codice è molto lunga, puoi suddividerla in più righe e questo codice verrà trattato dall'interprete DelphiScript come se fosse stato scritto su una singola riga.

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à alle maiuscole/minuscole

Il linguaggio DelphiScript utilizzato per scrivere script non è sensibile alle maiuscole/minuscole, vale a dire che tutte le parole chiave, istruzioni, nomi di variabili, nomi di funzioni e procedure possono essere scritti senza tenere conto dell'uso di lettere maiuscole o minuscole. I caratteri maiuscoli e minuscoli sono considerati equivalenti.

Ad esempio, il nome della variabile myVar è equivalente a myvar e MYVAR. DelphiScript tratta tutti questi nomi come la stessa variabile.

L'unica eccezione riguarda le stringhe letterali, come la stringa del titolo di una definizione di finestra di dialogo o il valore di una variabile stringa. Queste stringhe mantengono le differenze tra maiuscole e minuscole.

Il carattere spazio

Uno spazio viene utilizzato per separare le parole chiave in un'istruzione di script. Tuttavia, DelphiScript ignora eventuali spazi bianchi aggiuntivi in un'istruzione.

Ad esempio:

X   = 5
// is equivalent to
X =5

Puoi usare gli spazi bianchi per rendere il tuo script più leggibile.

Funzioni e procedure in uno script

L'interprete DelphiScript consente due tipi di metodi (procedure): procedure e funzioni. L'unica differenza tra una funzione e una procedura è che una funzione restituisce un valore.

Uno script può avere almeno una procedura che definisce il codice principale del programma. Puoi comunque definire altre procedure e funzioni che possono essere chiamate dal tuo codice.

Come in Embarcadero Delphi, procedure e funzioni sono definite all'interno di un blocco di istruzioni Begin-End. Per richiamare o chiamare una funzione o procedura, includi il nome della funzione o della procedura in un'istruzione nello stesso modo in cui si usano le funzioni e le procedure integrate di DelphiScript. Se la funzione o la procedura richiede parametri, questi devono essere inclusi nell'istruzione di chiamata. Sia le funzioni sia le procedure possono essere definite per accettare parametri, ma solo le funzioni possono essere definite per restituire un valore all'istruzione chiamante.

È possibile assegnare qualsiasi nome a funzioni e procedure quando vengono definite, purché sia conforme alle convenzioni standard di denominazione di 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;

Il nome di una funzione non può essere usato per impostarne il valore di ritorno. Deve invece essere usata la parola chiave Result.

Var, Begin-End global block:

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

Suggerimenti per lo scripting

Riferimento agli script in un progetto di script

Il codice in uno script può chiamare una procedura in un altro script dello stesso progetto di script. Qualsiasi variabile globale in qualunque script può essere accessibile all'interno dello stesso progetto.

Variabili locali e globali

Poiché gli script hanno variabili locali e globali, è importante usare nomi di variabili univoci negli script all'interno di un progetto di script. Se le variabili sono definite al di fuori di qualsiasi procedura o funzione, sono globali e possono essere accessibili da qualsiasi unità nello stesso progetto. Se le variabili sono definite all'interno di una procedura o funzione, allora queste variabili locali non sono accessibili al di fuori di tali procedure/funzioni.

Si consiglia di inserire in un progetto script di natura simile e di mantenere il numero di script in un progetto a una dimensione gestibile: tenere traccia delle variabili globali in molti script può diventare problematico. Non è obbligatorio archiviare gli script in un progetto di script, poiché gli script possono essere inseriti in altri tipi di progetto.

Identificatori univoci e variabili

Quando si usano i form di script, assicurarsi che tutti i form di script abbiano nomi di form univoci. È possibile avere tutti i form di script denominati form1 (ad esempio) nello stesso progetto di script. In questo caso, il sistema di scripting entra in conflitto quando tenta di visualizzare il form corretto durante l'esecuzione di un form di script.

Il nome di un form di script può essere modificato usando Object Inspector. Il nome verrà modificato automaticamente sia nei file dell'unità di script sia nei file del form di script.

Procedure e funzioni senza parametri

Gli script devono essere scritti in modo che le procedure richieste da richiamare per eseguire lo script compaiano solo nella finestra di dialogo Select Items to Run dialog. Per evitare che altre procedure/funzioni compaiano nella finestra di dialogo Select Items to Run, è possibile inserire un parametro (Dummy : Integer) accanto al nome del metodo. Vedere l'esempio seguente.

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

Codici di errore DelphiScript