DelphiScript

Esta sección describe el lenguaje DelphiScript utilizado por el motor de scripting de Altium Designer y proporciona detalles de referencia sobre las sentencias, funciones y extensiones compatibles. Se trata de procedimientos especiales que se utilizan para controlar y comunicarse directamente con Altium Designer.

También en esta referencia:

• Diferencias entre DelphiScript y Delphi
• Palabras clave de DelphiScript
• Sentencias y operadores de DelphiScript
• Funciones de DelphiScript
• Formularios y componentes de DelphiScript

El lenguaje DelphiScript

Esta referencia de DelphiScript asume que está familiarizado con los conceptos básicos de programación, así como con el funcionamiento básico de Altium Designer. El sistema de scripting admite el lenguaje DelphiScript, que es muy similar a Embarcadero Delphi™.

La diferencia principal es que DelphiScript es un lenguaje de scripting sin tipos o no tipado, lo que significa que no puede definir registros ni clases ni pasar punteros como parámetros a funciones. Aun así, las variables pueden declararse dentro de los scripts para mejorar la legibilidad.

Esta página y sus subpáginas asociadas contienen material de referencia sobre interfaces, componentes, rutinas globales, tipos y variables que conforman el lenguaje de scripting DelphiScript.

Elementos clave de Delphiscript

Objetos

En DelphiScript, un objeto consta de métodos y, en muchos casos, propiedades y eventos. Las propiedades representan los datos contenidos en el objeto, los métodos son las acciones que el objeto puede realizar y los eventos son condiciones a las que el objeto puede responder. Todos los objetos descienden (y heredan) del objeto de nivel superior del tipo TObject.

Interfaces de objetos

Una interfaz de objeto consta de métodos y, en muchos casos, de propiedades, pero no puede tener campos de datos. Una interfaz representa un objeto existente, y cada interfaz tiene un GUID que la identifica como única. Las propiedades representan los datos contenidos en el objeto con el que la interfaz está asociada. Los métodos son las acciones que el objeto (con el que la interfaz está asociada) puede realizar.

Componentes

Los componentes son objetos visuales del panel Tool Palette que pueden manipularse en tiempo de diseño. Todos los componentes descienden de la clase del sistema TComponent en la biblioteca Visual Component Library (VCL) de Embarcadero Delphi.

Rutinas

Las rutinas globales son los procedimientos y funciones del sistema de scripting. Estas rutinas no forman parte de una clase, pero pueden llamarse directamente o desde métodos de clase dentro de un script.

Tipos

Los tipos de variable se utilizan como tipos de retorno y tipos de parámetros para métodos y propiedades de interfaces, métodos, propiedades y eventos de objetos, y rutinas globales. En muchos casos, los tipos se documentan en las secciones de tipos enumerados de la documentación de la API.

Altium Designer y la RTL de Delphi

El sistema de scripting admite un subconjunto de la biblioteca de tiempo de ejecución (RTL) de Embarcadero Delphi y la API de Altium Designer.

Archivos fuente de DelphiScript

En Altium Designer, un proyecto de script se organiza para almacenar documentos de script (unidades de script y formularios de script). Puede ejecutar el script desde un elemento de menú, un botón de barra de herramientas o desde el cuadro de diálogo Select Item To Run, disponible en el menú principal de Altium Designer.

Archivos PRJSCR, PAS y DFM

Los scripts se organizan en proyectos con una extensión *.PRJSCR. Cada proyecto consta de archivos con una extensión *.pas. Los archivos pueden ser unidades de script o formularios de script; tenga en cuenta que cada formulario tiene un archivo de script con una extensión *.pas y un archivo de formulario correspondiente con una extensión *.dfm. Un formulario de script es una ventana gráfica (cuadro de diálogo) que se ejecuta sobre Altium Designer y aloja distintos controles accesibles para el usuario.

Es posible adjuntar scripts a distintos proyectos, y se recomienda encarecidamente organizar los scripts en diferentes proyectos para gestionar la cantidad de scripts y sus procedimientos/funciones.

Scripts de ejemplo

La colección de ejemplos de scripts ilustra las funciones básicas de la programación en DelphiScript mediante scripts sencillos para usar en Altium Designer.

A continuación se indican la ubicación y el propósito de una selección de scripts de ejemplo:

• Scripts\DelphiScript Scripts\DXP carpeta - Demuestra la API de Client y del sistema
• Scripts\DelphiScript Scripts\PCCarpeta B - Demuestra la API de PCB
• Scripts\DelphiScript Scripts\Processes carpeta - Demuestra los procesos del servidor
• Scripts\DelphiScript Scripts\General carpeta - Demuestra las palabras clave de DelphiScript
• Scripts\DelphiScript Scripts\Sch carpeta - Demuestra la API de esquemáticos
• Scripts\DelphiScript Scripts\WSM carpeta - Demuestra la API de Workspace Manager

Escritura de scripts DelphiScript

Convenciones de nomenclatura de DelphiScript

En general, no hay restricciones en los nombres que se asignan a procedimientos, funciones, variables y constantes, siempre que cumplan las siguientes reglas:

• El nombre puede contener las letras A a Z, a a z, el carácter de subrayado "_" y los dígitos del 0 al 9.
• El nombre debe comenzar con una letra.
• El nombre no puede ser una palabra clave, directiva o palabra reservada de DelphiScript.
• Al interpretarse, los nombres no distinguen entre mayúsculas y minúsculas. Se pueden usar tanto mayúsculas como minúsculas al nombrar una función, subrutina, variable o constante; sin embargo, el intérprete no distinguirá entre caracteres en mayúscula y minúscula. Los nombres que sean idénticos salvo por el uso de mayúsculas o minúsculas se tratarán como el mismo nombre en DelphiScript.

En un archivo DelphiScript, las funciones y procedimientos se declaran mediante los bloques Procedure-Begin-End o Function-Begin-End. Ambos bloques de sentencias requieren que se asigne un nombre al procedimiento o la función. DelphiScript le permite crear variables y constantes con nombre para contener valores utilizados en el script actual.

Inclusión de comentarios

En un script, los comentarios son líneas de código no ejecutables que se incluyen para beneficio del programador. Los comentarios pueden incluirse prácticamente en cualquier parte de un script.

Cualquier texto que siga a // o que esté delimitado por (* *) o {} es ignorado por 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
*)

Los comentarios también pueden incluirse en la misma línea que el código ejecutado. Por ejemplo, todo lo que aparece después del punto y coma en la siguiente línea de código se trata como un comentario.

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

Variables locales y globales

Dado que todos los scripts tienen variables locales y globales, es muy importante disponer de nombres de variables únicos en los scripts dentro de un proyecto de script. Si las variables se definen outside cualquier procedimiento o función, son globales y cualquier unidad de script del mismo proyecto puede acceder a ellas.

Si las variables se definen inside de un procedimiento o función, entonces estas variables locales no son accesibles fuera de esos procedimientos/funciones.

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 de variables con nombre

En un script, se crean variables o constantes con nombre para almacenar valores que se usarán durante la ejecución del programa. Todas las variables en un script son siempre de tipo Variant. La conversión de tipos no se aplica, por lo que los tipos en las declaraciones de variables se ignoran y pueden omitirse. Por tanto, estas declaraciones son correctas:

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

División de una línea

Cada sentencia de código termina con el carácter ; punto y coma para indicar el final de la sentencia. DelphiScript le permite escribir una sentencia en varias líneas de código, dividiendo una instrucción larga en dos o más líneas. La única restricción al dividir sentencias de programación en distintas líneas es que una cadena literal no puede abarcar varias líneas.

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 no impone ningún límite práctico a la longitud de una sola línea de código en un script, pero por motivos de legibilidad y facilidad de depuración, es una buena práctica limitar la longitud de las líneas de código para que puedan leerse fácilmente en pantalla o en formato impreso.

Si una línea de código es muy larga, puede dividirla en varias líneas, y el intérprete de DelphiScript tratará este código como si estuviera escrito en una sola línea.

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;

Sensibilidad a mayúsculas y minúsculas

El lenguaje DelphiScript utilizado para escribir scripts no distingue entre mayúsculas y minúsculas; es decir, todas las palabras clave, sentencias, nombres de variables, nombres de funciones y nombres de procedimientos pueden escribirse sin tener en cuenta el uso de mayúsculas o minúsculas. Tanto los caracteres en mayúscula como en minúscula se consideran equivalentes.

Por ejemplo, el nombre de variable myVar es equivalente a myvar y MYVAR. DelphiScript trata todos estos nombres como la misma variable.

La única excepción a esto se da en las cadenas literales, como la cadena de título de una definición de cuadro de diálogo o el valor de una variable de tipo cadena. Estas cadenas conservan las diferencias entre mayúsculas y minúsculas.

El carácter de espacio

Se utiliza un espacio para separar palabras clave en una sentencia de script. Sin embargo, DelphiScript ignora cualquier espacio en blanco adicional en una sentencia.

Por ejemplo:

X   = 5
// is equivalent to
X =5

Puede usar espacios en blanco para que su script sea más legible.

Funciones y procedimientos en un script

El intérprete de DelphiScript permite dos tipos de métodos (procedimientos): procedimientos y funciones. La única diferencia entre una función y un procedimiento es que una función devuelve un valor.

Un script puede tener al menos un procedimiento que defina el código principal del programa. Sin embargo, también puede definir otros procedimientos y funciones que puedan ser llamados por su código.

Al igual que en Embarcadero Delphi, los procedimientos y funciones se definen dentro de un bloque de sentencias Begin-End. Para invocar o llamar una función o procedimiento, incluya el nombre de la función o del procedimiento en una sentencia, del mismo modo que al usar las funciones y procedimientos integrados de DelphiScript. Si la función o el procedimiento requiere parámetros, estos deben incluirse en la sentencia de llamada. Tanto las funciones como los procedimientos pueden definirse para aceptar parámetros, pero solo las funciones pueden definirse para devolver un valor a la sentencia de llamada.

Se puede asignar cualquier nombre a las funciones y procedimientos cuando se definen, siempre que cumpla las convenciones estándar de nomenclatura 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;

El nombre de una función no puede usarse para establecer su valor de retorno. En su lugar, debe usarse la palabra clave Result.

Var, Begin-End global block:

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

Consejos de scripting

Referencia a scripts en un proyecto de scripts

El código de un script puede llamar a un procedimiento en otro script dentro del mismo proyecto de scripts. Se puede acceder a cualquier variable global de cualquier script dentro del mismo proyecto.

Variables locales y globales

Dado que los scripts tienen variables locales y globales, es importante que los nombres de las variables sean únicos en los scripts de un proyecto de scripts. Si las variables se definen fuera de cualquier procedimiento o función, son globales y cualquier unidad del mismo proyecto puede acceder a ellas. Si las variables se definen dentro de un procedimiento o función, entonces estas variables locales no son accesibles fuera de esos procedimientos/funciones.

Se recomienda colocar en un proyecto scripts de naturaleza similar y mantener la cantidad de scripts del proyecto en un tamaño manejable; hacer un seguimiento de las variables globales en muchos scripts puede convertirse en un problema. No es obligatorio almacenar scripts en un proyecto de scripts, ya que también pueden incluirse en otros tipos de proyecto.

Identificadores y variables únicos

Al usar formularios de script, asegúrese de que todos los formularios de script tengan nombres de formulario únicos. Es posible tener todos los formularios de script llamados form1 (por ejemplo) en el mismo proyecto de scripts. En este caso, el sistema de scripting entra en conflicto al intentar mostrar el formulario correcto cuando se ejecuta un formulario de script.

El nombre de un formulario de script puede cambiarse usando Object Inspector. El nombre se cambiará automáticamente tanto en la unidad de script como en los archivos del formulario de script.

Procedimientos y funciones sin parámetros

Los scripts deben escribirse de forma que los procedimientos que deban invocarse para ejecutar el script sean los únicos que aparezcan en el cuadro de diálogo Select Items to Run dialog. Para evitar que otros procedimientos/funciones aparezcan en el cuadro de diálogo Select Items to Run, puede insertarse un parámetro (Dummy : Integer) junto al nombre del método. Vea el ejemplo a continuación.

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

Códigos de error de DelphiScript