DelphiScript
De un vistazo
- Comprende las variables sin tipo de DelphiScript, las reglas de nomenclatura, el ámbito y la distinción entre mayúsculas y minúsculas.
- Aprende cómo se organizan las unidades de script y los formularios dentro de los proyectos y cómo se pueden ejecutar los scripts.
- Encuentra referencias sobre las características del lenguaje admitidas, las API de Altium Designer y los scripts de ejemplo, incluidas las advertencias sobre ejemplos antiguos.
Esta sección describe el lenguaje DelphiScript utilizado por el motor de scripting de Altium Designer y proporciona información de referencia sobre las sentencias, funciones y extensiones compatibles. Se trata de procedimientos especiales que se utilizan para controlar Altium Designer y comunicarse directamente con él.
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 presupone que conoce los conceptos básicos de programación, así como 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, lo que significa que no se pueden definir registros ni clases, ni pasar punteros como parámetros a las funciones. Aun así, se pueden declarar variables dentro de los scripts para facilitar su lectura.
Esta página y sus subpáginas contienen material de referencia sobre las interfaces, los componentes, las rutinas globales, los tipos y las 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, de propiedades y eventos. Las propiedades representan los datos que contiene el objeto, los métodos son las acciones que puede realizar el objeto y los eventos son las condiciones a las que puede reaccionar. Todos los objetos descienden del objeto de nivel superior del tipo TObject y heredan de él.
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 de forma única. Las propiedades representan los datos contenidos en el objeto al que está asociada la interfaz. Los métodos son las acciones que puede realizar el objeto al que está asociada la interfaz.
Componentes
Los componentes son objetos visuales del panel Paleta de herramientas que pueden manipularse durante el diseño. Todos los componentes descienden de la clase del sistema TComponent de la biblioteca de componentes visuales (VCL) de Embarcadero Delphi.
Rutinas
Las rutinas globales son los procedimientos y las funciones del sistema de scripting. Estas rutinas no forman parte de una clase, pero pueden llamarse directamente o desde los métodos de una clase en un script.
Tipos
Los tipos de variables se utilizan como tipos de retorno y de parámetros para los métodos y las propiedades de las interfaces, los métodos, las propiedades y los eventos de los objetos, y las 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 de la API de Altium Designer.
Archivos fuente de DelphiScript
En Altium Designer, un proyecto de scripts se organiza para almacenar documentos de script (unidades y formularios de script). Puede ejecutar el script desde un elemento de menú, un botón de la barra de herramientas o el cuadro de diálogo Seleccionar elemento para ejecutar, disponible en el menú principal de Altium Designer.
Archivos PRJSCR, PAS y DFM
Los scripts se organizan en proyectos con la extensión *.PRJSCR. Cada proyecto consta de archivos con la extensión *.pas. Los archivos pueden ser unidades o formularios de script; tenga en cuenta que cada formulario tiene un archivo de script con la extensión *.pas y un archivo de formulario correspondiente con la extensión *.dfm. Un formulario de script es una ventana gráfica (cuadro de diálogo) que se ejecuta sobre Altium Designer y contiene distintos controles accesibles para el usuario.
Es posible asociar scripts a distintos proyectos, y se recomienda encarecidamente organizarlos en diferentes proyectos para gestionar la cantidad de scripts y sus procedimientos y funciones.
Scripts de ejemplo
La colección de scripts de ejemplo ilustra las características básicas de la programación en DelphiScript mediante scripts sencillos para su uso en Altium Designer.
A continuación se indican la ubicación y la finalidad de una selección de los scripts de ejemplo:
-
Scripts\DelphiScript Scripts\DXPcarpeta: muestra el uso de la API de Client y del sistema -
Scripts\DelphiScript Scripts\PCB carpeta: muestra el uso de la API de PCB -
Scripts\DelphiScript Scripts\Processescarpeta: muestra el uso de los procesos del servidor -
Scripts\DelphiScript Scripts\Generalcarpeta: muestra el uso de las palabras clave de DelphiScript -
Scripts\DelphiScript Scripts\Schcarpeta: muestra el uso de la API de esquemáticos -
Scripts\DelphiScript Scripts\WSMcarpeta: muestra el uso de la API de Workspace Manager
Escritura de scripts en DelphiScript
Convenciones de nomenclatura de DelphiScript
En general, no hay restricciones para los nombres que se asignan a procedimientos, funciones, variables y constantes, siempre que cumplan las siguientes reglas:
- El nombre puede contener las letras de la A a la Z y de la a a la z, el carácter de guion bajo "_" y los dígitos del 0 al 9.
- El nombre debe comenzar por una letra.
- El nombre no puede ser una palabra clave, una directiva ni una palabra reservada de DelphiScript.
- Al interpretar los nombres, no se distingue entre mayúsculas y minúsculas. Se pueden utilizar tanto mayúsculas como minúsculas al asignar un nombre a una función, subrutina, variable o constante; sin embargo, el intérprete no distinguirá entre ellas. Los nombres que sean idénticos salvo por el uso de mayúsculas y minúsculas se tratarán como el mismo nombre en DelphiScript.
En un archivo DelphiScript, las funciones y los 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 a la función. DelphiScript permite crear variables y constantes con nombre para almacenar los 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 ayudar al programador. Los comentarios pueden incluirse prácticamente en cualquier lugar de un script.
DelphiScript ignora cualquier texto que siga a // o que esté delimitado por (* *) o {}.
//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
*)
También pueden incluirse comentarios 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 que los nombres de las variables sean únicos en los scripts de un mismo proyecto de scripts. Si las variables se definen outside de cualquier procedimiento y función, son globales y se puede acceder a ellas desde cualquier unidad de script del mismo proyecto.
Si las variables se definen inside de un procedimiento o una función, estas variables locales no son accesibles fuera de dichos procedimientos o 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 utilizarán durante la ejecución del programa. Todas las variables de un script son siempre de tipo Variant. La conversión de tipos no se aplica, por lo que los tipos de las declaraciones de variables se ignoran y pueden omitirse. Por lo 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 de punto y coma ; para indicar el final de la sentencia. DelphiScript 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 un literal de cadena 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 línea de código de un script, pero, para facilitar la lectura y la depuración, se recomienda limitar la longitud de las líneas de código de modo 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;
Distinción entre 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, funciones y procedimientos pueden escribirse indistintamente con letras mayúsculas o minúsculas. Los caracteres en mayúsculas y minúsculas 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 son las cadenas literales, como la cadena del título de la definición de un cuadro de diálogo o el valor de una variable de cadena. Estas cadenas conservan las diferencias entre mayúsculas y minúsculas.
El carácter de espacio
El espacio se utiliza para separar palabras clave en una sentencia del script. Sin embargo, DelphiScript ignora los espacios en blanco adicionales de una sentencia.
Por ejemplo:
X = 5
// is equivalent to
X =5
Puede utilizar espacios en blanco para facilitar la lectura del script.
Funciones y procedimientos en un script
El intérprete de DelphiScript permite dos clases de métodos (procedimientos): procedimientos y funciones. La única diferencia entre una función y un procedimiento es que la función devuelve un valor.
Un script puede tener al menos un procedimiento que defina el código del programa principal. No obstante, puede definir otros procedimientos y funciones a los que se pueda llamar desde el código.
Al igual que en Embarcadero Delphi, los procedimientos y las funciones se definen dentro de un bloque de sentencias Begin-End. Para invocar o llamar a una función o un procedimiento, incluya su nombre en una sentencia del mismo modo que al utilizar las funciones y los 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 los procedimientos al definirlos, siempre que cumpla las convenciones de nomenclatura estándar 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;
No se puede utilizar el nombre de una función para establecer su valor de retorno. En su lugar, debe utilizarse 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 para la creación de scripts
Referencias a scripts en un proyecto de scripts
El código de un script puede llamar a un procedimiento de otro script 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 una función, estas variables locales no son accesibles desde fuera de dichos procedimientos o funciones.
Se recomienda agrupar los scripts de naturaleza similar en un proyecto y mantener una cantidad manejable de scripts por proyecto, ya que llevar un seguimiento de las variables globales en muchos scripts puede resultar problemático. No es obligatorio almacenar los scripts en un proyecto de scripts, ya que pueden incluirse en otros tipos de proyectos.
Identificadores y variables únicos
Al utilizar formularios de scripts, asegúrese de que todos tengan nombres únicos. Es posible que todos los formularios de scripts se llamen form1 (por ejemplo) en el mismo proyecto de scripts. En ese caso, se produce un conflicto en el sistema de scripts al intentar mostrar el formulario correcto cuando se ejecuta un formulario de script.
El nombre de un formulario de script puede cambiarse mediante Object Inspector. El nombre se cambiará automáticamente tanto en el archivo de la unidad del script como en el del formulario del script.
Procedimientos y funciones sin parámetros
Los scripts deben escribirse de modo que solo los procedimientos que deban invocarse para ejecutar el script aparezcan en el cuadro de diálogo Seleccionar elementos para ejecutar. Para evitar que otros procedimientos o funciones aparezcan en el cuadro de diálogo Select Items to Run, se puede insertar un parámetro (Dummy : Integer) junto al nombre del método. Consulte el ejemplo siguiente.
// 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
Error |
Description |
|---|---|
|
Se ha utilizado una cadena incorrecta en el script. |
|
Se ha utilizado una cadena incorrecta en el script. |
|
No se permiten varias instancias de funciones con el mismo nombre en el código. Cambie el nombre de las otras funciones que tengan el mismo nombre. |
|
Identificador desconocido. Es necesario declarar este identificador antes de utilizarlo. |
|
El script contiene un tipo de variable no válido o desconocido. |
|
No se permiten varias instancias de unidades con el mismo nombre. Asegúrese de que los nombres de las unidades de scripts sean únicos. |
|
La declaración de la unidad no está definida correctamente. |
|
Falta una función en el script. |
|
DelphiScript no puede vincular el script con los componentes internos necesarios. |
|
Existen varias instancias de la misma etiqueta en el script. Asegúrese de que las etiquetas sean únicas en el script. |
|
El bloque de declaraciones no está definido correctamente. |
|
La etiqueta Goto no está definida. |
|
Existen varias instancias de las mismas variables en el script. Asegúrese de que las variables sean únicas. |
|
Existe un error en el bloque de declaración de variables. Las declaraciones son incorrectas o el sistema de scripts no las reconoce. |
|
La variable no se ha definido, por lo que el sistema de scripts no puede definirla. |
|
La firma del método no es válida. |
|
Se han utilizado parámetros incorrectos para el método. |
|
El sistema de scripts no reconoce las propiedades de un objeto. |
|
Se ha intentado declarar elementos distintos de clases. |
|
Existe un error de declaración en el script. |
|
Se ha producido un error de sintaxis en el script |
|
Nombre de identificador no válido, como un nombre de identificador duplicado. Redefina el nombre del identificador. |
|
Identificador no válido. Defina un nuevo identificador |
|
La función no se ha utilizado correctamente en el script |
|
El procedimiento no se ha utilizado correctamente en el script |
|
El valor de la constante hexadecimal no se ha declarado correctamente. |
|
Es necesario compilar el script antes de ejecutarlo. Error interno. |
|
Error en la declaración de una constante de tipo real. |
|
Error en la declaración de una constante de tipo cadena. |
|
El sistema de scripting ha informado de un tipo de parámetro desconocido. |
|
No se ha encontrado el resultado del valor de la variable para la cadena especificada en el script. |
|
Falta un procedimiento en el script. |
|
Falta un parámetro en el script. |
|
Error interno. |
|
La declaración y la implementación del mismo procedimiento o función son diferentes. Compruebe los parámetros de ambas. |
|
Uno de los parámetros de un método, función o procedimiento no tiene un tipo Variant correcto. |
|
Se ha intentado asignar un valor a una propiedad de solo lectura o a una propiedad que no existe. |
|
Los argumentos utilizados para el procedimiento o la función no son válidos para el script. |
|
Falta el valor de un parámetro. |
|
Se ha utilizado un tipo de parámetro incorrecto. |
|
Esta interfaz no está declarada ni definida. |
|
Falta un parámetro obligatorio para el método, la función o el procedimiento. |
|
DelphiScript ha detectado un error de script desconocido que no está definido en la tabla de errores internos. |
|
DelphiScript ha detectado un código de operación no válido. |