VBScript
Этот справочник описывает язык сценариев VisualBasic, используемый для создания скриптов в Altium Designer. В нём приведены сведения об операторах, функциях и расширениях VisualBasic Scripting, поддерживаемых системой скриптинга.
Также в этом справочнике:
Язык VBScript
Visual Basic Scripting (сокращённо VBScript) можно использовать для создания скриптов, работающих с объектными моделями и визуальными компонентами Altium Designer. В этом справочнике предполагается, что вы знакомы с базовыми концепциями программирования и основами работы в Altium Designer.
Система скриптинга Altium Designer поддерживает язык VBScript (наряду с другими языками скриптинга), производный от системы Microsoft ActiveX Scripting. Поэтому, например, вы должны иметь возможность использовать CScripts или WScripts, которые основаны на том же движке ActiveX scripting, что используется в Altium Designer.
Все языки скриптинга, поддерживаемые в Altium Designer, являются безтиповыми (untyped), то есть скрипт не может определять записи или классы и передавать указатели в качестве параметров функций.
VBScript script example
Sub DisplayName (sName)
MsgBox "My Name is " & sName
End Sub
Altium Designer и Delphi RTL
Система скриптинга поддерживает подмножество библиотеки времени выполнения Embarcadero Delphi Run Time Library (RTL) и API Altium Designer.
Скрипты VBScript могут получать доступ к нескольким объектным моделям в Altium Designer. Например, объектную модель PCB можно использовать в VBScript для работы с объектами печатной платы в PCB-документе, либо объектную модель Workspace Manager — для работы с проектами и их документами с целью извлечения данных нетлиста.
Справочник по скриптингу содержит информацию об интерфейсах объектных моделей 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 (Object Interfaces) доступны для использования в VBScript. Например, вы можете обновлять объекты проекта в документах схемы и PCB, используя соответственно интерфейсы схемы и интерфейсы PCB.
Интерфейсы объектов Altium Designer доступны для использования в любом скрипте. Обычно в скриптах нет необходимости создавать экземпляр интерфейса. Извлекается интерфейс, представляющий существующий объект Altium Designer, и из этого интерфейса можно извлечь встроенные или агрегированные интерфейсные объекты, чтобы получать или задавать значения их свойств.
Чтобы получить доступ к PCB-документу и его объектам данных, сначала вызовите функцию PCBServer. По соглашению имена интерфейсов имеют префикс в виде символа I — например, IPCB_Board представляет интерфейс существующего PCB-документа в 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
Чтобы получить доступ к PCB-документу, вызовите 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 в скриптах возможен из следующих источников:
- Client API
- PCB Server API
- Schematic Server API
- Work Space Manager Server API
- Nexus API
- Altium Designer API functions
- Параметрические процессы
Зарезервированные слова и функции
Система скриптинга поддерживает язык 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
Локализовано с помощью ИИ