5. PCB迭代程序

  5.1 迭代程序的概念

迭代程序通过遍历印制板(PCB)编辑器数据库来查找印制板(PCB)对象，迭代程序被用于在数据库内，通过设置过滤选项，来查找具有指定属性的对象。印制板(PCB)编辑器支持两种类型的迭代程序，对象迭代程序和空间迭代程序。如果您选择了一种迭代程序类型，系统将自动地激活印制板(PCB)编辑器数据库，来选择一个适合的数据结构(平直的或空间的结构)。

迭代程序是一个强大的工具，使在印制板(PCB)文档中查找指定的印制板(PCB)对象，并且它有可能使用由程序开发者定义的查找标准来读取印制板(PCB)对象，实现此目的很简单，无需在您的数据库中创建一个相应的镜像数据结构，来查找印制板(PCB)对象。迭代程序是一个从印制板(PCB)编辑器的数据库中访问或修改或删除印制板(PCB)对象的紧密的方法。下面会有一些少量的例子，来说明如何适当的使用迭代程序。对象迭代程序，空间迭代程序将分别进行阐述。

  5.2 对象迭代程序

  5.2.1对象迭代程序函数

对象迭代程序用印制板句柄或组对象句柄遍历数据库，使用一组对象集合、迭代程序进程类型和定义的层来设立迭代程序机制。迭代函数需要使用下列API：

·PcbApi_CreateIterator

·PcbApi_DestroyIterator

·PcbApi_GetFirstObject

·PcbApi_GetNextObject

这四个迭代程序是设置查找和检索机制所必需的方法，每一个函数和它们的参数将被在其明细中说明，例子将说明如何使用迭代程序。

PCBApi_CreateIterator

PCBApi_CreateIterator返回对象迭代程序的句柄，为了遍历所有的层，使用一个外循环是必需的，这样每一层能被读取到PCBApi_CreateIterator函数中，对象查找方法，eProcessAll类型查找所有PCB对象类型，eProcessFree类型查找自由PCB对象或者仅图元，eProcessComponent类型仅查找内置元件对象。

PCBApi_DestroyIterator

PcbApi_DestroyIterator函数用于查找进程结束时销毁迭代程序对象。

PcbApi_GetFirstObject

PcbAPI_GetFirstObject返回第一个查找到的印制板(PCB)对象的句柄。

PcbApi_GetNextObject

PcbAPI_GetNextObject返回下一个查找到的印制板(PCB)对象的句柄。

此进程使用基于While Do的对象迭代程序来查找指定的PCB对象，也就是说，循环体直到查找到PCB对象的句柄是零为止。

通过PcbApi_GetCurrentBoardHandle函数获得当前的印制板句柄。

PcbApi_CreateIterator函数通过使用支持的参数、父类句柄、对象类型、进程方法和层来获得迭代程序的句柄。

用PcbApi_GetFirstObject函数取得第一个查找到的PCB对象的句柄并且接着做一些处理，不要忘记对此PCB对象调用QueryDatabase(eGetState)和QueryDatabase(eSetState) 。使用PcbApi_GetNextObject函数继续调用对象句柄并且做处理。

一旦对象句柄为零，也就是说，这里没有更多的查找到的对象，接着使用PcbApi_DestroyIterator函数来销毁此迭代程序。

  5.2.2对象迭代程序例子

·例子1，统计焊盘数量

请见SDK例子\SAMPLES\NO4\API\PCB\CountPads。

{....................................................................................}

//此代码例子遍历PCB编辑器数据库来统计焊盘(pad)对象，报告在PCB文档中查找到的焊盘(pad)数量。

Procedure RunIteratorExample;

Var

BoardHandle: TObjectHandle;

PadHandle: TObjectHandle;

IteratorHandle : TObjectHandle;

PadNumber: Integer;

Begin

PadNumber := 0;

BoardHandle := PcbApi_GetCurrentBoardHandle;

//PcbApi_GetCurrentBoardHandle函数返回当前在设计资源管理器中的PCB文档的句柄，如果印制板没有找到，则返回值是空(nil)。

IteratorHandle:= PcbApi_CreateIterator(BoardHandle, ePadObject,

eProcessAll, eIgnoreLayer);

//PcbApi_CreateIterator函数返回到一个迭代程序对象的对象句柄。

PadHandle := PcbApi_GetFirstObject(IteratorHandle);

// PcbApi_GetFirstObject函数使用给定的迭代程序(iterator)句柄返回第一个发现的PCB对象句柄。此函数在PcbApi_CreateIterator函数后和PcbApi_GetNextObject函数被使用前被立即调用。

While(PadHandle <> 0) Do

Begin

PadNumber := PadNumber + 1;

//计数查找到的焊盘数量。

PadHandle := PcbApi_GetNextObject(IteratorHandle);

//PcbApi_GetNextObject函数使用给定的迭代程序句柄返回下一个查找到的PCB对象的句柄。

End;

PcbApi_DestroyIterator(IteratorHandle);

//销毁此迭代程序对象。

ShowInfo('焊盘总数(Pad Count) = ' + IntToStr(PadNumber));

//显示焊盘数量。

End;

此段代码使用了下列重要的函数或过程。

这段代码做什么?

PcbApi_CreateIterator使用当前印制板的句柄、焊盘种类(ePadObject)、eProcessAll和eIgnoreLaye参数创建迭代程序对象，在迭代程序循环前，PcbApi_GetFirstObject函数使用迭代程序对象句柄来查找到第一个焊盘对象。PcbApi_GetNextObject方法被调用直到没有更多的焊盘对象句柄被查找到为止，一旦没有更多的焊盘对象被查找到，PcbApi_DestroyIterator被调用来销毁迭代程序对象。