SpaceClaim二次开发（2）

第三章 Documents and Doc Objects（文档和文档对象）

3.1 概述

3.2 父子层次结构

3.3 零部件

3.4实例和事件

3.5 作用链

3.6 一般对象和master

3.7 原始和master

3.8 转化为主空间

3.9 获取事件

本篇主要介绍SpaceClaim二次开发文档的第三章。（由于使用的翻译，很多专业名词翻译可能存在问题，如有错误，相互交流学习）

第三章 Documents and Doc Objects（文档和文档对象）

3.1 概述

文档是加载和保存的单位。假设已保存，则文档对应于磁盘上的SpaceClaim scdoc文件。

DocObject是属于文档的对象。文档对象不是保存文档时唯一保存的对象，但它们是唯一具有document属性的对象。文档对象的示例包括：零件、组件、设计体、设计面、基准面和注释。

文档对象提供：

父子树包含层次结构。

用于持续识别的监视器。

更新状态以指示文档对象已更改。

用于存储第三方数据的自定义属性。

3.2 父子层次结构

文档对象是父子包含层次结构的一部分，其中父对象表示容器，子对象表示内容。如果删除一个doc对象，则其所有子对象（递归的子对象）也将被删除。

例如，一个零件包含零个或多个设计体对象，每个对象都包含一个或多个人设计面对象。设计面的父级是设计体，设计体的父级是零件。同样，设计体是零件的子体，设计面是设计体的子体。

Public static void Example(DesignBody desBody) {
Part part = desBody.Parent;  //获取父对象
// a part is a root object, so it has no parent
Debug.Assert(part.Parent == null); //assert用于检验关系是否正确
Debug.Assert(part.Root == part);// GetChildren<T> returns immediate children of type T
foreach (DocObject child in part.GetChildren<DocObject>()) { //遍历part的子对象
// Parent returns the immediate parent
Debug.Assert(child.Parent == part); //检验子对象的父亲是part
}// DesignBody.Faces is equivalent to GetChildren<DesignFace>
foreach (DesignFace desFace in desBody.Faces) {  //遍历设计体的面
// Root returns the topmost parent
Debug.Assert(desFace.Root == part); //检验设计面的根对象为part
}// GetDescendants<T> gets all nested children of type T 获取所有T类型的嵌套子节点
// the search starts with the object itself 搜索从对象本身开始
foreach (DesignFace desFace in part.GetDescendants<DesignFace>()) { 
// GetAncestor<T> crawls up the parent chain to find an object of type T                 
// GetAncestor<T>向上爬取父链以查找T类型的对象
Debug.Assert(desFace.GetAncestor<Part>() == part);
// the search starts with the object itself
Debug.Assert(desFace.GetAncestor<DesignFace>() == desFace);
}
}

父链沿着层次结构向上延伸，直到到达根对象。这是最上面的父级，它本身没有父级（其父级为null）。根对象的示例包括：零件、图纸和图层。

同一父子层次结构中的所有文档对象都属于同一文档。Document类提供了访问其根对象的属性：MainPart、Parts、DrawingSheet和Layers。

3.3 零部件

零件包含零个或多个设计体对象和零个或更多组件对象。这意味着一个零件可以包含设计体和组件，在这种情况下，它既不是纯单件零件，也不是纯装配。支持这一点，以便交互式用户可以将设计体重构为组件，反之亦然。

组件是模板零件的实例。它有一个放置矩阵，用于将组件定位到装配空间中。模板既不是组件的子级，也不是父级。如果父子层次结构被可视化为一个倒置的树结构，根在顶部，叶节点在底部，那么模板是对另一个部分的横向引用，而另一个零件是另一个层次结构的根。

模板部分可能与组件位于同一文档中，从而产生交互式用户所称的内部组件，也可能位于另一个文档中，进而产生外部组件。严格来说，模板部分是内部或外部的，而不是组件本身。

3.4实例和事件

工程视图也是模板零件的实例，因为工程视图将零件转换为图纸空间，就像组件将零件转换到装配空间一样。Component和DrawingView都继承自Instance。

实例递归地生成Template对象的转换出现及其子对象的出现。模板对象始终是根对象。转换由Placement矩阵定义。Content属性提供对模板对象出现的访问，模板对象是实例的子对象。

模板对象未被复制。相反，每个事件都是一个轻量级的包装器，是其原始对应物的转换表示。引用呈现的几何图形位于实例空间中，这意味着零部件的装配空间和工程视图的图纸空间。当原始对象更改或实例位置更改时，引用会隐式更改。对事件所做的任何更改实际上都是对原始事件的更改。

事件与产生它们的实例属于同一父子层次结构。整个父子层次结构位于同一坐标空间中。

3.5 作用链

如果模板对象本身包含实例，则会生成出现的实例。例如，这发生在两级装配中，因为顶级装配包含一个实例化子装配零件的组件，而子装配零件本身包含一个实例零件的组件。

3.6 一般对象和master

一般来说，文档对象要么是事件，要么是主对象。在处理一般文档对象（可能是引用或主对象的文档对象）时，会使用接口，例如IPart、IComponent和IDesignBody。这些都源自IDocObject。

由于理论或实践原因，有些方法和性质不是由事件呈现的，因此只能由masters呈现。在处理母版时，使用类，例如Part、Component和DesignBody。这些都源自于实现IDocObject的DocObject。

Part实现了IPart，Component实现了IComponent，以此类推，因此master支持通用对象支持的一切，而且通常还支持更多。

请注意，尽管Part始终是根对象，但IPart可能是也可能不是根对象。如果IPart恰好是主对象，则它是根对象，但如果它恰好是事件，则其父对象将是IComponent或IDrawingView。

3.7 原始和master

IDocObject是所有文档对象功能的基础。它提供了遍历父子层次结构的成员（Children、GetChildren<T>、GetDescendants<T>，parent、GetAncestor<T>和Root），我们已经见过这些成员，它还提供了遍历引用结构的成员：

Original–获取原始IDocObject，否则如果这是主对象，则为null。

Master–获取最终的原始文件，即出现链末尾的DocObject主文件。如果对象是主对象，则返回对象本身。

instance–获取产生此事件的实例，如果这是主实例，否则为null。

3.8 转化为主空间

这些属性中最常用的是Master，因为Master可以提供通用对象上不可用的方法和属性。由于主对象可能位于与一般对象不同的坐标空间中，因此可以使用TransformToMaster来获取将一般空间中的对象映射到主空间中对象的变换。

Public static void Example(Icomponent comp, Frame placement) {// the Placement property is available on Component, but not Icomponent
// Placement属性在Component上可用，但在Icomponent上不可用
Component master = comp.Master;// map placement frame into master-space  将地图放置到主空间中
Matrix transToMaster = comp.TransformToMaster;
Frame masterPlacement = transToMaster * placement;// apply master placement frame to master component  将主放置框架应用于主组件
master.Placement = Matrix.CreateMapping(masterPlacement);
}

3.9 获取事件

在主空间中完成了一些工作后，可能需要在一般空间中获得一个物体。如果原始对象来自窗口选择，并且您希望在窗口中设置新的选择，则这很常见。

窗口选择始终在窗口空间中，即在与该窗口中显示的场景相同的坐标空间中（与window.scene相同的坐标系）。因此，如果窗口显示装配，则选定对象位于装配空间中。

GetOccurrence可用于获取普通空间中的对象。它返回一个与提供的伴随对象类似的事件。请注意，伴随对象是一个一般对象，它可能是也可能不是一个事件。如果是一个事件，则返回该主题的等效事件。如果不是事件，则返回主题本身。这允许您编写正确工作的代码，而无需测试对象是否确实是一个事件。

Public static void Example() {
Window window = Window.ActiveWindow;
if (window == null)
return;// the selected component is in window-space 所选组件位于窗口空间中
IComponent oldComp = window.SingleSelection as IComponent;
if (oldComp == null)
return;// copy the component master  复制组件主数据
Component oldMaster = oldComp.Master;
Component newMaster = Component.Create(oldMaster.Parent, oldMaster.Template);
newMaster.Placement = oldMaster.Placement;// get an occurrence of the new master in window-space 在窗口空间中获取新主节点的出现
IComponent newComp = newMaster.GetOccurrence(oldComp);// select the newly created component  选择新创建的组件
window.SingleSelection = newComp;
}