VBScript
Sơ lược
- Nắm vững các quy ước đặt tên, phạm vi biến, cách gọi thủ tục, chú thích và cách nối dòng trong VBScript.
- Tìm hiểu cách tổ chức các đơn vị mã script và biểu mẫu thành dự án cũng như cách chạy script.
- Xem cách script truy cập các mô hình đối tượng của Altium Designer, các API được hỗ trợ và một phần của thư viện thời gian chạy Delphi.
Tài liệu tham khảo này mô tả ngôn ngữ VisualBasic Scripting được dùng để tạo tập lệnh trong Altium Designer. Tài liệu cung cấp thông tin chi tiết về các câu lệnh, hàm và phần mở rộng của VisualBasic Scripting được hệ thống tập lệnh hỗ trợ.
Nội dung khác trong tài liệu tham khảo này:
- Các câu lệnh VBScript
- Chương trình con và hàm trong VBScript
- Sử dụng các thành phần biểu mẫu với VBScript
Ngôn ngữ VBScript
Visual Basic Scripting (hay viết tắt là VBScript) có thể được dùng để tạo các tập lệnh làm việc với các mô hình đối tượng và thành phần trực quan của Altium Designer. Tài liệu tham khảo này giả định rằng bạn đã quen với các khái niệm lập trình cơ bản và cách vận hành cơ bản của Altium Designer.
Hệ thống tập lệnh của Altium Designer hỗ trợ ngôn ngữ VBScript (cùng với các ngôn ngữ tập lệnh khác), vốn được phát triển từ hệ thống Microsoft ActiveX Scripting. Vì vậy, chẳng hạn, bạn có thể sử dụng CScripts hoặc WScripts dựa trên cùng bộ máy thực thi tập lệnh ActiveX được dùng trong Altium Designer.
Tất cả các ngôn ngữ tập lệnh được hỗ trợ trong Altium Designer đều không định kiểu, nghĩa là tập lệnh không thể định nghĩa bản ghi hoặc lớp và truyền con trỏ làm tham số cho hàm.
VBScript script example
Sub DisplayName (sName)
MsgBox "My Name is " & sName
End Sub
Altium Designer và Delphi RTL
Hệ thống tập lệnh hỗ trợ một tập con của thư viện thời gian chạy Embarcadero Delphi (RTL) và API Altium Designer.
Các tập lệnh VBScript có thể truy cập nhiều mô hình đối tượng trong Altium Designer. Ví dụ: có thể sử dụng mô hình đối tượng PCB trong VBScript để làm việc với các đối tượng PCB trên tài liệu PCB, hoặc mô hình đối tượng Workspace Manager để làm việc với các dự án và tài liệu của chúng nhằm trích xuất dữ liệu danh sách kết nối.
Tài liệu tham khảo về tập lệnh chứa thông tin về các giao diện liên quan đến mô hình đối tượng Altium Designer, các thành phần, chương trình con toàn cục, kiểu và biến cấu thành ngôn ngữ tập lệnh này. Tham khảo tài liệu Microsoft Visual Basic để biết thêm thông tin về các hàm VBScript.
Tiến trình máy chủ
Có thể sử dụng tập lệnh để thực thi các tiến trình máy chủ, vốn đại diện cho các lệnh trong Altium Designer.
Tệp mã nguồn VBScript
Dự án VBScript được tổ chức để lưu trữ các tài liệu tập lệnh (đơn vị mã tập lệnh và biểu mẫu tập lệnh). Có thể thực thi tập lệnh từ một mục menu, nút trên thanh công cụ hoặc từ hộp thoại Run Script trong menu hệ thống.
Các tệp PRJSCR, VBS và DFM
Các tập lệnh được tổ chức thành dự án có phần mở rộng *.PRJSCR. Mỗi dự án VBScript gồm các tệp có phần mở rộng *.vbs. Các tệp có thể là đơn vị mã tập lệnh hoặc biểu mẫu tập lệnh — mỗi biểu mẫu có một tệp tập lệnh VBScript với phần mở rộng *.vbs và một biểu mẫu tương ứng với phần mở rộng *.dfm). Biểu mẫu tập lệnh là một cửa sổ đồ họa (hộp thoại) chứa các điều khiển khác nhau chạy trên nền Altium Designer.
Có thể đính kèm tập lệnh vào các dự án khác nhau. Bạn nên tổ chức tập lệnh thành nhiều dự án để quản lý số lượng tập lệnh cùng các thủ tục/hàm của chúng. Tập lệnh (đơn vị mã tập lệnh và biểu mẫu tập lệnh) gồm các hàm/thủ tục có thể được gọi trong Altium Designer.
Ví dụ về VBScript
Các ví dụ đơn giản trong tài liệu tham khảo này minh họa những tính năng cơ bản của việc lập trình VBScript trong Altium Designer.
Các tập lệnh VBScript có thể sử dụng biểu mẫu tập lệnh, đơn vị mã tập lệnh, hàm và đối tượng từ API tập lệnh Altium Designer, cùng một tập con các hàm và đối tượng từ Embarcadero Delphi RTL được cung cấp trong hệ thống tập lệnh.
Viết tập lệnh VBScript
Phần này trình bày các khái niệm cơ bản về cách viết VBScript trong Altium Designer.
Quy ước đặt tên trong VBScript
Biến trong VBScript không phân biệt chữ hoa và chữ thường — nghĩa là các biến viết bằng chữ hoa và chữ thường có cùng ý nghĩa:
Example
The variables b and B are the same.
b = 60
B = 60
Biến cục bộ và biến toàn cục
Vì mọi tập lệnh đều có biến cục bộ và biến toàn cục, bạn cần đặt tên biến duy nhất cho các tập lệnh trong cùng một dự án tập lệnh. Nếu các biến được định nghĩa outside mọi chương trình con và hàm, chúng là biến toàn cục và có thể được truy cập từ bất kỳ đơn vị mã nào trong cùng dự án.
Nếu các biến được định nghĩa inside một chương trình con, thì không thể truy cập các biến cục bộ này từ bên ngoài chương trình con đó. Vì tập lệnh không định kiểu nên các biến không được khởi tạo kèm theo kiểu.
Các biến cục bộ bên trong một thủ tục được khởi tạo tự động.
Variable Initialization
Sub Example
Dim X
Dim s
' x set to 0
x = 0
' s set to empty
s = ""
End Sub
Chương trình con và hàm
VBScript cho phép hai loại thủ tục: chương trình con và hàm — chỉ hàm mới trả về giá trị. Cú pháp gọi chương trình con hoặc hàm trong tập lệnh là:
Call SubRoutineA(parameters)
...hoặc
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
Tham số và đối số
Trong VBScript, khai báo thủ tục thường có một danh sách tham số — lưu ý rằng các biến được xem là không định kiểu và hệ thống tập lệnh tự động xác định kiểu của biến. Giá trị được dùng thay cho tham số khi bạn gọi thủ tục được gọi là đối số.
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
Lưu ý rằng việc sử dụng từ khóa Call để gọi chương trình con hoặc hàm là không bắt buộc (được duy trì để tương thích ngược).
Chú thích trong tập lệnh
Trong tập lệnh, chú thích là những dòng mã không được thực thi, được thêm vào để hỗ trợ lập trình viên. Có thể thêm chú thích ở hầu hết mọi vị trí trong tập lệnh.
Đối với chú thích trong VBScript:
-
Mọi văn bản theo sau
'đều bị bỏ qua. -
Mọi văn bản theo sau
Remđều bị bỏ qua.
Example
' This whole line is a comment
REM this whole line is also a comment
DocName = Document.Name ' Get name of active document
Ngắt dòng tập lệnh
Trong VBScript, mỗi câu lệnh mã được kết thúc trên dòng (bằng tổ hợp CR/LF) để đánh dấu điểm kết thúc câu lệnh. VBScript cho phép bạn viết một câu lệnh trên nhiều dòng mã, chia một chỉ thị dài thành hai dòng trở lên bằng ký tự gạch dưới (_).
VBScript không đặt ra giới hạn thực tế nào đối với độ dài của một dòng mã trong tập lệnh. Tuy nhiên, để mã dễ đọc và dễ gỡ lỗi, bạn nên giới hạn độ dài các dòng mã sao cho có thể dễ dàng đọc trên màn hình hoặc bản in. Nếu một dòng mã quá dài, có thể ngắt thành nhiều dòng và trình thông dịch VB sẽ xử lý đoạn mã này như thể nó được viết trên một dòng duy nhất.
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
Sử dụng mô hình đối tượng Altium Designer
Tính năng nổi bật nhất của hệ thống tập lệnh là cho phép sử dụng các giao diện của đối tượng Altium Designer (giao diện đối tượng) trong VBScript. Ví dụ: bạn có thể cập nhật các đối tượng thiết kế trên tài liệu sơ đồ nguyên lý và PCB thông qua giao diện sơ đồ nguyên lý và giao diện PCB tương ứng.
Các giao diện đối tượng Altium Designer có thể được sử dụng trong bất kỳ tập lệnh nào. Thông thường, trong tập lệnh không cần khởi tạo giao diện. Giao diện đại diện cho một đối tượng Altium Designer hiện có được truy xuất; từ giao diện này, có thể truy xuất các đối tượng giao diện nhúng hoặc tổng hợp để lấy hoặc đặt giá trị thuộc tính của chúng.
Để truy cập tài liệu PCB và các đối tượng dữ liệu của tài liệu đó, trước tiên bạn gọi hàm PCBServer. Theo quy ước, tên giao diện có tiền tố là ký tự I — ví dụ, IPCB_Board đại diện cho một giao diện của tài liệu PCB hiện có trong 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
Để truy cập tài liệu PCB, hãy gọi 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
Đối tượng, giao diện và hàm
Có thể truy cập các đối tượng, giao diện và hàm của Altium Designer trong tập lệnh thông qua:
- API Client
- API PCB Server
- API Schematic Server
- API Work Space Manager Server
- API Nexus
- Các hàm API của Altium Designer
- Các quy trình có tham số
Các từ dành riêng và hàm
Hệ thống tập lệnh hỗ trợ ngôn ngữ VBScript, được phát triển từ công nghệ ngôn ngữ Microsoft Active Scripting. Các từ dành riêng trong VBScript là:
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