4.3.15 ClientApi_LoadDocument过程

声明(来自ClientProcs单元)：

Procedure ClientApi_LoadDocument(DocumentLoader: TObjectHandle;

ADocumentEntity : TObjectHandle;

Scope: TLoadScope;

EditorKinds: TString);

描述：

ClientApi_LoadDocument过程加载一个指定编辑器种类的文档。

例子：

ValidLoader := ClientApi_CreateDocumentLoader;

//ClientAPI_CreateDocumentLoader函数在设计资源管理器内创建一个内部的列表。

If ValidLoader = 0 Then Exit;//如果列表没有建立成功则退出。

EntityHandle :=

ClientApi_FindEntityByDataHandle(MessageRouter_GetState_CurrentEditorWindow);

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

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

ClientApi_LoadDocument(ValidLoader,Entityhandle,eLoadAllDocumentsInHierarchy,‘Sch’);

//把当前实体按原理图SCH加载到ValidLoader列表中。eLoadAllDocumentsInHierarchy表示所有文档加载在同一个层中。

ClientApi_DestroyDocumentLoader(validLoader);//销毁列表。

此例子加载一个原理图项目中的原理图文档。

参见其它：

  4.3.16 ClientApi_OLEDocumentIsCertified函数

声明(来自ClientProcs单元)：

Function ClientApi_OLEDocumentIsCertified(ProgID : TString) : TBoolean;

描述：

ClientApi_OLEDocumentIsCertified函数接受OLE类名称作为一个字符串，并且返回此文档是否是被创建在一个OLE应用程序中的逻辑值。

  4.3.17 ClientApi_OpenDocumentEntity过程

声明(来自ClientProcs单元)：

Procedure ClientApi_OpenDocumentEntity(ADocumentEntity : TObjectHandle; NewView : TBoolean);

描述：

ClientApi_OpenDocumentEntity过程打开一个设计数据库中的文档实体窗口，NewView参数为True文档将被显示在窗体中，为False显示在设计资源管理器中。OLE文档将被在与它们相匹配的OLE应用程序中打开。

例子：

Entity := TDocumentEntity.Create(EntityHandle);//创建一个实体。

Entity.QueryDatabase(eGetState);//同步数据。

If Entity.ObjectHandle = 0 Then //没有窗体。

Begin

ClientApi_OpenDocumentEntity(EntityHandle, False);//在窗体中打开文档。

Entity.QueryDatabase(eGetState);//同步数据

End

Else

ClientApi_SetAsCurrentDocument(EntityHandle);

//ClientApi_SetAsCurrentDocument函数设置一个打开的文档实体作为当前焦点或在设计资源管理器中活动文档。用当前焦点窗体打开文档。

Result := Entity.ObjectHandle;

Entity.Free;

此代码片段示范如何使用ClientAPI_OpenDocumentEntity过程，如果实体的“ObjectHandle”是零(意味着没有窗体)，那么此过程打开实体窗体并且返回此文档实体窗体句柄。然而如果实体的窗体句柄不是零，ClientApi_SetAsCurrentDocument过程确保此实体窗体被激活。

参见其它：

  4.3.18 ClientApi_PerformAutoZoomForDocumentEntity过程

声明(来自ClientProcs单元)：

Procedure ClientApi_PerformAutoZoomForDocumentEntity(ADocumentEntity : TObjectHandle);

描述：

带有文档实体句柄的ClientApi_PerformAutoZoomForDocumentEntity过程在设计资源管理器中对文档执行自动缩放，也就是说，一个文档被完整地在文档窗体中以整页尺寸方式显示。

  4.3.19 ClientApi_PerformBackupSaveForDocumentEntity过程

声明(来自ClientProcs单元)：

Procedure ClientApi_PerformBackupSaveForDocumentEntity(ADocumentEntity : TObjectHandle; ABackupFileName : TString);

描述：

ClientApi_PerformBackupSaveForDocumentEntity过程通过文档实体句柄和备份文件名称两个参数来备份设计数据库的文档实体，此文档实体被作为一个文件保存在此服务器DLL文件所在的目录中。

例子:

请参见\SAMPLES\NO6\API\Client\PerformBackupSaveForDocumentEntity代码。

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

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

var

EntityHandle : TObjectHandle;

Begin

EntityHandle := ClientAPI_FindEntityByDataHandle(MessageRouter_GetState_CurrentEditorWindow);

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

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

If MessageRouter_GetState_WindowKind(SchAPI_GetCurrentEditorWindow) <> 'Text' Then

begin

Showinfo('当前文件不是文本文件');

Exit;

end

else

showinfo('当前文件是文本文件，输出文件在当前DLL服务器所在的文件夹下，名称名称为File.Txt');

//如果当前文档实体的类型不是文本则退出。

ClientApi_PerformBackupSaveForDocumentEntity(EntityHandle,'File.txt');//保存文件。

End;

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

如果您有一个文本文档打开在设计资源管理器中，在此文档上运行此代码例子，此文本文档的内容将被保持在文本文件中。

  4.3.20 ClientApi_PerformLoadForDocumentEntity过程

声明(来自ClientProcs单元)：

Procedure ClientApi_PerformLoadForDocumentEntity(ADocumentEntity : TObjectHandle);

描述：

ClientApi_PerformLoadForDocumentEntity过程打开一个适当的编辑器窗体并且从一个设计数据库中加载一个文档的内容。

例子:

...

ClientApi_PerformLoadForDocumentEntity(TextEntity.Handle);

ClientApi_SetAsCurrentDocument(TextEntity.Handle);

...

此代码片段打开一个文本编辑器窗体并且加载一个文本文档内容到此文本窗体中，再设置成为当前文档。

参见其它：

  4.3.21 ClientApi_PerformSaveForDocumentEntity过程

声明(来自ClientProcs单元)：

Procedure ClientApi_PerformSaveForDocumentEntity(ADocumentEntity : TObjectHandle);

描述：

ClientApi_PerformSaveForDocumentEntity过程使用文档实体的句柄作为参数来保存设计资源管理器的一个文档实体。

例子：

hModule := MessageRouter_Modulehandle(‘Sch’);

//MessageRouter_ModuleHandle函数返回指定名称模块的句柄，模块名称是Sch表示返回原理图编辑器模块句柄。

IfMessageRouter_SendGetStateDocumentHasChanged(hModule,Entity.Objecthandle) Then

ClientApi_PerformSaveForDocumentEntity(Entity.Handle)

//MessageRouter_SendGetStateDocumentHasChanged判断文档对象Entity是否已被修改。

此代码片段示范只要一个文档被修改(例如被用户改变了内容)，那么函数ClientApi_PerformSaveForDocumentEntity保存此新文档。hModule变量表示服务器模块的句柄。

参见其它：

  4.3.22 ClientApi_QueryDocumentEntity过程

声明(来自ClientProcs单元)：

Procedure ClientApi_QueryDocumentEntity(...);

描述：

ClientApi_QueryDocumentEntity过程依赖于查询模式(eGetState或eSetState)来设置或返回一个实体的值。当eGetState参数使用时，数据被从客户端内部服务器中传送到您的服务器中。当eSetState参数被使用时，您的服务器的数据被传送到客户端内部服务器中，在您的服务器从内部服务器数据库中提取了数据并进行了修改的情况下，使数据得到了同步。因而使用AModeQuery参数是必要的，确保从客户端数据库中提取出的数据和您的外部服务器的数据完全地同步。

例子：

Begin

EntityHandle :=

ClientAPI_FindEntityByDataHandle(MessageRouter_GetState_CurrentEditorWindow);

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

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

If Entityhandle = 0 Then Exit;//当前无实体则退出。

ClientApi_QueryDocumentEntity(EntityHandle,eGetState,AParentHandle,

AEntityId,AOwnerBinder,AKind,

AName,AEditorKind,ADBAttributes,

ADocumentDBId,FullAddress,AObjectHandle);

//用内部服务器数据同步外部服务器数据。

ShowInfo('Parenthandle = '+ IntToStr(AParenthandle)+ #13 +

'AEntityId = '+ IntToStr(Ord(AEntityId)) + #13 +

'AOwnerBinder = ' + IntToStr(AOwnerBinder)+ #13 +

'Kind = '+ AKind+ #13 +

'Name = '+ AName+ #13 +

'Editor Kind = '+ AEditorKind+ #13 +

'DBAttributes = '+ IntToStr(ADBAttributes)+ #13 +

'Document DB Id = ' + IntToStr(ADocumentDBId)+ #13 +

'full address = '+ FullAddress+ #13 +

'Object handle = '+ IntToStr(AObjectHandle));

End;

//显示实体的参数。

您需要在设计资源管理器中打开一个设计数据库并且运行此代码。如果此文档的编辑器种类是一个“workgroup”，在设计中它是项层的文件夹，对所有文档和文件夹来说，此文件夹是父文件夹，如果编辑器种类是一个文件夹并且EntityId值是2，它意味着此实体是设计本身。

参见其它：

  4.3.23 ClientApi_PostNetworkMessage过程

声明(来自ClientProcs单元)：

Procedure ClientApi_PostNetworkMessage(Target :　TString; MsgID : Word; MsgData : TString);

描述：

ClientApi_PostNetworkMessage过程跨越网络发送一个消息到设计数据库和设计资源管理器应用程序中。

参见其它：

  4.3.24 ClientApi_RunDocumentPropertiesDialog过程

声明(来自ClientProcs单元)：

Procedure ClientApi_RunDocumentPropertiesDialog(ADocumentEntity : TObjectHandle);

描述：

ClientApi_RunDocumentPropertiesDialog过程使用文档实体的句柄来显示此特定设计文档的属性，如文档的类型、文档的位置、字节大小、此文档的被创建、被修改和被访问的日期与时间属性等等。

  4.3.25 ClientApi_RepopulateDocumentEntity过程

声明(来自ClientProcs单元)：

Procedure ClientApi_RepopulateDocumentEntity(ADocumentEntity : TObjectHandle; Recursive : TBoolean);

描述：

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

例子：

EntityHandle :=

ClientAPI_FindEntityByDataHandle(MessageRouter_GetState_CurrentEditorWindow);

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

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

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

BinderHandle := ClientApi_GetDocumentOwnerBinder(EntityHandle);

//得到当前实体所在的容器。

ClientApi_RepopulateDocumentEntity(BinderHandle,False);

  4.3.26 ClientApi_RegisterEntityIcon函数

声明(来自ClientProcs单元)：

Function ClientApi_RegisterEntityIcon(AServerName, AnIconName : TString) : Integer;

描述：

ClientApi_RegisterEntityIcon函数在设计资源管理器的浏览器中分配和显示服务器的图标。在此函数成功地注册您的图标前，您需要服务器的名称和服务器使用的图标名称，当图标被注册后，它被增加到一个客户端的一个内部列表中，设计资源管理器使用此列表来在浏览器或导航器面板中管理图标的表现。

  4.3.27 ClientApi_SendCommandToModule函数

声明(来自ClientProcs单元)：

Function ClientApi_SendCommandToModule(...) : TBoolean;

描述：

ClientApi_SendCommandToModule函数运行指定模块中的指定进程，如果成功返回真(True)，否则返回假(False)。此函数允许一个服务器来运行其它服务器中的进程。目标窗体句柄为要运行的进程指定了目标文档对象的窗体句柄，如果没有文档被服务器所支持，参数应设置为cProcessWindow_DontCare，如果目标服务器没有启动，此函数将自动地启动目标服务器。

如果服务器模块标识符没有被应用在进程参数中，它默认为“Client”，举例来说，“CreateNewDocument”被此函数认为是“Client:CreateNewDocument”。

使用Parameters参数，进程能返回结果。例如，“Client:RunCommonDialog”进程运行一个对话框并且通过此参数返回结果，当参数被交付到目标服务器模块时，参数大小允许为64K，然而，当进程返回MaxParameterSize参数时，表示调用模块有多少个字节被拷贝返回到Parameters参数中。

  4.3.28 ClientApi_SetAsCurrentDocument函数

声明(来自ClientProcs单元)：

Function ClientApi_SetAsCurrentDocument(ADocumentEntity : TObjectHandle) : TObjectHandle;

描述：

ClientApi_SetAsCurrentDocument函数设置一个打开的文档实体作为当前焦点或成为在设计资源管理器中的活动文档。如果一个文档实体没有在一个窗体中被打开，函数返回零值，另外，如果文档实体不是一个文档或设计数据库，函数也返回零值，当您需要来让一个隐藏的文档窗体在其它设计资源管理器窗体的前面时，此函数常被使用。

参见其它：

  4.3.29 ClientApi_ShowDocument过程

声明(来自ClientProcs单元)：

Procedure ClientApi_ShowDocument(ADocumentEntity : TObjectHandle; Show : Boolean);

描述：

ClientApi_ShowDocument过程为您显示您所感兴趣的文档，ADocumentEntity是文档的句柄，Show参数控制文件是否被显示。

例子：

ClientApi_ShowDocument(EntityHandleOfADocument,True);

此代码片段使用ClientAPI_ShowDocument函数强制特定的文档来被显示。

  4.3.30 SetAllClientApiProcedures过程

声明(来自ClientProcs单元)：

Procedure SetAllClientApiProcedures;

描述：

SetAllClientApiProcedures过程初始化并且设置所有客户端API调用。

  5. 类

  5.1 TEntity类

声明(来自ClientClass单元)：

Type

TEntity = Class

Handle: TObjectHandle;

ParentHandle: TObjectHandle;

EntityId: TEntityId;

OwnerDesign: TObjectHandle;

Kind: TString;

Name: TString;

ObjectHandle: TObjectHandle;

Constructor Create(AHandle : TObjectHandle);

DestructorDestroy;

ProcedureQueryDatabase(AQueryMode : TQueryMode); Virtual;

ProcedureWriteToDebug;

End;

描述：

TEntity类代表一个设计数据库基本的实体。对于提供有关在一个设计数据库中的文档的信息的TDocumentEntity类而言，此类是基础类。

注意：

Querydatabase过程确保在您的服务器中的TEntity对象和设计资源管理器客户端服务器中的数据之间的数据完整性得到了保护。因而，如果您想要的数据已被您的服务器修改，您需要用eSetState模式来通知客户端服务器，或如果您想要从客户端中提取数据，您需要用eGetState模式来通知客户端服务器。

参见其它：

  5.2 TDocumentEntity类

声明(来自ClientClass单元)：

TDocumentEntity = Class(TEntity)

EditorKind : TString;

DocumentDBId : Integer;

DBAttributes : Integer;

FullAddress: TString;

Constructor Create(AHandle : TObjectHandle);

ProcedureQueryDatabase(AQueryMode : TQueryMode); Override;

FunctionGetAbsoluteAddress : TString;

End;

描述：

TDocumentEntity类代表一个设计数据库的文档实体。一个文档实体代表设计数据库中一个文档或一个文件夹。此类从TEntity基础类继承。

请见SDK例子\SAMPLES\NO6\API\Client\Document Entity Details。

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

Procedure GetDocumentEntityInfo;

Var

EntityHandle: TObjectHandle;//实体对象句柄。

BinderHandle: TObjectHandle;//容器对象句柄。

DocumentEntity: TDocumentEntity;//文档对象句柄。

Begin

EntityHandle :=

ClientAPI_FindEntityByDataHandle(MessageRouter_GetState_CurrentEditorWindow);

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

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

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

DocumentEntity := TDocumentEntity.Create(EntityHandle);//创建一个文档实体对象。

DocumentEntity.QueryDatabase(eGetState);//用客户端数据同步外部外部服务器数据。

ShowInfo('Object handle = '+ IntToStr(DocumentEntity.ObjectHandle)+ #13 +

'Parent handle = '+ IntToStr(DocumentEntity.ParentHandle)+ #13 +

'Binder handle = '+ IntToStr(DocumentEntity.OwnerDesign)+ #13 +

'AEntityId = '+ IntToStr(Ord(DocumentEntity.EntityId)) + #13 +

'Editor Kind = '+ DocumentEntity.EditorKind+ #13 +

'Document DB Id = ' + IntToStr(DocumentEntity.DocumentDBId)+ #13 +

'Full address = '+ DocumentEntity.FullAddress

);

DocumentEntity.Free;//释放文档实体对象。

End;

TDocumentEntity类封装ClientAPI_QueryDocumentEntity函数来提取有关一个特定的文档实体明细。

参见其它：

  6. 客户端API例子

  6.1打开想要的文档

如何您想要打开一个指定的文档，且您仅仅知道设计文档的名称，那么您能运行此小规模的附加的服务器，在“\SAMPLES\NO2\API\Client\SearchAndOpenDocuments”文件夹下。当您读完客户端API章节后，您就能了解此服务器是如何工作的。

为了使用这个“SearchAndOpen”附加的服务，您只需输入参数“DocumentName1=Value1 | DocumentName2 = Value2”等，在这里，ValueX是设计文档的文件名称(例如，“DocumentName1 =Control.pcb | DocumentName2 = logic.sch”)。(e-works)