VBScript
Ten materiał referencyjny opisuje język skryptowy VisualBasic używany do tworzenia skryptów w Altium Designer. Zawiera szczegółowe informacje o instrukcjach, funkcjach i rozszerzeniach VisualBasic Scripting, które są obsługiwane w systemie skryptowym.
Również w tym materiale:
Język VBScript
Visual Basic Scripting (w skrócie VBScript) może być używany do tworzenia skryptów, które operują na modelach obiektowych Altium Designer oraz komponentach wizualnych. W tym materiale zakłada się, że znasz podstawowe pojęcia programistyczne oraz podstawową obsługę Altium Designer.
System skryptowy Altium Designer obsługuje język VBScript (wraz z innymi językami skryptowymi), który wywodzi się z systemu Microsoft ActiveX Scripting. Dlatego na przykład powinno być możliwe używanie CScripts lub WScripts, które bazują na tym samym silniku ActiveX Scripting, z którego korzysta Altium Designer.
Wszystkie języki skryptowe obsługiwane w Altium Designer są beztypowe (untyped), co oznacza, że skrypt nie może definiować rekordów ani klas oraz 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 Delphi RTL
System skryptowy obsługuje podzbiór biblioteki uruchomieniowej Embarcadero Delphi Run Time Library (RTL) oraz API Altium Designer.
Skrypty VBScript mogą uzyskiwać dostęp do kilku modeli obiektowych w Altium Designer. Na przykład model obiektowy PCB może być używany w skryptach VBScript do pracy z obiektami PCB w dokumencie PCB, albo model obiektowy Workspace Manager do pracy z projektami i ich dokumentami w celu wyodrębniania danych netlisty.
Scripting Reference zawiera informacje o interfejsach w odniesieniu do modeli obiektowych Altium Designer, komponentów, procedur globalnych, typów i zmiennych składających się na ten język skryptowy. Więcej informacji o funkcjach VBScript znajdziesz w dokumentacji Microsoft Visual Basic.
Procesy serwera
Skrypt może służyć do uruchamiania procesów serwera, które odpowiadają poleceniom w Altium Designer.
Pliki źródłowe VBScript
Projekt VBScript jest zorganizowany tak, aby przechowywać dokumenty skryptów (jednostki skryptowe i formularze skryptowe). Skrypt można uruchomić z pozycji menu, przycisku paska narzędzi lub z okna dialogowego Run Script w menu systemowym.
Pliki PRJSCR, VBS i DFM
Skrypty są organizowane w projekty z rozszerzeniem *.PRJSCR. Każdy projekt VBScript składa się z plików z rozszerzeniem *.vbs. Pliki mogą być jednostkami skryptowymi albo formularzami skryptowymi — każdy formularz ma plik skryptu VBScript z rozszerzeniem *.vbs oraz odpowiadający mu formularz z rozszerzeniem *.dfm). Formularz skryptowy to graficzne okno (dialog), które zawiera różne kontrolki działające w ramach Altium Designer.
Możliwe jest dołączanie skryptów do różnych projektów i zdecydowanie zaleca się organizowanie skryptów w oddzielne projekty, aby zarządzać liczbą skryptów oraz ich procedurami/funkcjami. Skrypty (jednostki skryptowe i formularze skryptowe) składają się z funkcji/procedur, które mogą być wywoływane w Altium Designer.
Przykłady VBScript
Proste przykłady zawarte w tym materiale referencyjnym ilustrują podstawowe możliwości programowania w VBScript w Altium Designer.
Skrypty VBScript mogą używać formularzy skryptowych, jednostek skryptowych, funkcji i obiektów z API skryptowego Altium Designer oraz podzbioru funkcji i obiektów z Embarcadero Delphi RTL udostępnionych w systemie skryptowym.
Pisanie skryptów VBScript
Ta sekcja omawia podstawowe koncepcje pisania skryptów VBScript w Altium Designer.
Konwencje nazewnictwa VBScript
W VBScript wielkość liter w nazwach zmiennych nie ma znaczenia — to znaczy, że zmienne zapisane 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 mają zmienne lokalne i globalne, ważne jest, aby w obrębie projektu skryptowego stosować unikalne nazwy zmiennych. Jeśli zmienne są zdefiniowane outside jakimikolwiek podprogramami i funkcjami, są globalne i mogą być dostępne z dowolnej jednostki w tym samym projekcie.
Jeśli zmienne są zdefiniowane inside procedury, wówczas te zmienne lokalne nie są dostępne poza tymi procedurami. Ponieważ skrypty są beztypowe, zmienne nie są inicjalizowane wraz z ich typami.
Zmienne lokalne wewnątrz procedury są inicjalizowane automatycznie.
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 dopuszcza dwa rodzaje procedur: podprogramy (subroutines) i funkcje — funkcja zwraca 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 VBScript deklaracja procedury zwykle zawiera listę parametrów — pamiętaj, że zmienne są traktowane jako beztypowe, a system skryptowy automatycznie ustala, jakie są typy zmiennych. Wartość użyta w miejscu parametru podczas wywołania procedury nazywa się 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
Zwróć uwagę, że użycie słowa kluczowego Call do wywołania podprogramu lub funkcji jest opcjonalne (utrzymane ze względu na zgodność wsteczną).
Komentarze w skryptach
W skrypcie komentarze to niewykonywane linie kodu, dodawane z myślą o programiście. Komentarze można umieszczać praktycznie w dowolnym miejscu skryptu.
Komentarze w VBScript:
-
Dowolny tekst po
'jest ignorowany. -
Dowolny tekst po
Remjest ignorowany.
Example
' This whole line is a comment
REM this whole line is also a comment
DocName = Document.Name ' Get name of active document
Dzielenie linii skryptu
W VBScript każda instrukcja kodu jest zakończona na końcu linii (kombinacją CR/LF), co oznacza koniec instrukcji. VBScript pozwala zapisać instrukcję w kilku liniach kodu, dzieląc długie polecenie na dwie lub więcej linii, używając znaku podkreślenia (_).
VBScript nie nakłada praktycznego limitu długości pojedynczej linii kodu w skrypcie. Jednak ze względu na czytelność i łatwość debugowania dobrą praktyką jest ograniczanie długości linii kodu tak, aby można je było łatwo odczytać na ekranie lub w wydruku. Jeśli linia kodu jest bardzo długa, można ją podzielić na wiele linii, a interpreter VB potraktuje ten kod tak, jakby był zapisany w jednej linii.
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
Używanie modeli obiektowych Altium Designer
Największą zaletą systemu skryptowego jest to, że interfejsy obiektów Altium Designer (Object Interfaces) są dostępne do użycia w skryptach VBScript. Na przykład możesz aktualizować obiekty projektu w dokumentach schematu i PCB, korzystając odpowiednio z interfejsów schematu (Schematic Interfaces) i interfejsów PCB.
Interfejsy obiektów Altium Designer są dostępne do użycia w dowolnym skrypcie. Zwykle w skryptach nie ma potrzeby tworzenia instancji interfejsu. Pobierany jest interfejs reprezentujący istniejący obiekt Altium Designer, a z tego interfejsu można wydobyć osadzone lub agregowane obiekty interfejsów, aby odczytywać lub ustawiać wartości ich właściwości.
Aby uzyskać dostęp do dokumentu PCB i jego obiektów danych, najpierw wywołaj funkcję PCBServer. Zgodnie z konwencją nazwy interfejsów są poprzedzane znakiem I — na przykład IPCB_Board reprezentuje interfejs dla istniejącego dokumentu PCB w 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, wywołaj 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
Do obiektów, interfejsów i funkcji Altium Designer można uzyskać dostęp w skryptach z następujących źródeł:
- Client API
- PCB Server API
- Schematic Server API
- Work Space Manager Server API
- Nexus API
- Funkcje API Altium Designer
- Procesy parametryczne
Słowa zastrzeżone i funkcje
System skryptowy obsługuje język VBScript, który wywodzi się z technologii języka Microsoft Active Scripting. Słowa zastrzeżone 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
Tłumaczenie SI