VBScript

В данном справочнике описывается язык сценариев Visual Basic Scripting, используемый для создания сценариев в Altium Designer. В нем приведены подробные сведения об операторах, функциях и расширениях Visual Basic Scripting, поддерживаемых в системе сценариев.

Также в данном справочнике:

• Операторы VBScript
• Подпрограммы и функции VBScript
• Использование компонентов форм с VBScript

Язык VBScript

Язык Visual Basic Scripting (или VBScript) можно использовать для создания скриптов, работающих с объектными моделями и визуальными компонентами Altium Designer. В данном справочнике предполагается, что вы знакомы с основными концепциями программирования и принципами работы Altium Designer.

Система скриптов Altium Designer поддерживает язык VBScript (наряду с другими языками скриптов), который является производным от системы Microsoft ActiveX Scripting. Так, например, вы можете использовать CScripts или WScripts, которые основаны на том же движке ActiveX Scripting, что и Altium Designer.

Все языки сценариев, поддерживаемые в Altium Designer, являются бестиповыми, что означает, что в сценарии нельзя определять записи или классы, а также передавать указатели в качестве параметров функциям.

VBScript script example

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

Altium Designer и библиотека выполнения Delphi (RTL)

Система скриптов поддерживает подмножество библиотеки выполнения (RTL) Embarcadero Delphi и API Altium Designer.

Скрипты VBScript могут обращаться к нескольким объектным моделям в Altium Designer. Например, объектная модель печатной платы (PCB) может использоваться в скриптах VBScript для работы с объектами печатной платы в документе PCB, а объектная модель диспетчера рабочего пространства — для работы с проектами и их документами с целью извлечения данных списка соединений.

Справочник по скриптам содержит информацию об интерфейсах, относящихся к объектным моделям Altium Designer, компонентам, глобальным процедурам, типам и переменным, составляющим этот язык скриптов. Дополнительную информацию о функциях VBScript см. в документации по Microsoft Visual Basic.

Серверные процессы

Скрипт можно использовать для запуска серверных процессов, которые представляют собой команды в Altium Designer.

Исходные файлы VBScript

Проект VBScript организован для хранения документов скриптов (блоков и форм скриптов). Скрипт можно запустить через пункт меню, кнопку на панели инструментов или из диалогового окна Run Script диалогового окна в системном меню.

Файлы PRJSCR, VBS и DFM

Скрипты объединены в проекты с *.PRJSCR расширением. Каждый проект VBScript состоит из файлов с *.vbs расширением. Файлы могут быть либо модулями скриптов, либо формами скриптов — каждая форма имеет файл скрипта VBScript с *.vbs расширением и соответствующей формой с *.dfm расширением). Форма скрипта представляет собой графическое окно (диалоговое окно), содержащее различные элементы управления, которые запускаются поверх Altium Designer.

Скрипты можно привязывать к разным проектам, и настоятельно рекомендуется группировать скрипты по проектам для удобства управления их количеством, а также соответствующими процедурами и функциями. Скрипты (модули и формы) состоят из функций и процедур, которые можно вызывать из среды Altium Designer.

Примеры VBScript

Простые примеры, приведённые в данном справочнике, иллюстрируют основные возможности программирования на VBScript в Altium Designer.

В скриптах VBScript можно использовать формы скриптов, модули скриптов, функции и объекты из API скриптов Altium Designer, а также подмножество функций и объектов из Embarcadero Delphi RTL, доступных в системе скриптов.

Написание скриптов VBScript

В этом разделе рассматриваются основные концепции написания скриптов VBScript в Altium Designer.

Соглашения об именовании в VBScript

В переменных VBScript не учитывается регистр — то есть переменные, написанные заглавными и строчными буквами, имеют одинаковое значение:

Example

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

Локальные и глобальные переменные

Поскольку все скрипты содержат локальные и глобальные переменные, важно, чтобы имена переменных в скриптах одного проекта были уникальными. Если переменные определены outside в подпрограммах или функциях, они являются глобальными и доступны из любого модуля в том же проекте.

Если переменные определены inside в подпрограмме, то эти локальные переменные недоступны за пределами данной подпрограммы. Поскольку скрипты не имеют типов, переменные не инициализируются с указанием их типов.

Локальные переменные внутри процедуры инициализируются автоматически.

Variable Initialization

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

Подпрограммы и функции

VBScript поддерживает два вида процедур: подпрограммы и функции — при этом функция возвращает только значение. Синтаксис вызова подпрограммы или функции в скрипте следующий:

Call SubRoutineA(parameters)
...или
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

Параметры и аргументы

В VBScript объявление процедуры обычно содержит список параметров — обратите внимание, что переменные считаются безтиповыми, и система скриптов автоматически определяет их типы. Значение, используемое вместо параметра при вызове процедуры, называется аргументом.

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

Обратите внимание, что использование ключевого слова Call для вызова подпрограммы или функции не является обязательным (сохранено для обратной совместимости).

Комментарии в скриптах

В скрипте комментарии — это неисполняемые строки кода, которые включаются для удобства программиста. Комментарии можно размещать практически в любом месте скрипта.

Особенности комментариев в VBScript:

• Любой текст, следующий за символами ' игнорируются.
• Любой текст, следующий за Rem игнорируется.

Example

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

Разделение строки скрипта

В VBScript каждая инструкция кода заканчивается в конце строки (комбинацией CR/LF), что указывает на конец инструкции. VBScript позволяет записывать инструкцию на нескольких строках кода, разбивая длинную инструкцию на две или более строк с помощью символа подчеркивания (_).

VBScript не устанавливает никаких практических ограничений на длину отдельной строки кода в скрипте. Однако для удобства чтения и упрощения отладки рекомендуется ограничивать длину строк кода, чтобы их можно было легко читать на экране или в распечатанном виде. Если строка кода очень длинная, её можно разбить на несколько строк, и этот код будет обрабатываться интерпретатором VB так, как если бы он был написан в одной строке.

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

Использование объектных моделей Altium Designer

Главной особенностью системы скриптов является то, что интерфейсы объектов Altium Designer (объектные интерфейсы) доступны для использования в VBScript. Например, вы можете обновлять объекты проекта в документах схемы и печатной платы с помощью интерфейсов схемы и печатной платы соответственно.

Интерфейсы объектов Altium Designer доступны для использования в любом скрипте. Как правило, в скриптах нет необходимости создавать экземпляр интерфейса. Вызывается интерфейс, представляющий существующий объект Altium Designer, и из этого интерфейса можно извлечь вложенные или агрегированные объекты-интерфейсы для получения или установки значений их свойств.

Для доступа к документу печатной платы и его объектам данных сначала необходимо вызвать функцию PCBServer функцию. По соглашению, имена интерфейсов начинаются с префикса I — например, IPCB_Board представляет интерфейс для существующего документа печатной платы в 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

Чтобы получить доступ к документу печатной платы, вызовите функцию 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

Объекты, интерфейсы и функции

Доступ к объектам, интерфейсам и функциям Altium Designer в скриптах можно получить из следующих источников:

• Клиентский API
• API сервера печатных плат
• API сервера схем
• API сервера Work Space Manager
• API Nexus
• Функции API Altium Designer
• Параметрические процессы

Зарезервированные слова и функции

Система скриптов поддерживает язык VBScript, основанный на технологии Microsoft Active Scripting. Зарезервированные слова VBScript:

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