Criação de scripts para componentes gráficos

Esta referência descreve os componentes gráficos suportados para scripting e as suas principais propriedades e métodos.

Os componentes visuais de formulário disponíveis para utilização em scripts do Altium Designer derivam, na sua maioria, da Visual Component Library (VCL) da Embarcadero, que é uma coleção de componentes visuais definidos para o desenvolvimento de aplicações Windows com as linguagens Delphi e C++.

Desenvolvidas como uma biblioteca visual de classes, as classes VCL descendem do objeto TComponent (ele próprio descendente do objeto raiz TObject) numa hierarquia linear de objetos. Por conseguinte, um componente de script comum, como o objeto TButton, herda as propriedades, os métodos e os eventos dos seus objetos ascendentes. Neste caso, a hierarquia de classes é: TObject → TPersistent → TComponent → TControl → TWinControl → TButtonControl → TButton.

Tenha em atenção que os componentes que descendem do objeto TControl são, em geral, componentes visuais (controlos), e os componentes comuns que descendem de TWinControl são, na sua maioria, encapsulamentos da API do Windows.

► Consulte Embarcadero RAD Studio VCL para obter uma visão geral da arquitetura e dos componentes da VCL.

Ao criar um Form no Script Editor do Altium Designer, os componentes são acedidos a partir do painel Tool Palette. Os Script Forms têm um ficheiro *.DFM associado que inclui detalhes sobre a configuração do formulário, a localização dos seus componentes e outros atributos – o ficheiro pode ser encontrado na pasta anfitriã do projeto de script. O Altium Designer permite que os componentes sejam utilizados tanto por DelphiScript como por VBScript ao desenhar Script Forms.

O painel Tool Palette contém controlos visuais categorizados que podem ser colocados num script Form.

O painel Tool Palette panel contém seleções categorizadas de componentes que podem ser colocados num Script Form. Os componentes disponíveis estão reunidos em secções expansíveis no painel Tool Palette, categorizadas como Standard, Additional, Win32, System, Dialogs, Altium Standard e Instrument Controls.

Os componentes (ou “controlos”) disponíveis na Palette são componentes visuais quando utilizados num script form, o que significa que o utilizador pode ver um controlo e, possivelmente, interagir com ele em tempo de execução. Todos os controlos têm propriedades, métodos e eventos que descrevem aspetos da sua aparência, como a propriedade de posição do controlo, métodos para desenhar ou mover o controlo e eventos que respondem a ações do utilizador.

As propriedades e os eventos estão disponíveis no painel Object Inspector panel para o componente de formulário atualmente selecionado, incluindo o próprio formulário. Os métodos são procedimentos e funções suportados por esse componente.

Visão geral dos Script Forms

Script Forms

Um Script Form é a interface principal com o utilizador nos scripts, embora existam outros formulários, como caixas de diálogo, janelas secundárias, entre outros. Para criar um novo Script Form, com um projeto aberto no Altium Designer, selecione File » New » Script » Script Form ou clique com o botão direito do rato no nome do projeto Script e escolha Add New to Project » Script Form. Se a linguagem VBScript estiver ativada, o comando estará disponível tanto para VB Script como para Delphi Script.

Um novo Script Form é apresentado com o nome predefinido Form1, que pode ser alterado através da propriedade Name (em Misc) no painel Object Inspector. Os nomes dos Script Forms devem ser únicos dentro de um projeto.

Ao desenhar um script Form, abra o painel Object Inspector a partir do botão Script na barra de estado inferior.

Um formulário em branco é basicamente uma janela visual à qual podem ser adicionados controlos. Uma caixa de diálogo e um painel são tipos diferentes de formulários e, por predefinição, um formulário inclui funcionalidades padrão de janela, tais como:

• Controlos
• Botões Minimizar e Maximizar
• Barra de título
• Redimensionável ao arrastar a moldura

Estas funcionalidades, juntamente com qualquer outra propriedade de formulário disponível, podem ser alteradas em tempo de conceção através do painel Object Inspector. Como um Script Form é um componente VCL, tem os três itens seguintes:

• Properties – As características de um objeto que influenciam o seu comportamento visível ou as suas operações. Por exemplo, a propriedade Visible determina se um objeto pode ser visto num script form.
• Events – Ações ou ocorrências detetadas pelo script. Um script tem de incluir código para cada manipulador de eventos, que é concebido para capturar um evento específico, como um clique do rato.
• Methods – Procedimentos de script associados a objetos (neste caso, objetos de componente) e que definem o seu comportamento.

► Consulte Writing Scripts para obter um guia básico de desenvolvimento de um script baseado em formulários.

Propriedades, métodos e eventos do formulário

Os controlos do painel Tool Palette baseiam-se na Embarcadero Visual Component Library (VCL). Para obter detalhes completos sobre os métodos, propriedades e eventos do componente Form (TForm), consulte a documentação VCL da Embarcadero.

► Consulte a referência Embarcadero TFormTenha em atenção que a ligação acima se refere à referência Embarcadero RAD Studio XE6 da biblioteca VCL. A documentação de versões anteriores (até à versão de 2010) também está disponível.

Propriedades do TForm

As Propriedades disponíveis para o objeto de componente TForm, o formulário base do script, podem ser visualizadas das seguintes formas:

• Através do painel Object Inspector – na vista Form do editor (separador Form selecionado), clique no corpo do próprio formulário e selecione o separador Object Inspector's Properties .

Tenha em atenção que apenas os objetos de componentes visuais aparecerão no painel. Os objetos não visuais, que funcionam como controlos nos bastidores, não são apresentados no formulário.

• Utilizando a funcionalidade de conclusão de código – na vista Code do editor (separador Code selecionado), a janela de conclusão de código sensível ao contexto apresentará todas as opções de código para o nome de um objeto.

Para o objeto Form, introduza TForm. (tenha em atenção o ponto final) para ativar a janela. Restrinja a pesquisa escrevendo as primeiras letras da propriedade pretendida – tenha em atenção que são apresentadas tanto propriedades como métodos.

• A partir da documentação de referência da Embarcadero na página TForm Properties reference page.

Métodos do TForm

Os Métodos disponíveis para o objeto de componente TForm podem ser visualizados das seguintes formas:

• Utilize a funcionalidade de conclusão de código – na vista Code do editor, escreva o nome de um componente seguido de um ponto final. A janela de conclusão de código abrir-se-á para apresentar os métodos de código (e propriedades) de um nome de objeto. Tenha em atenção que a janela de código pode ser ativada manualmente com as teclas de atalho Crtl+Space.

• Consulte a documentação de referência da Embarcadero na página TForm Methods reference page. Tenha em atenção que esta apresenta todos os métodos herdados, embora essa opção possa ser desmarcada.

Eventos do TForm

Os Eventos disponíveis para o objeto de componente TForm podem ser visualizados das seguintes formas:

• O painel Object Inspector – na vista Form do editor, clique no corpo do próprio formulário e selecione o separador Events do Object Inspector.

• A documentação de referência da Embarcadero na página TFrom Events reference page.

Propriedades, eventos e métodos dos componentes

Os controlos do painel Tool Palette baseiam-se na Embarcadero Visual Component Library (VCL). Para obter detalhes completos sobre os métodos, propriedades e eventos da maioria dos componentes, consulte as categorias de componentes na documentação VCL da Embarcadero. Alguns tipos de Component no Tool Palette, em particular os Altium Instrument Controls, são exclusivos do Altium Designer e não estão incluídos na documentação de referência da Embarcadero.

► Consulte o Índice de categorias de componentes VCL da EmbarcaderoTenha em atenção que a ligação acima se refere à referência Embarcadero RAD Studio XE6 para a biblioteca VCL. A documentação de versões anteriores (até à versão de 2010) também está disponível.

Propriedades dos componentes

Para ver uma lista de Propriedades de um componente:

• Selecione um componente no Form e ative o separador Properties no painel Object Inspector – como mostrado acima para o objeto de componente TForm.
• Selecione a ligação Properties (no topo) na página de referência do componente apropriado na documentação de referência da Embarcadero. No caso do controlo TButton, por exemplo, selecione a categoria Standard Component, a página TButton e depois a vista Properties.

Eventos dos componentes

Para ver uma lista de Eventos aos quais um componente pode reagir:

• Selecione um componente no Form e ative o separador Events no painel Object Inspector – como mostrado acima para o objeto de componente TForm.
• Selecione uma página de referência de componente apropriada e depois a respetiva ligação Events na documentação de referência da Embarcadero. Tenha em atenção que isto é útil como guia para os eventos disponíveis de um componente e pode não corresponder totalmente aos eventos disponíveis para os componentes de scripting do Altium Designer.

Para criar um procedimento de tratamento de eventos, escolha o evento ao qual o componente deve reagir no separador Object Inspector Events e faça duplo clique no campo de entrada do Evento. O procedimento de tratamento de eventos, nomeado com base no componente e na ação do evento, é então gerado automaticamente no script. Se o evento for renomeado no painel Object Inspector, então o procedimento de código correspondente é renomeado em conformidade.

Métodos dos componentes

Isto inclui referências para as seguintes categorias de objetos de controlo.

• Standard
• Additional
• Win32
• System
• Dialog
• Altium Standard
• Instrument Controls

Na sua maioria, estas categorias agrupam tipos de controlos visuais de formulário com base em componentes VCL padrão do tipo Delphi. As categorias Altium Standard e Instrument Controls são a exceção, uma vez que oferecem componentes exclusivos do sistema de scripting do Altium Designer.

► Consulte Tool Palette Component Categories.

Trabalhar com Forms e componentes

Personalizar Script Forms

• Para fazer com que um formulário permaneça sobre os outros painéis abertos, por exemplo, defina a propriedade FormStyle como fsStayOnTop.
• Para definir o comportamento predefinido de um formulário, defina FormKind para um dos seguintes valores: fkNone, fkNormal, fkServerPanel ou fkModal.
  • Se fkModal estiver selecionado, então o formulário será modal. Ou seja, um formulário que fica à espera da introdução do utilizador antes de prosseguir com ações como fechar o formulário.
  • Se fkServerPanel estiver selecionado, então o formulário será apresentado como um painel do Servidor.
  • Se fkNormal estiver selecionado, então o formulário comporta-se como um formulário normal não modal.
• Para adicionar/remover as barras de deslocamento de um formulário, altere o valor das propriedades HorzScrollBar e VertScrollBar.
• Para tornar o formulário numa moldura ou filho MDI (Multiple Document Interface), utilize a propriedade FormStyle.
• Para alterar o estilo do contorno de um 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 de um formulário (por exemplo, minimizado, maximizado ou normal), utilize a propriedade WindowState.
• Para definir a área de trabalho de um 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, enquanto Height e Width representam toda a área do formulário.
• Para especificar que controlo tem o foco inicial num formulário em tempo de execução, utilize a propriedade ActiveControl para escolher entre os componentes disponíveis.
• Para passar todos os eventos do teclado para um formulário, independentemente do controlo selecionado, utilize a propriedade KeyPreview.
• Para especificar um menu em particular, se um formulário contiver mais do que um menu, utilize a propriedade Menu.

Atualizar formulários e componentes

Em alguns casos, o aspeto visual de um formulário de script pode ficar desatualizado, por exemplo, se um processamento intensivo em segundo plano de um script fizer com que os controlos não sejam atualizados nem redesenhados, parecendo bloqueados ou corrompidos.

O método Update do formulário de script fornece uma forma programática de atualizar o conteúdo gráfico de um formulário ou de controlo(s) específico(s). No exemplo de código abaixo, as linhas de código do método Update estão destacadas a cinzento.

Using the Update method to refresh the Status Bar:

Procedure TConverterForm.loadbuttonClick(Sender: TObject);
Var
   I, J : Integer;
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
            For J := 0 to Image1.Picture.Height – 1 Do
                For I := 0 to Image1.Picture.Height – 1 Do
            Begin
                If Image1.Canvas.Pixels[I,J] <> clWhite Then
                    Image1.Canvas.Pixels[I,J] := clBlack;
            End;
        End;

        ScalingFactorChange(Nil);

        convertbutton.Enabled  := True;
        LoadButton.Enabled     := False;
        XStatusBar1.SimpleText := '  Ready...';
        XStatusBar1.Update;
    End;
End;

Consulte o projeto de script PCB Logo Creator, localizado na pasta Scripts\Delphiscript Scripts\PCB\PCB Logo Creator da coleção transferível de scripts .