Utilização de componentes de formulário em VBScript

Utilização de componentes em formulários VBScript

Embora os formulários e os componentes se baseiem na Visual Component Library (VCL) do Embarcadero Delphi™, o Altium Designer, baseado em Delphi, Tool Palette continua a ser utilizado para inserir controlos num formulário quando se utiliza VBScript. Além disso, os manipuladores de eventos são gerados e o código é escrito utilizando a linguagem VBScript, independentemente das origens Delphi do formulário/componente no Altium Designer.

Visão geral dos componentes

O sistema de scripts suporta 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 utilizados para diferentes tarefas, tais como as funções fornecidas pelo Timer, OpenDialog e MainMenu . Por exemplo, o componente não visual Timer é utilizado para ativar código específico em intervalos programados e nunca é visível para o utilizador. O Button, Edit e Memo são componentes visuais — são visíveis para o utilizador.

Ambos os tipos de componentes aparecem na fase de conceção, mas os componentes não visuais não são visíveis na fase de execução. Os componentes do Tool Palette são orientados a objetos e apresentam 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 Visible determina se este objeto pode ser visualizado 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 manipulador 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 desse objeto.

Todos os formulários de script têm um ou mais componentes. Os componentes geralmente apresentam informações ou permitem que um utilizador execute uma ação. Por exemplo, um «Label» é utilizado para apresentar texto estático, uma caixa de «Edit» é utilizada para permitir que um 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, permitindo que o utilizador interaja com eles quando o script está a ser executado (tempo de execução). Cabe ao programador de scripts decidir o que acontece quando um utilizador clica num botão ou altera um texto numa caixa de edição.

O sistema de scripts fornece uma variedade de componentes para criar interfaces de utilizador simples ou complexas para scripts. Todos os componentes que podem ser colocados num formulário encontram-se no painel «Paleta de Ferramentas».

Para colocar um componente num formulário, localize o seu ícone no Tool Palette painel e clicar duas vezes nele. Esta ação coloca um componente no formulário ativo na sua posição predefinida, com largura e altura predefinidas. A representação visual da maioria dos componentes é determinada pelo seu conjunto de propriedades associadas.

Um componente inserido, na sua posição e largura-altura predefinidas, pode ser redimensionado ou reposicionado utilizando o rato ou através do Object Inspector painel. Quando um componente é solto num formulário, o sistema de Scripting gera automaticamente o código básico necessário para utilizar o componente e atualiza o formulário de script. Para que o componente no formulário funcione, basta definir as propriedades, inserir código nos manipuladores de eventos e utilizar métodos conforme necessário.

Conceção de formulários de script

Um formulário de script é concebido para interagir com um utilizador no ambiente do Altium Designer. A conceção de formulários de script constitui o cerne do desenvolvimento visual no Altium Designer.

Cada componente colocado num formulário de script e cada propriedade definida são armazenados num ficheiro que descreve o formulário (um *.dfm ficheiro) e tem uma relação com o código de script associado (o *.vbs ficheiro). Assim, para cada formulário de script, existe o *.vbs ficheiro e o *.dfm ficheiro.

Ao trabalhar com um formulário de script e os seus componentes, as suas propriedades podem ser acedidas e modificadas utilizando o Object Inspector painel. É possível selecionar mais do que um componente clicando nos mesmos enquanto mantém a tecla Shift premida, ou arrastando um retângulo de seleção à volta dos componentes no formulário de script. Um formulário de script tem um título associado à Caption propriedade no Object Inspector painel.

Criar um novo formulário de script

Com um projeto de script aberto, clique com o botão direito do rato no projeto no Projects painel e selecione a opção Add New to Project e, em seguida, os VB Script Form itens dos menus de contexto. É criado um novo formulário de script com o EditScript1.vbs . Em alternativa, num *.PrjPCB projeto, selecione File » New » Script Files » VB Script Form comando.

Exibir um formulário de script

Um script tem de conter uma rotina que exiba o formulário quando o formulário do script for executado no Altium Designer. Dentro desta rotina, o ShowModal método é invocado para o formulário. A Visible deve ser definida como «false» (desmarcada) para que o método do formulário de script ShowModal funcionar corretamente.

Exemplo de ShowModal

Sub RunDialog
  DialogForm.ShowModal
End Sub

O ShowModal é uma forma simples de apresentar o formulário de script quando a RunDialog caixa de diálogo do script é invocada. Note-se que é possível atribuir valores aos componentes do DialogForm objeto antes de o DialogForm.ShowModal método ser invocado.

O ModalResult exemplo apresentado abaixo é mais complexo. Os seus métodos finais são utilizados para os botões no formulário de script. Os métodos de script fazem com que a caixa de diálogo seja encerrada quando um utilizador clica no OK ou Cancel , o que irá devolver mrOk ou mrCancel , respetivamente, a partir do ShowModal método.

ModalResult Example

sub bOKButtonClick(Sender)
  ModalResult := mrOK
end sub
 
sub bCancelButtonClick(Sender)
  ModalResult := mrCancel
end sub
 
sub RunShowModalExample
  'Form Visible property must be false for ShowModal to work properly.
  If Form.ShowModal = mrOk     Then ShowMessage("mrOk")
  If Form.ShowModal = mrCancel Then ShowMessage("mrCancel")
end sub

O mesmo resultado que o acima descrito poderia ser obtido definindo o ModalResult valor para mrOk para o OK botão e a mrCancel para o Cancel botão, respetivamente, nos seus manipuladores de eventos. Quando um utilizador clica em qualquer um dos botões, a caixa de diálogo fecha-se. Não é necessário chamar o Close método, porque quando o ModalResult método tiver sido definido, o motor de script fecha o formulário de script automaticamente.

Note-se que, para definir o ModalResult para cancelar quando um utilizador premir a Esc tecla, deve definir a Cancel propriedade «Cancelar» do botão para «true» (marcada) no Object Inspector painel, ou insira Sender.Cancel := True no manipulador de eventos do botão CancelButtonClick .

Aceitar entradas do utilizador

Um dos componentes mais comuns que pode aceitar entradas de um utilizador é o EditBox componente. Este EditBox componente possui um campo de texto onde o utilizador pode introduzir uma sequência de caracteres. Existem também outros componentes que podem aceitar texto, como o componente de edição com máscara, que é um componente de edição com uma máscara de entrada no campo de texto. A máscara controla, ou filtra, a entrada e é armazenada numa cadeia de caracteres de parâmetro.

O exemplo abaixo ilustra o que acontece quando um utilizador clica no botão após digitar texto na caixa de edição. Note-se que, se um utilizador não tiver digitado qualquer texto no componente de edição, o manipulador de eventos responde com uma mensagem de aviso

sub TScriptForm.ButtonClick(Sender)
  If Edit1.Text = "" Then
  ShowMessage("Warning - empty input!")
  Exit
  End
  ' do something else for the input
End sub

Note que o utilizador pode deslocar o foco de entrada no formulário utilizando a tecla Tab ou clicando noutro controlo do formulário.

Resposta a eventos

Quando um formulário ou um componente é selecionado por um utilizador, o Altium Designer envia uma mensagem ao Sistema de Scripts, que responde à notificação do evento chamando o método de manipulador de eventos apropriado.

Escrever manipuladores de eventos

Um script pode precisar de responder a eventos que possam ocorrer num componente em tempo de execução. Um evento é uma ligação entre uma ocorrência no Altium Designer, como clicar num botão, e um trecho de código que responde a essa ocorrência. O código de resposta é um manipulador de eventos, que modifica valores de propriedades e chama métodos.

Juntamente com as propriedades de um componente, cada um possui um conjunto de nomes de eventos. Um programador de scripts decide como este irá reagir às ações de um 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 este novo evento — se o OnClick evento para um botão estiver especificado, este é executado.

Todos esses componentes têm também um evento para ganhar e perder o foco. No entanto, se o código para OnEnter e OnExit não estiver especificado (OnEnter - o controlo tem o foco; OnExit - o controlo perde o foco), o evento será ignorado pelo script.

Propriedades do componente

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

Eventos do componente

Para ver uma lista dos eventos aos quais um componente pode reagir, selecione um componente e aceda ao Events separador no Object Inspector painel. Para criar um procedimento de tratamento de eventos ao qual um componente possa reagir, escolha um evento adequado e clique duas vezes no seu nome.

Por exemplo, selecione o Button1 componente no Tool Palette painel, arraste-o para o formulário de script e clique duas vezes ao lado do OnClick nome do evento. O sistema de scripts voltará a focar-se no Editor de Código, onde o código esqueleto para o OnClick evento já terá sido criado. Se um botão tiver um Close método no seu CloseClick manipulador de eventos, quando o botão é clicado, o seu manipulador de eventos captura o evento «on-click» e o código dentro do manipulador de eventos é executado. Ou seja, o Close método fecha o formulário de script.

Em resumo, um manipulador de eventos é criado num script selecionando um componente no formulário, ou através do Object Inspector painel e, em seguida, clicando duas vezes à direita do evento pretendido (por exemplo, OnClick) no separador Events — a estrutura de código adequada aparecerá no script.

Em alternativa, ao clicar duas vezes num botão, o sistema de scripts adicionará um manipulador para um OnClick evento. Outros tipos de componentes terão ações predefinidas completamente diferentes.

Métodos dos componentes

Consulte a Referência de Componentes para obter uma lista de métodos de um componente e consulte a documentação do Embarcadero Delphi para obter informações mais detalhadas.

Criação de componentes em tempo de execução

Os componentes podem ser criados e destruídos diretamente num script. Normalmente, não é necessário passar o identificador do formulário, uma vez que o formulário do script trata disso automaticamente — em vez disso, passe um Nil parâmetro ao construtor do componente.

Por exemplo, o Open e Save caixas de diálogo podem ser criadas e destruídas (a TOpenDialog e TSaveDialog , como parte da RTL do Delphi).