DelphiScript

De un vistazo

Explora la compatibilidad con DelphiScript en Altium Designer, desde sus principales diferencias con Delphi hasta los elementos del lenguaje y las convenciones de scripting que se utilizan para interactuar con Altium Designer. Esta referencia abarca la organización de los proyectos de scripts, las variables, los comentarios, el formato, las funciones y los procedimientos, con enlaces a la documentación de las API y a scripts de ejemplo. Sigue leyendo para ampliar tus conocimientos y abordar tus propios scripts de DelphiScript con mayor confianza.

- 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.
Profundiza con IA:

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:

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.

Consulte Diferencias entre DelphiScript y Delphi para obtener información detallada sobre las diferencias entre Delphi y DelphiScript.

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.

Por ejemplo, los tipos enumerados de Client para el modelo de objetos DXP se detallan en la página API del sistema.

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.

Consulte Uso de la API de Altium Designer en scripts para obtener una descripción general de cómo aprovechar la API en los scripts.

Consulte la documentación de la API de Altium Designer para obtener información más detallada.

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.

Descargue la colección de scripts de ejemplo.

A continuación se indican la ubicación y la finalidad de una selección de los scripts de ejemplo:

  • Scripts\DelphiScript Scripts\DXP carpeta: 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\Processes carpeta: muestra el uso de los procesos del servidor
  • Scripts\DelphiScript Scripts\General carpeta: muestra el uso de las palabras clave de DelphiScript
  • Scripts\DelphiScript Scripts\Sch carpeta: muestra el uso de la API de esquemáticos
  • Scripts\DelphiScript Scripts\WSM carpeta: muestra el uso de la API de Workspace Manager
Debido a las actualizaciones progresivas de la API de Altium Designer, es posible que algunos scripts de ejemplo antiguos no funcionen como se había previsto originalmente. No obstante, los scripts de ejemplo son un recurso y una referencia útiles para crear sus propios scripts.

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.
Consulte Palabras clave de DelphiScript para obtener información detallada sobre las palabras clave.

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;
  • Consulte la página Sentencias y operadores de DelphiScript para obtener información detallada sobre los operadores de expresiones de DelphiScript.
  • Consulte la página Funciones de DelphiScript para obtener información detallada sobre las funciones y rutinas de DelphiScript, como las rutinas de entrada/salida de archivos y las rutinas matemáticas.
  • Consulte la página Formularios y componentes de scripts de DelphiScript para obtener una descripción general del uso de los cuadros de diálogo de formularios y los componentes visuales de DelphiScript.

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

%s expected but %s found

Se ha utilizado una cadena incorrecta en el script.

%s or %s expected

Se ha utilizado una cadena incorrecta en el script.

Function %s is already defined

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.

Unknown identifier: %s

Identificador desconocido. Es necesario declarar este identificador antes de utilizarlo.

Unknown variable type during writing program

El script contiene un tipo de variable no válido o desconocido.

Unit %s already defined

No se permiten varias instancias de unidades con el mismo nombre. Asegúrese de que los nombres de las unidades de scripts sean únicos.

Unit declaration error

La declaración de la unidad no está definida correctamente.

Function %s not found

Falta una función en el script.

Link Error

DelphiScript no puede vincular el script con los componentes internos necesarios.

Label <%s> already defined

Existen varias instancias de la misma etiqueta en el script. Asegúrese de que las etiquetas sean únicas en el script.

Error in declaration block

El bloque de declaraciones no está definido correctamente.

Label <%s> not defined

La etiqueta Goto no está definida.

Variable <%s> already defined

Existen varias instancias de las mismas variables en el script. Asegúrese de que las variables sean únicas.

Error in variable declaration block

Existe un error en el bloque de declaración de variables. Las declaraciones son incorrectas o el sistema de scripts no las reconoce.

Variable <%s> not defined

La variable no se ha definido, por lo que el sistema de scripts no puede definirla.

Method declaration error

La firma del método no es válida.

Method parameters declaration error

Se han utilizado parámetros incorrectos para el método.

Properties are not supported

El sistema de scripts no reconoce las propiedades de un objeto.

Only class declarations allowed

Se ha intentado declarar elementos distintos de clases.

%s declaration error

Existe un error de declaración en el script.

Syntax error at Line: %d Char: %d'#13#10'%s

Se ha producido un error de sintaxis en el script
: sentencia no válida, carácter ausente o palabra clave no reconocida.

Bad identifier name <%s>

Nombre de identificador no válido, como un nombre de identificador duplicado. Redefina el nombre del identificador.

Bad identifier <%s>

Identificador no válido. Defina un nuevo identificador

Invalid function usage

La función no se ha utilizado correctamente en el script
- por ejemplo, por parámetros no válidos.

Invalid procedure usage

El procedimiento no se ha utilizado correctamente en el script
- por ejemplo, por parámetros no válidos.

Hex constant declaration error

El valor de la constante hexadecimal no se ha declarado correctamente.

Compile before run

Es necesario compilar el script antes de ejecutarlo. Error interno.

Real constant declaration error

Error en la declaración de una constante de tipo real.

String constant declaration error

Error en la declaración de una constante de tipo cadena.

Unsupported parameter type

El sistema de scripting ha informado de un tipo de parámetro desconocido.

Variable Result not found for %s

No se ha encontrado el resultado del valor de la variable para la cadena especificada en el script.

Procedure %s not found

Falta un procedimiento en el script.

Parameter %S not found

Falta un parámetro en el script.

Unknown reader type

Error interno.

Wrong number of params

La declaración y la implementación del mismo procedimiento o función son diferentes. Compruebe los parámetros de ambas.

One of the params is not a valid variant type

Uno de los parámetros de un método, función o procedimiento no tiene un tipo Variant correcto.

Property does not exist or is readonly

Se ha intentado asignar un valor a una propiedad de solo lectura o a una propiedad que no existe.

Named arguments are not supported

Los argumentos utilizados para el procedimiento o la función no son válidos para el script.

Parameter not found

Falta el valor de un parámetro.

Parameter type mismatch

Se ha utilizado un tipo de parámetro incorrecto.

Unknown interface

Esta interfaz no está declarada ni definida.

A required parameter was omitted

Falta un parámetro obligatorio para el método, la función o el procedimiento.

Unknown error

DelphiScript ha detectado un error de script desconocido que no está definido en la tabla de errores internos.

Invalid operation code

DelphiScript ha detectado un código de operación no válido.

AI-LocalizedLocalizado por IA
Si encuentra un problema, seleccione el texto/imagen y presioneCtrl + Enterpara enviarnos sus comentarios.
Nav
Contents
Disponibilidad de funciones

Las funciones disponibles para usted dependen de qué solución de Altium tenga: Altium Develop, Altium Agile Teams, Altium Agile Enterprise o Altium Designer (con suscripción activa).

Si no ve una función documentada en su software actual, contacte con Ventas de Altium para obtener más información.

Documentación heredada

La documentación de Altium Designer ya no está versionada. Si necesita acceder a la documentación de versiones anteriores de Altium Designer, visite la sección Documentación heredada de la página de Otros instaladores.

Contents