VBScript

Tài liệu tham khảo này mô tả ngôn ngữ Visual Basic Scripting được sử dụng để tạo các tập lệnh trong Altium Designer. Tài liệu này cung cấp thông tin chi tiết về các câu lệnh, hàm và tiện ích mở rộng của Visual Basic Scripting được hỗ trợ trong hệ thống tập lệnh.

Ngoài ra, tài liệu tham khảo này còn bao gồm:

• Các câu lệnh VBScript
• Hàm 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 (viết tắt là VBScript) có thể được sử dụng để tạo các tập lệnh xử lý các Mô hình đối tượng và Thành phần trực quan của Altium Designer. Trong tài liệu tham khảo này, chúng tôi giả định rằng bạn đã quen thuộc 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 Altium Designer hỗ trợ ngôn ngữ VBScript (cùng với các ngôn ngữ tập lệnh khác) có nguồn gốc từ hệ thống Microsoft ActiveX Scripting. Ví dụ, bạn có thể sử dụng CScripts hoặc WScripts dựa trên cùng một công cụ tập lệnh ActiveX được sử dụng trong Altium Designer.

Tất cả các ngôn ngữ kịch bản được hỗ trợ trong Altium Designer đều là ngôn ngữ không kiểu (untyped), có nghĩa là một kịch bản không thể định nghĩa các bản ghi (records) hoặc lớp (classes) và không thể truyền các con trỏ (pointers) làm tham số cho các hàm.

VBScript script example

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

Altium Designer và RTL của Delphi

Hệ thống kịch bản hỗ trợ một tập con của Thư viện Thời gian Chạy (RTL) của Embarcadero Delphi và API của Altium Designer.

Các kịch bản VBScript có thể truy cập nhiều Mô hình Đối tượng trong Altium Designer. Ví dụ, Mô hình Đối tượng PCB có thể được sử dụng trong VBScript để thao tác với các đối tượng PCB trên tài liệu PCB, hoặc Mô hình Đối tượng Quản lý Không gian Làm việc để 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 netlist.

Tài liệu tham khảo về kịch bản chứa thông tin về các giao diện liên quan đến các Mô hình đối tượng Altium Designer, các thành phần, các thói quen toàn cục, các loại và các biến tạo nên ngôn ngữ kịch bản 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.

Các quy trình máy chủ

Có thể sử dụng tập lệnh để thực thi các quy trình máy chủ, đại diện cho các lệnh trong Altium Designer.

Tệp nguồn VBScript

Một dự án VBScript được tổ chức để lưu trữ các tài liệu kịch bản (các đơn vị kịch bản và biểu mẫu kịch bản). Một kịch bản có thể được thực thi từ một mục menu, nút trên thanh công cụ hoặc từ hộp thoại Run Script hộp thoại từ menu hệ thống.

Tệp PRJSCR, VBS và DFM

Các tập lệnh được tổ chức thành các dự án với phần mở rộng *.PRJSCR phần mở rộng. Mỗi dự án VBScript bao gồm các tệp có *.vbs . Các tệp có thể là đơn vị kịch bản hoặc biểu mẫu kịch bản — mỗi biểu mẫu có một tệp kịch bản VBScript với *.vbs và một biểu mẫu tương ứng có phần mở rộng *.dfm ). Một biểu mẫu kịch bản 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ể gắn các tập lệnh vào các dự án khác nhau, và chúng tôi khuyến nghị mạnh mẽ việc tổ chức các tập lệnh thành các dự án riêng biệt để quản lý số lượng tập lệnh cũng như các thủ tục/hàm của chúng. Các tập lệnh (đơn vị tập lệnh và biểu mẫu tập lệnh) bao gồm các hàm/thủ tục có thể được gọi từ bên trong Altium Designer.

Ví dụ về VBScript

Các ví dụ đơn giản được trình bày trong tài liệu tham khảo này minh họa các tính năng cơ bản của lập trình VBScript trong Altium Designer.

Các VBScript có thể sử dụng các biểu mẫu tập lệnh, đơn vị tập lệnh, hàm và đối tượng từ API tập lệnh Altium Designer, cũng như một tập hợp con các hàm và đối tượng từ Embarcadero Delphi RTL được hiển thị trong hệ thống tập lệnh.

Viết kịch bản VBScript

Phần này trình bày các khái niệm cơ bản về việc viết kịch bản VBScript trong Altium Designer.

Quy ước đặt tên trong VBScript

Các biến VBScript không phân biệt chữ hoa chữ thường — nghĩa là, các biến viết hoa và viết 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ì tất cả các kịch bản đều có biến cục bộ và biến toàn cục, nên việc đặt tên biến duy nhất trong các kịch bản của bạn trong một dự án kịch bản là rất quan trọng. Nếu các biến được định nghĩa outside trong các tiểu chương trình và hàm, chúng sẽ là biến toàn cục và có thể được truy cập bởi bất kỳ đơn vị nào trong cùng một dự án.

Nếu các biến được định nghĩa inside trong một thủ tục, thì các biến cục bộ này không thể truy cập được bên ngoài các thủ tục đó. Vì các tập lệnh không phân biệt kiểu dữ liệu, các biến không được khởi tạo với kiểu dữ liệu của chúng.

Các biến cục bộ bên trong một thủ tục sẽ đượ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

Tiểu chương trình và hàm

VBScript cho phép hai loại thủ tục: hàm con và hàm — một hàm chỉ trả về một giá trị. Cú pháp gọi một hàm con hoặc hàm trong một 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 các tham số — lưu ý rằng các biến được coi là không có kiểu và hệ thống kịch bản sẽ tự động xác định kiểu của các biến đó. Giá trị được sử 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 một hàm con hoặc hàm là tùy chọn (được duy trì để đảm bảo tương thích ngược).

Chú thích trong tập lệnh

Trong một tập lệnh, chú thích là các dòng mã không được thực thi, được đưa vào để hỗ trợ người lập trình. Chú thích có thể được đưa vào hầu như bất kỳ vị trí nào trong tập lệnh.

Với chú thích trong VBScript:

• Bất kỳ văn bản nào nằm sau ' sẽ bị bỏ qua.
• Bất kỳ văn bản nào sau Rem sẽ 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

Chia dòng lệnh

Trong VBScript, mỗi câu lệnh được kết thúc trên cùng một dòng (bằng tổ hợp CR/LF) để chỉ ra điểm kết thúc của 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ã, nhằm chia một câu lệnh dài thành hai dòng hoặc nhiều dòng, bằng cách sử dụng ký tự gạch dưới (_).

VBScript không đặt ra bất kỳ giới hạn thực tế nào về độ dài của một dòng mã trong tập lệnh. Tuy nhiên, để đảm bảo tính dễ đọc và dễ gỡ lỗi, bạn nên hạn chế độ dài của các dòng mã để có thể dễ dàng đọc trên màn hình hoặc khi in ra. Nếu một dòng mã quá dài, bạn có thể chia nó thành nhiều dòng, và mã này sẽ được trình thông dịch VB xử lý 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 kịch bản là các Giao diện Đối tượng của Altium Designer (Object Interfaces) có thể được sử dụng trong các kịch bản VBScript. Ví dụ, bạn có thể cập nhật các đối tượng thiết kế trên các tài liệu Sơ đồ và PCB thông qua việc sử dụng các Giao diện Sơ đồ 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 các tập lệnh, không cần phải khởi tạo một giao diện. Giao diện đại diện cho một đối tượng Altium Designer hiện có sẽ được trích xuất, và từ giao diện này, các đối tượng giao diện nhúng hoặc tổng hợp có thể được trích xuất để lấy hoặc thiết lập các 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 nó, trước tiên bạn cần gọi hàm PCBServer hàm này. Theo quy ước, tên giao diện được đặt trước bằng mộ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 vào một tài liệu PCB, hãy gọi hàm 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 các tập lệnh từ:

• API khách hàng
• API máy chủ PCB
• API máy chủ sơ đồ
• API máy chủ Quản lý không gian làm việc
• API Nexus
• Các hàm API của Altium Designer
• Quy trình tham số

Các từ khóa và hàm được dành riêng

Hệ thống kịch bản hỗ trợ ngôn ngữ VBScript, được phát triển dựa trên công nghệ ngôn ngữ Microsoft Active Scripting. Các từ khóa được 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