VBScript

Niniejszy dokument opisuje język skryptowy Visual Basic, wykorzystywany do tworzenia skryptów w programie Altium Designer. Zawiera on szczegółowe informacje na temat instrukcji, funkcji i rozszerzeń języka Visual Basic, które są obsługiwane przez system skryptowy.

Ponadto w niniejszym podręczniku:

• Instrukcje VBScript
• Podprogramy i funkcje VBScript
• Korzystanie z komponentów formularzy w języku VBScript

Język VBScript

Język Visual Basic Scripting (w skrócie VBScript) może być wykorzystywany do tworzenia skryptów obsługujących modele obiektowe programu Altium Designer oraz komponenty wizualne. W niniejszym podręczniku zakłada się, że czytelnik posiada podstawową wiedzę z zakresu programowania oraz zna podstawowe zasady działania programu Altium Designer.

System skryptowy programu Altium Designer obsługuje język VBScript (wraz z innymi językami skryptowymi), który wywodzi się z systemu Microsoft ActiveX Scripting. Dzięki temu można na przykład korzystać ze skryptów CScript lub WScript, opartych na tym samym silniku skryptowym ActiveX, który jest używany w programie Altium Designer.

Wszystkie języki skryptowe obsługiwane w programie Altium Designer są beztypowe, co oznacza, że skrypt nie może definiować rekordów ani klas, ani przekazywać wskaźników jako parametrów do funkcji.

VBScript script example

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

Altium Designer i biblioteka RTL języka Delphi

System skryptowy obsługuje podzbiór biblioteki Embarcadero Delphi Run Time Library (RTL) oraz interfejsu API programu Altium Designer.

Skrypty VBScript mogą uzyskać dostęp do kilku modeli obiektowych w programie Altium Designer. Na przykład model obiektowy PCB może być wykorzystywany w skryptach VBScript do obsługi obiektów PCB w dokumencie PCB, a model obiektowy menedżera obszaru roboczego — do pracy z projektami i ich dokumentami w celu wyodrębnienia danych listy połączeń.

Dokumentacja skryptów zawiera informacje na temat interfejsów związanych z modelami obiektowymi programu Altium Designer, komponentami, procedurami globalnymi, typami i zmiennymi, które składają się na ten język skryptowy. Więcej informacji na temat funkcji języka VBScript można znaleźć w dokumentacji języka Microsoft Visual Basic.

Procesy serwerowe

Skrypt można wykorzystać do uruchamiania procesów serwerowych, które odpowiadają poleceniom w programie Altium Designer.

Pliki źródłowe VBScript

Projekt VBScript jest zorganizowany tak, aby przechowywać dokumenty skryptowe (jednostki skryptowe i formularze skryptowe). Skrypt można uruchomić z pozycji menu, przycisku na pasku narzędzi lub z okna dialogowego Run Script okna dialogowego w menu systemowym.

Pliki PRJSCR, VBS i DFM

Skrypty są zorganizowane w projekty z *.PRJSCR rozszerzeniem. Każdy projekt VBScript składa się z plików o *.vbs rozszerzeniem. Pliki mogą być jednostkami skryptowymi lub formularzami skryptowymi — każdy formularz posiada plik skryptu VBScript z *.vbs rozszerzeniem oraz odpowiadającym mu formularzem z *.dfm rozszerzeniem). Formularz skryptowy to okno graficzne (okno dialogowe), w którym znajdują się różne elementy sterujące uruchamiane w środowisku programu Altium Designer.

Możliwe jest dołączanie skryptów do różnych projektów; zdecydowanie zaleca się organizowanie skryptów w ramach poszczególnych projektów w celu łatwiejszego zarządzania ich liczbą oraz procedurami i funkcjami. Skrypty (jednostki skryptowe i formularze skryptowe) składają się z funkcji i procedur, które można wywoływać w programie Altium Designer.

Przykłady VBScript

Proste przykłady zawarte w niniejszym przewodniku ilustrują podstawowe funkcje programowania w języku VBScript w programie Altium Designer.

Skrypty VBScript mogą wykorzystywać formularze skryptowe, jednostki skryptowe, funkcje i obiekty z interfejsu API skryptowego programu Altium Designer, a także podzbiór funkcji i obiektów z biblioteki Embarcadero Delphi RTL, które są udostępniane w systemie skryptowym.

Tworzenie skryptów VBScript

W tej sekcji omówiono podstawowe zasady pisania skryptów VBScript w programie Altium Designer.

Konwencje nazewnictwa w języku VBScript

W zmiennych VBScript nie rozróżnia się wielkości liter — oznacza to, że zmienne pisane wielkimi i małymi literami mają to samo znaczenie:

Example

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

Zmienne lokalne i globalne

Ponieważ wszystkie skrypty zawierają zmienne lokalne i globalne, ważne jest, aby nazwy zmiennych w skryptach w ramach jednego projektu skryptowego były unikalne. Jeśli zmienne są zdefiniowane outside podprogramach i funkcjach, są one globalne i mogą być wykorzystywane przez dowolną jednostkę w tym samym projekcie.

Jeśli zmienne są zdefiniowane inside w ramach procedury, to te zmienne lokalne nie są dostępne poza tymi procedurami. Ponieważ skrypty są beztypowe, zmienne nie są inicjowane z określeniem ich typów.

Zmienne lokalne wewnątrz procedury są automatycznie inicjowane.

Variable Initialization

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

Podprogramy i funkcje

VBScript obsługuje dwa rodzaje procedur: podprogramy i funkcje — funkcja zwraca wyłącznie wartość. Składnia wywołania podprogramu lub funkcji w skrypcie jest następująca:

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

Parametry i argumenty

W języku VBScript deklaracja procedury zazwyczaj zawiera listę parametrów — należy pamiętać, że zmienne są traktowane jako beztypowe, a system skryptowy automatycznie określa ich typy. Wartość używana w miejsce parametru podczas wywołania procedury nazywana jest argumentem.

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

Należy pamiętać, że użycie słowa kluczowego Call słowa kluczowego do wywołania podprogramu lub funkcji jest opcjonalne (zachowane ze względu na kompatybilność wsteczną).

Komentarze w skryptach

W skrypcie komentarze to nieegzekwowane wiersze kodu, które są umieszczane dla wygody programisty. Komentarze można umieszczać praktycznie w dowolnym miejscu skryptu.

W przypadku komentarzy w języku VBScript:

• Wszelki tekst następujący po ' jest ignorowany.
• Wszelki tekst następujący po Rem jest ignorowany.

Example

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

Podział wiersza skryptu

W języku VBScript każda instrukcja kodu kończy się w danym wierszu (kombinacją znaków CR/LF), co oznacza koniec instrukcji. VBScript pozwala na zapisanie instrukcji w kilku wierszach kodu, aby podzielić długą instrukcję na dwa lub więcej wierszy, używając znaku podkreślenia (_).

VBScript nie nakłada żadnych praktycznych ograniczeń dotyczących długości pojedynczego wiersza kodu w skrypcie. Jednak ze względu na czytelność i łatwość debugowania dobrą praktyką jest ograniczanie długości wierszy kodu tak, aby można je było łatwo odczytać na ekranie lub w formie wydruku. Jeśli wiersz kodu jest bardzo długi, można go podzielić na wiele wierszy, a interpreter VB potraktuje ten kod tak, jakby był zapisany w jednym wierszu.

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

Korzystanie z modeli obiektowych programu Altium Designer

Najważniejszą cechą systemu skryptowego jest to, że interfejsy obiektów programu Altium Designer (interfejsy obiektowe) są dostępne do wykorzystania w skryptach VBScript. Na przykład można aktualizować obiekty projektu w dokumentach schematu i płytki drukowanej, korzystając odpowiednio z interfejsów schematu i interfejsów płytki drukowanej.

Interfejsy obiektów programu Altium Designer są dostępne do wykorzystania w dowolnym skrypcie. Zazwyczaj w skryptach nie ma potrzeby instancjonowania interfejsu. Wyodrębniany jest interfejs reprezentujący istniejący obiekt programu Altium Designer, a z tego interfejsu można wyodrębnić obiekty interfejsów osadzonych lub zagregowanych w celu uzyskania lub ustawienia wartości ich właściwości.

Aby uzyskać dostęp do dokumentu PCB i jego obiektów danych, należy najpierw wywołać funkcję PCBServer . Zgodnie z konwencją nazwy interfejsów mają przedrostek I — na przykład IPCB_Board oznacza interfejs dla istniejącego dokumentu PCB w programie 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

Aby uzyskać dostęp do dokumentu PCB, należy wywołać funkcję 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

Obiekty, interfejsy i funkcje

Dostęp do obiektów, interfejsów i funkcji programu Altium Designer w skryptach można uzyskać za pomocą następujących elementów:

• API klienta
• API serwera PCB
• Interfejs API serwera schematów
• Interfejs API serwera menedżera obszaru roboczego
• API serwisu Nexus
• Funkcje API programu Altium Designer
• Procesy parametryczne

Słowa zastrzeżone i funkcje

System skryptowy obsługuje język VBScript, który wywodzi się z technologii językowej Microsoft Active Scripting. Słowa zastrzeżone w języku VBScript to:

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