VBScript

Diese Referenz beschreibt die VisualBasic-Skriptsprache, die zum Erstellen von Skripten in Altium Designer verwendet wird. Sie enthält Details zu den VisualBasic-Skriptanweisungen, Funktionen und Erweiterungen, die im Skriptsystem unterstützt werden.

Außerdem in dieser Referenz:

• VBScript-Anweisungen
• VBScript-Subroutinen und -Funktionen
• Verwendung von Formularkomponenten mit VBScript

Die VBScript-Sprache

Visual Basic Scripting (kurz VBScript) kann verwendet werden, um Skripte zu erstellen, die mit den Altium Designer-Objektmodellen und visuellen Komponenten arbeiten. In dieser Referenz wird vorausgesetzt, dass Sie mit grundlegenden Programmierkonzepten und der grundlegenden Bedienung von Altium Designer vertraut sind.

Das Skriptsystem von Altium Designer unterstützt die Sprache VBScript (zusammen mit anderen Skriptsprachen), die vom Microsoft ActiveX-Skriptsystem abgeleitet ist. Sie sollten daher beispielsweise CScripts oder WScripts verwenden können, die auf derselben ActiveX-Skript-Engine basieren, die auch in Altium Designer verwendet wird.

Alle in Altium Designer unterstützten Skriptsprachen sind typfrei bzw. untypisiert. Das bedeutet, dass ein Skript keine Records oder Klassen definieren und keine Pointer als Parameter an Funktionen übergeben kann.

VBScript script example

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

Altium Designer und die Delphi RTL

Das Skriptsystem unterstützt eine Teilmenge der Embarcadero Delphi Run Time Library (RTL) und der Altium Designer API.

VBScript-Skripte können auf mehrere Objektmodelle in Altium Designer zugreifen. So kann beispielsweise das PCB-Objektmodell in VBScript-Skripten verwendet werden, um mit PCB-Objekten in einem PCB-Dokument zu arbeiten, oder das Workspace Manager-Objektmodell, um mit Projekten und deren Dokumenten zu arbeiten und Netlist-Daten zu extrahieren.

Die Scripting Reference enthält Informationen zu Schnittstellen in Bezug auf Altium Designer-Objektmodelle, Komponenten, globale Routinen, Typen und Variablen, aus denen diese Skriptsprache besteht. Weitere Informationen zu VBScript-Funktionen finden Sie in der Microsoft Visual Basic-Dokumentation.

Serverprozesse

Ein Skript kann verwendet werden, um Serverprozesse auszuführen, die Befehle in Altium Designer darstellen.

VBScript-Quelldateien

Ein VBScript-Projekt ist so organisiert, dass Skriptdokumente (Skripteinheiten und Skriptformulare) gespeichert werden. Ein Skript kann über einen Menüeintrag, eine Symbolleistenschaltfläche oder über den Dialog Run Script aus dem Systemmenü ausgeführt werden.

PRJSCR-, VBS- und DFM-Dateien

Skripte sind in Projekten mit einer Erweiterung *.PRJSCR organisiert. Jedes VBScript-Projekt besteht aus Dateien mit einer Erweiterung *.vbs. Dateien können entweder Skripteinheiten oder Skriptformulare sein — jedes Formular besitzt eine VBScript-Skriptdatei mit der Erweiterung *.vbs und ein entsprechendes Formular mit der Erweiterung *.dfm). Ein Skriptformular ist ein grafisches Fenster (Dialog), das verschiedene Steuerelemente enthält, die innerhalb von Altium Designer ausgeführt werden.

Es ist möglich, Skripte an verschiedene Projekte anzuhängen, und es wird dringend empfohlen, Skripte in verschiedenen Projekten zu organisieren, um die Anzahl der Skripte und ihrer Prozeduren/Funktionen zu verwalten. Skripte (Skripteinheiten und Skriptformulare) bestehen aus Funktionen/Prozeduren, die innerhalb von Altium Designer aufgerufen werden können.

VBScript-Beispiele

Die einfachen Beispiele in dieser Referenz veranschaulichen die grundlegenden Merkmale der VBScript-Programmierung in Altium Designer.

VBScript-Skripte können Skriptformulare, Skripteinheiten, Funktionen und Objekte aus der Altium Designer Scripting API sowie eine Teilmenge von Funktionen und Objekten aus der Embarcadero Delphi RTL verwenden, die im Skriptsystem verfügbar gemacht werden.

VBScript-Skripte schreiben

Dieser Abschnitt behandelt die grundlegenden Konzepte zum Schreiben von VBScript-Skripten in Altium Designer.

VBScript-Benennungskonventionen

Bei VBScript wird nicht zwischen Groß- und Kleinschreibung unterschieden — das heißt, Variablen in Groß- und Kleinbuchstaben haben dieselbe Bedeutung:

Example

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

Lokale und globale Variablen

Da alle Skripte lokale und globale Variablen haben, ist es wichtig, in Ihren Skripten innerhalb eines Skriptprojekts eindeutige Variablennamen zu verwenden. Wenn die Variablen outside einer beliebigen Subroutine oder Funktion definiert sind, sind sie global und können von jeder Einheit im selben Projekt aus aufgerufen werden.

Wenn Variablen inside einer Routine definiert sind, dann sind diese lokalen Variablen außerhalb dieser Routinen nicht zugänglich. Da Skripte typfrei sind, werden Variablen nicht mit ihren Typen initialisiert.

Die lokalen Variablen innerhalb einer Prozedur werden automatisch initialisiert.

Variable Initialization

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

Subroutinen und Funktionen

VBScript erlaubt zwei Arten von Prozeduren: Subroutinen und Funktionen — nur eine Funktion gibt einen Wert zurück. Die Syntax zum Aufrufen einer Subroutine oder Funktion in einem Skript lautet:

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

Parameter und Argumente

In VBScript hat eine Prozedurdeklaration normalerweise eine Liste von Parametern — beachten Sie, dass Variablen als typfrei gelten und das Skriptsystem automatisch ermittelt, welche Variablentypen vorliegen. Der Wert, der beim Aufruf einer Prozedur anstelle des Parameters verwendet wird, wird Argument genannt.

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

Beachten Sie, dass die Verwendung des Schlüsselworts Call zum Aufrufen einer Subroutine oder Funktion optional ist (aus Gründen der Abwärtskompatibilität beibehalten).

Kommentare in Skripten

In einem Skript sind Kommentare nicht ausgeführte Codezeilen, die zum Nutzen des Programmierers eingefügt werden. Kommentare können praktisch überall in einem Skript eingefügt werden.

Bei VBScript-Kommentaren gilt:

• Jeder Text nach ' wird ignoriert.
• Jeder Text nach Rem wird ignoriert.

Example

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

Aufteilen einer Skriptzeile

In VBScript wird jede Codeanweisung in der Zeile beendet (durch eine CR/LF-Kombination), um das Ende der Anweisung anzuzeigen. VBScript erlaubt es, eine Anweisung über mehrere Codezeilen zu schreiben, um eine lange Anweisung mithilfe des Unterstrichzeichens (_) auf zwei oder mehr Zeilen aufzuteilen.

VBScript setzt der Länge einer einzelnen Codezeile in einem Skript praktisch keine Grenze. Aus Gründen der Lesbarkeit und der einfacheren Fehlersuche ist es jedoch gute Praxis, die Länge von Codezeilen so zu begrenzen, dass sie auf dem Bildschirm oder in gedruckter Form leicht gelesen werden können. Wenn eine Codezeile sehr lang ist, kann sie in mehrere Zeilen aufgeteilt werden, und dieser Code wird vom VB-Interpreter so behandelt, als wäre er in einer einzigen Zeile geschrieben.

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

Verwendung von Altium Designer-Objektmodellen

Die wichtigste Eigenschaft des Skriptsystems ist, dass die Schnittstellen von Altium Designer-Objekten (Objektschnittstellen) in VBScript-Skripten verwendet werden können. So können Sie beispielsweise Entwurfsobjekte in Schaltplan- und PCB-Dokumenten mithilfe von Schaltplanschnittstellen bzw. PCB-Schnittstellen aktualisieren.

Die Altium Designer-Objektschnittstellen stehen in jedem Skript zur Verfügung. Normalerweise ist es in Skripten nicht erforderlich, eine Schnittstelle zu instanziieren. Die Schnittstelle, die ein vorhandenes Altium Designer-Objekt repräsentiert, wird extrahiert, und aus dieser Schnittstelle können die eingebetteten oder aggregierten Schnittstellenobjekte extrahiert werden, um deren Eigenschaftswerte abzurufen oder festzulegen.

Um auf ein PCB-Dokument und seine Datenobjekte zuzugreifen, rufen Sie zunächst die Funktion PCBServer auf. Konventionsgemäß beginnen Schnittstellennamen mit dem Zeichen I — zum Beispiel repräsentiert IPCB_Board eine Schnittstelle für ein vorhandenes PCB-Dokument in 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

Um Zugriff auf ein PCB-Dokument zu erhalten, rufen Sie PCBServer auf.

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

Objekte, Schnittstellen und Funktionen

Auf Altium Designer-Objekte, -Schnittstellen und -Funktionen kann in Skripten über Folgendes zugegriffen werden:

• Client-API
• PCB-Server-API
• Schaltplan-Server-API
• Workspace Manager Server API
• Nexus API
• Altium Designer API-Funktionen
• Parametrische Prozesse

Reservierte Wörter und Funktionen

Das Skriptsystem unterstützt die VBScript-Sprache, die von der Microsoft Active Scripting-Sprachtechnologie abgeleitet ist. Die reservierten Wörter von VBScript sind:

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