Writing Scripts

Escrever Scripts

Há um conjunto de conceitos e termos essenciais que se aplicam à escrita de scripts:

• Os processos são cadeias de comandos que pode utilizar para executar comandos em scripts.
• Os componentes são objetos de controlo visual no painel Tool Palette panel que pode arrastar e largar num formulário de script para manipular o design.
• Um componente colocado num formulário de script tem métodos, propriedades e eventos.
• As interfaces de objeto são interfaces de objeto especiais que pode utilizar para extrair e modificar dados em documentos de design a partir dos seus scripts.

Linguagens de Script

A linguagem de script predefinida está definida como DelphiScript (*.pas). O próprio motor de scripting é escrito em Embarcadero Delphi, e o painel Tool Palette baseia-se na VCL (Visual Component Library) do Delphi.

Uma Unit DelphiScript

Um exercício de scripting rápido e básico pode ser realizado criando primeiro um novo projeto e ficheiro de script. Assumindo que o projeto e o ficheiro de script estão definidos para a linguagem DelphiScript, pode introduzir-se um script simples de 'Hello World' como abaixo.

Procedure ShowAMessage;
Var
 DefaultMessage;
Begin
 DefaultMessage := 'Hello World!';
 ShowMessage(DefaultMessage);
End;

Dentro do procedimento, existe uma função ShowMessage padrão de DelphiScript que abre uma caixa de diálogo com a mensagem "Hello World", tal como definido pela variável DefaultMessage.

Executar o Script

Para executar um dos scripts, selecione File » Run Script nos menus principais e depois escolha um procedimento de script disponível na caixa de diálogo Select Item To Run. Quando uma versão é executada, abre-se uma caixa de diálogo para apresentar a mensagem.

Execução de uma HelloWorld unit de script simples a partir do menu File » Run Script.

Um script também pode ser executado utilizando o comando Run do editor, acedido pelo botão Run (), pela tecla de atalho F9 , ou selecionando Run » Run nos menus principais.

Juntamente com o próprio comando Run, o menu pendente Run oferece um conjunto de comandos de controlo e depuração de scripts.

Quando o comando Run é selecionado pela primeira vez, a caixa de diálogo Select Item to Run abre-se, permitindo especificar o procedimento principal de um script (ShowAMessage neste caso). Depois de definido, o script torna-se fácil de executar repetidamente a partir do editor usando o comando Run . Utilize Run » Set Project Startup Procedure para alterar a definição para um procedimento diferente, ou feche e volte a abrir o projeto de script para limpar a definição.

Para parar um script em execução, utilize o botão Stop (), selecione Run » Stop no menu principal, ou utilize o atalho Ctrl+F3.

Desenvolvendo o projeto HelloWorld criado acima, pode ser criado um script semelhante usando uma unit de formulário.

Um Script Form é uma janela de diálogo que pode alojar uma variedade de controlos, como botões, memos e caixas de lista. Tem manipuladores de eventos que respondem quando um controlo gera um evento, como quando se clica num botão.

Para criar o novo formulário de script, clique com o botão direito do rato no nome do projeto no Projects panel, escolha a opção Add New to Project e selecione Script Form. O script pode ser guardado e renomeado usando File » Save As nos menus principais.

Com um novo projeto de script estabelecido, adicione um novo script ao projeto.

Para ver e editar os valores das propriedades do formulário atualmente em foco ou dos seus componentes, abra o painel Object Inspector. O painel Object Inspector é utilizado para alterar as propriedades do formulário e inserir código nos manipuladores de eventos associados ao formulário atual.

A configuração e as propriedades da janela do Script Form são demonstradas no painel Object Inspector.

Tenha em atenção que o Script Form oferece dois separadores na parte inferior do documento: os separadores Code e Form .

O separador Code contém os manipuladores de eventos e procedimentos, como mostrado acima, enquanto o separador Form representa a caixa de diálogo e tem controlos e manipuladores de eventos associados. Utilize os separadores ou a tecla de atalho F12 para alternar entre os dois.

O painel Object Inspector permite-lhe inspecionar e editar as propriedades e os eventos dos componentes no formulário de script ativo. Clicar num único componente no formulário de script ativo na janela do editor de design irá selecionar o componente e apresentar os respetivos atributos no painel Object Inspector. Em alternativa, utilize o campo pendente no topo do painel para escolher a partir de uma lista de todos os componentes atualmente colocados no formulário ativo. O próprio formulário também está incluído.

 
Utilize o painel Object Inspector para configurar a caixa de diálogo do formulário e a sua ação.

A informação é apresentada em dois separadores – Properties e Events:

• O separador Properties do painel lista todos os atributos de propriedade do componente selecionado. A lista exata de atributos disponíveis dependerá do tipo específico de componente atualmente em inspeção. Uma propriedade é uma característica de um objeto que influencia o seu comportamento visível ou o seu funcionamento. Por exemplo, a propriedade Visible (na subcategoria Behavior ) determina se o objeto é ou não apresentado no formulário de script em que foi colocado. As propriedades de um componente podem ser modificadas conforme necessário. Clique dentro do campo à direita de uma propriedade e escreva diretamente, alterne uma caixa de verificação ou selecione uma entrada de uma lista pendente, conforme apropriado.
• O separador Events do painel fornece uma lista de todos os eventos aos quais o componente atualmente selecionado pode reagir. Mais uma vez, a lista exata de eventos disponíveis dependerá do tipo específico de componente atualmente em inspeção. Quando ocorre um evento, como o clique num botão de um formulário, o script executará a ação apropriada, desde que tenha sido definido no código um procedimento de tratamento para o evento. Este tipo de procedimento é designado por manipulador de eventos.

A base estrutural para um manipulador de eventos pode ser adicionada ao código do documento de script a partir do painel Object Inspector. Basta selecionar o componente para o qual pretende definir um evento, escolher o tipo específico de evento e depois fazer duplo clique dentro do campo à direita do evento. É criado um nome para o evento e utilizado na definição do nome do procedimento de tratamento do evento - FormName.EventName. O código-base para o procedimento de tratamento do evento é então adicionado ao código principal do script, que passa a ser o separador ativo no espaço de design. O preenchimento do procedimento de tratamento do evento pode depois ser programado para fornecer a resposta pretendida quando o evento ocorre e é detetado pelo script em execução.

A secção inferior do painel fornece uma descrição resumida da propriedade ou evento atualmente selecionado, quando disponível.

Para este script de formulário, altere as propriedades Caption do formulário no painel Object Inspector de HelloWorldForm para Hello World!. Estas cadeias correspondem às utilizadas no exemplo de manipulador de eventos e código de procedimento mostrado mais abaixo.

Adicionar e Configurar Controlos

Com o formulário básico configurado, podem ser adicionados controlos à caixa de diálogo conforme necessário, acedendo ao painel Tool Palette. O Tool Palette, baseado na Visual Component Library do Delphi, é uma paleta de componentes que oferece uma vasta gama de controlos de janela organizados como categorias de componentes (consulte as páginas  Scripting Graphical Components e  Component Categories para mais detalhes).

As secções do painel Tool Palette podem ser expandidas e recolhidas utilizando os separadores de cabeçalho da região.

Utilize os controlos na parte superior do painel, os nomes das categorias e o menu de contexto obtido com o botão direito do rato para configurar a apresentação dos controlos no painel: expandir/recolher categorias, alterar a apresentação dos itens da paleta, etc.

Para a versão em caixa de diálogo do projeto "Hello World", existem dois botões no formulário - Display e Close. Clique em TButton na região Standard do painel Tool Palette.

Faça isto duas vezes para colocar dois botões no formulário. Um botão será utilizado para apresentar uma mensagem "Hello World!" numa caixa de diálogo separada, e o segundo botão será utilizado para fechar a caixa de diálogo principal.

Todos os componentes no painel têm Propriedades, Métodos e Eventos associados, em que:

• Uma Property é uma característica de um objeto que influencia o seu comportamento visível ou as suas operações. Por exemplo, a propriedade Visible determina se um objeto pode ser visto num formulário de script.
• Um Method é um procedimento que está sempre associado a um objeto e define o comportamento desse objeto.
• Um Event é uma ação ou ocorrência detetada pelo script. Num script, o programador escreve código para cada Event Handler, concebido para captar um evento específico, como um clique do rato.

As propriedades e os eventos de um componente podem ser inspecionados e modificados após a sua colocação utilizando o painel Object Inspector.

Utilizando o painel Object Inspector, as configurações dos dois botões podem ser alteradas dos nomes e legendas predefinidos.

Configure o nome do primeiro botão para bDisplay e a respetiva legenda para Display. Configure o nome do segundo botão para bClose e a respetiva legenda para Close. Isto serve para corresponder ao código de exemplo do manipulador de eventos apresentado abaixo.

Selecione um componente e edite as suas propriedades no painel Object Inspector.

O código do manipulador de eventos pode ser construído referenciando diretamente os controlos no formulário. Neste exemplo, o botão Display irá desencadear uma caixa de diálogo ShowMessage sobre o formulário existente, e a ação do botão Close irá fechar este formulário.

Código do Manipulador de Eventos

Fazer duplo clique no botão Display irá abrir o formulário na vista Code e criar o código esqueleto para o respetivo manipulador de eventos. Em alternativa, selecione o botão e depois o separador Events no painel Object Inspector. Fazer duplo clique no evento OnClick no painel abrirá a vista de código como acima. Na vista Code, a instrução ShowMessage pode ser incluída no manipulador de eventos, como mostrado na listagem abaixo.

Procedure THelloWorldForm.bDisplayClick(Sender: TObject);
Begin
 ShowMessage('Hello World!');
End;

Procedure THelloWorldForm.bCloseClick(Sender: TObject);
Begin
 Close;
End;

Com os manipuladores de eventos definidos, é necessário existir um procedimento no script que seja usado como ponto de partida ao chamar a caixa de diálogo a partir do software. Isto é adicionado no final do script de código.

Note que o nome do formulário é HelloWorldForm e o nome do procedimento é RunHelloWorld — é importante ter nomes de formulário únicos no mesmo script para evitar conflitos de nomes de formulário.

Procedure RunHelloWorld;
Begin
 HelloWorldForm.ShowModal;
End;

O script pode ser guardado e depois executado a partir dos menus principais (File» Run Script) executando o item de procedimento RunHelloWorld sob a entrada HelloWorldDialog.

Em alternativa, o procedimento pode ser atribuído ao comando/botão Run () através do menu Run » Set Startup Project Procedure.

Executar um script de formulário HelloWorld, em que o botão Display do formulário ativa uma caixa de diálogo ShowMessage.

O painel Object Inspector facilita a alteração das propriedades e eventos de uma unidade de formulário. Por exemplo, para alterar a posição do formulário na área de trabalho, utilize o painel para modificar o valor poScreenCenter da propriedade de posição do formulário. A caixa de diálogo será agora colocada no centro do ecrã do ambiente de trabalho quando o script for executado.

Chamar um Procedimento

Como mencionado acima, qualquer script (que utilize o mesmo conjunto de linguagens) dentro de um projeto tem acesso a variáveis e procedimentos globais, pelo que um procedimento num script pode chamar outro procedimento num script diferente do projeto.

Isto pode ser demonstrado pela secção de código adicional ShowAParametricMessage no projeto de exemplo HelloWorld:

Procedure ShowAParametricMessage(S : String);
Var
    DefaultMessage;
Begin
    DefaultMessage := 'Hello World!';

    If S = '' Then ShowMessage(DefaultMessage)
              Else ShowMessage(S);
End;

Isto estabelece uma variável de cadeia de caracteres 'S' que pode ser passada ao procedimento ShowAParametricMessage.

A cadeia de caracteres passada será apresentada utilizando a função de caixa de diálogo ShowMessage, enquanto um método If-Then-Else simples faz com que seja apresentada uma mensagem predefinida "Hello World!" se a cadeia estiver vazia.

Para ver isto em ação, abra o projeto de exemplo (HelloWorld.PrjScr) e adicione a linha destacada a cinzento ao script HelloWorldDialog (não ao script HelloWorld), como mostrado abaixo.

...
Procedure THelloWorldForm.bDisplayClick(Sender: TObject);
Begin
    Showmessage('Hello World!');
End;

Procedure THelloWorldForm.bCloseClick(Sender: TObject);
Begin
    ShowAParametricMessage('Goodbye World');
    close;
End;

Procedure RunHelloWorld;
Begin
    HelloWorldForm.ShowModal;
End;
...

Quando o script HelloWorldDialog é executado e o botão Close é clicado, o procedimento global ShowAParametricMessage é chamado a partir do script HelloWorld.

Um procedimento paramétrico no script HelloWorld é chamado a partir do script HelloWorldDialog.

A chamada passa a cadeia de mensagem "Goodbye World" ao procedimento ShowAParametricMessage, pelo que esta mensagem é apresentada quando se clica no botão Close, antes de o formulário fechar.

A chamada de script mostrada acima insere uma mensagem especificada no procedimento de fecho do formulário HelloWoldDialog.

Se o parâmetro de cadeia passado estiver vazio, ShowAParametricMessage(''), a mensagem predefinida "Hello World!" é apresentada conforme definido no procedimento ShowAParametricMessage.

Navegar pelos Identificadores do Script com o Painel Code Explorer

O painel Code Explorer fornece um resumo visual de todos os identificadores (variáveis, funções e procedimentos) utilizados no documento de script ativo.

O painel Code Explorer

A informação de identificadores que aparece no painel está agrupada nas seguintes pastas de nível superior:

• Procedures & Functions – inclui todos os procedimentos e funções declarados no documento de script ativo. Para cada procedimento/função, quaisquer parâmetros passados ao procedimento/função ou variáveis locais ao mesmo também são listados.

  

• Variables – inclui todas as variáveis globais declaradas no documento de script ativo.

  

Se forem declaradas variáveis locais para um procedimento/função, estas aparecerão listadas numa subpasta de variáveis, sob esse procedimento/função. São utilizados ícones únicos para distinguir os vários identificadores:

Fazer duplo clique numa entrada no painel (ou selecioná-la e premir a tecla Enter) irá levá-lo para a área correspondente do código no espaço de trabalho.