VBScript

このリファレンスでは、Altium Designer でスクリプトを作成するために使用される Visual Basic スクリプト言語について説明しています。スクリプトシステムでサポートされている Visual Basic スクリプトの文、関数、および拡張機能の詳細が記載されています。

また、このリファレンスには以下の内容も含まれています：

• VBScript 文
• VBScriptのサブルーチンと関数
• VBScript でのフォームコンポーネントの使用

VBScript 言語

Visual Basic Scripting（略称 VBScript）を使用すると、Altium Designer のオブジェクトモデルやビジュアルコンポーネントを扱うスクリプトを作成できます。このリファレンスでは、読者が基本的なプログラミングの概念および Altium Designer の基本的な操作に精通していることを前提としています。

Altium Designerのスクリプトシステムは、Microsoft ActiveX Scriptingシステムに由来するVBScript言語（およびその他のスクリプト言語）をサポートしています。したがって、例えば、Altium Designerで使用されているものと同じActiveXスクリプトエンジンに基づいたCScriptやWScriptを使用することも可能です。

Altium Designer でサポートされているすべてのスクリプト言語は型なし（untyped）であるため、スクリプトではレコードやクラスを定義したり、関数のパラメータとしてポインタを渡したりすることはできません。

VBScript script example

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

Altium Designer と Delphi RTL

スクリプトシステムは、Embarcadero Delphi ランタイムライブラリ (RTL) および Altium Designer API のサブセットをサポートしています。

VBScript スクリプトは、Altium Designer 内のいくつかのオブジェクトモデルにアクセスできます。たとえば、VBScript では、PCB オブジェクトモデルを使用して PCB ドキュメント上の PCB オブジェクトを処理したり、ワークスペース マネージャー オブジェクトモデルを使用してプロジェクトやそのドキュメントを操作し、ネットリストデータを抽出したりすることができます。

スクリプティングリファレンスには、このスクリプト言語を構成する Altium Designer オブジェクトモデル、コンポーネント、グローバルルーチン、型、および変数に関するインターフェース情報が記載されています。VBScript 関数の詳細については、Microsoft Visual Basic のドキュメントを参照してください。

サーバープロセス

スクリプトを使用して、Altium Designer におけるコマンドに相当するサーバープロセスを実行することができます。

VBScript ソースファイル

VBScript プロジェクトは、スクリプトドキュメント（スクリプトユニットおよびスクリプトフォーム）を格納するように構成されています。スクリプトは、メニュー項目、ツールバーボタン、またはシステムメニューの Run Script ダイアログから実行できます。

PRJSCR、VBS、および DFM ファイル

スクリプトは、 *.PRJSCR 拡張子を持つプロジェクトに整理されます。各VBScriptプロジェクトは、 *.vbs 拡張子を持つファイルで構成されています。ファイルはスクリプト・ユニットまたはスクリプト・フォームのいずれかであり、各フォームには *.vbs 拡張子を持つVBScriptスクリプトファイルと、 *.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 では、サブルーチンと関数の 2 種類のプロシージャが使用できます。関数は値を返すのみです。スクリプト内でサブルーチンや関数を呼び出す構文は次のとおりです。

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 では、アンダースコア (_）を使用して、長い命令を2行以上に分割し、1つのコード行に記述することができます。

VBScriptでは、スクリプト内の1行あたりのコード長に実質的な制限は設けられていません。ただし、可読性とデバッグのしやすさを考慮すると、画面上や印刷物で読みやすいように、コード行の長さを制限することが推奨されます。 コード行が非常に長い場合は、複数の行に分割することができます。この場合、VBインタプリタは、そのコードをあたかも1行で記述されたかのように扱います。

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 で利用できることです。たとえば、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 関数
• パラメトリック処理

予約語と関数

このスクリプトシステムは、Microsoft Active Scripting 言語技術に由来する VBScript 言語をサポートしています。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