脚本实例分析

为了进一步了解脚本系统的总体情况，以及在脚本中使用 Delphi 和 X2 对象模型的情况，这里将从功能角度对两个示例项目--电路板大纲复制器和网表生成脚本--进行审查。

电路板大纲复制器和网表脚本是使用 X2 对象模型开发的，用于说明 Altium Designer 中脚本系统的功能。这些脚本是脚本示例集中的现有脚本，如下所示：

• 电路板轮廓复制器脚本利用 PCB 对象模型，将现有的 PCB 电路板轮廓复制到指定层上的轨道和圆弧上。
  请参见 \Scripts\VB Scripts\CopyBoardOutlinePRJ.PRJSCR.
• 网表生成器脚本利用工作空间管理器对象模型生成传统 Protel（v1 和 v2）格式的网表。
  参见 \Scripts\Delphiscript Scripts\WSM\Protel Netlister\ScripterProtelNetlist.PRJSCR.

电路板大纲复制器项目

电路板大纲复制器的目的是将 PCB 文档中已有的电路板大纲复制到同一文档中的不同层。

该项目使用脚本窗体，因此用户可以与对话框交互，指定电路板轮廓的宽度，并从下拉菜单中选择目标层。使用 PCB API 中的 PCB 对象模型及其 PCB 接口，可以提取电路板轮廓的对象并将其复制到指定的层上。

► 脚本操作示例

脚本的主要部分包括

• 一个全局 PCB_Board(类型）变量。 IPCB_Board类型）变量。
• A CopyBoardOutline子程序接受 AWidth和 ALayer参数的子程序。
• 事件处理程序 bOkClick事件处理程序从脚本表单中获取宽度和图层值，然后执行 CopyBoardOutline子程序。
• 事件处理程序 bCancelClick事件处理程序，用于关闭电路板大纲脚本窗体（对话框）。

脚本功能

脚本使用的脚本窗体需要事件处理程序来捕捉单个控件的鼠标点击，如 OK和 Cancel按钮的鼠标点击。

OK 按钮事件处理程序基本如下：

子 bOKClick(Sender)
  尺寸
  尺寸

  调用 StringToCoordUnit(eWidth.Text,Width,PCB_Board.DisplayUnit)
  层 = String2Layer(cbLayers.Items(cbLayers.ItemIndex))
结束子操作

在这里，表单的鼠标 OnClick事件处理程序 (bOKClick) 使用 StringToCoordUnit函数获取输入的轮廓宽度（从 eWidth字符串）的内部坐标值。该函数将当前的棋盘单位 (PCB_Board.DisplayUnit属性）应用到 Width变量。

同样，所选图层字符串（表单 TComboBox 中的 cbLayers项）传递给 String2Layer函数，以便为 Layer变量的枚举值。请注意，在本项目中，表单的 TComboBox 已预先填充了层字符串的索引列表 (cbLayers.Items) - 请参阅表单的 CopyBoardOutlineForm.dfm文件中的层列表。

事件处理程序的最后一步 (bOKClick) 调用 CopyBoardOutline子程序。 Width和 Layer变量作为参数调用子程序。表单的 Cancel按钮 (bCancelClick) 的处理程序只是关闭表单。

IPCB_Board 接口

在 OK 按钮处理程序（bOKClick)中，通过 IPCB_Board接口通过 IPCB_ServerInterface返回的 PCBServer函数从接口中获取当前板卡。在这里 GetCurrentPCB函数将当前电路板的引用设置为 PCB_Board变量。

然后，在整个脚本中都可以从当前电路板大纲 (IPC_BoardOutline) 然后在整个脚本中从 IPCB_Board接口 BoardOutline属性中获取当前板的轮廓 ( )，并使用上述 PCB_Board电路板引用。

在复制和创建新大纲之前，需要先初始化电路板大纲。由 IPCB_BoardOutline接口所代表的大纲可使用接口的重建/验证方法进行初始化。

PCB_Board.BoardOutline.Invalidate
PCB_Board.BoardOutline.Rebuild
PCB_Board.BoardOutline.Validate

勾画弧线和轨迹线段

界面 IPCB_BoardOutline接口继承自代表棋盘轮廓的 IPCB_Group接口继承。接口 IPCB_Group接口代表一个可存储子对象的组对象。例如 IPCB_Group接口的一个例子是多边形或棋盘轮廓，因为它们可以将弧线和轨道作为子对象存储。

一个棋盘轮廓对象可以存储两种不同类型的线段，即 ePolySegmentLine和 ePolySegmentArc分别代表轨道或弧线对象。线段的数量由 PointCount属性决定。 IPCB_BoardOutline接口的属性决定，该接口会将每个轮廓顶点提取到 I变量的 For-To-Next循环。

获得的电路板轮廓的每个线段都要用 If PCB_Board.BoardOutline.Segments(I).Kind = ePolySegmentLine Then语句检查轨道和弧。如果不是轨道段 (ePolySegmentLine) Else则语句的一部分假定该段为弧。

对于找到的每个线段，根据线段类型，将使用 PCBObjectFactory函数创建一个新的轨迹或弧对象。

PCBObjectFactory 函数

创建新的 PCB 对象时，使用 PCBObjectFactory函数直接从 IPCB_ServerInterface接口的函数。

创建新的轨道对象
PCBServer.PCBObjectFactory(eTrackObject, eNoDimension, eCreate_Default)

创建新的弧形对象
PCBServer.PCBObjectFactory(eArcObject, eNoDimension, eCreate_Default)

函数 PCBObjectFactory函数参数可设置对象类型（轨迹、弧、Via 等）、尺寸类型（线性、径向等）和对象创建模式（本地默认模式或全局首选模式）。

每个轨道或圆弧对象由 PCBObjectFactory过程创建每个轨道或圆弧对象后，其属性将由后面的轨道/圆弧语句实例化。

轨迹和弧属性由各自的接口表示、 IPCB_Track和 IPCB_Arc，其中相关属性由脚本实现。例如，新的轨迹坐标来自源轮廓段顶点，其中 Track.X1和 Track.Y1代表轨迹的初始坐标，而 X2和 Y2属性为最终坐标。

Track.X1 = PCB_Board.BoardOutline.Segments(I).vx
Track.Y1 = PCB_Board.BoardOutline.Segments(I).vy
Track.X2 = PCB_Board.BoardOutline.Segments(J).vx
Track.Y2 = PCB_Board.BoardOutline.Segments(J).vy
Track.Layer = ALayer
轨道宽度 = AWidth

从上面的代码片段中还可以看出，轨道层和宽度属性只是由从用户界面对话框中提取的传递值定义的，即窗体的 cbLayers和 eWidth变量。

完全定义后，新对象将被添加到 PCB 文档的指定层，并使用 PCB_Board.AddPCBObject(NewObject)语句，其中 NewObject此处为轨道或弧线。

预处理和后处理

创建 PCB 对象时，PCB 文件中的 PreProcess方法 IPCB_ServerInterface对象接口中的方法，为 PCB 服务器做好准备。创建对象后，需要调用 PostPocess方法（也来自 IPCB_ServerInterface接口）来通知服务器对象添加完成。

调用 PreProcess和 PostProcess方法使撤销系统和 PCB 编辑器的其他子系统保持更新和同步。下面是一个具有代表性的代码片段，其中包含 PreProcess和 PostProcess语句的代表性代码片段。

PCBServer.PreProcess
创建 PCB 对象
PCBServer.PostProcess

当对象被添加到 PCB 文档中尚未显示的指定层时，需要强制该层可见。这由 PCB_Board.LayerIsDisplayed(ALayer) = True语句来处理，其中 ALayer是用户选择的图层。

文档刷新

最后，使用 PCB:Zoom命令及其相关 Action = Redraw参数刷新。在使用 AddStringParameter方法清除参数缓冲区后，使用 ResetParameters方法清除参数缓冲区后，使用程序应用缩放命令参数。

网表项目

该 Netlister 脚本项目旨在为包含原理图的 Altium Designer 项目生成标准 Protel 网表（版本 1 或版本 2 格式）。原理图项目的平面网表分为两部分：

• 元件代号和与每个元件相关的信息、
• 网络名称和与每个网络名称相关的信息，以及引脚连接（组件的引脚）。

► 脚本操作示例

API 的工作空间管理器对象模型（WorkSpace Manager Object Model）提供了表示项目及其组成元素 （文档、组件及其引脚和网）的接口。工作空间管理器是一个系统服务器，与处理项目及其相关文档的客户端模块紧密耦合。它提供编译、多工作表设计支持、连接导航工具、多通道支持、多执行文档等功能。要检索工作空间管理器界面，请调用 GetWorkspace函数，该函数将生成 IWorkspace接口。

对于 Netlister 脚本，我们感兴趣的接口有 IWorkSpace, IProject, IDocument, IComponent和 INet接口。

请注意，某些接口，尤其是设计对象接口，与等效的示意图对象接口相对应。这是因为项目中的逻辑文档是带有连接信息的示意图文档。事实上，可以使用示意图对象模型来代替工作空间管理器，但后者提供了编译项目、从项目中提取文档以及从示意图对象中检索数据的功能。

Netlister 脚本的主要部分包括

• 一个全局 TargetFileName字符串变量，即网表的文件名。
• 一个全局网表 TStringList集合对象，其中包含网表数据。
• 在 WriteComponent_Version1和 WriteComponent_Version2程序。
• 和程序。 WriteNet_Version1和程序。 WriteNet_Version2程序。
• A ConvertElectricToString函数将引脚的电气属性转换为字符串
• 程序 GenerateNetlist存储过程，用于管理数据生成以及文件名、路径和目录管理任务。

脚本功能

两个无参数过程 GenerateProtelV1FormatNetlist和 GenerateProtelV2FormatNetlist将出现在 "选择要运行的项目 "对话框中，提供生成 Protel V1 格式网表或 Protel V2 格式网表的选择。这些程序会调用 GenerateNetlist程序，并选择网表格式（0或 1) 作为传递参数调用存储过程。

存储过程 GenerateProtelV1FormatNetlist；
变量
 版本：整数；
开始
 // Protel 1 网表格式，通过 0
 GenerateNetlist(0)；
结束；

过程 GenerateProtelV2FormatNetlist；
版本
 版本：整数；
开始
 // Protel 2 网表格式，通过 1
 GenerateNetlist(1)；
结束；

生成网表

程序 GenerateNetList存储过程将检索工作区接口，以便提取当前项目的项目接口 (IWorkspace.DM_FocusedProject).

在提取网络之前，需要对项目进行编译，因为编译过程会建立项目的连接信息。项目界面的 DM_Compile方法 (IProject.DM_Compile) ，如下面的代码片段所示。请注意，Altium Designer 的最新版本会自动编译项目，因此此步骤是可选的。

WS := GetWorkspace；
 If WS = Nil Then Exit；

Prj := WS.DM_FocusedProject；
 If Prj = Nil Then Exit；

// 编译项目以获取设计的连接信息。
 Prj.DM_Compile；

组件和网络信息存储在 Netlist 对象的 TStringList类型的 Netlist 对象中，稍后将使用该对象生成格式化的网表文本文件。该 TStringList对象是一个 Delphi 类，可在脚本中使用。

然后 Generate过程，并通过参数定义当前项目路径和文件名，以及网表格式版本。

生成

过程 Generate存储过程获取项目路径作为生成网表文件的目标输出路径（从传递的 DocumentPath参数），确定网表文件名 (TargetFileName) 并检查项目的扁平化状态 (IProject.DM_DocumentFlattened).

对于项目中的所有原理图文档，将使用 WriteNets和 WriteComponents程序检查网络和组件，并最终提取到 Netlist对象。

编写网和元件

网表由元件和网部分组成，因此需要两个程序分别写入元件数据和网数据。

只有节点数大于两个的网才会被写入网表，节点数小于两个的网会被丢弃。对于每个网，网名基于 Net 的 DM_CalculatedNetName方法，该方法从已编译项目的连接信息中提取网名。

下图是第一版网表格式中元件和网部分的两个代码片段。请注意，元件和网数据存储在 NetList对象中，该对象是一个 TStringList类型。生成的网表由两个部分组成：元件信息部分和网信息部分。

组件部分

在 WriteComponent程序中，将检查从项目中找到的每个组件是否为实际组件，然后提取物理代号、足迹和部件类型值。这些值将被添加到网表对象容器 (NetList.Add) 中，以构建网表本身。

如果组件 > 无 那么
开始
 NetList.Add('[')；
 NetList.Add(Component.DM_PhysicalDesignator)；
 NetList.Add(Component.DM_FootPrint)；
 NetList.Add(Component.DM_PartType)；
 NetList.Add('')；
 NetList.Add('')；
 NetList.Add('')；
 NetList.Add(']')；
结束；

网络部分

在 "网络 "过程中，如果一个网络有两个或多个引脚 (INet.DM_PinCount).网络和引脚信息以及格式化字符将被添加到 Netlist容器中，以创建网表。下面的代码段是第 1 版网表的编写过程。

如果 Net.DM_PinCount >= 2 那么
开始
 NetList.Add('(')；
 NetList.Add(Net.DM_CalculatedNetName)；
 For i := 0 To Net.DM_PinCount - 1 Do
 开始
   Pin := Net.DM_Pins(i)；
   PinDsgn := Pin.DM_PhysicalPartDesignator；
   PinNo := Pin.DM_PinNumber；
   NetList.Add(PinDsgn + '-' + PinNo)；
 结束；
 NetList.Add(')')；
结束；

需要注意的是，Protel v2 这种更冗长的网表格式包含了网络引脚的电气属性 (In, Out, Passive, HiZ等）。

第 2 版格式的网络编写程序 (WriteNet_Version2) 因此会询问每个网络引脚的电气属性 (INet.DM_Electical) ，然后由调用的 ConvertElectricToString程序进行转换--本质上是一个字符串转换查找表。然后，这些属性会被添加到一个本地字符串变量(ElectricalString) 中，然后将其添加到网表容器对象中。

创建网表文件

最后 Netlist容器对象完全填充了所选格式的项目组件和网络信息后，程序将 Generate程序将 Netlist数据写入文件 (TStringList.SaveToFile).文件路径和名称由 TargetFileName字符串变量定义的。 Generate程序中确定。