VBScript

Diese Dokumentation beschreibt die Skriptsprache Visual Basic Scripting, die zur Erstellung von Skripten in Altium Designer verwendet wird. Sie enthält detaillierte Informationen zu den Anweisungen, Funktionen und Erweiterungen von Visual Basic Scripting, die vom Skriptsystem unterstützt werden.

Ebenfalls in dieser Referenz:

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

Die Sprache VBScript

Mit Visual Basic Scripting (kurz VBScript) lassen sich Skripte erstellen, die mit den Objektmodellen und visuellen Komponenten von Altium Designer arbeiten. In dieser Referenz wird davon ausgegangen, dass Sie mit grundlegenden Programmierkonzepten und der grundlegenden Bedienung von Altium Designer vertraut sind.

Das Skriptsystem von Altium Designer unterstützt die Sprache VBScript (neben anderen Skriptsprachen), die vom Microsoft ActiveX Scripting-System abgeleitet ist. So sollten Sie beispielsweise in der Lage sein, CScripts oder WScripts zu verwenden, die auf derselben ActiveX-Skript-Engine basieren, die auch in Altium Designer zum Einsatz kommt.

Alle in Altium Designer unterstützten Skriptsprachen sind typenlos oder untypisiert, was bedeutet, dass ein Skript keine Datensätze oder Klassen definieren und keine Zeiger 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 verschiedene 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 Netzlistendaten zu extrahieren.

Die Skript-Referenz 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 zur Ausführung von Serverprozessen verwendet werden, die Befehle in Altium Designer darstellen.

VBScript-Quelldateien

Ein VBScript-Projekt ist so organisiert, dass es Skriptdokumente (Skripteinheiten und Skriptformulare) speichert. Ein Skript kann über einen Menüpunkt, eine Symbolleisten-Schaltfläche oder über den Run Script Dialogfeld im Systemmenü ausgeführt werden.

PRJSCR-, VBS- und DFM-Dateien

Skripte sind in Projekten mit der *.PRJSCR Dateiendung. Jedes VBScript-Projekt besteht aus Dateien mit der *.vbs Dateiendung. Bei den Dateien kann es sich entweder um Skript-Einheiten oder um Skript-Formulare handeln – jedes Formular verfügt über eine VBScript-Skriptdatei mit der *.vbs Erweiterung und einem entsprechenden Formular mit der *.dfm Erweiterung). Ein Skriptformular ist ein grafisches Fenster (Dialog), das verschiedene Steuerelemente enthält, die über Altium Designer ausgeführt werden.

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

VBScript-Beispiele

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

Die VBScripts können Skriptformulare, Skripteinheiten, Funktionen und Objekte aus der Altium Designer-Skript-API sowie eine Teilmenge von Funktionen und Objekten aus der Embarcadero Delphi RTL nutzen, die im Skriptsystem verfügbar sind.

Erstellen von VBScript-Skripten

Dieser Abschnitt behandelt die grundlegenden Konzepte zum Schreiben von VBScripts in Altium Designer.

Namenskonventionen für VBScript

Bei VBScript-Variablen wird die Groß-/Kleinschreibung nicht berücksichtigt – 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 enthalten, ist es wichtig, dass die Variablennamen in Ihren Skripten innerhalb eines Skriptprojekts eindeutig sind. Wenn die Variablen outside Subroutinen und Funktionen definiert, sind sie global und können von jeder Einheit im selben Projekt aufgerufen werden.

Werden Variablen inside einer Routine definiert, sind diese lokalen Variablen außerhalb dieser Routinen nicht zugänglich. Da Skripte typfrei sind, werden Variablen nicht mit ihrem Typ 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

Unterprogramme und Funktionen

VBScript unterstützt zwei Arten von Prozeduren: Unterprogramme und Funktionen – eine Funktion gibt ausschließlich einen Wert zurück. Die Syntax zum Aufruf eines Unterprogramms oder einer 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 enthält eine Prozedurdeklaration normalerweise eine Liste von Parametern – beachten Sie, dass Variablen als typfrei gelten und das Skriptsystem automatisch ermittelt, um welche Variablentypen es sich handelt. Der Wert, der bei einem Prozeduraufruf anstelle des Parameters verwendet wird, wird als Argument bezeichnet.

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 Call Schlüsselworts zum Aufruf einer Unterroutine oder einer Funktion ist optional (aus Gründen der Abwärtskompatibilität beibehalten).

Kommentare in Skripten

In einem Skript sind Kommentare nicht ausgeführte Codezeilen, die zur Unterstützung des Programmierers eingefügt werden. Kommentare können praktisch an jeder Stelle in einem Skript eingefügt werden.

Bei VBScript-Kommentaren gilt:

• Jeder Text, der auf ' steht, wird ignoriert.
• Jeder Text, der auf 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

Aufteilung einer Skriptzeile

In VBScript wird jede Codeanweisung am Zeilenende (durch eine CR/LF-Kombination) beendet, um das Ende der Anweisung zu kennzeichnen. VBScript ermöglicht es Ihnen, eine Anweisung über mehrere Codezeilen zu schreiben und eine lange Anweisung mithilfe des Unterstrichs (_).

VBScript legt keine praktische Begrenzung für die Länge einer einzelnen Codezeile in einem Skript fest. Im Interesse der Lesbarkeit und zur Erleichterung der Fehlersuche empfiehlt es sich jedoch, die Länge der Codezeilen so zu begrenzen, dass sie auf dem Bildschirm oder in gedruckter Form leicht lesbar sind. Ist eine Codezeile sehr lang, kann sie in mehrere Zeilen aufgeteilt werden; dieser Code wird vom VB-Interpreter dann 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 der Altium Designer-Objektmodelle

Das herausragendste Merkmal des Skriptsystems besteht darin, dass die Schnittstellen von Altium Designer-Objekten (Objektschnittstellen) in VBScripts genutzt werden können. So können Sie beispielsweise Designobjekte in Schaltplan- und Leiterplatten-Dokumenten aktualisieren, indem Sie die entsprechenden Schaltplan- bzw. Leiterplatten-Schnittstellen verwenden.

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 dessen Datenobjekte zuzugreifen, rufen Sie zunächst die PCBServer Funktion auf. Gemäß Konvention werden Schnittstellennamen mit einem I Zeichen vorangestellt – zum Beispiel IPCB_Board steht für eine Schnittstelle zu einem vorhandenen 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 die 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

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
• Work Space Manager-Server-API
• Nexus-API
• Altium Designer-API-Funktionen
• Parametrische Prozesse

Reservierte Wörter und Funktionen

Das Skriptsystem unterstützt die Sprache VBScript, die auf der Microsoft Active Scripting-Technologie basiert. Die reservierten Wörter in 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