Formulários e Componentes

Visão geral dos componentes gráficos

O sistema de scripts 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 utilizados para diferentes tarefas, tais como Timer, OpenDialog e MainMenu componentes.

• O Timer componente não visual pode ser 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.

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 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 Visível determina se esse 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 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 o utilizador execute uma ação. Por exemplo, um Label é utilizada para apresentar texto estático, uma Edit caixa é utilizada para permitir que um utilizador introduza alguns dados, um Button pode ser utilizado para iniciar ações.

Pode colocar-se qualquer combinação de componentes num formulário e, enquanto o script estiver a ser executado, o utilizador pode interagir com qualquer componente do formulário. Cabe ao programador decidir o que acontece quando um utilizador clica num botão ou altera o texto numa Edit caixa.

O sistema de scripts 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 seu ícone nopainel «Paleta de Ferramentas» e clique duas vezes nele. Esta ação coloca um componente no formulário ativo. A representação visual da maioria dos componentes é definida através das suas 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 é possível alterar o tamanho e a posição posteriormente, utilizando o Object Inspector painel.

Quando um componente é solto num formulário, o sistema de Scripting gera automaticamente o código necessário para utilizar o componente e atualiza o formulário de script. Basta definir as propriedades e implementar o código do manipulador de eventos para utilizar os métodos desejados e fazer com que o componente no formulário funcione.

Conceção de formulários de script

Um formulário de script é concebido para interagir com o utilizador no ambiente. A conceção de formulários de script constitui o cerne 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 *.DFM ficheiro) que tem uma relação com o código de script associado (o *.PAS ficheiro). Para cada formulário de script, existe o .PAS ficheiro e o seu correspondente .DFM ficheiro.

Ao trabalhar com um formulário de script e os seus componentes, todas as propriedades dos elementos podem ser inspecionadas e modificadas utilizando o Object Inspector painel. Pode selecionar mais do que um componente clicando nos componentes enquanto mantém a tecla Shift premida, ou arrastando um retângulo de seleção à volta dos componentes no formulário. Um formulário de script tem um título (a 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 num projeto no Projects painel, clique no Add New to Project no menu de contexto que aparece e escolha um Delphi Script Form opção. Será aberto um novo formulário de script com o nome predefinido de EditScript1.pas.

Exibir um formulário de script

Um script tem de conter um procedimento que exiba o formulário quando o formulário de script for executado. Dentro deste procedimento, o ShowModal método pode ser invocado para o formulário. A Visible propriedade do formulário tem de estar definida como «false» para que o ShowModal método do formulário de script funcionar corretamente.

ShowModal example:

Procedure RunDialog;
Begin
  DialogForm.ShowModal;
End;

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

O ModalResult exemplo de propriedade apresentado abaixo é um pouco mais complexo. Os métodos seguintes no script são utilizados para os botões de um formulário de script. Os métodos fazem com que a caixa de diálogo seja encerrada quando o utilizador clica no OK ou Cancel , o que devolve mrOk ou mrCancel do 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 deste formulário de script, a caixa de diálogo fecha-se. Não é necessário chamar o Close método, porque quando o ModalResult método estiver definido, o motor de script fecha o formulário de script automaticamente.

Note que, se pretender definir o ModalResult para Cancel quando um utilizador premir a Esc tecla, utilize o Object Inspector painel para definir a propriedade Cancel para True, 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 do utilizador é o TEdit componente. Este componente possui um campo onde o utilizador pode introduzir uma sequência de caracteres. Note-se que existem outros componentes do Delphi, tais como TMaskEdit, que é um componente de edição com uma máscara de entrada armazenada numa cadeia de caracteres — isto controla ou filtra a entrada.

O exemplo abaixo ilustra o processo que ocorre quando o utilizador clica no botão após digitar algo na caixa de edição. Se o utilizador não tiver digitado nada no componente de edição (em branco), o manipulador 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-se que o utilizador pode alterar o foco de entrada da caixa de diálogo utilizando a Tab tecla ou clicando noutro controlo do formulário.

Resposta a eventos

Quando se clica num botão num formulário ou num componente, o Sistema de Scripting responde ao receber uma notificação de evento do Altium Designer e ao chamar o método de manipulador de eventos apropriado.

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

Escrever manipuladores de eventos

Cada componente num script de formulário possui um conjunto de nomes de eventos, que são utilizados pelos manipuladores de eventos do script para determinar como o script 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 ao script e este reage a este novo evento. Se o OnClick evento para um botão estiver especificado, este é executado.

O código para responder aos eventos está normalmente contido nos manipuladores de eventos do 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 OnClick evento que é disparado quando um 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 tiver recebido 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 um trecho de código que responde a essa ocorrência. O código de resposta é um manipulador de eventos. Este código modifica valores de propriedades e chama métodos.

Propriedades do componente

Para ver uma lista das propriedades de um componente, selecione um componente e abra 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 abra o Events separador no Object Inspector painel. Para criar um procedimento de tratamento de eventos, selecione o evento ao qual pretende que o componente reaja e clique duas vezes no nome do evento — o sistema de scripts irá inserir automaticamente o código da estrutura do manipulador de eventos.

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

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

Em resumo, selecione um componente de botão, quer no formulário, quer utilizando o Object Inspector painel, selecione a Events página e clique duas vezes no lado direito do OnClick evento e um novo manipulador de eventos aparecerá no script. Em alternativa, clique duas vezes no próprio botão e o sistema de scripts adicionará um manipulador para este OnClick evento. Note que outros tipos de componentes terão ações predefinidas diferentes.

Métodos dos componentes

Para ver uma lista de métodos de um componente, consulte o documento «Referência de Componentes ».

Colocar componentes num formulário de script

Para utilizar componentes do painel «Paleta de Ferramentas» num script, é necessário que exista um formulário de script antes de se poderem arrastar componentes para o formulário. Normalmente, quando os componentes são arrastados para um formulário de script, estes objetos não precisam de ser criados nem destruídos — o formulário de script faz isso automaticamente.

O sistema de scripts 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, inserir código nos manipuladores de eventos e utilizar os métodos necessários para implementar um formulário de script funcional.

Criação de Componentes num Script

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

Personalização de formulários de script

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

• Para forçar um formulário a permanecer na frente de outros painéis abertos, defina a FormStyle propriedade para fsStayOnTop.
• Para definir o comportamento predefinido de um formulário, defina a FormKind para um dos seguintes valores; fkNone, fkNormal, fkServerPanel ou fkModal.
• Se fkModal estiver fechado, o formulário será um formulário modal — ou seja, aguardará a entrada do utilizador antes de prosseguir, por exemplo, para fechar o formulário. Se fkServerPanel então o formulário será apresentado como um painel do servidor. Se fkNormal então o formulário funciona como um formulário normal não modal.
• Para remover as barras de deslocamento predefinidas do formulário, altere o valor do HorzScrollBar e VertScrollBar .
• Para tornar o formulário um quadro MDI ou um elemento filho MDI, utilize a FormStyle .
• Para alterar o estilo da moldura do formulário, utilize a BorderIcons e BorderStyle (os resultados são visíveis em tempo de execução).
• Para alterar o ícone do formulário minimizado, utilize a Icon .
• Para especificar a posição inicial de um formulário na janela da aplicação, utilize a Position propriedade.
• Para especificar o estado inicial do formulário (por exemplo, minimizado, maximizado ou normal), utilize a WindowState propriedade.
• Para definir a área de trabalho do formulário em tempo de execução, utilize a ClientHeight e ClientWidth (note que ClientHeight e ClientWidth representam a área dentro da borda do formulário; Height e Width representam toda a área do formulário).
• Para especificar qual o controlo que tem o foco inicial no formulário em tempo de execução, utilize a ActiveControl propriedade.
• Para passar todos os eventos de teclado para o formulário, independentemente do controlo selecionado, utilize a KeyPreview propriedade.
• Para especificar um menu específico, caso um formulário contenha mais do que um menu, utilize a Menu propriedade.

Atualização de formulários e componentes de script

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

O Update método do formulário de script e muitos dos componentes de script do Tool Palette painel, oferecem uma forma de atualizar o conteúdo gráfico do formulário ou de um ou mais controlos específicos. As linhas que contêm o Update método estão destacadas 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 fragmento de código acima provém do PCB Logo Creator projeto de script, que se encontra na Scripts\Delphiscript Scripts\Pcb\PCB Logo Creator pasta da coleção de scripts disponível para download.