DelphiScript

本节介绍 Altium Designer 脚本引擎使用的 DelphiScript 语言，并提供支持的语句、函数和扩展的参考详细信息。这些特殊程序用于控制 Altium Designer 并与 Altium Designer 直接通信。

本参考资料中还有

• DelphiScript 与 Delphi 的区别
• DelphiScript 关键字
• DelphiScript 语句和操作符
• DelphiScript 函数
• DelphiScript 窗体和组件

DelphiScript 语言

本 DelphiScript 参考资料假定您已熟悉基本编程概念以及 Altium Designer 的基本操作。脚本系统支持与 Embarcadero Delphi™ 非常相似的 DelphiScript 语言。

主要区别在于 DelphiScript 是一种无类型或无类型脚本语言，这意味着你不能定义记录或类，也不能将指针作为参数传递给函数。为了便于阅读，仍可在脚本中声明变量。

本页及其附带子页包含组成 DelphiScript 脚本语言的接口、组件、全局例程、类型和变量的参考资料。

Delphiscript 关键元素

对象

在 DelphiScript 中，对象由方法、属性和事件组成。属性代表对象中包含的数据，方法是对象可以执行的操作，而事件则是对象可以做出反应的条件。所有对象都从顶层对象的 TObject类型。

对象接口

对象接口由方法组成，在很多情况下还包括属性，但不能有数据字段。接口代表一个现有的对象，每个接口都有一个 GUID，标志着它是唯一的。属性代表接口所关联的对象中包含的数据。方法是对象（与接口相关联）可以执行的操作。

组件

组件是工具面板中的可视化对象，可以在设计时进行操作。所有组件都从 TComponent系统类。

例程

全局例程是脚本系统中的过程和函数。这些例程不是类的一部分，但可以在脚本中直接调用或从类方法中调用。

类型

变量类型可用作接口方法和属性、对象方法、属性和事件以及全局例程的返回类型和参数类型。在许多情况下，API 文档中的枚举类型部分会对类型进行记录。

Altium Designer 和 Delphi RTL

脚本系统支持 Embarcadero Delphi 运行时库（RTL）和 Altium Designer API 的子集。

DelphiScript 源文件

在 Altium Designer 中，脚本项目用于存储脚本文档（脚本单元和脚本窗体）。您可以通过菜单项、工具栏按钮或 Altium Designer 主菜单中的 "选择要运行的项目"对话框来执行脚本。

PRJSCR、PAS 和 DFM 文件

脚本被组织到项目中，并以 *.PRJSCR扩展名的项目。每个项目由扩展名为 *.pas扩展名的文件组成。文件可以是脚本单元，也可以是脚本表单--请注意，每个表单都有一个扩展名为 *.pas扩展名的脚本文件和相应的表单文件。 *.dfm扩展名。脚本窗体是在 Altium Designer 上运行的图形窗口（对话框），包含不同的用户可访问控件。

可以将脚本附加到不同的项目中，强烈建议将脚本组织到不同的项目中，以便管理脚本的数量及其程序/功能。

脚本示例

脚本示例集通过在 Altium Designer 中使用简单脚本来说明 DelphiScript 编程的基本功能。

下面列出了部分示例脚本的位置和用途：

• Scripts\DelphiScript Scripts\DXP文件夹 - 演示客户端和系统 API
• Scripts\DelphiScript Scripts\PCB 文件夹 - 演示 PCB API
• Scripts\DelphiScript Scripts\Processes文件夹 - 演示服务器进程
• Scripts\DelphiScript Scripts\General文件夹 - 演示 DelphiScript 关键字
• Scripts\DelphiScript Scripts\Sch文件夹 - 演示示意图 API
• Scripts\DelphiScript Scripts\WSM文件夹 - 演示工作区管理器 API

编写 DelphiScript 脚本

DelphiScript 命名约定

一般来说，程序、函数、变量和常量的命名没有任何限制，只要它们遵守以下规则即可：

• 名称中可以包含字母 A 至 Z、a 至 z、下划线字符"_"以及数字 0 至 9。
• 名称必须以字母开头。
• 名称不能是 DelphiScript 关键字、指令或保留字。
• 名称在解释时不区分大小写。在命名函数、子程序、变量或常量时，可以使用大小写，但解释器不会区分大小写字符。在 DelphiScript 中，除大小写外完全相同的名称将被视为相同的名称。

在 DelphiScript 文件中，函数和过程使用 Procedure-Begin-End或 Function-Begin-End语句块来声明函数和过程。这两个语句块都要求为存储过程或函数命名。DelphiScript 允许您创建命名变量和常量，以保存当前脚本中使用的值。

包含注释

在脚本中，注释是不可执行的代码行，为程序员提供方便。注释几乎可以包含在脚本的任何地方。

在 //或用 (* *)或 {}括起来的文本都会被 DelphiScript 忽略。

//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
*)

注释也可以与已执行的代码包含在同一行中。例如，以下代码行中分号后的所有内容都将被视为注释。

ShowMessage ('Hello World'); //Display Message

局部变量和全局变量

由于所有脚本都有局部变量和全局变量，因此在脚本项目中的脚本中使用唯一的变量名非常重要。如果变量被定义为 outside那么它们就是全局变量，同一项目中的任何脚本单元都可以访问它们。

如果变量定义在 inside则这些局部变量在这些过程/函数之外是不可访问的。

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';

使用命名变量

在脚本中，命名变量或常量用于存储程序执行过程中使用的值。脚本中的所有变量都是变量类型。类型定义不适用，因此变量声明中的 Types 会被忽略，可以跳过。因此，这些声明是正确的：

Var a : integer;
Var b : integer;
Var c, d;

分行

每个代码语句都以分号 ;字符来结束语句。DelphiScript 允许您在多行代码中编写语句，将一条长指令拆分成两行或多行。将程序语句分割成不同行的唯一限制是，一个字符串文字不能跨越多行。

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 对脚本中单行代码的长度没有任何实际限制，但为了便于阅读和调试，限制代码行的长度是一种好的做法，这样可以方便地在屏幕上阅读或打印出来。

如果一行代码很长，可以将其分成多行，DelphiScript 解释器将把这些代码当作单行代码处理。

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;

大小写敏感性

编写脚本时使用的 DelphiScript 语言对大小写不敏感，也就是说，所有关键字、语句、变量名、函数和过程名在书写时都可以不分大小写。大写和小写字母都被认为是等价的。

例如，变量名 myVar等同于 myvar和 MYVAR.DelphiScript 会将所有这些名称视为同一个变量。

唯一的例外是字面字符串，例如对话框定义的标题字符串或字符串变量的值。这些字符串保留大小写差异。

空格字符

空格用于分隔脚本语句中的关键字。但是，DelphiScript 会忽略语句中的任何额外空格。

例如

X   = 5
// is equivalent to
X =5

您可以使用空格来提高脚本的可读性。

脚本中的函数和过程

DelphiScript 解释器允许使用两种方法（过程）：过程和函数。函数和过程的唯一区别是函数返回一个值。

一个脚本至少可以有一个定义主程序代码的过程。不过，你也可以定义其他程序和函数，供代码调用。

与 Embarcadero Delphi 一样，存储过程和函数是在语句块中定义的。 Begin-End语句块中定义。要调用函数或过程，请在语句中包含函数或过程的名称，方法与使用 DelphiScript 内置函数和过程时相同。如果函数或存储过程需要参数，则必须在调用语句中包含这些参数。函数和存储过程都可以定义为接受参数，但只有函数可以定义为向调用语句返回值。

在定义函数和存储过程时，只要符合 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;

函数名称不能用于设置其返回值。必须使用 Result关键字。

Var, Begin-End global block:

Var
  A, B, C;
Begin
  B := 10;
  C := 20;
  A := B + C;
  ShowMessage(IntToStr(A));
End;

脚本提示

在脚本项目中引用脚本

在同一个脚本项目中，一个脚本中的代码可以调用另一个脚本中的过程。任何脚本中的全局变量都可以在同一项目中访问。

局部变量和全局变量

由于脚本具有局部变量和全局变量，因此在脚本项目中的脚本必须具有唯一的变量名。如果变量是在任何过程和函数之外定义的，那么它们就是全局变量，同一项目中的任何单元都可以访问它们。如果变量是在存储过程或函数内部定义的，那么这些局部变量在这些存储过程/函数之外是无法访问的。

建议将性质相似的脚本放在一个项目中，并将项目中的脚本数量控制在可管理的范围内，因为在许多脚本中跟踪全局变量会成为一个问题。在脚本项目中存储脚本并不是强制性的，因为脚本可以放在其他项目类型中。

唯一标识符和变量

使用脚本表单时，确保所有脚本表单都有唯一的表单名称。可以将所有脚本表单命名为 form1(例如）放在同一个脚本项目中。在这种情况下，当执行脚本表单时，脚本系统在尝试显示正确表单时会发生冲突。

可以使用 Object Inspector.该名称将在脚本单元和脚本窗体文件中自动更改。

无参数过程和函数

编写脚本时，应使运行脚本所需的程序只出现在 "选择要运行的项目 "对话框中。为防止其他程序/函数出现在 Select Items to Run对话框中，可以在方法旁边插入一个 (Dummy : Integer)参数。请参阅下面的示例。

// 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;

DelphiScript 错误代码