【CATIA的二次开发23】抽象对象Document涉及文档激活控制的方法

在CATIA VBA开发中，Document对象是最核心、最基础的对象之一。它代表了当前在CATIA会话中打开的一个文档（文件）。
几乎所有与文件操作、模型访问相关的操作都始于获取一个Document对象。Document对象包含多种方法和属性，以下介绍Document对象方法和属性

一、Document对象方法

1、方法和属性列表

2、方法分类

分类	方法	功能描述	适用文档类型	示例代码
文档激活控制	Activate	激活文档使其成为当前活动文档	所有文档类型	targetDoc.Activate
	NewWindow	为文档创建新窗口	所有文档类型	doc.NewWindow
文档生命周期	Close	关闭文档	所有文档类型	doc.Close catSaveChanges
	Save	保存文档	所有文档类型	If Not doc.Saved Then doc.Save
	SaveAs	文档另存为	所有文档类型	doc.SaveAs “C:\NewName.CATPart”
数据交换	ExportData	导出文档为其他格式	所有文档类型	doc.ExportData “C:\export.stp”, “stp”
交互选择	Indicate2D	在2D环境(工程图)中交互选择元素	DrawingDocument	Set elem = doc.Indicate2D(“选择元素”, catSelectionFilterDimension)
	Indicate3D	在3D环境(零件/装配)中交互选择元素	PartDocument ProductDocument	Set face = doc.Indicate3D(“选择面”, catSelectionFilterFace)
对象引用	CreateReferenceFromName	通过名称创建对象引用	所有文档类型	Set ref = doc.CreateReferenceFromName(“Part1\Sketch.1”)
	GetItem	通过名称获取文档中的项目(参数、关系等)	所有文档类型	Set param = doc.GetItem(“LengthParam”)
工作环境控制	GetWorkbench	获取指定工作台对象	所有文档类型	Set pdWB = doc.GetWorkbench(“PartDesignWorkbench”)
选择过滤	CreateFilter	创建选择过滤器	所有文档类型	Set filter = doc.CreateFilter(“FaceFilter”)
	RemoveFilter	移除选择过滤器	所有文档类型	doc.RemoveFilter filter

二、方法～文档激活控制(Activate方法和NewWindow方法)

1、Activate方法

在CATIA VBA开发中，Document 对象的Activate方法用于将指定的文档设置为当前活动文档（即获得焦点的文档）。
当CATIA会话中有多个文档打开时，该方法至关重要，因为它决定了后续操作将在哪个文档上执行。

方法功能
1. 目标文档会前置显示在 CATIA 窗口中（如果被遮挡）；
2. 该文档成为当前操作上下文（后续代码默认作用于该文档）；
3. CATIA.ActiveDocument 属性会自动更新为被激活的文档。
方法语法

myDocument.Activate

典型使用场景

场景一：切换活动文档（多文档操作）

Dim doc1 As Document, doc2 As Document
Set doc1 = CATIA.Documents.Open("C:\Part1.CATPart")
Set doc2 = CATIA.Documents.Open("C:\Assembly1.CATProduct")' 激活零件文档
doc1.Activate  
' 此时在 Part1 上操作...' 切换到装配文档
doc2.Activate  
' 后续操作在 Assembly1 上进行

场景二：确保文档处于活动状态

' 获取非活动文档的引用
Dim inactiveDoc As Document
Set inactiveDoc = CATIA.Documents.Item(2)  ' 假设是第二个打开的文档' 强制激活它
inactiveDoc.Activate' 现在可以安全操作该文档
Dim sel As Selection
Set sel = CATIA.ActiveDocument.Selection  ' 正确获取选择集

场景三：新建文档后立即激活

Dim newDrawing As Document
Set newDrawing = CATIA.Documents.Add("Drawing")
newDrawing.Activate  ' 确保新工程图成为当前文档' 直接操作新文档
Dim sheet1 As DrawingSheet
Set sheet1 = newDrawing.Sheets.Item("Sheet.1")

重要注意事项
1. 非阻塞方法
  Activate 方法会立即返回，但 CATIA 界面可能需要短暂时间完成切换（通常无需额外等待）
2. 与 ActiveDocument 的关系激活后，以下等式成立：
```
myDocument.Activate
Debug.Print (myDocument Is CATIA.ActiveDocument)  ' 输出 True
```
1. 避免不必要的激活
  如果只需读取文档属性（如 Name, Path），无需激活：
```
' 不激活即可获取信息
Dim docName As String
docName = myDocument.Name
```
1. 错误处理
  尝试激活已关闭的文档会引发错误：
```
On Error Resume Next
myDocument.Activate
If Err.Number <> 0 ThenMsgBox "文档已关闭或无效"
End If
```
最佳实践

' 安全激活文档的模板代码
Sub SafeActivate(targetDoc As Document)On Error GoTo err_handlertargetDoc.ActivateExit Suberr_handler:If Err.Number = -2147467259 Then ' 典型错误号MsgBox "无法激活文档: " & targetDoc.Name & vbCrLf & _"可能已被关闭", vbExclamationElseMsgBox "未知错误: " & Err.DescriptionEnd If
End Sub

经验总结

方法	作用	是否需要激活文档
Activate	切换活动文档	前置条件
Save	保存文档	否
Close	关闭文档	否
GetItem	按名称获取文档内对象	否（但对象需有效）
Update	强制更新文档特征	否

大部分文档操作（如保存/关闭）不需要文档处于激活状态，但图形交互操作（如通过 Selection 对象选择元素）必须在活动文档中进行。

2、NewWindow方法

在 CATIA VBA 开发中，Document.NewWindow 方法是一个强大的多窗口管理工具，用于为当前文档创建新的独立视图窗口。
这个方法在需要同时查看同一文档的不同区域或视角时特别有用，显著提升设计效率和可视化能力。

方法功能
为当前文档创建新的视图窗口
方法语法
```
Function NewWindow() As Window
```
- 返回值：新创建的 Window 对象
核心功能与优势
1. 多视图协同
  同时查看模型的多个视角（如俯视图、前视图、3D视图）
2. 独立控制
  每个窗口可独立设置：
  - 缩放级别
  - 观察角度
  - 渲染模式
  - 显示/隐