VBScript

Esta referência descreve a linguagem de script Visual Basic utilizada para criar scripts no Altium Designer. Apresenta detalhes sobre as instruções, funções e extensões do Visual Basic Scripting que são suportadas pelo sistema de script.

Também nesta referência:

• Instruções VBScript
• Sub-rotinas e funções do VBScript
• Utilização de componentes de formulário com VBScript

A linguagem VBScript

O Visual Basic Scripting (ou VBScript, para abreviar) pode ser utilizado para criar scripts que lidam com os modelos de objetos e os componentes visuais do Altium Designer. Nesta referência, pressupõe-se que esteja familiarizado com os conceitos básicos de programação e com o funcionamento básico do Altium Designer.

O sistema de scripts do Altium Designer suporta a linguagem VBScript (juntamente com outras linguagens de script), que deriva do sistema Microsoft ActiveX Scripting. Assim, por exemplo, deverá poder utilizar CScripts ou WScripts, que se baseiam no mesmo motor de scripts ActiveX utilizado no Altium Designer.

Todas as linguagens de script suportadas no Altium Designer são sem tipos ou não tipadas, o que significa que um script não pode definir registos ou classes nem passar ponteiros como parâmetros para funções.

VBScript script example

Sub DisplayName (sName)
  MsgBox "My Name is " & sName
End Sub

O Altium Designer e a RTL do Delphi

O sistema de scripts suporta um subconjunto da Biblioteca de Tempo de Execução (RTL) do Embarcadero Delphi e da API do Altium Designer.

Os scripts VBScript podem aceder a vários modelos de objetos no Altium Designer. Por exemplo, o modelo de objetos PCB pode ser utilizado em scripts VBScript para lidar com objetos PCB num documento PCB, ou o modelo de objetos do Gestor de Espaço de Trabalho para trabalhar com projetos e os seus documentos, a fim de extrair dados da lista de ligações.

A Referência de Scripts contém informações sobre interfaces relativas aos modelos de objetos do Altium Designer, componentes, rotinas globais, tipos e variáveis que compõem esta linguagem de script. Consulte a documentação do Microsoft Visual Basic para obter mais informações sobre as funções do VBScript.

Processos do servidor

É possível utilizar um script para executar processos de servidor, que representam comandos no Altium Designer.

Ficheiros-fonte VBScript

Um projeto VBScript está organizado para armazenar documentos de script (unidades de script e formulários de script). Um script pode ser executado a partir de um item de menu, de um botão da barra de ferramentas ou da caixa de diálogo Run Script caixa de diálogo do menu do sistema.

Ficheiros PRJSCR, VBS e DFM

Os scripts são organizados em projetos com uma *.PRJSCR extensão. Cada projeto VBScript é composto por ficheiros com uma *.vbs extensão. Os ficheiros podem ser unidades de script ou formulários de script — cada formulário tem um ficheiro de script VBScript com *.vbs extensão e um formulário correspondente com uma *.dfm extensão). Um formulário de script é uma janela gráfica (caixa de diálogo) que aloja diferentes controlos que são executados sobre o Altium Designer.

É possível associar scripts a diferentes projetos, sendo altamente recomendável organizá-los em projetos distintos para gerir o número de scripts e os seus procedimentos/funções. Os scripts (unidades de script e formulários de script) consistem em funções/procedimentos que podem ser chamados no Altium Designer.

Exemplos de VBScript

Os exemplos simples incluídos nesta referência ilustram as funcionalidades básicas da programação em VBScript no Altium Designer.

Os VBScripts podem utilizar formulários de script, unidades de script, funções e objetos da API de scripting do Altium Designer, bem como um subconjunto de funções e objetos do Embarcadero Delphi RTL que estão disponíveis no sistema de scripting.

Escrever scripts VBScript

Esta secção aborda os conceitos básicos da criação de scripts VBScript no Altium Designer.

Convenções de nomenclatura do VBScript

As variáveis VBScript não distinguem maiúsculas de minúsculas — ou seja, variáveis em maiúsculas e minúsculas têm o mesmo significado:

Example

The variables b and B are the same.
b = 60
B = 60

Variáveis locais e globais

Uma vez que todos os scripts têm variáveis locais e globais, é importante que os nomes das variáveis sejam únicos nos seus scripts dentro de um projeto de script. Se as variáveis forem definidas outside em sub-rotinas e funções, estas são globais e podem ser acedidas por qualquer unidade no mesmo projeto.

Se as variáveis forem definidas inside uma rotina, essas variáveis locais não são acessíveis fora dessas rotinas. Uma vez que os scripts não têm tipos, as variáveis não são inicializadas com os seus tipos.

As variáveis locais dentro de um procedimento são inicializadas automaticamente.

Variable Initialization

Sub Example
  Dim X
  Dim s
  ' x set to 0
  x =  0
  ' s set to empty
  s = ""
End Sub

Sub-rotinas e funções

O VBScript permite dois tipos de procedimentos: sub-rotinas e funções — uma função devolve apenas um valor. A sintaxe para chamar uma sub-rotina ou função num script é:

Call SubRoutineA(parameters)
...ou
SubRoutine parameters

Subroutine example

Sub SetTheHeight AHeight
  Set Component.Height = AHeight
End Sub

Function example

Function Addone(value)
  AddOne = Value + 1
End Function

Another Function example

Function Test(s)
 Test = S + " rules.."
End Function
 
Sub DisplayName (sName)
 MsgBox sName
End Sub
 
Sub Main
Dim S
 S = "Altium Designer"
 DisplayName Test(s)
End Sub

Parâmetros e argumentos

No VBScript, a declaração de um procedimento inclui normalmente uma lista de parâmetros — note-se que as variáveis são consideradas sem tipo e que o sistema de scripts determina automaticamente quais são os tipos das variáveis. O valor utilizado no lugar do parâmetro quando se efetua uma chamada ao procedimento é designado por argumento.

Example of a subroutine with a parameter

Sub DisplayName (sName)
  MsgBox "My Name is " & sName
End Sub

Example of calling a subroutine

Sub Main
  DisplayName "Altium Designer  Rules"
End Sub

Note-se que a utilização da Call para invocar uma sub-rotina ou uma função é opcional (mantida por motivos de compatibilidade com versões anteriores).

Comentários nos scripts

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

Nos comentários do VBScript:

• Qualquer texto que se siga a ' é ignorado.
• Qualquer texto que se siga a Rem é ignorado.

Example

' This whole line is a comment
REM this whole line is also a comment
DocName = Document.Name ' Get name of active document

Divisão de uma linha de script

No VBScript, cada instrução de código termina na linha (através de uma combinação de CR/LF) para indicar o fim da instrução. O VBScript permite escrever uma instrução em várias linhas de código, para dividir uma instrução longa em duas ou mais linhas, utilizando o caractere de sublinhado (_).

O VBScript não impõe qualquer limite prático ao comprimento de uma única linha de código num script. No entanto, 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 na versão impressa. Se uma linha de código for muito longa, pode ser dividida em várias linhas, e esse código será tratado pelo interpretador VB 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 EndIf

Formatted code example

If Not (PcbApi_ChooseRectangleByCorners(BoardHandle,_ 
                                        “Choose first corner”,_ 
                                        “Choose final corner”,_ 
                                        x1,y1,x2,y2)) Then EndIf

Utilização dos Modelos de Objetos do Altium Designer

A principal característica do sistema de scripts é que as interfaces dos objetos do Altium Designer (Interfaces de Objeto) estão disponíveis para utilização em VBScripts. Por exemplo, é possível atualizar objetos de projeto em documentos de esquemático e de PCB através da utilização das interfaces de esquemático e das interfaces de PCB, respetivamente.

As Interfaces de Objetos do Altium Designer estão disponíveis para utilização em qualquer script. Normalmente, nos scripts, não é necessário instanciar uma interface. A interface que representa um objeto existente do Altium Designer é extraída e, a partir dessa interface, os objetos de interface incorporados ou agregados podem ser extraídos para obter ou definir os valores das suas propriedades.

Para aceder a um documento PCB e aos seus objetos de dados, deve primeiro invocar a PCBServer função. Por convenção, os nomes das interfaces são precedidos por um I — por exemplo, IPCB_Board representa uma interface para um documento PCB existente no Altium Designer.

Example

' Checks if the current document is a Schematic document
  If SchServer Is Nothing Then Exit Sub
  Set CurrentSheet = SchServer.GetCurrentSchDocument
  If CurrentSheet Is Nothing Then Exit Sub

Para aceder a um documento PCB, invoque a PCBServer.

Creation of a PCB Object Using the PCB Object Model

Sub ViaCreation
  Dim Board
  Dim Via
  Set Board = PCBServer.GetCurrentPCBBoard
  If Board is Nothing Then Exit Sub
  ' Create a Via object
  Via = PCBServer.PCBObjectFactory(eViaObject, eNoDimension, eCreate_Default)
  Via.X = MilsToCoord(7500)
  Via.Y = MilsToCoord(7500)
  Via.Size   = MilsToCoord(50)
  Via.HoleSize   = MilsToCoord(20)
  Via.LowLayer   = eTopLayer
  Via.HighLayer = eBottomLayer
  ' Put this via in the Board object
  Board.AddPCBObject(Via)
End Sub

Objetos, Interfaces e Funções

Os objetos, interfaces e funções do Altium Designer podem ser acedidos em scripts a partir do seguinte:

• API do Cliente
• API do servidor de PCB
• API do servidor de esquemas
• API do servidor do Gestor do Espaço de Trabalho
• API do Nexus
• Funções da API do Altium Designer
• Processos paramétricos

Palavras e funções reservadas

O sistema de scripts suporta a linguagem VBScript, que deriva da tecnologia de linguagem Microsoft Active Scripting. As palavras reservadas do VBScript são:

A, B
Abs, Array, Asc, Atn
C
Call, Case, CBool, CByte, CCur, CDate, CDbl, Chr, CInt, Class, CLng, Const, Conversions, Cos, CreateObject, CSng, CStr
D, E
DateAdd, DateDiff, DatePart, DateSerial, DateValue, Day, Derived Math, Dim, Do, Each, Erase, Escape, Empty, Eval, Execute, Exit, Exp
F, G, H
False, Filter, For, FormatCurrency, FormatDateTime, FormatNumber, FormatPercent, Function GetLocale, GetObject, GetRef, Hex, Hour
I, L, M
If, Is, InputBox, Instr, InStrRev, Int, IsArray, IsDate, IsEmpty, IsNull, IsNumeric, IsObject, Join, LBound, LCase, Left, Len, LoadPicture, Log, LTrim, Maths, Mid, MInute, Month, MonthName, MsgBox
N, O
Next, Nothing, Now, Null, Oct, On Error
P, R
Private, Property, Public, Randomize, ReDim, Rem, RTrim, Replace, RGB, Right, Rnd, Round
S, T
ScriptEngine, ScriptEngineBuildVersion, ScriptEngineMajorVersion, ScriptEngineMinorVersion, Second, Select, Set, SetLocale, Sgn, Sin, Space, Split, Sqr, Stop, StrComp, String, StrReverse, Sub, Tan, Then, Time, Timer, Timeserial, TimeValue, Trim, True, TypeName
U, V, W, X, Y
UCase, Unescape, While, Wend, With, VarType, Weekday, WeekdayName, Year