Creación de scripts para componentes gráficos

Esta referencia describe los componentes gráficos compatibles para scripting y sus principales propiedades y métodos.

Los componentes visuales de formularios disponibles para su uso en scripts de Altium Designer derivan en su mayoría de la Visual Component Library (VCL) de Embarcadero, que es una colección de componentes visuales definidos para desarrollar aplicaciones de Windows con los lenguajes Delphi y C++.

Desarrolladas como una biblioteca visual de clases, las clases de la VCL descienden del objeto TComponent (que a su vez desciende del objeto raíz TObject) en una jerarquía lineal de objetos. Por lo tanto, un componente de script común, como el objeto TButton, hereda las propiedades, métodos y eventos de los objetos de los que desciende. En este caso, la jerarquía de clases es: TObject → TPersistent → TComponent → TControl → TWinControl → TButtonControl → TButton.

Tenga en cuenta que los componentes que descienden del objeto TControl son, por lo general, componentes visuales (controles), y los componentes comunes que descienden de TWinControl son en su mayoría contenedores alrededor de la API de Windows.

► Consulte Embarcadero RAD Studio VCL para obtener una visión general de la arquitectura y los componentes de la VCL.

Al crear un Form en el Editor de Scripts de Altium Designer, se accede a los componentes desde el panel Tool Palette. Los Script Forms tienen un archivo *.DFM asociado que incluye detalles sobre la configuración del formulario, la ubicación de sus componentes y otros atributos; este archivo se encuentra en la carpeta anfitriona del proyecto de script. Altium Designer permite usar los componentes con DelphiScript o VBScript al diseñar Script Forms.

El panel Tool Palette contiene controles visuales categorizados que pueden colocarse en un Form de script.

El panel Tool Palette panel contiene selecciones categorizadas de componentes que pueden colocarse en un Script Form. Los componentes disponibles están organizados en secciones expandibles en el panel Tool Palette, clasificadas como Standard, Additional, Win32, System, Dialogs, Altium Standard e Instrument Controls.

Los componentes (o "controles") disponibles en la Palette son componentes visuales cuando se usan en un formulario de script, lo que significa que un usuario puede ver un control y posiblemente interactuar con él en tiempo de ejecución. Todos los controles tienen propiedades, métodos y eventos que describen aspectos de su apariencia, como la propiedad de posición del control, métodos para dibujar o mover el control y eventos que responden a acciones del usuario.

Las propiedades y los eventos están disponibles en el panel Object Inspector panel para el componente del formulario seleccionado actualmente, incluido el propio formulario. Los métodos son procedimientos y funciones compatibles con ese componente.

Descripción general de Script Forms

Script Forms

Un Script Form es la interfaz de usuario principal en los scripts, aunque también existen otros formularios como cuadros de diálogo, ventanas secundarias, etc. Para crear un nuevo Script Form, con un proyecto abierto en Altium Designer, seleccione File » New » Script » Script Form o haga clic con el botón derecho en el nombre del proyecto de Script y elija Add New to Project » Script Form. Si el lenguaje VBScript está habilitado, el comando estará disponible tanto para VB Script como para Delphi Script.

Aparecerá un nuevo Script Form con el nombre de formulario Form1 como valor predeterminado, que puede cambiarse mediante la propiedad Name (en Misc) en el panel Object Inspector. Los nombres de los formularios de script deben ser únicos dentro de un proyecto.

Al diseñar un Form de script, abra el panel Object Inspector desde el botón Script en la barra de estado inferior.

Un formulario en blanco es básicamente una ventana visual a la que pueden agregarse controles. Un cuadro de diálogo y un panel son tipos diferentes de formularios y, de forma predeterminada, un formulario incluye funcionalidad estándar de ventana como:

• Controles
• Botones Minimizar y Maximizar
• Barra de título
• Redimensionable arrastrando el borde

Estas características, junto con cualquier otra propiedad disponible del formulario, pueden modificarse en tiempo de diseño mediante el panel Object Inspector. Dado que un Script Form es un componente VCL, tiene los tres elementos siguientes:

• Properties – Las características de un objeto que influyen en su comportamiento visible o en sus operaciones. Por ejemplo, la propiedad Visible determina si un objeto puede verse en un formulario de script.
• Events – Acciones o sucesos detectados por el script. Un script debe incluir código para cada controlador de eventos, diseñado para capturar un evento específico, como un clic del ratón.
• Methods – Procedimientos de script asociados a objetos (en este caso, objetos de componentes) y que definen su comportamiento.

► Consulte Writing Scripts para obtener una guía básica sobre el desarrollo de un script basado en formularios.

Propiedades, métodos y eventos del formulario

Los controles del panel Tool Palette se basan en la Visual Component Library (VCL) de Embarcadero. Para obtener información completa sobre los métodos, propiedades y eventos del componente Form (TForm), consulte la documentación de Embarcadero VCL.

► Consulte la referencia de Embarcadero TForm.Tenga en cuenta que el enlace anterior hace referencia a la referencia Embarcadero RAD Studio XE6 de la biblioteca VCL. También está disponible la documentación de versiones anteriores (hasta la versión 2010).

Propiedades de TForm

Las propiedades disponibles para el objeto componente TForm, el formulario base del script, pueden verse de las siguientes maneras:

• Mediante el panel Object Inspector: en la vista Form del editor (con la pestaña Form seleccionada), haga clic en el cuerpo del propio formulario y seleccione la pestaña Object Inspector's Properties .

Tenga en cuenta que solo los objetos de componentes visuales aparecerán en el panel. Los objetos no visuales, que actúan como controles entre bastidores, no se muestran en el formulario.

• Usando la función de autocompletado de código: en la vista Code del editor (con la pestaña Code seleccionada), la ventana de Code Completion sensible al contexto mostrará todas las opciones de código para un nombre de objeto.

Para el objeto Form, introduzca TForm. (observe el punto) para activar la ventana. Acote la búsqueda escribiendo las primeras letras de la propiedad deseada; tenga en cuenta que se muestran tanto propiedades como métodos.

• Desde la documentación de referencia de Embarcadero en la página TForm Properties reference page.

Métodos de TForm

Los métodos disponibles para el objeto componente TForm pueden verse de las siguientes maneras:

• Use la función Code Completion: en la vista Code del editor, escriba un nombre de componente seguido de un punto. Se abrirá la ventana Code Completion para mostrar los métodos de código (y propiedades) de un nombre de objeto. Tenga en cuenta que la ventana de código puede activarse manualmente con las teclas de acceso rápido Crtl+Space.

• Consulte la documentación de referencia de Embarcadero en la página TForm Methods reference page. Tenga en cuenta que esta muestra todos los métodos heredados; sin embargo, esa opción puede deseleccionarse.

Eventos de TForm

Los eventos disponibles para el objeto componente TForm pueden verse de las siguientes maneras:

• El panel Object Inspector: en la vista Form del editor, haga clic en el cuerpo del propio formulario y seleccione la pestaña Events del Object Inspector.

• La documentación de referencia de Embarcadero en la página TFrom Events reference page.

Propiedades, eventos y métodos de componentes

Los controles del panel Tool Palette se basan en la Visual Component Library (VCL) de Embarcadero. Para obtener información completa sobre los métodos, propiedades y eventos de la mayoría de los componentes, consulte las categorías de componentes en la documentación de Embarcadero VCL. Algunos tipos de componentes del Tool Palette, en particular los Altium Instrument Controls, son exclusivos de Altium Designer y no están incluidos en la documentación de referencia de Embarcadero.

► Consulte el índice de categorías de componentes VCL de Embarcadero.Tenga en cuenta que el enlace anterior hace referencia a la documentación de Embarcadero RAD Studio XE6 para la biblioteca VCL. También está disponible la documentación de versiones anteriores (hasta la versión 2010).

Propiedades de componentes

Para ver una lista de propiedades de un componente:

• Seleccione un componente en el Form y active la pestaña Properties en el panel Object Inspector; como se muestra arriba para el objeto componente TForm.
• Seleccione el enlace Properties (en la parte superior) en la página de referencia del componente correspondiente en la documentación de referencia de Embarcadero. En el caso del control TButton, por ejemplo, seleccione la categoría Standard Component, la página TButton y luego la vista Properties.

Eventos de componentes

Para ver una lista de eventos a los que un componente puede reaccionar:

• Seleccione un componente en el Form y active la pestaña Events en el panel Object Inspector; como se muestra arriba para el objeto componente TForm.
• Seleccione una página de referencia de componente adecuada y luego su enlace Events en la documentación de referencia de Embarcadero. Tenga en cuenta que esto es útil como guía de los eventos disponibles para un componente y puede que no coincida completamente con los eventos disponibles para los componentes de scripting de Altium Designer.

Para crear un procedimiento de gestión de eventos, elija el evento al que debe reaccionar el componente en la pestaña Object Inspector Events y haga doble clic en el campo de entrada del evento. El procedimiento controlador del evento, nombrado a partir del componente y la acción del evento, se genera automáticamente en el script. Si el evento se cambia de nombre en el panel Object Inspector, el procedimiento de código correspondiente también se renombrará en consecuencia.

Métodos de componentes

Esto incluye referencias para las siguientes categorías de objetos de control.

• Standard
• Additional
• Win32
• System
• Dialog
• Altium Standard
• Instrument Controls

En su mayor parte, estas categorías agrupan tipos de controles visuales de formularios basados en componentes VCL estándar de tipo Delphi. Las categorías Altium Standard e Instrument Controls son la excepción, ya que ofrecen componentes exclusivos del sistema de scripting de Altium Designer.

► Consulte Tool Palette Component Categories.

Trabajo con formularios y componentes

Personalización de Script Forms

• Para hacer que un formulario permanezca por encima de otros paneles abiertos, por ejemplo, establezca la propiedad FormStyle en fsStayOnTop.
• Para definir el comportamiento predeterminado de un formulario, establezca FormKind en uno de los siguientes valores: fkNone, fkNormal, fkServerPanel o fkModal.
  • Si se selecciona fkModal, el formulario será modal. Es decir, un formulario que espera la entrada del usuario antes de continuar con acciones como cerrar el formulario.
  • Si se selecciona fkServerPanel, el formulario se mostrará como un panel del servidor.
  • Si se selecciona fkNormal, el formulario actuará como un formulario normal no modal.
• Para agregar o quitar las barras de desplazamiento de un formulario, cambie el valor de las propiedades HorzScrollBar y VertScrollBar.
• Para convertir el formulario en un marco o elemento secundario MDI (Multiple Document Interface), use la propiedad FormStyle.
• Para cambiar el estilo del borde de un formulario, use las propiedades BorderIcons y BorderStyle. (Los resultados son visibles en tiempo de ejecución).
• Para cambiar el icono del formulario minimizado, use la propiedad Icon.
• Para especificar la posición inicial de un formulario en la ventana de la aplicación, use la propiedad Position.
• Para especificar el estado inicial de un formulario (por ejemplo, minimizado, maximizado o normal), use la propiedad WindowState.
• Para definir el área de trabajo de un formulario en tiempo de ejecución, use las propiedades ClientHeight y ClientWidth. Tenga en cuenta que ClientHeight y ClientWidth representan el área dentro del borde del formulario, mientras que Height y Width representan el área total del formulario.
• Para especificar qué control tiene el foco inicial en un formulario en tiempo de ejecución, use la propiedad ActiveControl para elegir entre los componentes disponibles.
• Para pasar todos los eventos del teclado a un formulario, independientemente del control seleccionado, use la propiedad KeyPreview.
• Para especificar un menú determinado, si un formulario contiene más de un menú, use la propiedad Menu.

Actualizar formularios y componentes

En algunos casos, el aspecto visual de un formulario de script puede quedar desactualizado; por ejemplo, si un procesamiento intensivo en segundo plano desde un script hace que los controles no se actualicen ni se repinten, y parezcan congelados o dañados.

El método Update del formulario de script proporciona una manera programática de actualizar el contenido gráfico de un formulario o de controles específicos. En el ejemplo de código siguiente, las líneas de código del método Update están resaltadas en gris.

Using the Update method to refresh the Status Bar:

Procedure TConverterForm.loadbuttonClick(Sender: TObject);
Var
   I, J : Integer;
Begin
    If OpenPictureDialog1.Execute then
    Begin
        XPProgressBar1.Position := 0;
        XStatusBar1.SimpleText  := '  Loading...';
        XStatusBar1.Update;

        // loading a monochrome bitmap only
        Image1.Picture.LoadFromFile(OpenPictureDialog1.FileName);

        // Check if image is monochrome, otherwise prompt a warning
        If Image1.Picture.Bitmap.PixelFormat <> pf1bit Then
        Begin
            For J := 0 to Image1.Picture.Height – 1 Do
                For I := 0 to Image1.Picture.Height – 1 Do
            Begin
                If Image1.Canvas.Pixels[I,J] <> clWhite Then
                    Image1.Canvas.Pixels[I,J] := clBlack;
            End;
        End;

        ScalingFactorChange(Nil);

        convertbutton.Enabled  := True;
        LoadButton.Enabled     := False;
        XStatusBar1.SimpleText := '  Ready...';
        XStatusBar1.Update;
    End;
End;

Consulte el proyecto de script PCB Logo Creator, ubicado en la carpeta Scripts\Delphiscript Scripts\PCB\PCB Logo Creator de la colección de scripts descargable .