Formularios y componentes

Descripción general de los componentes gráficos

El sistema de scripts gestiona dos tipos de componentes: los componentes visuales y los no visuales.

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

• El Timer componente no visual puede utilizarse para activar código específico a intervalos programados, y el usuario nunca lo ve.
• El 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 Tool Palette son orientados a objetos y cuentan con los tres elementos siguientes:

• Propiedades
• Eventos
• Métodos

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 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 ratón.

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

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

En un formulario se puede colocar cualquier combinación de componentes y, mientras se ejecuta el script, el usuario puede interactuar con cualquier componente del formulario. Es tarea del programador decidir qué ocurre cuando un usuario hace clic en un botón o modifica el texto de un Edit cuadro.

El sistema de scripts proporciona una serie de componentes que pueden utilizarse para crear interfaces de usuario complejas para los scripts. Para colocar un componente en un formulario, localiza su icono en elpanel «Paleta de herramientas» y haz doble clic en él. Esta acción coloca el componente en el formulario activo. La representación visual de la mayoría de los componentes se configura mediante sus propiedades. Inicialmente, un componente se coloca en una posición predeterminada en el formulario, pero se puede reposicionar (arrastrar) y cambiar su tamaño (estirar) según sea necesario. También puedes modificar el tamaño y la posición posteriormente utilizando el Object Inspector panel.

Cuando se suelta un componente en un formulario, el sistema de scripts 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 utilizar los métodos deseados y 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 constituye el núcleo del desarrollo visual.

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

Al trabajar con un formulario de script y sus componentes, todas las propiedades de los elementos se pueden inspeccionar y modificar mediante el Object Inspector panel. Puedes seleccionar más de un componente haciendo clic en ellos mientras mantienes pulsada la tecla Mayús, o arrastrando un rectángulo de selección alrededor de los componentes del formulario. Un formulario de script tiene un título (la Caption propiedad del Object Inspector ).

Creación de un nuevo formulario de script

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

Visualización de un formulario de script

Un script debe contener un procedimiento que muestre el formulario cuando se ejecute el formulario de script. Dentro de este procedimiento, se puede invocar el ShowModal se puede invocar el método del formulario. La Visible propiedad del formulario debe estar establecida en «false» para que el ShowModal método del formulario de script funcione correctamente.

ShowModal example:

Procedure RunDialog;
Begin
  DialogForm.ShowModal;
End;

El ShowModal ejemplo muestra una forma muy sencilla de mostrar el formulario de script cuando RunDialog se invoca el procedimiento. Ten en cuenta que se pueden asignar valores a los componentes del DialogForm objeto antes de que se DialogForm.ShowModal se invoque el método.

El ModalResult ejemplo de propiedad 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. Estos métodos hacen que el cuadro de diálogo se cierre cuando el usuario hace clic en el botón OK o Cancel , lo que devuelve mrOk o mrCancel del 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, se cierra el cuadro de diálogo. No es necesario llamar al Close método, ya que cuando se establece el ModalResult se establece el método, el motor de scripts cierra el formulario de script automáticamente.

Ten en cuenta que, si deseas establecer el ModalResult en Cancel cuando el usuario pulse la Esc tecla, utilice el Object Inspector para configurar la propiedad Cancel a True, o inserta Sender.Cancel := True en el controlador de eventos del botón CancelButtonClick del formulario.

Aceptación de entradas del usuario

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

El ejemplo siguiente ilustra el proceso que se produce cuando el usuario hace clic en el botón tras escribir algo en el cuadro de edición. Si el usuario no ha escrito nada en el componente de edición (está 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 el usuario puede cambiar el foco de entrada del cuadro de diálogo utilizando la 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 de Altium Designer y llamando al método de controlador de eventos adecuado.

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

Escribir controladores de eventos

Cada componente de un script de formulario tiene un conjunto de nombres de eventos, que son utilizados por los controladores de eventos del script para determinar cómo reaccionará este 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 este reacciona ante este nuevo evento. Si se especifica el OnClick se ha especificado un evento para un botón, este se ejecuta.

El código para responder a los eventos suele estar contenido en los controladores de eventos de DelphiScript, y todos los componentes tienen un conjunto de eventos a los que pueden reaccionar. Por ejemplo, todos los componentes en los que se puede hacer clic tienen un OnClick evento que se activa cuando un usuario hace clic en un componente. Todos estos componentes también tienen un evento para recibir y perder el foco. Sin embargo, si el código para OnEnter y OnExit no se ha especificado (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 un suceso en Altium Designer, como hacer clic en un botón, y un fragmento de código que responde a ese suceso. El código que responde es un controlador de eventos. Este código modifica los valores de las propiedades y llama a métodos.

Propiedades de los componentes

Para ver una lista de las propiedades de un componente, selecciona un componente y abre la Properties pestaña del Object Inspector panel.

Eventos del componente

Para ver una lista de los eventos a los que puede reaccionar un componente, selecciona un componente y abre la Events pestaña del Object Inspector panel. Para crear un procedimiento de gestión de eventos, selecciona el evento al que quieres que reaccione el componente y haz doble clic en el nombre del evento; el sistema de scripts insertará automáticamente el código del marco del gestor de eventos.

Por ejemplo, selecciona el TButton componente del Tool Palette y arrástralo hasta el formulario de script; a continuación, haz doble clic junto al OnClick nombre del evento en el Object Inspector panel. El sistema de scripts activará el Editor de código y se creará el código esqueleto para el OnClick evento.

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

En resumen, selecciona un componente de botón, ya sea en el formulario o mediante el Object Inspector panel, selecciona la Events página y haz doble clic en la parte derecha del OnClick evento y aparecerá un nuevo controlador de eventos en el script. Como alternativa, haz doble clic en el propio botón y el sistema de scripts añadirá un controlador para este OnClick evento. Ten en cuenta que otros tipos de componentes tendrán acciones predeterminadas diferentes.

Métodos de los componentes

Para ver una lista de métodos de un componente, consulta el documento «Referencia de componentes ».

Colocar componentes en un formulario de script

Para utilizar componentes del panel «Paleta de herramientas» en un script, es necesario que exista un formulario de script antes de poder soltar los componentes en él. Normalmente, cuando se sueltan 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 scripts también genera automáticamente el código necesario para utilizar un componente y actualiza el formulario de script. A continuación, solo hay que configurar las propiedades, introducir código en los controladores de eventos y utilizar los métodos necesarios para implementar un formulario de script que funcione.

Creación de componentes en un script

Los componentes se pueden crear o destruir directamente en un script pasando un Nil parámetro a la Constructor de un componente. Normalmente no es necesario pasar el identificador del formulario, ya que el formulario de script se encarga de ello automáticamente. Por ejemplo, puedes crear y destruir Open y Save cuadros de diálogo (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 encima de otros paneles abiertos, configura la FormStyle propiedad en fsStayOnTop.
• Para definir el comportamiento predeterminado de un formulario, establece la FormKind en uno de los siguientes valores: fkNone, fkNormal, fkServerPanel o fkModal.
• Si fkModal está cerrado, el formulario será modal, es decir, esperará a que el usuario introduzca datos antes de continuar, por ejemplo, para cerrar el formulario. Si fkServerPanel entonces el formulario se mostrará como un panel de servidor. Si fkNormal entonces el formulario se comportará como un formulario normal no modal.
• Para eliminar las barras de desplazamiento predeterminadas del formulario, cambia el valor de la propiedad HorzScrollBar y VertScrollBar .
• Para convertir el formulario en un marco MDI o en un elemento secundario MDI, utilice la FormStyle .
• Para cambiar el estilo del borde del formulario, utiliza la BorderIcons y BorderStyle (los resultados se ven en tiempo de ejecución).
• Para cambiar el icono del formulario minimizado, utilice la Icon .
• Para especificar la posición inicial de un formulario en la ventana de la aplicación, utiliza la Position propiedad.
• Para especificar el estado inicial del formulario (por ejemplo, minimizado, maximizado o normal), utiliza la WindowState propiedad.
• Para definir el área de trabajo del formulario en tiempo de ejecución, utiliza la ClientHeight y ClientWidth (tenga en cuenta que ClientHeight y ClientWidth representan el área dentro del borde del formulario; Height y Width representan toda el área del formulario).
• Para especificar qué control tiene el foco inicial en el formulario en tiempo de ejecución, utilice la ActiveControl propiedad.
• Para pasar todos los eventos de teclado al formulario, independientemente del control seleccionado, utilice la KeyPreview propiedad.
• Para especificar un menú concreto, si un formulario contiene más de un menú, utilice la Menu propiedad.

Actualización de formularios y componentes de script

Cuando la interfaz de un formulario de script queda desactualizada —por ejemplo, cuando los controles no se actualizan o no se vuelven a dibujar—, estos pueden parecer bloqueados o dañados; esto podría deberse a un procesamiento intensivo en segundo plano por parte de dicho script.

El Update método del formulario de script, así como muchos de los componentes de script del Tool Palette panel, ofrecen una forma de actualizar el contenido gráfico del formulario o de uno o varios controles específicos. Las líneas que contienen el Update método aparecen 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 procede del PCB Logo Creator proyecto de scripts, que se puede encontrar en la Scripts\Delphiscript Scripts\Pcb\PCB Logo Creator carpeta de la colección de scripts descargables.