VBScript

Esta referência descreve a linguagem de scripting VisualBasic utilizada para criar scripts no Altium Designer. Fornece detalhes sobre as instruções, funções e extensões de VisualBasic Scripting suportadas no sistema de scripting.

Também nesta referência:

• Instruções do VBScript
• Subrotinas e Funções do VBScript
• Utilizar Componentes de Formulário com VBScript

A Linguagem VBScript

O Visual Basic Scripting (ou VBScript, abreviadamente) pode ser utilizado para criar scripts que interagem com os Modelos de Objetos e Componentes Visuais do Altium Designer. Nesta referência, assume-se que está familiarizado com os conceitos básicos de programação e com o funcionamento básico do Altium Designer.

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

Todas as linguagens de scripting suportadas no Altium Designer são sem tipo 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

Altium Designer e a RTL do Delphi

O sistema de scripting suporta um subconjunto da Embarcadero Delphi Run Time Library (RTL) 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 trabalhar com objetos PCB num documento PCB, ou o Modelo de Objetos Workspace Manager para trabalhar com Projetos e os respetivos documentos para extrair dados de netlist.

A Referência de Scripting contém informações sobre interfaces relativas aos Modelos de Objetos do Altium Designer, componentes, rotinas globais, tipos e variáveis que constituem esta linguagem de scripting. Consulte a documentação do Microsoft Visual Basic para obter mais informações sobre funções VBScript.

Processos do Servidor

Um script pode ser utilizado para executar processos do servidor, que representam comandos no Altium Designer.

Ficheiros-fonte VBScript

Um projeto VBScript é 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, botão da barra de ferramentas ou a partir da caixa de diálogo Run Script no menu do sistema.

Ficheiros PRJSCR, VBS e DFM

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

É possível anexar scripts a diferentes projetos, sendo altamente recomendável organizar os scripts 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 VBScript no Altium Designer.

Os scripts VBScript 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 da RTL do Embarcadero Delphi que estão expostos no sistema de scripting.

Escrever Scripts VBScript

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

Convenções de Nomenclatura do VBScript

As variáveis VBScript não são sensíveis a maiúsculas e 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 ter nomes de variáveis únicos nos seus scripts dentro de um projeto de script. Se as variáveis forem definidas outside quaisquer subrotinas e funções, são globais e podem ser acedidas por qualquer unidade no mesmo projeto.

Se as variáveis forem definidas inside uma rotina, então estas variáveis locais não são acessíveis fora dessas rotinas. Como os scripts não são tipados, as variáveis não são inicializadas com os respetivos 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

Subrotinas e Funções

O VBScript permite dois tipos de procedimentos: subrotinas e funções — uma função devolve apenas um valor. A sintaxe para chamar uma subrotina 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, uma declaração de procedimento tem normalmente uma lista de parâmetros — note que as variáveis são consideradas não tipadas e o sistema de scripting determina automaticamente quais são os tipos das variáveis. O valor utilizado no lugar do parâmetro quando faz uma chamada a um procedimento chama-se 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 que a utilização da palavra-chave Call para invocar uma subrotina ou uma função é opcional (mantida por compatibilidade retroativa).

Comentários em Scripts

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

Com comentários VBScript:

• Qualquer texto após ' é ignorado.
• Qualquer texto após 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

Dividir uma Linha de Script

No VBScript, cada instrução de código termina na linha (por uma combinação 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 por duas ou mais linhas, utilizando o caráter 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 motivos 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 ser dividida em várias linhas, e este 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

Utilizar Modelos de Objetos do Altium Designer

A maior funcionalidade do sistema de scripting é que as Interfaces dos objetos do Altium Designer (Interfaces de Objetos) estão disponíveis para utilização em scripts VBScript. Por exemplo, pode atualizar objetos de projeto em documentos Schematic e PCB através da utilização das Interfaces Schematic e das interfaces 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 desta interface, podem ser extraídos os objetos de interface incorporados ou agregados para obter ou definir os respetivos valores de propriedade.

Para aceder a um documento PCB e aos seus objetos de dados, invoque primeiro a função PCBServer. Por convenção, os nomes das interfaces são prefixados por um caráter 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 ter acesso a um documento PCB, invoque 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 dos seguintes:

• API do Cliente
• API do Servidor PCB
• API do Servidor Schematic
• API do Servidor Work Space Manager
• API Nexus
• Funções da API do Altium Designer
• Processos paramétricos

Palavras Reservadas e Funções

O sistema de scripting 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