Using VBScript Form Components

Utilizar Componentes em Formulários VBScript

Embora os Formulários e os Componentes sejam baseados na Visual Component Library (VCL) do Embarcadero Delphi™, o Tool Palette baseado em Delphi do Altium Designer continua a ser utilizado para colocar Controlos num formulário quando se usa VBScript. Além disso, os processadores de eventos são gerados e o código é escrito na linguagem VBScript, independentemente das raízes Delphi de Formulário/Componente no Altium Designer.

Visão Geral dos Componentes

O sistema de scripting processa 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, como as funções disponibilizadas pelos componentes Timer, OpenDialog e MainMenu. Por exemplo, o componente não visual Timer é utilizado para ativar código específico em intervalos programados e nunca é visto por um utilizador. Os componentes Button, Edit e Memo são componentes visuais — são vistos por um utilizador.

Ambos os tipos de componentes aparecem em tempo de conceção, mas os componentes não visuais não estã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 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 processador de eventos, concebido para captar 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 normalmente apresentam informação ou permitem que um utilizador execute uma ação. Por exemplo, um Label é utilizado para apresentar texto estático, uma caixa 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 um utilizador interaja com eles quando o script está em execução (runtime). Cabe ao programador do script decidir o que acontece quando um utilizador clica num botão ou altera texto numa caixa Edit.

O sistema de Scripting disponibiliza um conjunto de componentes para criar interfaces de utilizador simples ou complexas para scripts. Todos os componentes que podem ser colocados num formulário podem ser encontrados no painel Tool Palette.

Para colocar um componente num formulário, localize o seu ícone no painel Tool Palette e faça duplo clique. 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 colocado, na sua posição e dimensões predefinidas, pode ser redimensionado ou reposicionado com o rato ou através do painel Object Inspector. Quando um componente é colocado 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 do script. Para que o componente no Formulário funcione, resta apenas definir propriedades, colocar código nos processadores de eventos e utilizar métodos conforme necessário.

Conceber 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 é o núcleo do desenvolvimento visual no Altium Designer.

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

Ao trabalhar com um formulário de script e os seus componentes, as respetivas propriedades podem ser acedidas e modificadas através do painel Object Inspector. Pode selecionar mais do que um componente mantendo a tecla Shift premida enquanto clica nos componentes, 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 à 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 do rato no projeto no painel Projects e selecione os itens Add New to Project e depois VB Script Form nos menus de contexto. É criado um novo formulário de script com o nome predefinido EditScript1.vbs . Em alternativa, num projeto *.PrjPCB, selecione o comando File » New » Script Files » VB Script Form.

Apresentar um Formulário de Script

Um script precisa de ter uma rotina que apresente o formulário quando o formulário de script é executado no Altium Designer. Dentro desta rotina, é invocado o método ShowModal para o formulário. A propriedade Visible do formulário tem de ser definida como false (desmarcada) para que o método ShowModal do formulário de script funcione corretamente.

Exemplo de ShowModal

Sub RunDialog
  DialogForm.ShowModal
End Sub

O exemplo ShowModal acima é uma forma simples de apresentar o formulário de script quando a caixa de diálogo RunDialog do script é invocada. Note que podem ser atribuídos valores aos componentes do objeto DialogForm antes de o método DialogForm.ShowModal ser invocado.

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

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

A mesma coisa que acima poderia ser conseguida definindo o valor ModalResult como mrOk para o botão OK e como mrCancel para o botão Cancel nos respetivos processadores de eventos. Quando um utilizador clica em qualquer um dos botões, a caixa de diálogo fecha. Não é necessário chamar o método Close, porque quando o método ModalResult tiver sido definido, o motor de script fecha automaticamente o formulário de script.

Note que, para definir o ModalResult do formulário para cancelar quando um utilizador prime a tecla Esc, defina a propriedade Cancel do botão Cancel como true (marcada) no painel Object Inspector, ou insira Sender.Cancel := True no processador de eventos CancelButtonClick do botão do formulário.

Aceitar Entrada do Utilizador

Um dos componentes mais comuns que pode aceitar entrada de um utilizador é o componente EditBox. Este componente EditBox tem um campo de texto onde um utilizador pode escrever uma cadeia de caracteres. Existem também outros componentes que podem aceitar texto, como o componente masked edit, que é um componente de edição com uma máscara de entrada de campo de texto. A máscara controla, ou filtra, a entrada e é armazenada numa cadeia de parâmetros.

O exemplo abaixo ilustra o que acontece quando um utilizador clica no botão depois de escrever texto na caixa de edição. Note que, se um utilizador não tiver introduzido qualquer texto no componente de edição, o processador 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 um utilizador pode mover o foco de entrada no formulário utilizando a tecla Tab ou clicando noutro controlo do formulário.

Responder a Eventos

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

Escrever Processadores de Eventos

Um script pode precisar de responder a eventos que possam ocorrer a um 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 bloco de código que responde a essa ocorrência. O código de resposta é um processador de eventos, que modifica valores de propriedades e chama métodos.

Juntamente com as propriedades de um componente, cada um tem 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 ao script e o script reage a este novo evento — se o evento OnClick de um botão estiver especificado, ele será executado.

Todos esses componentes também têm um evento para obter 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 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 ative o separador Events no painel Object Inspector. Para criar um procedimento de tratamento de eventos para um componente reagir, escolha um evento adequado e faça duplo clique no seu nome.

Por exemplo, selecione o componente Button1 no painel Tool Palette, coloque-o no formulário de script e faça duplo clique junto ao nome do evento OnClick. O sistema de scripting mudará o foco para o Editor de Código, onde terá sido criado o código-base para o evento OnClick. Se um botão tiver um método Close no seu processador de eventos CloseClick, quando o botão for clicado o seu processador de eventos capta o evento de clique, e o código dentro do processador de eventos é executado. Ou seja, o método Close fecha o formulário de script.

Em resumo, um processador de eventos é criado num script selecionando um componente no formulário, ou com o painel Object Inspector, e depois fazendo duplo clique à direita do evento pretendido (por exemplo, OnClick) no separador Events do Inspector — a estrutura de código apropriada aparecerá no script.

Em alternativa, fazendo duplo clique num botão, o sistema de scripting adicionará um processador para um evento OnClick. Outros tipos de componentes terão ações predefinidas completamente diferentes.

Métodos do Componente

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.

Criar 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, porque o formulário do script trata disso automaticamente — em vez disso, passe um parâmetro Nil ao construtor do componente.

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