Escribir scripts

De un vistazo

Empieza a escribir scripts en Altium Designer con un sencillo ejemplo «Hola, mundo» en DelphiScript y, después, descubre cómo crear un formulario de script con controles interactivos. Este artículo presenta los términos esenciales de la programación de scripts, explica cómo ejecutar y detener scripts y muestra cómo los paneles Object Inspector y Tool Palette facilitan la configuración de formularios y la gestión de eventos. Sigue leyendo para dar tus primeros pasos en la creación y ejecución de tus propios scripts.

- Aprende los conceptos fundamentales de la programación de scripts, incluidos los procesos, los componentes, las interfaces de objetos, las propiedades, los métodos y los eventos.
- Descubre cómo crear y ejecutar un procedimiento básico en DelphiScript y definir un procedimiento de inicio del proyecto.
- Explora cómo crear formularios de script, añadir botones y configurar las propiedades de los componentes y los controladores de eventos.
Profundiza con IA:
 

Escritura de scripts

Existen varios conceptos y términos esenciales que se aplican a la escritura de scripts:

  • Los procesos son cadenas de comandos que puede utilizar para ejecutar comandos en scripts.
  • Los componentes son objetos de control visual del panel Tool Palette que puede arrastrar y soltar en un formulario de script para manipular el diseño.
  • Un componente colocado en un formulario de script tiene métodos, propiedades y eventos.
  • Las interfaces de objetos son interfaces especiales que puede utilizar para extraer y modificar datos de los documentos de diseño desde sus scripts.

Lenguajes de scripting

El lenguaje de scripting predeterminado es DelphiScript (*.pas). El propio motor de scripting está escrito en Embarcadero Delphi, y el panel Tool Palette se basa en la VCL (biblioteca de componentes visuales) de Delphi.

  • Puede abrir y ejecutar scripts existentes escritos en VBScript y JavaScript (Jscript). Para poder crear nuevos scripts escritos en VBScript, debe habilitar la opción Legacy.Scripts.SupportOldLanguages en el cuadro de diálogo Advanced Settings.

  • La documentación de la API de scripting se encuentra aquí: Objetos de la API de scripting. Tenga en cuenta que esta documentación se actualizó por última vez para una versión anterior de Altium Designer. Aunque muchos de los principios y enfoques seguirán siendo los mismos, tenga presente que las interfaces, los objetos, los métodos, las propiedades y otros elementos habrán cambiado desde entonces y no reflejarán la totalidad de los que se encuentran en versiones posteriores del software.

Una unidad de DelphiScript

Puede realizar un ejercicio de scripting rápido y básico creando primero un proyecto y un archivo de script nuevos. Suponiendo que el proyecto y el archivo de script estén configurados con el lenguaje DelphiScript, puede introducir un sencillo script «Hello World» como se muestra a continuación.

Procedure ShowAMessage;
Var
 DefaultMessage;
Begin
 DefaultMessage := 'Hello World!';
 ShowMessage(DefaultMessage);
End;
Cuando se edita un documento, aparece un asterisco junto al documento de script y el icono del panel Projects cambia a rojo. Cuando se edita una línea de código del script, aparece un bloque rojo en el margen izquierdo de la línea para indicar que se ha modificado.

Dentro del procedimiento, hay una función ShowMessage estándar de DelphiScript que abre un cuadro de diálogo con el mensaje «Hello World», tal como se define en la variable DefaultMessage.

Dado que todas las variables de los scripts son de tipo variant, no es necesario definir el tipo de la variable DefaultMessage en el script.

Ejecución del script

Para ejecutar uno de los scripts, seleccione File » Run Script en los menús principales y, a continuación, elija un procedimiento de script disponible en el cuadro de diálogo Select Item To Run. Al ejecutar una versión, se abrirá un cuadro de diálogo para mostrar el mensaje.

Ejecución de una unidad de script HelloWorld sencilla desde el menú File » Run Script.
Ejecución de una unidad de script HelloWorld sencilla desde el menú File » Run Script.

Este script tiene un procedimiento sin parámetros. Solo los procedimientos o funciones que don't tienen parámetros aparecen en el cuadro de diálogo Select Item To Run. Los procedimientos que requieren que se les pasen parámetros se llaman desde el propio script (o desde otro script), pero no desde un sistema externo, como el cuadro de diálogo Select Item To Run, donde no se pasan parámetros.

También puede ejecutar un script mediante el comando Run del editor, al que se accede con el botón Run (), con el atajo de teclado F9 o seleccionando Run » Run en los menús principales.

Además del propio comando Run, el menú desplegable Run  ofrece diversos comandos de control y depuración de scripts.Además del propio comando Run, el menú desplegable Run ofrece diversos comandos de control y depuración de scripts.

Al seleccionar el comando Run por primera vez, se abrirá el cuadro de diálogo Select Item to Run, que le permitirá especificar el procedimiento principal de un script (ShowAMessage en este caso). Una vez configurado, resulta fácil ejecutar el script repetidamente desde el editor mediante el comando Run . Utilice Run » Set Project Startup Procedure para cambiar la configuración a otro procedimiento, o cierre y vuelva a abrir el proyecto de script para borrar la configuración.

Para detener un script en ejecución, utilice el botón Stop (), seleccione Run » Stop en el menú principal o utilice el atajo de teclado Ctrl+F3.

Un formulario de DelphiScript

A partir del proyecto HelloWorld creado anteriormente, puede crear un script similar utilizando una unidad de formulario.

Un formulario de script es una ventana de diálogo que puede alojar diversos controles, como botones, campos de texto multilínea y cuadros de lista. Tiene controladores de eventos que responden cuando un control genera un evento, por ejemplo, al hacer clic en un botón.

Para crear el nuevo formulario de script, haga clic con el botón derecho en el nombre del proyecto en el panel Projects, elija la opción Add New to Project y seleccione Script Form. Puede guardar el script y cambiarle el nombre mediante File » Save As en los menús principales.

Una vez creado un nuevo proyecto de script, añada un nuevo script al proyecto. Una vez creado un nuevo proyecto de script, añada un nuevo script al proyecto.

El formulario de script crea dos archivos: un archivo *.dfm que define los elementos y los identificadores de la ventana del formulario, y un archivo *.pas que contiene los controladores de eventos y los procedimientos o funciones del formulario.

Para ver y editar los valores de las propiedades del formulario que tiene el foco o de sus componentes, abra el panel Object Inspector. El panel Object Inspector se utiliza para cambiar las propiedades del formulario e insertar código en los controladores de eventos asociados al formulario actual.

La configuración y las propiedades de la ventana del formulario de script se muestran en el panel Object Inspector.
La configuración y las propiedades de la ventana del formulario de script se muestran en el panel Object Inspector.

Tenga en cuenta que el formulario de script ofrece dos pestañas en la parte inferior del documento: las pestañas Code y Form .

La pestaña Code contiene los controladores de eventos y los procedimientos, como se muestra arriba, mientras que la pestaña Form representa el cuadro de diálogo e incluye controles y sus controladores de eventos asociados. Utilice las pestañas o el atajo de teclado F12 para alternar entre ambas.

Los términos «cuadro de diálogo» y «formulario de script» son equivalentes a efectos descriptivos en esta guía. El término «formulario» se refiere a la ventana que se está diseñando en tiempo real en el sistema de scripting, y un «cuadro de diálogo» es un formulario activo en el software que espera una respuesta del usuario y realiza una acción cuando se hace clic en un botón o control del cuadro de diálogo.

El panel Object Inspector le permite consultar y editar las propiedades y los eventos de los componentes del formulario de script activo. Al hacer clic en un componente del formulario de script activo en la ventana del editor de diseño, se seleccionará el componente y se mostrarán sus atributos asociados en el panel Object Inspector. También puede utilizar el campo desplegable de la parte superior del panel para elegir entre una lista de todos los componentes colocados actualmente en el formulario activo. El propio formulario también se incluye.

Utilice el panel Object Inspector para configurar el cuadro de diálogo del formulario y su acción. 
Utilice el panel Object Inspector para configurar el cuadro de diálogo del formulario y su acción.

La información se muestra en dos pestañas: Properties y Events:

  • La pestaña Properties del panel enumera todos los atributos de las propiedades del componente seleccionado. La lista exacta de atributos disponibles dependerá del tipo concreto de componente que se esté inspeccionando. Una propiedad es una característica de un objeto que influye en su comportamiento visible o en sus operaciones. Por ejemplo, la propiedad Visible (en Behavior subcategoría) determina si el objeto se muestra o no en el formulario de script en el que se coloca. Las propiedades de un componente se pueden modificar según sea necesario. Haga clic en el campo situado a la derecha de una propiedad y escriba directamente, marque o desmarque una casilla de verificación o seleccione una entrada de una lista desplegable, según corresponda.
  • La pestaña Events del panel proporciona una lista de todos los eventos a los que puede responder el componente seleccionado actualmente. Una vez más, la lista exacta de eventos disponibles dependerá del tipo concreto de componente que se esté examinando. Cuando se produce un evento, como hacer clic en un botón de un formulario, el script ejecutará la acción correspondiente, siempre que se haya definido en el código un procedimiento para gestionar dicho evento. Este tipo de procedimiento se denomina controlador de eventos.

La estructura básica de un controlador de eventos se puede añadir al código del documento de script desde el panel Object Inspector. Simplemente seleccione el componente para el que desea definir un evento, elija el tipo de evento concreto y, a continuación, haga doble clic en el campo situado a la derecha del evento. Se crea un nombre para el evento que se utiliza para definir el nombre del procedimiento de gestión de eventos: FormName.EventName. A continuación, el código base del procedimiento de gestión de eventos se añade al código principal del script, cuya pestaña se activa en el espacio de diseño. Después se puede programar el contenido del procedimiento de gestión de eventos para proporcionar la respuesta deseada cuando se produzca el evento y el script en ejecución lo detecte.

La sección inferior del panel proporciona una descripción resumida de la propiedad o del evento seleccionado actualmente, cuando está disponible.

Se pueden seleccionar y editar varios componentes simultáneamente. En el panel se mostrarán las propiedades y los eventos comunes a todos los componentes de la selección. Las propiedades y los eventos que tengan valores distintos entre los componentes se mostrarán en blanco. Simplemente edite las propiedades o los eventos según sea necesario: los cambios realizados se aplicarán al instante a cada componente de la selección. Por ejemplo, puede que desee cambiar el texto de varios botones a una fuente concreta. Seleccione todos los botones y cambie las propiedades de la categoría Font según sea necesario: todos los botones se actualizarán para mostrar su texto con la misma fuente.

Para este script de formulario, cambie las propiedades Caption del formulario en el panel Object Inspector de HelloWorldForm a Hello World!. Estas cadenas coinciden con las utilizadas en el código de ejemplo del controlador de eventos y del procedimiento que se muestra más abajo.

Para obtener información más detallada sobre los componentes y sus propiedades, métodos y eventos, consulte la página Categorías de componentes.

Añadir y configurar controles

Una vez configurado el formulario básico, se pueden añadir controles al cuadro de diálogo según sea necesario desde el panel Tool Palette. El Tool Palette, basado en la biblioteca de componentes visuales de Delphi, es una paleta de componentes que ofrece una amplia gama de controles de ventana organizados en categorías de componentes (consulte las páginas Componentes gráficos para scripts y  Categorías de componentes para obtener más información).

Las secciones del panel Tool Palette se pueden expandir y contraer mediante las pestañas de encabezado de las regiones.
Las secciones del panel Tool Palette se pueden expandir y contraer mediante las pestañas de encabezado de las regiones.

Utilice los controles de la parte superior del panel, los nombres de las categorías y el menú contextual para configurar la presentación de los controles en el panel: expandir o contraer categorías, cambiar la presentación de los elementos de la paleta, etc.

Todos los componentes utilizados en el panel derivan de TComponent de la biblioteca de componentes visuales de Borland Delphi.

En la versión con cuadro de diálogo del proyecto «Hola mundo», hay dos botones en el formulario: Display y Close. Haga clic en TButton en la región Standard del panel Tool Palette.

Hágalo dos veces para colocar dos botones en el formulario. Un botón se utilizará para mostrar el mensaje «¡Hola mundo!» en un cuadro de diálogo independiente y el segundo se utilizará para cerrar el cuadro de diálogo principal.

Los componentes se pueden colocar en un formulario de script haciendo doble clic en el componente en el panel Tool Palette, o haciendo clic una vez en el componente y luego en el lugar del formulario donde desee que aparezca.

Todos los componentes del panel tienen propiedades, métodos y eventos asociados, donde:

  • Una Property es una característica de un objeto que influye en su comportamiento visible o en sus operaciones. Por ejemplo, la propiedad Visible determina si un objeto puede verse en un formulario de script.
  • Un Method es un procedimiento que siempre está asociado a un objeto y define su comportamiento.
  • Un Event es una acción o un suceso detectado por el script. En un script, el programador escribe código para cada controlador de eventos, diseñado para capturar un evento específico, como un clic del ratón.

Las propiedades y los eventos de un componente se pueden consultar y modificar después de colocarlo mediante el panel Object Inspector.

Mediante el panel Object Inspector, se pueden cambiar los nombres y los textos predeterminados de los dos botones.

Configure el nombre del primer botón como bDisplay y su texto como Display. Configure el nombre del segundo botón como bClose y su texto como Close. Esto permite que coincidan con el código de ejemplo del controlador de eventos que se presenta a continuación.

Seleccione un componente y edite sus propiedades en el panel Object Inspector.
Seleccione un componente y edite sus propiedades en el panel Object Inspector.

El cuadro de comentarios situado en la parte inferior del panel Object Inspector proporciona una descripción de la propiedad resaltada.

El código del controlador de eventos se puede crear haciendo referencia directamente a los controles del formulario. En este ejemplo, el botón Display abrirá un cuadro de diálogo ShowMessage sobre el formulario existente y la acción del botón Close cerrará este formulario.

Código del controlador de eventos

Al hacer doble clic en el botón Display, se abrirá el formulario en la vista Código y se creará el código base de su controlador de eventos. Como alternativa, seleccione el botón y luego la pestaña Events en el panel Object Inspector. Al hacer doble clic en el evento OnClick del panel, se abrirá la vista de código como se ha descrito anteriormente. En la vista Código, se puede incluir la instrucción ShowMessage en el controlador de eventos, tal como se muestra en el listado siguiente.

Procedure THelloWorldForm.bDisplayClick(Sender: TObject);
Begin
 ShowMessage('Hello World!');
End;
Para ver los controladores de eventos predefinidos de cualquier componente del formulario de script, seleccione el componente y, a continuación, haga clic en la pestaña Events del panel Object Inspector.
Del mismo modo, el controlador de eventos del botón Cerrar se puede definir generando un evento OnClick que aplique la instrucción Close (form):
Procedure THelloWorldForm.bCloseClick(Sender: TObject);
Begin
 Close;
End;

Una vez definidos los controladores de eventos, debe haber un procedimiento en el script que se utilice como punto de partida al abrir el cuadro de diálogo desde el software. Este se añade al final del código del script.

Tenga en cuenta que el nombre del formulario es HelloWorldForm y el del procedimiento es RunHelloWorld: es importante que los nombres de los formularios sean únicos dentro de un mismo script para evitar conflictos.

Procedure RunHelloWorld;
Begin
 HelloWorldForm.ShowModal;
End;

El script se puede guardar y luego ejecutar desde los menús principales (File» Run Script) ejecutando el elemento de procedimiento RunHelloWorld bajo la entrada HelloWorldDialog.

Como alternativa, el procedimiento se puede asignar al comando/botón Run () a través del menú Run » Set Startup Project Procedure.

Ejecución de un script de formulario HelloWorld, en el que el botón Display del formulario activa un cuadro de diálogo ShowMessage.
Ejecución de un script de formulario HelloWorld, en el que el botón Display del formulario activa un cuadro de diálogo ShowMessage.

El panel Object Inspector facilita la modificación de las propiedades y los eventos de una unidad de formulario. Por ejemplo, para cambiar la posición del formulario en el espacio de trabajo, utilice el panel para modificar el valor poScreenCenter de la propiedad de posición del formulario. Ahora, el cuadro de diálogo se situará en el centro de la pantalla del escritorio cuando se ejecute el script.

Puede encontrar una versión de referencia de los scripts del proyecto Hello World en la carpeta Scripts\Delphiscript Scripts\General de la colección de scripts descargable. Tenga en cuenta que estos son diseños de referencia heredados y no se actualizan.

Llamada a un procedimiento

Como se ha mencionado anteriormente, cualquier script (que utilice el mismo lenguaje) de un proyecto tiene acceso a las variables y los procedimientos globales, por lo que un procedimiento de un script puede llamar a otro procedimiento de un script diferente del mismo proyecto.

Esto se puede demostrar con la sección de código adicional ShowAParametricMessage del proyecto de ejemplo HelloWorld:

Procedure ShowAParametricMessage(S : String);
Var
    DefaultMessage;
Begin
    DefaultMessage := 'Hello World!';

    If S = '' Then ShowMessage(DefaultMessage)
              Else ShowMessage(S);
End;

Esto define una variable de cadena 'S' que se puede pasar al procedimiento ShowAParametricMessage.

La cadena pasada se mostrará mediante la función de cuadro de diálogo ShowMessage, mientras que una estructura If-Then-Else sencilla hace que se muestre el mensaje predeterminado 'Hello World!' si la cadena está vacía.

Para ver cómo funciona, abra el proyecto de ejemplo (HelloWorld.PrjScr) y añada la línea resaltada en gris al script HelloWorldDialog (no al script HelloWorld), como se muestra a continuación.

...
Procedure THelloWorldForm.bDisplayClick(Sender: TObject);
Begin
    Showmessage('Hello World!');
End;

Procedure THelloWorldForm.bCloseClick(Sender: TObject);
Begin
    ShowAParametricMessage('Goodbye World');
    close;
End;

Procedure RunHelloWorld;
Begin
    HelloWorldForm.ShowModal;
End;
...

Cuando se ejecuta el script HelloWorldDialog y se hace clic en el botón Close , se llama al procedimiento global ShowAParametricMessage del script HelloWorld.

Desde el script HelloWorldDialog se llama a un procedimiento con parámetros del script HelloWorld.
Desde el script HelloWorldDialog se llama a un procedimiento con parámetros del script HelloWorld.

La llamada pasa la cadena de mensaje 'Goodbye World' al procedimiento ShowAParametricMessage, de modo que este mensaje se muestra al hacer clic en el botón Close, antes de que se cierre el formulario.

La llamada al script que se muestra arriba inserta un mensaje específico en el procedimiento de cierre del formulario HelloWoldDialog.
La llamada al script que se muestra arriba inserta un mensaje específico en el procedimiento de cierre del formulario HelloWoldDialog.

Si el parámetro de cadena pasado está vacío, ShowAParametricMessage(''), se muestra el mensaje predeterminado 'Hello World!', tal como se define en el procedimiento ShowAParametricMessage.

Para obtener una lista de los atajos de teclado que ayudan a agilizar la escritura y depuración de scripts, consulte la página Herramientas del editor de scripts.

Exploración de los identificadores de scripts mediante el panel Code Explorer

El panel Code Explorer proporciona un resumen visual de todos los identificadores (variables, funciones y procedimientos) que se utilizan en el documento de script activo.

El panel Code Explorer
El panel Code Explorer

La información de los identificadores que aparece en el panel se agrupa en las siguientes carpetas de nivel superior:

  • Procedures & Functions – incluye todos los procedimientos y funciones declarados en el documento de script activo. Para cada procedimiento o función, también se enumeran los parámetros que se le pasan y sus variables locales.

  • Variables – incluye todas las variables globales declaradas en el documento de script activo.

Si se declaran variables locales para un procedimiento o una función, aparecerán en una subcarpeta de variables dentro de dicho procedimiento o función. Se utilizan iconos distintos para diferenciar los diversos identificadores:

Procedimiento

Función

Parámetro de procedimiento o función

Variable (local o global)

Al hacer doble clic en una entrada del panel (o seleccionarla y pulsar la tecla Enter), se saltará al área de código correspondiente en el espacio de diseño.

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