6.6 输入一个文档例子

此例子创建一个简单的外部文本文件，然后把此文本文件输入到一个设计数据库中，作为一个文本实体对象。

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

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

//创建一个外部的文本文件。

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;//抽象地址字符串。

Entity : TDocumentEntity;//文档实体。

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

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

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

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

ClientApi_RepopulateDocumentEntity(BinderHandle,False);

//ClientApi_RepopulateDocumentEntity 过程在封装对象中刷新文档实体的内容依赖于Recursive参数值，如果参数为false，当前实体被刷新，否则实体的封装对象被刷新。它在当文档被增加到一个封装对象中您需要刷新封装对象来让设计资源管理器知道有新的文档时情况下很有用。

EntityHandle := ClientApi_FindChildDocumentInBinder(BinderHandle, NewDocName);

//在空器中查找NewDocName文档。

If EntityHandle <> 0 Then

Begin

Entity := TDocumentEntity.Create(EntityHandle);

//根据查找到的实体句柄创建一个实体对象。

Entity.QueryDatabase(ClientTypes.eGetState);//用内部服务器数据同步外部服务器数据。

Entity.EditorKind := 'TEXT';//编辑器类型。

Entity.QueryDatabase(ClientTypes.eSetState);//用外部服务器数据同步内部服务器数据。

Entity.Free;//释放实体。

End

else ShowInfo('新输入的文件没有发现!');

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

End;

这段代码做什么？

此段代码片段中重要的函数和类。

此例子说明如何输入一个外部文件到数据库中。例子开始于在C盘驱动器根目录下产生一个小的文本文件，当然，您需要有一个硬盘驱动器盘符如“C:\”，当前打开的设计文档的实体句柄被通过函数ClientAPI_FindEntityByDataHandle和MessageRouter_GetState_CurrentEditorWindow获得，DocumentName字符串有完整的Windows格式文件路径和文件名称，NewDocName字符串仅是整个文件名称(不含路径，即不是FullPath)。

使用TDDBAddress对象，把EditorKind和Offset.Name字段分别分配“TEXT”和NewDocName值，即新建的TDDBAddress对象的对象类型为文本，对象名称是NewDocName。然后, 使用DDB_ImportFile函数把文件输入数据库中，DocumentName和Address作为函数的参数。再下来，设计数据库内容通过ClientAPI_RepopulateDocumentEntity函数被刷新，但新输入的文件没有出现在设计资源管理器界面上，为了使用输入的文件显示在设计资源管理器界面上，您需要按下列方法来做：

ClientAPI_FindChildDocumentInBinder函数来获得输入文档的实体的句柄，容器句柄(Binderhandle)和要查找文件实体对象的句柄(NewDocName)作为参数，此实体句柄被传递到TDocumentEntity类，然后EditorKind被分配“TEXT”值。Querydatabase(eSetState)函数注册此新文本文档实体到设计资源管理器应用程序。现在您有一个切实的文档实体。

这段程序在当前实体的上一级容器中输入外部文本文件，但是程序实际上有些问题，那就是新加入的文件并没有显示，EntityHandle := ClientApi_FindChildDocumentInBinder(BinderHandle, NewDocName)执行没有找到新加的文件。所以没有显示。如何改进请参见6.7。