DelphiScript

Esta secção descreve a linguagem DelphiScript utilizada pelo Scripting Engine do Altium Designer e fornece detalhes de referência sobre as instruções, funções e extensões suportadas. Estes são procedimentos especiais utilizados para controlar e comunicar diretamente com o Altium Designer.

Também nesta referência:

• Diferenças entre DelphiScript e Delphi
• Palavras-chave de DelphiScript
• Instruções e Operadores de DelphiScript
• Funções de DelphiScript
• Formulários e Componentes de DelphiScript

A linguagem DelphiScript

Esta referência de DelphiScript assume que está familiarizado com os conceitos básicos de programação, bem como com o funcionamento básico do Altium Designer. O sistema de scripting suporta a linguagem DelphiScript, que é muito semelhante ao Embarcadero Delphi™.

A principal diferença é que o DelphiScript é uma linguagem de scripting sem tipos, ou não tipada, o que significa que não é possível definir registos ou classes e passar ponteiros como parâmetros para funções. Ainda assim, as variáveis podem ser declaradas nos scripts para facilitar a legibilidade.

Esta página e as respetivas subpáginas contêm material de referência sobre interfaces, componentes, rotinas globais, tipos e variáveis que constituem a linguagem de scripting DelphiScript.

Elementos principais de DelphiScript

Objetos

Em DelphiScript, um Objeto consiste em métodos e, em muitos casos, propriedades e eventos. As propriedades representam os dados contidos no objeto, os Métodos são as ações que o objeto pode executar e os Eventos são condições às quais o Objeto pode reagir. Todos os Objetos descendem (e herdam) do objeto de nível superior do tipo TObject.

Interfaces de Objetos

Uma Interface de Objeto consiste em métodos e, em muitos casos, propriedades, mas não pode ter campos de dados. Uma Interface representa um Objeto existente e cada Interface tem um GUID que a torna única. As propriedades representam os dados contidos no Objeto ao qual a Interface está associada. Os métodos são as ações que o Objeto (ao qual a interface está associada) pode executar.

Componentes

Os Componentes são objetos visuais do painel Tool Palette que podem ser manipulados em tempo de conceção. Todos os Componentes descendem da classe de sistema TComponent na Visual Component Library (VCL) do Embarcadero Delphi.

Rotinas

As Rotinas Globais são os Procedures e Functions do sistema de scripting. Estas Rotinas não fazem parte de uma classe, mas podem ser chamadas diretamente ou a partir de métodos de classe num script.

Tipos

Os Tipos de Variáveis são utilizados como tipos de retorno e tipos de parâmetros para métodos e propriedades de Interfaces, métodos, propriedades e eventos de objetos e rotinas globais. Em muitos casos, os Tipos estão documentados nas secções de Tipos Enumerados na documentação da API.

Altium Designer e a RTL de Delphi

O sistema de scripting suporta um subconjunto da Run Time Library (RTL) do Embarcadero Delphi e da API do Altium Designer.

Ficheiros-fonte de DelphiScript

No Altium Designer, um projeto de script é organizado para armazenar documentos de script (Units de script e Forms de script). Pode executar o script a partir de um item de menu, de um botão da barra de ferramentas ou da caixa de diálogo Select Item To Run, disponível no menu principal do Altium Designer.

Ficheiros PRJSCR, PAS e DFM

Os scripts são organizados em projetos com uma extensão *.PRJSCR. Cada projeto é composto por ficheiros com uma extensão *.pas. Os ficheiros podem ser Units de script ou Forms de script — tenha em atenção que cada Form tem um ficheiro de script com uma extensão *.pas e um ficheiro Form correspondente com uma extensão *.dfm. Um Form de script é uma janela gráfica (caixa de diálogo) que é executada sobre o Altium Designer e aloja diferentes controlos acessíveis ao utilizador.

É possível associar scripts a diferentes projetos, sendo altamente recomendável organizar os scripts em projetos distintos para gerir o número de scripts e os respetivos procedimentos/funções.

Scripts de exemplo

A coleção de scripts de exemplo ilustra as funcionalidades básicas da programação em DelphiScript, utilizando scripts simples para uso no Altium Designer.

A localização e a finalidade de uma seleção dos scripts de exemplo são indicadas abaixo:

• Scripts\DelphiScript Scripts\DXP pasta - Demonstra a API de Client e de sistema
• Scripts\DelphiScript Scripts\PCB pasta - Demonstra a API de PCB
• Scripts\DelphiScript Scripts\Processes pasta - Demonstra os Processos do servidor
• Scripts\DelphiScript Scripts\General pasta - Demonstra palavras-chave de DelphiScript
• Scripts\DelphiScript Scripts\Sch pasta - Demonstra a API Schematic
• Scripts\DelphiScript Scripts\WSM pasta - Demonstra a API Workspace Manager

Escrever scripts DelphiScript

Convenções de nomenclatura em DelphiScript

Em geral, não existem restrições quanto aos nomes atribuídos a procedimentos, funções, variáveis e constantes, desde que respeitem as seguintes regras:

• O nome pode conter as letras A a Z, a a z, o caráter underscore "_" e os dígitos 0 a 9.
• O nome tem de começar por uma letra.
• O nome não pode ser uma palavra-chave, diretiva ou palavra reservada de DelphiScript.
• Os nomes não são sensíveis a maiúsculas e minúsculas quando interpretados. Podem ser utilizadas letras maiúsculas e minúsculas ao nomear uma função, subrotina, variável ou constante; no entanto, o interpretador não distinguirá entre caracteres maiúsculos e minúsculos. Nomes idênticos exceto na capitalização serão tratados como o mesmo nome em DelphiScript.

Num ficheiro DelphiScript, as funções e procedimentos são declarados utilizando os blocos Procedure-Begin-End ou Function-Begin-End. Ambos estes blocos de instruções exigem que seja atribuído um nome ao procedimento ou à função. O DelphiScript permite criar variáveis e constantes nomeadas para conter valores utilizados no script atual.

Incluir comentários

Num script, os comentários são linhas de código não executáveis incluídas para benefício do programador. Os comentários podem ser incluídos praticamente em qualquer parte de um script.

Qualquer texto após // ou incluído entre (* *) ou {} é ignorado pelo DelphiScript.

//This whole line is a comment

{This whole line is a comment}

{
These lines are comments
These lines are comments
}

(* This whole line is a comment *)
 
(*
These lines are comments
These lines are comments
*)

Os comentários também podem ser incluídos na mesma linha que o código executado. Por exemplo, tudo o que estiver após o ponto e vírgula na linha de código seguinte é tratado como comentário.

ShowMessage ('Hello World'); //Display Message

Variáveis locais e globais

Uma vez que todos os scripts têm variáveis locais e globais, é muito importante ter nomes de variáveis únicos nos scripts dentro de um projeto de script. Se as variáveis forem definidas outside quaisquer procedimentos e funções, são globais e podem ser acedidas por qualquer unit de script no mesmo projeto.

Se as variáveis forem definidas inside de um procedimento ou função, então estas variáveis locais não são acessíveis fora desses procedimentos/funções.

Example of Local and Global Variables in a Script:

// Note: The Uses keyword is not needed.

{ The global variable from UnitA script (see below) is available to this Script Unit,
  as long UnitA is in the same project as this Script Unit. }

Const
  GlobalVariableFromThisUnit='Global Variable from this unit';

Procedure TestLocal;
var
  Local;
Begin
  Local := 'Local Variable';
  ShowMessage(Local);
End;

Procedure TestGlobal;
Begin
  //ShowMessage(Local); // This line produces an error because the 'Local' variable is not global.
  ShowMessage(GlobalVariableFromThisUnit);
  // A variable from UnitA can be accessed without the Uses keyword.
  ShowMessage(GlobalVariableFromUnitA);
End;

UnitA script:

Const
  GlobalVariableFromUnitA = 'Global Variable from Unit A';

Utilizar variáveis nomeadas

Num script, são criadas variáveis ou constantes nomeadas para armazenar valores a utilizar durante a execução do programa. Todas as variáveis num script são sempre do tipo Variant. O typecasting não se aplica, pelo que os Tipos nas declarações de variáveis são ignorados e podem ser omitidos. Estas declarações estão, por isso, corretas:

Var a : integer;
Var b : integer;
Var c, d;

Dividir uma linha

Cada instrução de código termina com o caráter ponto e vírgula ; para indicar o fim da instrução. O DelphiScript permite escrever uma instrução em várias linhas de código, dividindo uma instrução longa em duas ou mais linhas. A única restrição na divisão de instruções de programação por diferentes linhas é que um literal de string não pode estender-se por várias linhas.

For example:

X.AddPoint( 25, 100);
X.AddPoint( 0, 75);
// is equivalent to:
X.AddPoint( 25, 100); X.AddPoint( 0, 75);

however...

'Hello World!'
\\is not equivalent to
'Hello
World!'

O DelphiScript não impõe qualquer limite prático ao comprimento de uma única linha de código num script, mas, por uma questão de legibilidade e facilidade de depuração, é boa prática limitar o comprimento das linhas de código para que possam ser facilmente lidas no ecrã ou em formato impresso.

Se uma linha de código for muito longa, pode dividi-la em várias linhas, e este código será tratado pelo interpretador DelphiScript como se tivesse sido escrito numa única linha.

Unformatted code example:

If Not (PcbApi_ChooseRectangleByCorners(BoardHandle,'Choose first corner','Choose final corner',x1,y1,x2,y2)) Then Exit; 

Formatted code example:

If Not (PcbApi_ChooseRectangleByCorners(BoardHandle,
'Choose first corner',
'Choose final corner',
x1,y1,x2,y2)) Then Exit;

Sensibilidade a maiúsculas e minúsculas

A linguagem DelphiScript utilizada na escrita de scripts não é sensível a maiúsculas e minúsculas — isto é, todas as palavras-chave, instruções, nomes de variáveis, nomes de funções e de procedimentos podem ser escritos sem ter em conta o uso de letras maiúsculas ou minúsculas. Os caracteres em maiúsculas e minúsculas são considerados equivalentes.

Por exemplo, o nome da variável myVar é equivalente a myvar e MYVAR. O DelphiScript trata todos estes nomes como a mesma variável.

A única exceção ocorre nas strings literais, como a string de título de uma definição de caixa de diálogo ou o valor de uma variável do tipo string. Estas strings mantêm as diferenças entre maiúsculas e minúsculas.

O caráter de espaço

Um espaço é utilizado para separar palavras-chave numa instrução de script. No entanto, o DelphiScript ignora quaisquer espaços em branco adicionais numa instrução.

Por exemplo:

X   = 5
// is equivalent to
X =5

Pode utilizar espaços em branco para tornar o seu script mais legível.

Funções e procedimentos num script

O interpretador DelphiScript permite dois tipos de métodos (procedimentos): Procedures e Functions. A única diferença entre uma função e um procedimento é que uma função devolve um valor.

Um script pode ter pelo menos um procedimento que define o código principal do programa. No entanto, pode definir outros procedimentos e funções que podem ser chamados pelo seu código.

Tal como no Embarcadero Delphi, os procedimentos e funções são definidos dentro de um bloco de instruções Begin-End. Para invocar ou chamar uma função ou procedimento, inclua o nome da função ou do procedimento numa instrução da mesma forma que ao utilizar as funções e procedimentos incorporados do DelphiScript. Se a função ou o procedimento exigir parâmetros, estes têm de ser incluídos na instrução de chamada. Tanto as funções como os procedimentos podem ser definidos para aceitar parâmetros, mas apenas as funções podem ser definidas para devolver um valor à instrução de chamada.

Qualquer nome pode ser atribuído a funções e procedimentos quando são definidos, desde que esteja em conformidade com as convenções de nomenclatura padrão do DelphiScript.

Typical DelphiScript Procedure:

Procedure CreateSchObjects;
Begin
  If SchServer = Nil Then Exit;
  SchDoc := SchServer.GetCurrentSchDocument;
 
  If SchDoc = Nil Then Exit;
  PlaceSchematicObjects;
  SchDoc.GraphicallyInvalidate;
End;

Typical DelphiScript Function:

Function BooleanToString(AValue : Boolean) : String;
Begin
  If (AValue) Then Result := 'True'
  Else   Result := 'False';
End;

O nome de uma função não pode ser usado para definir o respetivo valor de retorno. Em vez disso, deve ser utilizada a palavra-chave Result.

Var, Begin-End global block:

Var
  A, B, C;
Begin
  B := 10;
  C := 20;
  A := B + C;
  ShowMessage(IntToStr(A));
End;

Sugestões de Scripting

Referenciar Scripts num Projeto de Script

O código num script pode chamar um procedimento noutro script do mesmo projeto de script. Qualquer variável global em qualquer script pode ser acedida dentro do mesmo projeto.

Variáveis Locais e Globais

Uma vez que os scripts têm variáveis locais e globais, é importante ter nomes de variáveis únicos nos scripts dentro de um projeto de script. Se as variáveis forem definidas fora de quaisquer procedimentos e funções, são globais e podem ser acedidas por qualquer unidade no mesmo projeto. Se as variáveis forem definidas dentro de um procedimento ou função, então essas variáveis locais não são acessíveis fora desses procedimentos/funções.

Recomenda-se colocar scripts de natureza semelhante num projeto e manter o número de scripts num projeto a um tamanho gerível — acompanhar variáveis globais em muitos scripts pode tornar-se um problema. Não é obrigatório armazenar scripts num projeto de script, uma vez que os scripts podem ser colocados noutros tipos de projeto.

Identificadores e Variáveis Únicos

Ao utilizar formulários de script, certifique-se de que todos os formulários de script têm nomes de formulário únicos. É possível ter todos os formulários de script com o nome form1 (por exemplo) no mesmo projeto de script. Neste caso, o sistema de scripting entra em conflito ao tentar apresentar o formulário correto quando um formulário de script é executado.

O nome de um formulário de script pode ser alterado utilizando o Object Inspector. O nome será alterado automaticamente tanto nos ficheiros da unidade de script como nos do formulário de script.

Procedimentos e Funções sem Parâmetros

Os scripts devem ser escritos de forma a que os procedimentos necessários para executar o script apareçam apenas na caixa de diálogo Selecionar Itens a Executar. Para impedir que outros procedimentos/funções apareçam na caixa de diálogo Select Items to Run, pode ser inserido um parâmetro (Dummy : Integer) junto ao nome do método. Veja o exemplo abaixo.

// This function is prevented from appearing in the Select Items to Run dialog.
Function TSineWaveform.CreateShape(Dummy : Integer);
Begin
    //Do something
End;
{..................................................}
 
{..................................................}
Procedure TSineWaveform.bCloseClick(Sender: TObject);
var
  I : integer;
Begin
     //Doing something
Close;
End;
{..................................................}
 
{..................................................}
procedure DrawSine;
Begin
    SineWaveform.showmodal;
End;

Códigos de Erro do DelphiScript