Formularios y componentes

Descripción general de los componentes gráficos

El sistema de scripting maneja dos tipos de componentes: componentes visuales y no visuales.

Los componentes visuales se utilizan para crear la interfaz de usuario, y los componentes no visuales se utilizan para distintas tareas, como los componentes Timer, OpenDialog y MainMenu.

• El componente no visual Timer puede utilizarse para activar código específico en intervalos programados, y el usuario nunca lo ve.
• Los componentes Button, Edit y Memo son componentes visuales.

Ambos tipos de componentes aparecen en tiempo de diseño, pero los componentes no visuales no son visibles en tiempo de ejecución. Los componentes del panel Tool Palette están orientados a objetos y tienen los tres elementos siguientes:

• Propiedades
• Eventos
• Métodos

Una Property es una característica de un objeto que influye ya sea en el comportamiento visible o en las operaciones de este objeto. Por ejemplo, la propiedad Visible determina si este objeto puede verse o no en un formulario de script.

Un Event es una acción o 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 mouse.

Un Method es un procedimiento que siempre está asociado a un objeto y define el comportamiento de un objeto.

Todos los formularios de script tienen uno o más componentes. Los componentes normalmente muestran información o permiten al usuario realizar una acción. Por ejemplo, un Label se utiliza para mostrar texto estático, un cuadro Edit se utiliza para permitir que un usuario introduzca datos, y un Button puede utilizarse para iniciar acciones.

Se puede colocar cualquier combinación de componentes en un formulario y, mientras el script se está ejecutando, el usuario puede interactuar con cualquier componente del formulario. Es tarea del programador decidir qué sucede cuando un usuario hace clic en un botón o cambia el texto en un cuadro Edit.

El sistema de scripting proporciona varios componentes que pueden utilizarse para crear interfaces de usuario complejas para scripts. Para colocar un componente en un formulario, localice su icono en el panel Tool Palette panel y haga doble clic sobre él. Esta acción coloca un componente en el formulario activo. La representación visual de la mayoría de los componentes se define mediante sus propiedades. Inicialmente, un componente se coloca en una posición predeterminada del formulario, pero puede reposicionarse (arrastrarse) y redimensionarse (estirarse) según sea necesario. También puede cambiar el tamaño y la posición más adelante mediante el panel Object Inspector .

Cuando se coloca un componente en un formulario, el sistema de scripting genera automáticamente el código necesario para utilizar el componente y actualiza el formulario de script. Solo es necesario configurar las propiedades e implementar el código del controlador de eventos para usar los métodos deseados y hacer que el componente del formulario funcione.

Diseño de formularios de script

Un formulario de script está diseñado para interactuar con el usuario dentro del entorno. El diseño de formularios de script es el núcleo del desarrollo visual.

En la práctica, todos los componentes se colocan en un formulario de script, y cada propiedad configurada se almacena en un archivo que describe el formulario (un archivo *.DFM) que tiene relación con el código de script asociado (el archivo *.PAS). Para cada formulario de script, existe el archivo .PAS y su correspondiente archivo .DFM.

Cuando se trabaja con un formulario de script y sus componentes, todas las propiedades de los elementos pueden inspeccionarse y modificarse mediante el panel Object Inspector. Puede seleccionar más de un componente haciendo Shift-clic en los componentes o arrastrando un rectángulo de selección alrededor de los componentes en el formulario. Un formulario de script tiene un título (la propiedad Caption en el panel Object Inspector).

Creación de un nuevo formulario de script

Con un proyecto de script abierto, haga clic con el botón derecho en un proyecto en el panel Projects, haga clic en el elemento Add New to Project en el menú contextual emergente y elija un elemento Delphi Script Form. Se abrirá un nuevo formulario de script con el nombre predeterminado EditScript1.pas.

Visualización de un formulario de script

Un script necesita tener un procedimiento que muestre el formulario cuando se ejecuta el formulario de script. Dentro de este procedimiento, se puede invocar el método ShowModal para el formulario. La propiedad Visible del formulario debe ser false para que el método ShowModal del formulario de script funcione correctamente.

ShowModal example:

Procedure RunDialog;
Begin
  DialogForm.ShowModal;
End;

El ejemplo ShowModal es un enfoque muy sencillo para mostrar el formulario de script cuando se invoca el procedimiento RunDialog. Tenga en cuenta que se pueden asignar valores a los componentes del objeto DialogForm antes de invocar el método DialogForm.ShowModal.

El ejemplo de la propiedad ModalResult que se muestra a continuación es un poco más complejo. Los siguientes métodos del script se utilizan para los botones de un formulario de script. Los métodos hacen que el cuadro de diálogo finalice cuando el usuario hace clic en el botón OK o en el botón Cancel, lo que devuelve mrOk o mrCancel desde el método ShowModal, respectivamente.

ModalResult Example:

Procedure TForm.OKButtonClick(Sender: TObject);
Begin
  ModalResult := mrOK;
End;

Procedure TForm.CancelButtonClick(Sender: TObject);
Begin
  ModalResult := mrCancel;
End;

Procedure RunShowModalExample;
Begin
  // Form's Visible property must be false for ShowModal to work correctly.
  If Form.ShowModal = mrOk Then ShowMessage('mrOk');
  If Form.ShowModal = mrCancel Then ShowMessage('mrCancel');
End;

Cuando el usuario hace clic en cualquiera de los botones de este formulario de script, el cuadro de diálogo se cierra. No es necesario llamar al método Close, porque cuando se establece el método ModalResult, el motor de scripting cierra automáticamente el formulario de script.

Tenga en cuenta que si desea establecer el ModalResult del formulario en Cancel cuando un usuario presione la tecla Esc , utilice el panel Object Inspector  para establecer la propiedad Cancel del botón Cancel en True, o inserte Sender.Cancel := True en el controlador de eventos CancelButtonClick del botón del formulario.

Aceptación de entrada del usuario

Uno de los componentes comunes que puede aceptar entrada del usuario es el componente TEdit. Este componente tiene un campo donde el usuario puede escribir una cadena de caracteres. Tenga en cuenta que existen otros componentes Delphi como TMaskEdit, que es un componente de edición con una máscara de entrada almacenada en una cadena; esto controla o filtra la entrada.

El ejemplo siguiente ilustra el proceso cuando el usuario hace clic en el botón después de escribir algo en el cuadro de edición. Si el usuario no escribió nada en el componente de edición (en blanco), el controlador de eventos responde con un mensaje de advertencia.

Procedure TScriptForm.ButtonClick(Sender : TObject);
Begin
  If Edit1.Text = '' Then
  Begin
    ShowMessage('Warning - empty input!');
    Exit;
  End;
  // do something else for the input
End;

Tenga en cuenta que un usuario puede cambiar el foco de entrada del cuadro de diálogo usando la tecla Tab o haciendo clic en otro control del formulario.

Respuesta a eventos

Cuando se hace clic en un botón de un formulario o en un componente, el sistema de scripting responde recibiendo una notificación de evento desde Altium Designer y llamando al método controlador de eventos apropiado.

See also
El proyecto HelloWorld de la carpeta Scripts\DelphiScript Scripts\General\ de la colección de scripts .
El script de ejemplo ShowModal de la carpeta Scripts\DelphiScript Scripts\General\ de la colección de scripts .

Escritura de controladores de eventos

Cada componente de un script de formulario tiene un conjunto de nombres de eventos, y estos son utilizados por los controladores de eventos del script que determinan cómo reaccionará el script ante las acciones del usuario en Altium Designer. Por ejemplo, cuando un usuario hace clic en un botón de un formulario, Altium Designer envía un mensaje al script y el script reacciona a este nuevo evento. Si se especifica el evento OnClick para un botón, este se ejecuta.

El código para responder a los eventos normalmente está contenido en controladores de eventos de DelphiScript, y todos los componentes tienen un conjunto de eventos ante los que pueden reaccionar. Por ejemplo, todos los componentes en los que se puede hacer clic tienen un evento OnClick que se dispara cuando un usuario hace clic en un componente. Todos esos componentes también tienen un evento para recibir y perder el foco. Sin embargo, si no se ha especificado el código para OnEnter y OnExit (OnEnter: el control ha recibido el foco; OnExit: el control ha perdido el foco), el script ignorará el evento.

En resumen, un evento es un vínculo entre una ocurrencia en Altium Designer, como hacer clic en un botón, y un fragmento de código que responde a esa ocurrencia. El código que responde es un controlador de eventos. Este código modifica valores de propiedades y llama a métodos.

Propiedades del componente

Para ver una lista de propiedades de un componente, seleccione un componente y abra la pestaña Properties en el panel Object Inspector.

Eventos del componente

Para ver una lista de eventos a los que un componente puede reaccionar, seleccione un componente y abra la pestaña Events en el panel Object Inspector. Para crear un procedimiento de manejo de eventos, seleccione el evento al que desea que el componente reaccione y haga doble clic en el nombre del evento: el sistema de scripting insertará automáticamente el código base del controlador de eventos.

Por ejemplo, seleccione el componente TButton del panel Tool Palette y colóquelo en el formulario de script; luego haga doble clic junto al nombre del evento OnClick en el panel Object Inspector . El sistema de scripting pondrá el foco en el Editor de código y se creará el código esqueleto para el evento OnClick.

Si un botón tiene un método Close en el controlador de eventos CloseClick, por ejemplo, cuando se hace clic en el botón, el controlador de eventos del botón capturará el evento OnClick, lo que hará que se ejecute el código dentro del controlador de eventos. En consecuencia, el método Close cierra el formulario de script.

En resumen, seleccione un componente de botón ya sea en el formulario o usando el panel Object Inspector, seleccione la página Events y haga doble clic en el lado derecho del evento OnClick; aparecerá un nuevo controlador de eventos en el script. Como alternativa, haga doble clic en el propio botón y el sistema de scripting agregará un controlador para este evento OnClick. Tenga en cuenta que otros tipos de componentes tendrán distintas acciones predeterminadas.

Métodos del componente

Para ver una lista de métodos de un componente, consulte el documento Component Reference.

Colocación de componentes en un formulario de script

Para usar componentes del panel Tool Palette panel en un script, debe existir primero un formulario de script antes de poder colocar componentes en él. Normalmente, cuando se colocan componentes en un formulario de script, no es necesario crear ni destruir estos objetos, ya que el formulario de script lo hace automáticamente.

El sistema de scripting también genera automáticamente el código necesario para usar un componente y actualiza el formulario de script. Después, solo se trata de establecer las propiedades, colocar código en los controladores de eventos y usar los métodos requeridos para implementar un formulario de script funcional.

Creación de componentes en un script

Los componentes pueden crearse o destruirse directamente en un script pasando un parámetro Nil al Constructor de un componente. Normalmente no es necesario pasar el identificador del formulario porque el formulario de script se encarga de ello automáticamente. Por ejemplo, puede crear y destruir cuadros de diálogo Open y Save (TOpenDialog y TSaveDialog clases del RTL de Embarcadero Delphi).

Personalización de formularios de script

Los puntos esenciales para personalizar formularios de script son:

• Para forzar que un formulario permanezca por encima de otros paneles abiertos, 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 fkModal está cerrado, el formulario será modal; es decir, esperará la entrada del usuario antes de continuar, por ejemplo, al cerrar el formulario. Si fkServerPanel, el formulario se mostrará como un panel del servidor. Si fkNormal, el formulario actuará como un formulario normal no modal.
• Para quitar las barras de desplazamiento predeterminadas del formulario, cambie el valor de las propiedades HorzScrollBar y VertScrollBar.
• Para convertir el formulario en un marco MDI o en un elemento secundario MDI, use la propiedad FormStyle.
• Para cambiar el estilo del borde del 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 del formulario (por ejemplo, minimizado, maximizado o normal), use la propiedad WindowState.
• Para definir el área de trabajo del 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; Height y Width representan el área completa del formulario).
• Para especificar qué control tiene el foco inicial en el formulario en tiempo de ejecución, use la propiedad ActiveControl.
• Para pasar todos los eventos del teclado al formulario, independientemente del control seleccionado, use la propiedad KeyPreview.
• Para especificar un menú en particular, si un formulario contiene más de un menú, use la propiedad Menu.

Actualización de formularios y componentes de script

Cuando la superficie de un formulario de script queda desactualizada, por ejemplo, cuando los controles no se actualizan ni se vuelven a dibujar, los controles pueden parecer congelados o dañados; esto puede deberse a un procesamiento intensivo en segundo plano de ese script.

El método Update del formulario de script, y muchos de los componentes de script del panel Tool Palette , proporcionan una forma de actualizar el contenido gráfico del formulario o de los controles específicos. Las líneas que contienen el método Update están resaltadas en gris en el ejemplo siguiente.

StatusBar component and its Update method Example:

Procedure TConverterForm.loadbuttonClick(Sender: TObject);
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
 ShowWarning('The image is not a monochrome!');
 Close;
 End;
 
 lImageSize.Caption := IntToStr(Image1.Picture.Width) + ' x ' +
 IntToStr(Image1.Picture.Height) + ' mils';
 
 convertbutton.Enabled  := True;
 LoadButton.Enabled     := False;
 XStatusBar1.SimpleText := '  Ready...';
 XStatusBar1.Update;
 End;
End;

El fragmento de código anterior pertenece al proyecto de script PCB Logo Creator, que puede encontrarse en la carpeta Scripts\Delphiscript Scripts\Pcb\PCB Logo Creator de la colección de scripts descargable.