<连载>Protel二次开发从入门到精通

10.2.6.3 TNetFormatter类的Run过程

//建立一个网络接线表。此run过程是服务器的核心过程。

Procedure TNetFormatter.Run(NetListOptions : TNetListOptions; Parameters : PChar);

Var

P : TChar;

W : Word;//初始化数据结构的返回值。

Flags : TInitializeDataStructure;//初始化数据结构记录

S : TString;

LoadFiles : TBoolean;

CurrentSchDoc : TObjectHandle;

HighestOpenSchDoc : TObjectHandle; //当前原理图最高层父原理图文档句柄。

T : TShortString;//存储当前原理图文档或当前原理图文档的最顶层原理图的句柄。

DocumentLoader : TObjectHandle; //文档加载对象句柄。

DDBItem : TDDBItem;

Begin

DocumentLoader := 0;

ParameterList := Parameters;

//把用户在菜单定制时输入服务器的进程参数赋予ParameterList。

LoadFiles := True; //网络连线表产生完成后，默认把其加载打开，所以设定LoadFiles为True。

GlobalNetListOptions := NetListOptions; //网络设置选项对象。

CurrentSchDoc :=

ClientAPI_FindEntityByDataHandle(MessageRouter_GetState_CurrentEditorWindow);

//MessageRouter_GetState_CurrentEditorWindow函数返回当前在项层的文档的窗体句柄。

//ClientApi_FindEnttyByDataHandle 函数使用一个编辑器窗体句柄来返回查找返回一个实体的句柄。

//得到当前原理图对象的句柄。

If Not Flags.SingleSheetOnly Then//如果Flags记录中的SingleSheetOnly为真，表示是单个原理图。

//如果不是单个原理图，打开这些原理图。Flags.SingleSheetOnly默认为False。为False执行下面Begin和End之间的代码。

Begin

DocumentLoader := ClientAPI_CreateDocumentLoader;

//ClientAPI_CreateDocumentLoader函数在设计资源管理器内创建一个内部的列表，将通过过程

//ClientAPI_LoadDocument来管理文档的加载。当您使用完文档时，您必须调用过程

//ClientApi_DestroyDocumentLoader或ClientApi_DestroyDocumentLoaderEx来销毁此内部列表。

ClientApi_LoadDocument(DocumentLoader, CurrentSchDoc, eLoadAllDocumentsInHierarchy, 'Sch|Text');

//ClientApi_LoadDocument过程加载原理图和文本文件种类的文档。

//eLoadAllDocumentsInHierarchy表示加载指定的文档，TLoadScope =(eLoadOnlyThisDocument,eLoadAllDocumentsInHierarchy,

//eLoadAllDocumentsInFolder,eLoadAllDocumentsInDesign,eLoadAllDocuments);

//TLoadScope类型定义了在设计资源管理器中加载的文件的范围。eLoadOnlyThisDocument设计资源管理器能被指定来加载指定的文档，

//eLoadAllDocumentsInHierarchy为在一个分层设计中所有的文档，eLoadAllDocumentsInDesign在一个设计数据库中的所有文档或eLoadAllDocuments加载所有文档。

//上述代码加载原理图和文本文件。

End;

If GlobalNetListOptions.SheetsToNetlist = eActiveProject Then //如果原理图是项目原理图，扩展名称为原理图扩展名称为prj。

HighestOpenSchDoc := GetState_TopLevelSchematicDocument(CurrentSchDoc)

//追溯当前原理图的最高层父原理图文档，并返回最高层父原理图文档句柄。

Else

HighestOpenSchDoc := CurrentSchDoc;

//如果是一般的原理图，直接得到当前原理图文档句柄。

ClientApi_GetDocumentEntityAbsoluteAddress(HighestOpenSchDoc, S);

//ClientApi_GetDocumentEntityAbsoluteAddress在关联的设计数据文档内获得一个文档实体的绝对地址。

StrPCopy(T,S);//把字符串转换到pchar型。

SetTopLevelDocument(T);

//SetTopLevelDocument是advsch.dll输出的过程，设置参数所指定的绝对地址文档为顶层。现在，已把当前原理图的顶层父原理图设置为顶层文档。

Flags := SetNetListOptionsForSchematic(GlobalNetListOptions);

//把网络选项对象中的设置放置到Flags记录中。

W := InitializeDataStructures(Flags,Design.DataHandle);

//InitializeDataStructures是advsch.dll输出的函数，用来初始化数据结构。函数有两个参数，一是存储网络选项的记录flags，

//另一个是有两个原理图列表的TDesign类实例对象Design的句柄。

If W = cAPI_Error_None then //无错误。

Begin

Design.ImportFrom_APIDataStructure;

//处理所有的原理图对象，把各个原理图对象中的图表符号、网络、端口、元件、BUS对象加到不同的对象列表中。

//此过程是一个非常重要的过程，正是此过程从各个原理图中把所有要处理的对象读出来，并构建出具体的实例，再加到存储对象的各自列表中。

GeneratedFilesCount := 0;//已产生的文件总数为0。

BuildFileNamesArrayToBeGenerated(Parameters);

//判断并检索用户在定制菜单时输入的参数值，如果包含filename1=value|filename2=value|......这样的参数据形式，

//则把参数值取出来，加到要产生的文件名称列表GeneratedFileNames中。

FileName := Design.GetState_DesignfileName;

//得到设计文件名称，实际上此时将会得到当前原理图的顶层父原理图的名称，因为此时要处理原理图已从当前原理图的遍历到其最项层原理图，filename不包含扩展名称。

DDBItem := TDDBItem.Create(GetState_CurrentuserId,FileName);

//GetState_CurrentUserId函数返回在设计资源管理器中当前打开的文档的用户ID号字符串。此用户ID号可能为一个系统管理员("admin")，一个访客或设计组中的一个成员。

//根据用户ID号和设计文件名称建立一个TDDBItem类的实例对象DDBItem。

DDBItem.Address.EditorKind := 'TEXT';//设置编辑器类型，即设置要产生的文件类型。

DDBItem.Address.Id := cUnassignedID; //设置地址ID，cUnassignedID常量在DDB_Database单元中定义，cUnassignedID = -1，表示未分配。

FileName := DDBItem.Address.AsParameters;//返回DDBItem的完整的抽象地址。

DDBItem.Free; //释放DDBItem对象。

//此时虽然建立了一个文档对象DDBItem，但此时文档中还没有内容，更没有显示出来。

CurrentSheetName := UpperCase(ExtractFileNameFromPath(FileName));

//ExtractFilenameFromPath函数提取DDBAddress.Offset.Name字符串中文件名称和扩展名称。

//UpperCase把字符串转变为大写。

DesignName := CurrentSheetName;//把CurrentSheetName赋予DesignName。

If IsHierarchical Then RunHierarchical Else RunFlat;

//如果IsHierarchical为真，运行RunHierarchical，否则运行RunFlat。

//如果NetList格式是eProtel_H，则调用RunHierarchical，否则调用RunFlat。

RebuildParametersFromFileNamesArray(Parameters);

//从存放已产生的文件名称的数组中把文件名称读出来，重新构建参数.

If Getstate_Parameter(Parameters, 'LoadFiles', S) Then

LoadFiles := TokenEqual(S, 'True');

//如果参数中有LoadFiles参数，则把其值读出来放置到S中，然后判断S是否为真，如果是则LoadFiles为真，即加载文件。

If LoadFiles = True Then

LoadGeneratedFiles(ClientApi_GetDocumentOwnerBinder(HighestOpenSchDoc));

//HighestOpenSchDoc当前原理图最高层父原理图文档句柄。 ClientApi_GetDocumentOwnerBinder得到HighestOpenSchDoc容器句柄。

//如果加载文件标记为真，LoadGeneratedFiles加载文件在设计资源管理器中打开。

End;

ClearTopLevelDocument;

//ClearTopLevelDocument是advsch.dll输出的过程，清除顶层的文档。

If DocumentLoader <> 0 Then //如果先前建立了DocumentLoader文档加载对象，则释放它。

Begin

SetState_Parameter(P, 'Action', 'Discard');

ClientApi_DestroyDocumentLoaderEx(DocumentLoader, P);

//ClientAPI_DestroyDocumentLoaderEx过程控制文档的工作情况，Parameter参数是以一个空(Null)终止字符串为结尾，

//此参数由一个名称和一个值组成，名称组成是"Action ="，Discard表示释放。

End;

End;

{………………………………………………………………………………………………………………}

此过程一看很复杂但是实际上不复杂，GlobalNetListOptions := NetListOptions把选项赋予NetFormatter对象的GlobalNetListOptions，从而下面就可以把一些属性或产生文件的选项放到GlobalNetListOptions中。

CurrentSchDoc取得当前原理图句柄。ClientAPI_CreateDocumentLoader在设计资源管理器内创建一个内部的列表，ClientApi_LoadDocument把文档加载入列表。