Formulários e Componentes

Descrição geral dos componentes gráficos

O sistema de scripting gere dois tipos de componentes: componentes visuais e não visuais.

Os componentes visuais são utilizados para construir a interface do utilizador e os componentes não visuais são usados para diferentes tarefas, como os componentes Timer, OpenDialog e MainMenu.

• O componente não visual Timer pode ser utilizado para ativar código específico em intervalos agendados, e nunca é visível para o utilizador.
• Os componentes Button, Edit e Memo são componentes visuais.

Ambos os tipos de componentes aparecem em tempo de conceção, mas os componentes não visuais não são visíveis em tempo de execução. Os componentes do painel Tool Palette são orientados a objetos e têm os três itens seguintes:

• Propriedades
• Eventos
• Métodos

Uma Property é uma característica de um objeto que influencia o comportamento visível ou as operações desse objeto. Por exemplo, a propriedade Visible determina se este objeto pode ou não ser visto num formulário de script.

Um Event é uma ação ou ocorrência detetada pelo script. Num script, o programador escreve código para cada gestor de eventos concebido para capturar um evento específico, como um clique do rato.

Um Method é um procedimento que está sempre associado a um objeto e define o comportamento de um objeto.

Todos os formulários de script têm um ou mais componentes. Os componentes normalmente apresentam informação ou permitem ao utilizador executar uma ação. Por exemplo, um Label é utilizado para apresentar texto estático, uma caixa Edit é utilizada para permitir que o utilizador introduza alguns dados, e um Button pode ser utilizado para iniciar ações.

Qualquer combinação de componentes pode ser colocada num formulário e, enquanto o script estiver em execução, o utilizador pode interagir com qualquer componente do formulário. Cabe ao programador decidir o que acontece quando o utilizador clica num botão ou altera o texto numa caixa Edit.

O sistema de scripting fornece vários componentes que podem ser utilizados para criar interfaces de utilizador complexas para scripts. Para colocar um componente num formulário, localize o respetivo ícone no painel Tool Palette panel e faça duplo clique sobre ele. Esta ação coloca um componente no formulário ativo. A representação visual da maioria dos componentes é definida através das respetivas propriedades. Um componente é inicialmente colocado numa posição predefinida no formulário, mas pode ser reposicionado (arrastado) e redimensionado (esticado) conforme necessário. Também pode alterar posteriormente o tamanho e a posição através do painel Object Inspector .

Quando um componente é largado num formulário, o sistema de scripting gera automaticamente o código necessário para utilizar o componente e atualiza o formulário do script. Apenas é necessário definir as propriedades e implementar o código do gestor de eventos para utilizar os métodos pretendidos e colocar o componente a funcionar no formulário.

Conceber formulários de script

Um formulário de script é concebido para interagir com o utilizador dentro do ambiente. A conceção de formulários de script é o núcleo do desenvolvimento visual.

Na prática, todos os componentes são colocados num formulário de script, e cada propriedade definida é armazenada num ficheiro que descreve o formulário (um ficheiro *.DFM) que está relacionado com o código de script associado (o ficheiro *.PAS). Para cada formulário de script, existe o ficheiro .PAS e o respetivo ficheiro .DFM correspondente.

Ao trabalhar com um formulário de script e os seus componentes, todas as propriedades dos elementos podem ser inspecionadas e modificadas através do painel Object Inspector. Pode selecionar mais do que um componente fazendo Shift+clique nos componentes, ou arrastando um retângulo de seleção à volta dos componentes no formulário. Um formulário de script tem um título (a propriedade Caption no painel Object Inspector).

Criar um novo formulário de script

Com um projeto de script aberto, clique com o botão direito num projeto no painel Projects, clique no item Add New to Project no menu de contexto emergente e escolha um item Delphi Script Form. Será aberto um novo formulário de script com o nome predefinido EditScript1.pas.

Apresentar um formulário de script

Um script precisa de ter um procedimento que apresente o formulário quando o formulário de script é executado. Dentro deste procedimento, o método ShowModal pode ser invocado para o formulário. A propriedade Visible do formulário tem de estar definida como false para que o método ShowModal do formulário de script funcione corretamente.

ShowModal example:

Procedure RunDialog;
Begin
  DialogForm.ShowModal;
End;

O exemplo ShowModal é uma abordagem muito simples para apresentar o formulário de script quando o procedimento RunDialog é invocado. Note que podem ser atribuídos valores aos componentes do objeto DialogForm antes de o método DialogForm.ShowModal ser invocado.

O exemplo da propriedade ModalResult mostrado abaixo é um pouco mais complexo. Os seguintes métodos no script são usados para botões num formulário de script. Os métodos fazem com que a caixa de diálogo termine quando o utilizador clica no botão OK ou no botão Cancel, devolvendo mrOk ou mrCancel do método ShowModal, respetivamente.

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;

Quando o utilizador clica em qualquer um dos botões neste formulário de script, a caixa de diálogo fecha-se. Não é necessário chamar o método Close, porque quando o método ModalResult é definido, o motor de script fecha automaticamente o formulário de script.

Note que, se pretender definir o ModalResult do formulário como Cancel quando o utilizador prime a tecla Esc , utilize o painel Object Inspector  para definir a propriedade Cancel do botão Cancel como True, ou insira Sender.Cancel := True no gestor de eventos CancelButtonClick do botão do formulário.

Aceitar entrada do utilizador

Um dos componentes comuns que pode aceitar dados introduzidos pelo utilizador é o componente TEdit. Este componente tem um campo onde o utilizador pode escrever uma cadeia de caracteres. Note que existem outros componentes Delphi, como TMaskEdit, que é um componente de edição com uma máscara de entrada armazenada numa cadeia — isto controla ou filtra a entrada.

O exemplo abaixo ilustra o processo quando o utilizador clica no botão depois de escrever algo na caixa de edição. Se o utilizador não tiver escrito nada no componente de edição (em branco), o gestor de eventos responde com uma mensagem de aviso.

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

Note que o utilizador pode alterar o foco de entrada da caixa de diálogo usando a tecla Tab ou clicando noutro controlo do formulário.

Responder a eventos

Quando é clicado um botão num formulário ou um componente, o sistema de scripting responde recebendo uma notificação de evento do Altium Designer e chamando o método de gestor de eventos adequado.

See also
O projeto HelloWorld da pasta Scripts\DelphiScript Scripts\General\ da coleção scripts collection.
O script de exemplo ShowModal da pasta Scripts\DelphiScript Scripts\General\ da coleção scripts collection.

Escrever gestores de eventos

Cada componente num script de formulário tem um conjunto de nomes de eventos, e estes são usados pelos gestores de eventos do script que determinam como o script irá reagir às ações do utilizador no Altium Designer. Por exemplo, quando um utilizador clica num botão num formulário, o Altium Designer envia uma mensagem para o script e o script reage a esse novo evento. Se o evento OnClick para um botão estiver especificado, este é executado.

O código para responder a eventos está normalmente contido em gestores de eventos DelphiScript, e todos os componentes têm um conjunto de eventos aos quais podem reagir. Por exemplo, todos os componentes clicáveis têm um evento OnClick que é acionado quando o utilizador clica num componente. Todos esses componentes têm também um evento para receber e perder o foco. No entanto, se o código para OnEnter e OnExit não tiver sido especificado (OnEnter - o controlo recebeu o foco; OnExit - o controlo perdeu o foco), o evento será ignorado por um script.

Em resumo, um evento é uma ligação entre uma ocorrência no Altium Designer, como clicar num botão, e uma parte de código que responde a essa ocorrência. O código que responde é um gestor de eventos. Este código modifica valores de propriedades e chama métodos.

Propriedades do componente

Para ver uma lista de propriedades de um componente, selecione um componente e abra o separador Properties no painel Object Inspector.

Eventos do componente

Para ver uma lista de eventos aos quais um componente pode reagir, selecione um componente e abra o separador Events no painel Object Inspector. Para criar um procedimento de tratamento de eventos, selecione o evento ao qual pretende que o componente reaja e faça duplo clique no nome do evento — o sistema de scripting irá inserir automaticamente o código base do gestor de eventos.

Por exemplo, selecione o componente TButton no painel Tool Palette e largue-o no formulário de script; em seguida, faça duplo clique ao lado do nome do evento OnClick no painel Object Inspector . O sistema de scripting colocará o foco no Editor de Código e será criado o código esqueleto para o evento OnClick.

Se um botão tiver um método Close no gestor de eventos CloseClick, por exemplo, quando o botão for clicado o gestor de eventos do botão irá capturar o evento OnClick, fazendo com que o código dentro do gestor de eventos seja executado. Consequentemente, o método Close fecha o formulário de script.

Em resumo, selecione um componente de botão no formulário ou usando o painel Object Inspector, selecione a página Events e faça duplo clique no lado direito do evento OnClick; surgirá um novo gestor de eventos no script. Em alternativa, faça duplo clique no próprio botão, e o sistema de scripting adicionará um gestor para este evento OnClick. Note que outros tipos de componentes terão ações predefinidas diferentes.

Métodos do componente

Para ver uma lista de métodos de um componente, consulte o documento Component Reference.

Largar componentes num formulário de script

Para utilizar componentes do painel Tool Palette num script, tem de existir um formulário de script antes de os componentes poderem ser colocados no formulário. Normalmente, quando os componentes são colocados num formulário de script, estes objetos não precisam de ser criados nem destruídos — o formulário de script trata disso automaticamente.

O sistema de scripting também gera automaticamente o código necessário para utilizar um componente e atualiza o formulário de script. Depois, basta definir as propriedades, colocar código nos processadores de eventos e usar os métodos necessários para implementar um formulário de script funcional.

Criar Componentes num Script

Os componentes podem ser criados ou destruídos diretamente num script passando um parâmetro Nil para o Constructor de um componente. Normalmente, não é necessário passar o identificador do formulário porque o formulário de script trata disso automaticamente. Por exemplo, pode criar e destruir caixas de diálogo Open e Save (TOpenDialog e TSaveDialog classes da RTL Embarcadero Delphi).

Personalizar Formulários de Script

Os pontos essenciais para personalizar formulários de script são:

• Para forçar um formulário a permanecer sobre os outros painéis abertos, defina a propriedade FormStyle como fsStayOnTop.
• Para definir o comportamento predefinido de um formulário, defina FormKind com um dos seguintes valores: fkNone, fkNormal, fkServerPanel ou fkModal.
• Se fkModal estiver fechado, o formulário será modal — ou seja, ficará à espera da introdução do utilizador antes de prosseguir, por exemplo, ao fechar o formulário. Se fkServerPanel, então o formulário será apresentado como um painel Server. Se fkNormal, então o formulário comporta-se como um formulário normal não modal.
• Para remover as barras de deslocamento predefinidas do formulário, altere o valor das propriedades HorzScrollBar e VertScrollBar.
• Para tornar o formulário num frame MDI ou num filho MDI, utilize a propriedade FormStyle.
• Para alterar o estilo do contorno do formulário, utilize as propriedades BorderIcons e BorderStyle (os resultados são visíveis em tempo de execução).
• Para alterar o ícone do formulário minimizado, utilize a propriedade Icon.
• Para especificar a posição inicial de um formulário na janela da aplicação, utilize a propriedade Position.
• Para especificar o estado inicial do formulário (por exemplo, minimizado, maximizado ou normal), utilize a propriedade WindowState.
• Para definir a área de trabalho do formulário em tempo de execução, utilize as propriedades ClientHeight e ClientWidth (tenha em atenção que ClientHeight e ClientWidth representam a área dentro do contorno do formulário; Height e Width representam a área total do formulário).
• Para especificar qual o controlo que tem o foco inicial no formulário em tempo de execução, utilize a propriedade ActiveControl.
• Para encaminhar todos os eventos do teclado para o formulário, independentemente do controlo selecionado, utilize a propriedade KeyPreview.
• Para especificar um menu em particular, se um formulário contiver mais de um menu, utilize a propriedade Menu.

Atualizar Formulários de Script e Componentes

Quando a superfície de um formulário de script fica desatualizada, por exemplo, quando os controlos não são atualizados nem redesenhados, os controlos podem parecer bloqueados ou corrompidos — isto pode dever-se a processamento intensivo em segundo plano desse script.

O método Update do formulário de script, e muitos dos componentes de script do painel Tool Palette , fornecem uma forma de atualizar o conteúdo gráfico do formulário ou do(s) controlo(s) específico(s). As linhas que contêm o método Update estão realçadas a cinzento no exemplo abaixo.

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;

O excerto de código acima é do projeto de script PCB Logo Creator, que pode ser encontrado na pasta Scripts\Delphiscript Scripts\Pcb\PCB Logo Creator da coleção de scripts descarregável.