6.7 改进输入一个文档例子

请见SDK例子\SAMPLES\NO2\API\Client\Import External File Amend。

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

//在一个循环中不断刷新当前新输入的实体，直到得到新输入的实体句柄，得到后中断退出。

Function WaitForCommit(BinderHandle　: TObjectHandle; Docname : TString) : TObjectHandle;

Var

I : Integer;

Begin

Result := 0;

For I := 1 to 50 Do

Begin

ClientAPI_RepopulateDocumentEntity(BinderHandle,False);

//ClientApi_RepopulateDocumentEntity 过程在封装对象中刷新文档实体的内容依赖于

//Recursive参数值，如果参数为false，当前实体被刷新，否则实体的封装对象被刷新。

//它在当文档被增加到一个封装对象中您需要刷新封装对象来让设计资源管理器知道有

//新的文档时情况下很有用。

Result := ClientAPI_FindChildDocumentInBinder(Binderhandle,Docname);

//ClientApi_FindChildDocumentInBinder过程在容器Binderhandle查找文档Docname，

//查找到返回其句柄，否则返回零。

If Result <> 0 Then Break;

//如果找到，则中断循环，找到表示新输入的文档句柄已得到，可以使用了。

WaitForSingleObject(GetCurrentThread,100);

//GetCurrentThread得到当前的线程

//WaitForSingleObject等待100毫秒。

End;

End;

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

Function GenerateASampleTextFile : TString;

Var

F : TextFile;//文本文件

Begin

Result := 'C:\TextFil$.Txt';//文本文件名称。

AssignFile(F,Result);//把文本文件名称和文本对象关联。

Rewrite(F);//创建一个文本文件对象。

Writeln(F,'Hello world!');//向文本文件中写内容。

Writeln(F,#13);//换一行。

Writeln(F,'Goodbye world!');//写内容。

CloseFile(F);//关闭文件。

End;

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

//主程序。

Procedure ImportAnExternalFile;

Var

Address : TDDBAddress;//抽象地址对象。

EntityHandle : ClientTypes.TObjecthandle;//实体对象。

BinderHandle : ClientTypes.TObjecthandle;//容器对象句柄。

S : TString;//抽象地址字符串。

NewDocName : TString;//新建文档名称变量。

DocumentName : TString;//外部文档完整路径。

NewImportTextDocHandle : TObjectHandle;//要新建的新的实体文件句柄。

Begin

DocumentName := GenerateASampleTextFile;//创建一个文件。

NewDocName := ExtractWholeFileNameFromPath(DocumentName);

//提取文件完整名称，包括扩展名称。ExtractWholeFileNameFromPath函数提取

//DocumentName字符串中名称和扩展名称。

EntityHandle :=

ClientAPI_FindEntityByDataHandle(MessageRouter_GetState_CurrentEditorWindow);

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

//当前在项层在文档的窗体句柄。ClientApi_FindEntityByDataHandle函数使用一个编辑

//器窗体句柄来返回查找返回一个实体的句柄。

If EntityHandle = 0 Then Exit; //如果无实体对象则退出。

ClientApi_GetDocumentEntityAbsoluteAddress(EntityHandle, S);

//把当前窗体中实体抽象地址赋予字符串S。

Address := TDDBAddress.Create(S);//创建一个抽象地址对象。

Address.EditorKind := 'TEXT';//文件类型是文本文件。

Address.Offset.Name := NewDocName;//文件名称为输入到设计数据库中的文本文件名。

DDB_ImportFile(DocumentName,Address,'Admin',False);

//DocumentName为外部文件句柄，Address为内部文件实体对象句柄。'Admin'是操作用户，

//False表示输入文档而不是作为一个外部连接，如为True则表示为连接。

//上面代码执行完成后，外部输入文档已输入到Address实体对象中，但并没有输入到设计

//数据库中，所以不会在资源管理器应用程序中显示。

//刷新设计资源管理器的浏览器的内容。

BinderHandle := ClientApi_GetDocumentOwnerBinder(EntityHandle);

//得到当前实体对象的容器对象句柄。

NewImportTextDochandle := WaitForCommit(BinderHandle,NewDocName);

//刷新实体直到获得实体句柄。把上级容器句柄和要刷新的文档作为参数。

ClientAPI_OpenDocumentEntity(NewImportTextDochandle,False);

//在窗体中打开新输入的实体文档。

Address.Free;// 释放地址对象。

End;

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

Procedure Command_ImportAFileInDDBAmend(Window : TServerWindow; Parameters : PChar);

Begin

ImportAnExternalFile;

End;

  6.8 输出一个设计实体例子

本例子把一个当前激活的设计文档输出到一个外部文件夹。

请见SDK例子\SAMPLES\NO2\API\Client\Export a DDB document。

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

Procedure ExportADDBDocument;

Var

S : TString;

FileLocation : TString;

NewExternalFileName : TString;

EntityHandle : ClientTypes.TObjecthandle;

Source : TDDBAddress;

Begin

EntityHandle :=

ClientAPI_FindEntityByDataHandle(MessageRouter_GetState_CurrentEditorWindow);

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

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

if EntityHandle = 0 then Exit; //如果无实体对象则退出。

ClientApi_GetDocumentEntityAbsoluteAddress(EntityHandle, S);

//把当前窗体中实体抽象地址赋予字符串S。

Source:= TDDBAddress.Create(S);//创建要输出的源对象。

FileLocation :=(ExtractFileDrive(ConvertToNormalFilePath(Source.AsParameters)));

//ConvertToNormalFilePath函数转换一个抽象的地址到一个常规的DOS文件路径。

//ExtractFileDrive从一个完整的路径中返回文件的包含驱动器名在内的文件路径(不包括文件名称)。

NewExternalFileName :=

(ExtractFileName(ConvertToNormalFilePath(Source.AsParameters)));

//ExtractFileName从一个完整路径中返回文件名称(不包括文件路径)。

DDB_ExportToFile(Source,FileLocation + '\'+ NewExternalFileName,'Admin');

//输出文件。

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

End;

这段代码做什么？

此段代码片段中使用的重要的函数和类如下表。

此例子在设计资源管理器中当前打开的设计文档中提取一个实体句柄，用一个TDDBAddress类表示实体的抽象地址对象，ClientApi_GetDocumentEntityAbsoluteAddress函数提取实体的抽象地址到一个字符串，并根据此字符串根据TDDBAddress对象，然后根据TDDBAddress对象的抽象地址参数，使用ConvertToNormalFilePath把抽象地址转换为DOS下常规路径，用ExtractFileDrive把路径中除文件名称以外的内容，包括驱动器名称提取出到FileLocation，作为输出文件的路径，用ExtractFileName路径中文件名称提取出到NewExternalFileName，不包括路径。ExtractFileDrive字符串加上ExtractFileName字符串，就合成了要输出的文件完整名称，合成字符串作为DDB_ExportToFile函数的参数，DDB_ExportToFile函数接下来把此实体内容输出保存到一个外部文件中。输出一个设计文档与输入一个外部文档相比并不复杂，都是很简单的。