VBScript

本参考资料介绍了用于在 Altium Designer 中创建脚本的 VisualBasic 脚本语言。它详细介绍了脚本系统支持的 VisualBasic 脚本语句、函数和扩展。

本参考资料还包括

• VBScript 语句
• VBScript 子程序和函数
• 使用 VBScript 表单组件

VBScript 语言

Visual Basic 脚本（简称 VBScript）可用于创建处理 Altium Designer 对象模型和可视化组件的脚本。在本参考资料中，假定您熟悉基本编程概念和 Altium Designer 的基本操作。

Altium Designer 脚本系统支持源于 Microsoft ActiveX 脚本系统的 VBScript 语言（以及其他脚本语言）。因此，您可以使用 CScripts 或 WScripts，它们基于 Altium Designer 中使用的相同 ActiveX 脚本引擎。

Altium Designer 支持的所有脚本语言都是无类型或非类型的，这意味着脚本不能定义记录或类，也不能将指针作为参数传递给函数。

VBScript script example

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

Altium Designer 和 Delphi RTL

脚本系统支持 Embarcadero Delphi 运行时库 (RTL) 和 Altium Designer API 的子集。

VBScripts 脚本可访问 Altium Designer 中的多个对象模型。例如，在 VBScripts 中可以使用 PCB 对象模型来处理 PCB 文档中的 PCB 对象，或使用工作区管理器对象模型来处理项目及其文档以提取网表数据。

脚本参考》包含与 Altium Designer 对象模型、组件、全局例程、类型和变量有关的接口信息，这些信息构成了脚本语言。有关 VBScript 功能的更多信息，请查阅 Microsoft Visual Basic 文档。

服务器进程

脚本可用于执行服务器进程，服务器进程代表 Altium Designer 中的命令。

VBScript 源文件

VBScript 项目用于存储脚本文档（脚本单元和脚本窗体）。脚本可通过菜单项、工具栏按钮或系统菜单对话框执行。 Run Script对话框执行脚本。

PRJSCR、VBS 和 DFM 文件

脚本被组织到项目中，项目后缀名为 *.PRJSCR扩展名的项目。每个 VBScript 项目由扩展名为 *.vbs扩展名的文件组成。文件可以是脚本单元，也可以是脚本表单--每个表单都有一个扩展名为 *.vbs扩展名为 *.dfm扩展名）。脚本窗体是一个图形窗口（对话框），其中包含在 Altium Designer 上运行的不同控件。

可以将脚本附加到不同的项目中，强烈建议将脚本组织到不同的项目中，以管理脚本的数量及其程序/功能。脚本（脚本单元和脚本窗体）由可在 Altium Designer 中调用的函数/程序组成。

VBScript 示例

本参考资料中包含的简单示例说明了 Altium Designer 中 VBScript 编程的基本功能。

VBScript 可以使用 Altium Designer 脚本 API 中的脚本窗体、脚本单元、函数和对象，以及脚本系统中公开的 Embarcadero Delphi RTL 中的函数和对象子集。

编写 VBScript 脚本

本节介绍在 Altium Designer 中编写 VBScript 的基本概念。

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 对象的接口（对象接口）可在 VBScripts 中使用。例如，您可以通过使用 Schematic 接口和 PCB 接口，分别更新 Schematic 和 PCB 文档上的设计对象。

Altium Designer 对象接口可用于任何脚本。通常在脚本中无需实例化接口。提取代表现有 Altium Designer 对象的接口，然后从该接口提取嵌入或聚合接口对象，以获取或设置其属性值。

要访问 PCB 文档及其数据对象，首先要调用 PCBServer函数。按照惯例，接口名称的前缀为 I字符作为前缀--例如 IPCB_Board代表 Altium Designer 中现有 PCB 文档的接口。

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 对象、接口和函数可通过以下脚本访问：

• 客户端 API
• PCB 服务器 API
• 原理图服务器 API
• 工作空间管理器服务器 API
• Nexus API
• Altium Designer API 功能
• 参数流程

保留字和函数

脚本系统支持 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