DelphiScript
Sơ lược
- Hiểu về các biến không định kiểu, quy tắc đặt tên, phạm vi và tính phân biệt chữ hoa, chữ thường trong DelphiScript.
- Tìm hiểu cách tổ chức các đơn vị mã và biểu mẫu trong dự án tập lệnh cũng như cách thực thi tập lệnh.
- Tìm tài liệu tham khảo về các tính năng ngôn ngữ được hỗ trợ, API của Altium Designer và các tập lệnh mẫu, bao gồm những lưu ý về các ví dụ cũ.
Phần này mô tả ngôn ngữ DelphiScript được công cụ tạo tập lệnh của Altium Designer sử dụng, đồng thời cung cấp thông tin tham khảo chi tiết về các câu lệnh, hàm và phần mở rộng được hỗ trợ. Đây là các thủ tục đặc biệt dùng để điều khiển và giao tiếp trực tiếp với Altium Designer.
Nội dung khác trong tài liệu tham khảo này:
- Điểm khác biệt giữa DelphiScript và Delphi
- Từ khóa DelphiScript
- Câu lệnh và toán tử DelphiScript
- Hàm DelphiScript
- Biểu mẫu và thành phần DelphiScript
Ngôn ngữ DelphiScript
Tài liệu tham khảo DelphiScript này giả định rằng bạn đã nắm vững các khái niệm lập trình cơ bản cũng như cách vận hành cơ bản của Altium Designer. Hệ thống tạo tập lệnh hỗ trợ ngôn ngữ DelphiScript, vốn rất giống với Embarcadero Delphi™.
Điểm khác biệt chính là DelphiScript là ngôn ngữ kịch bản không định kiểu, nghĩa là bạn 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. Bạn vẫn có thể khai báo biến trong tập lệnh để mã dễ đọc hơn.
Trang này và các trang con đi kèm chứa tài liệu tham khảo về các giao diện, 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ữ kịch bản DelphiScript.
Các yếu tố chính của DelphiScript
Đối tượng
Trong DelphiScript, một đối tượng bao gồm các phương thức và trong nhiều trường hợp có cả thuộc tính và sự kiện. Thuộc tính biểu thị dữ liệu chứa trong đối tượng, phương thức là các hành động mà đối tượng có thể thực hiện, còn sự kiện là các điều kiện mà đối tượng có thể phản hồi. Tất cả các đối tượng đều bắt nguồn (và kế thừa) từ đối tượng cấp cao nhất thuộc kiểu TObject.
Giao diện đối tượng
Một giao diện đối tượng bao gồm các phương thức và trong nhiều trường hợp có cả thuộc tính, nhưng không thể có các trường dữ liệu. Giao diện đại diện cho một đối tượng hiện có và mỗi giao diện có một GUID xác định tính duy nhất của nó. Thuộc tính biểu thị dữ liệu chứa trong đối tượng mà giao diện liên kết đến. Phương thức là các hành động mà đối tượng (được liên kết với giao diện) có thể thực hiện.
Thành phần
Thành phần là các đối tượng trực quan từ bảng Tool Palette có thể được thao tác trong quá trình thiết kế. Tất cả các thành phần đều kế thừa từ lớp hệ thống TComponent trong Thư viện thành phần trực quan (VCL) của Embarcadero Delphi.
Chương trình con
Chương trình con toàn cục là các thủ tục và hàm của hệ thống tạo tập lệnh. Các chương trình con này không thuộc một lớp nhưng có thể được gọi trực tiếp hoặc từ bên trong các phương thức của lớp trong tập lệnh.
Kiểu
Các kiểu biến được dùng làm kiểu trả về và kiểu tham số cho phương thức và thuộc tính của giao diện, phương thức, thuộc tính và sự kiện của đối tượng, cũng như các chương trình con toàn cục. Trong nhiều trường hợp, các kiểu được mô tả trong các phần Kiểu liệt kê của tài liệu API.
Altium Designer và Delphi RTL
Hệ thống tạo tập lệnh hỗ trợ một tập con của Thư viện thời gian chạy (RTL) Embarcadero Delphi và API Altium Designer.
Tệp mã nguồn DelphiScript
Trong Altium Designer, dự án tập lệnh đượ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). Bạn 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 Select Item To Run có thể truy cập qua menu chính của Altium Designer.
Tệp PRJSCR, PAS và DFM
Các tập lệnh được tổ chức thành các dự án có phần mở rộng *.PRJSCR. Mỗi dự án bao gồm các tệp có phần mở rộng *.pas. Các tệp có thể là đơn vị mã tập lệnh hoặc biểu mẫu tập lệnh — lưu ý rằng mỗi biểu mẫu có một tệp tập lệnh với phần mở rộng *.pas và một tệp biểu mẫu tương ứng có 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ạy trên Altium Designer và chứa nhiều điều khiển khác nhau mà người dùng có thể truy cập.
Bạn 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 các dự án riêng để quản lý số lượng tập lệnh cũng như các thủ tục/hàm của chúng.
Tập lệnh ví dụ
Bộ sưu tập tập lệnh ví dụ minh họa các tính năng cơ bản của lập trình DelphiScript thông qua những tập lệnh đơn giản dùng trong Altium Designer.
Vị trí và mục đích của một số tập lệnh ví dụ được liệt kê dưới đây:
-
Scripts\DelphiScript Scripts\DXPthư mục - Minh họa API Client và API hệ thống -
Scripts\DelphiScript Scripts\PCThư mục B - Minh họa API PCB -
Scripts\DelphiScript Scripts\Processesthư mục - Minh họa các tiến trình máy chủ -
Scripts\DelphiScript Scripts\Generalthư mục - Minh họa các từ khóa DelphiScript -
Scripts\DelphiScript Scripts\Schthư mục - Minh họa API sơ đồ nguyên lý -
Scripts\DelphiScript Scripts\WSMthư mục - Minh họa API Workspace Manager
Viết tập lệnh DelphiScript
Quy ước đặt tên trong DelphiScript
Nhìn chung, không có hạn chế đối với tên được đặt cho thủ tục, hàm, biến và hằng, miễn là tuân thủ các quy tắc sau:
- Tên có thể chứa các chữ cái từ A đến Z, a đến z, ký tự gạch dưới "_" và các chữ số từ 0 đến 9.
- Tên phải bắt đầu bằng một chữ cái.
- Tên không được trùng với từ khóa, chỉ thị hoặc từ dành riêng của DelphiScript.
- Tên không phân biệt chữ hoa và chữ thường khi được thông dịch. Bạn có thể dùng cả chữ hoa và chữ thường khi đặt tên cho hàm, chương trình con, biến hoặc hằng, nhưng trình thông dịch sẽ không phân biệt ký tự hoa và thường. Các tên chỉ khác nhau về chữ hoa và chữ thường sẽ được coi là cùng một tên trong DelphiScript.
Trong tệp DelphiScript, các hàm và thủ tục được khai báo bằng các khối Procedure-Begin-End hoặc Function-Begin-End. Cả hai khối câu lệnh này đều yêu cầu đặt tên cho thủ tục hoặc hàm. DelphiScript cho phép bạn tạo các biến và hằng có tên để lưu giữ những giá trị được sử dụng trong tập lệnh hiện tại.
Thêm chú thích
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. Bạn có thể thêm chú thích ở hầu hết mọi vị trí trong tập lệnh.
Mọi văn bản nằm sau // hoặc được bao trong (* *) hoặc {} đều bị DelphiScript bỏ qua.
//This whole line is a comment
{This whole line is a comment}
{
These lines are comments
These lines are comments
}
(* This whole line is a comment *)
(*
These lines are comments
These lines are comments
*)
Bạn cũng có thể thêm chú thích trên cùng dòng với mã được thực thi. Ví dụ: mọi nội dung sau dấu chấm phẩy trong dòng mã sau đều được coi là chú thích.
ShowMessage ('Hello World'); //Display Message
Biến cục bộ và biến toàn cục
Vì tất cả các tập lệnh đều có biến cục bộ và biến toàn cục, việc đặt tên biến duy nhất trong các tập lệnh thuộc cùng một dự án tập lệnh là rất quan trọng. Nếu các biến được định nghĩa outside mọi thủ tục 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ã tập lệnh nào trong cùng dự án.
Nếu các biến được định nghĩa inside một thủ tục hoặc hàm, thì không thể truy cập các biến cục bộ này từ bên ngoài những thủ tục/hàm đó.
Example of Local and Global Variables in a Script:
// Note: The Uses keyword is not needed.
{ The global variable from UnitA script (see below) is available to this Script Unit,
as long UnitA is in the same project as this Script Unit. }
Const
GlobalVariableFromThisUnit='Global Variable from this unit';
Procedure TestLocal;
var
Local;
Begin
Local := 'Local Variable';
ShowMessage(Local);
End;
Procedure TestGlobal;
Begin
//ShowMessage(Local); // This line produces an error because the 'Local' variable is not global.
ShowMessage(GlobalVariableFromThisUnit);
// A variable from UnitA can be accessed without the Uses keyword.
ShowMessage(GlobalVariableFromUnitA);
End;
UnitA script:
Const
GlobalVariableFromUnitA = 'Global Variable from Unit A';
Sử dụng biến có tên
Trong một tập lệnh, các biến hoặc hằng có tên được tạo để lưu trữ các giá trị sẽ được sử dụng trong quá trình thực thi chương trình. Tất cả các biến trong tập lệnh luôn có kiểu Variant. Việc ép kiểu không áp dụng, vì vậy kiểu dữ liệu trong khai báo biến sẽ bị bỏ qua và có thể được lược bỏ. Do đó, các khai báo sau đây là đúng:
Var a : integer;
Var b : integer;
Var c, d;
Ngắt dòng
Mỗi câu lệnh mã được kết thúc bằng ký tự dấu chấm phẩy ; để đánh dấu điểm kết thúc câu lệnh. DelphiScript cho phép bạn viết một câu lệnh trên nhiều dòng mã, chia một lệnh dài thành hai dòng trở lên. Hạn chế duy nhất khi chia câu lệnh lập trình thành nhiều dòng là một chuỗi ký tự nguyên văn không được trải dài trên nhiều dòng.
For example:
X.AddPoint( 25, 100);
X.AddPoint( 0, 75);
// is equivalent to:
X.AddPoint( 25, 100); X.AddPoint( 0, 75);
however...
'Hello World!'
\\is not equivalent to
'Hello
World!'
DelphiScript không đặt ra giới hạn thực tế nào về độ dài của một dòng mã trong tập lệnh, nhưng để dễ đọc và 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, bạn có thể ngắt dòng đó thành nhiều dòng, và trình thông dịch DelphiScript 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 Exit;
Formatted code example:
If Not (PcbApi_ChooseRectangleByCorners(BoardHandle,
'Choose first corner',
'Choose final corner',
x1,y1,x2,y2)) Then Exit;
Phân biệt chữ hoa và chữ thường
Ngôn ngữ DelphiScript dùng để viết tập lệnh không phân biệt chữ hoa và chữ thường — nghĩa là tất cả các từ khóa, câu lệnh, tên biến, tên hàm và tên thủ tục đều có thể được viết mà không cần quan tâm đến việc dùng chữ hoa hay chữ thường. Cả ký tự chữ hoa và chữ thường đều được xem là tương đương.
Ví dụ, tên biến myVar tương đương với myvar và MYVAR. DelphiScript coi tất cả các tên này là cùng một biến.
Ngoại lệ duy nhất là các chuỗi ký tự nguyên văn, chẳng hạn như chuỗi tiêu đề trong định nghĩa hộp thoại hoặc giá trị của một biến chuỗi. Các chuỗi này vẫn giữ nguyên sự khác biệt giữa chữ hoa và chữ thường.
Ký tự dấu cách
Dấu cách được dùng để phân tách các từ khóa trong một câu lệnh của tập lệnh. Tuy nhiên, DelphiScript bỏ qua mọi khoảng trắng bổ sung trong câu lệnh.
Ví dụ:
X = 5
// is equivalent to
X =5
Bạn có thể sử dụng khoảng trắng để tập lệnh dễ đọc hơn.
Hàm và thủ tục trong tập lệnh
Trình thông dịch DelphiScript cho phép hai loại phương thức: thủ tục và hàm. Điểm khác biệt duy nhất giữa hàm và thủ tục là hàm trả về một giá trị.
Một tập lệnh có thể có ít nhất một thủ tục định nghĩa mã chương trình chính. Tuy nhiên, bạn có thể định nghĩa các thủ tục và hàm khác để gọi từ mã của mình.
Tương tự như trong Embarcadero Delphi, thủ tục và hàm được định nghĩa trong một khối câu lệnh Begin-End. Để gọi một hàm hoặc thủ tục, hãy đưa tên hàm hoặc thủ tục đó vào một câu lệnh, giống như khi sử dụng các hàm và thủ tục tích hợp sẵn của DelphiScript. Nếu hàm hoặc thủ tục yêu cầu tham số, bạn phải đưa các tham số đó vào câu lệnh gọi. Cả hàm và thủ tục đều có thể được định nghĩa để nhận tham số, nhưng chỉ hàm mới có thể được định nghĩa để trả về một giá trị cho câu lệnh gọi.
Bạn có thể đặt bất kỳ tên nào cho hàm và thủ tục khi định nghĩa, miễn là tên đó tuân thủ các quy ước đặt tên tiêu chuẩn của DelphiScript.
Typical DelphiScript Procedure:
Procedure CreateSchObjects;
Begin
If SchServer = Nil Then Exit;
SchDoc := SchServer.GetCurrentSchDocument;
If SchDoc = Nil Then Exit;
PlaceSchematicObjects;
SchDoc.GraphicallyInvalidate;
End;
Typical DelphiScript Function:
Function BooleanToString(AValue : Boolean) : String;
Begin
If (AValue) Then Result := 'True'
Else Result := 'False';
End;
Không thể dùng tên hàm để gán giá trị trả về của hàm. Thay vào đó, phải sử dụng từ khóa Result.
Var, Begin-End global block:
Var
A, B, C;
Begin
B := 10;
C := 20;
A := B + C;
ShowMessage(IntToStr(A));
End;
Mẹo viết tập lệnh
Tham chiếu tập lệnh trong dự án tập lệnh
Mã trong một tập lệnh có thể gọi thủ tục trong một tập lệnh khác thuộc cùng dự án tập lệnh. Mọi biến toàn cục trong bất kỳ tập lệnh nào đều có thể được truy cập trong cùng dự án.
Biến cục bộ và biến toàn cục
Vì tập lệnh có cả biến cục bộ và biến toàn cục, việc đặt tên biến không trùng lặp giữa các tập lệnh trong một dự án tập lệnh là rất quan trọng. Nếu các biến được định nghĩa bên ngoài mọi thủ tục 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 bên trong một thủ tục hoặc hàm, thì không thể truy cập các biến cục bộ này từ bên ngoài thủ tục hoặc hàm đó.
Bạn nên đưa các tập lệnh có tính chất tương tự vào cùng một dự án và giữ số lượng tập lệnh trong dự án ở mức dễ quản lý — việc theo dõi các biến toàn cục trong nhiều tập lệnh có thể trở thành vấn đề. Không bắt buộc phải lưu tập lệnh trong dự án tập lệnh, vì tập lệnh cũng có thể được đặt trong các loại dự án khác.
Định danh và biến không trùng lặp
Khi sử dụng biểu mẫu tập lệnh, hãy đảm bảo tất cả các biểu mẫu đều có tên không trùng lặp. Chẳng hạn, tất cả các biểu mẫu tập lệnh trong cùng một dự án tập lệnh đều có thể được đặt tên là form1. Trong trường hợp này, hệ thống tập lệnh sẽ gặp xung đột khi cố gắng hiển thị đúng biểu mẫu lúc một biểu mẫu tập lệnh được thực thi.
Có thể thay đổi tên biểu mẫu tập lệnh bằng Object Inspector. Tên sẽ được tự động thay đổi trong cả tệp đơn vị mã tập lệnh và tệp biểu mẫu tập lệnh.
Thủ tục và hàm không có tham số
Nên viết tập lệnh sao cho chỉ các thủ tục cần gọi để chạy tập lệnh mới xuất hiện trong hộp thoại Chọn mục để chạy. Để ngăn các thủ tục/hàm khác xuất hiện trong hộp thoại Select Items to Run, có thể chèn tham số (Dummy : Integer) bên cạnh tên phương thức. Xem ví dụ bên dưới.
// This function is prevented from appearing in the Select Items to Run dialog.
Function TSineWaveform.CreateShape(Dummy : Integer);
Begin
//Do something
End;
{..................................................}
{..................................................}
Procedure TSineWaveform.bCloseClick(Sender: TObject);
var
I : integer;
Begin
//Doing something
Close;
End;
{..................................................}
{..................................................}
procedure DrawSine;
Begin
SineWaveform.showmodal;
End;
Mã lỗi DelphiScript
Error |
Description |
|---|---|
|
Sử dụng chuỗi không đúng trong tập lệnh. |
|
Sử dụng chuỗi không đúng trong tập lệnh. |
|
Không cho phép có nhiều hàm trùng tên trong mã. Hãy đổi tên các hàm khác có cùng tên. |
|
Định danh không xác định. Cần khai báo định danh này trước khi sử dụng. |
|
Tập lệnh có kiểu biến không hợp lệ hoặc không xác định. |
|
Không cho phép có nhiều đơn vị mã trùng tên. Hãy đảm bảo tên các đơn vị mã tập lệnh không trùng lặp. |
|
Khai báo đơn vị mã chưa được định nghĩa đúng. |
|
Thiếu hàm trong tập lệnh. |
|
DelphiScript không thể liên kết tập lệnh với các thành phần nội bộ cần thiết. |
|
Có nhiều nhãn trùng nhau trong tập lệnh. Hãy đảm bảo các nhãn trong tập lệnh không trùng lặp. |
|
Khối khai báo chưa được định nghĩa đúng. |
|
Nhãn Goto chưa được định nghĩa. |
|
Có nhiều biến trùng nhau trong tập lệnh. Hãy đảm bảo các biến không trùng lặp. |
|
Có lỗi trong khối khai báo biến. Khai báo không đúng hoặc không được hệ thống tập lệnh nhận dạng. |
|
Biến chưa được định nghĩa nên hệ thống tập lệnh không thể xác định biến này. |
|
Chữ ký phương thức không hợp lệ. |
|
Sử dụng tham số không đúng cho phương thức. |
|
Các thuộc tính của đối tượng không được hệ thống tập lệnh nhận dạng. |
|
Đã cố khai báo các thành phần không phải là lớp. |
|
Có lỗi khai báo trong tập lệnh. |
|
Đã xảy ra lỗi cú pháp trong tập lệnh |
|
Tên định danh không hợp lệ, chẳng hạn như tên định danh bị trùng. Hãy định nghĩa lại tên định danh. |
|
Định danh không hợp lệ. Hãy định nghĩa một định danh mới |
|
Hàm không được sử dụng đúng cách trong tập lệnh |
|
Thủ tục không được sử dụng đúng cách trong tập lệnh |
|
Giá trị hằng số thập lục phân không được khai báo đúng cách. |
|
Cần biên dịch tập lệnh trước khi thực thi. Lỗi nội bộ. |
|
Lỗi khai báo hằng số kiểu số thực. |
|
Lỗi khai báo hằng số kiểu chuỗi. |
|
Hệ thống tập lệnh báo cáo kiểu tham số không xác định. |
|
Không tìm thấy kết quả giá trị biến cho chuỗi được chỉ định trong tập lệnh. |
|
Thiếu thủ tục trong tập lệnh. |
|
Thiếu tham số trong tập lệnh. |
|
Lỗi nội bộ. |
|
Cùng một thủ tục hoặc hàm nhưng phần khai báo và phần triển khai không khớp nhau. Hãy kiểm tra các tham số giữa hai phần. |
|
Một trong các tham số của phương thức, hàm hoặc thủ tục có kiểu variant không đúng. |
|
Đã cố gắng gán giá trị cho thuộc tính chỉ đọc hoặc thuộc tính không tồn tại. |
|
Các đối số dùng cho thủ tục hoặc hàm không hợp lệ đối với tập lệnh. |
|
Thiếu giá trị tham số. |
|
Sử dụng sai kiểu tham số. |
|
Giao diện này chưa được khai báo hoặc định nghĩa. |
|
Thiếu tham số bắt buộc cho phương thức, hàm hoặc thủ tục. |
|
DelphiScript đã phát hiện một lỗi tập lệnh không xác định, chưa được định nghĩa trong bảng lỗi nội bộ. |
|
DelphiScript đã phát hiện một mã thao tác không hợp lệ. |