CATIA二次开发—API梳理

一、前言

上期《漫谈开发环境》中，提及了CATIA二次开发的底层技术，并制作了一个Hello CATIA实例，这里需要纠正一下上期中存在的一个错误：在进程内和进程外对比的表格中，本人对宏的缺点描述为没有交互界面，而其实自带的宏编辑器是可以制作简单的交互界面的，如下图所示。由于作者水平有限，所以不免犯一些差错，欢迎读者们批评指正。这期的内容还是从大的方面入手，不涉及具体的功能实现，咱聊一聊API的查询技巧、 V6 API的整体架构，并详细描述与CATIA对象直接相关的属性和方法。

图片引自Docker《CATIA VBA 二次开发入门与提高》

二、API 架构及CATIA Application

2.1 API 查询技巧

（1）继承关系查询

了解API结构继承关系，有利于程序的编制。例如很多时候我们需要进行类型的强制转换，这时应先确认被转换类是否继承至转换类，否则将导致转换失败，程序报错。

（2）索引查询

索引查询可以根据具体的类型去查询方法、属性、接口等等，并可以按首字母进行筛选。这种查询方式一般不用，有种大海捞针的感觉😂。

（3）直接搜索

搜索 API 简单粗暴且高效，我的做法是打开谷歌翻译，将想要实现的功能的关键词翻译为英文，填入搜索框进行搜索。例如想测量长度时，就直接搜索Length即可。

（4）录制宏

录制宏功能简直是CATIA二次开发人员的福音。API找不到？录制宏呀；功能不会实现？录制宏呀。总之，万事皆可录制，如果宏都录不出来那就自求多福吧。

2.2 API 基本架构

对比V5和V6的API整体设计（下图），不难发现两者存在较大差异。在《what is catia》中，我们已经说明了V6相对于V5的最大更新在于使用中央服务器来存储模型数据，而非本地存储。正是由于这种数据管理方式的迭代导致了API顶层设计的变化。所以，以前从事V5开发的工程师在接触V6时往往不太适应。在V5开发中，我们可以很轻松地创建新的产品和零件，但在V6中这却是个令人头疼的事情，新建产品或零件的过程本质上变成了操作服务器中的数据库。

API结构总览（左为V5，右为V6）

很明显的两点不同在于：Document变为了Editor，而Workbench变为了Service。举个开发实栗🌰：测量直线长度。

// V5
Workbench TheSPAWorkbench = CATIA.ActiveDocument.GetWorkbench("SPAWorkbench");
Measurable TheMeasurable1 = TheSPAWorkbench.GetMeasurable(referenceObject1);
double length = TheMeasurable1.Length;
// V6
MeasurableService theMeasureService = (MeasurableService)CATIA.ActiveEditor.GetService("MeasurableService");
MeasurableCurve theMeasureItem = (MeasurableCurve)theMeasureService.GetMeasurable(obj, CATMeasurableType.CAAMeasurableCurve);
Double length = theMeasureItem.GetLength();

就Service而言，其主要提供与对象无关（不能编辑对象）的一些操作，V6 API中将其分为两个级别： Session-level（下图左） 和 Editor-level（下图右）。前者可以应用于任何PLM根对象，或者是没有对象的状态下；后者是对Editor中指定的PLM根对象进行操作。比如SearchService位于 Session-level中，我们只要拿到CATIA对象便能进行服务调用，与当前是否存在Editor无关。而当我们使用MeasurableService时，因其位于Editor-level，所以我们需要获取到编辑对象（Editor）才能进行测量。

CATIA.GetSessionService("Search");
CATIA.ActiveEditor.GetService("MeasurableService");

两种 Sevice 的调用方式也不同，分别为 GetSessionService(" “) 和 GetService(” ")

两种Service

我个人对于V6 API 顶层设计的理解总结为下图。CATIA Application 理解为整个3DE 程序的窗体，在这个层级下，API 可以调用一些全局的功能或者设置，例如CATIA.RefreshDisplay = False 关闭刷新显示功能以提高性能，CATIA.Quit()退出CATIA程序，CATIA.StartCommand "undo" 执行 one-shot等等，具体见2.3节；Session 理解为CATIA程序的中的会话窗口，一个CATIA程序中我们可以同时打开多个子窗口，它们以选项卡的形式呈现，在该层级下的操作只与窗口相关，不能编辑模型数据；而Editor才真正涉及具体的模型数据，通过它，我们便能拿到结构树上的元素，并对其进行编辑操作。

CATIA界面与API对应逻辑

实际开发过程中，涉及最多的还是 Editor 中的 AnyObject（其内包含更深层次的结构图） 和 Selection。其他 API 功能，除非有特殊需求，一般接触不多。

2.3 CATIA 对象的属性及方法

2.3.1 属性

Property Index		译文
ActiveEditor	Returns the active editor.	返回当前激活的编辑对象
ActivePrinter	Returns or sets the active printer.	返回或设置激活的打印机
ActiveWindow	Returns the active window.	返回激活的窗口
CacheSize	Returns or sets the default local cache size used by the application.	返回或设置本地缓存容量
Caption	Returns or sets the application’s window title.	返回或设置程序窗口的标题
DisplayFileAlerts	Returns or sets the application ability to display file alerts.	是否显示文档警报信息
Editors	Returns the collection of editors currently managed by the application.	返回所有的编辑对象
FileSystem	Returns the file system.	返回文件系统
FullName	Returns the application’s executable file full name, including its path.	返回程序所在路径
HSOSynchronized	For selection performance purposes, returns or sets the HSO synchronization in comparison with the CSO.	返回或设置同步 HSO（Highlighted Set of Objects）、CSO(Current Set of Objects)
Height	Returns or sets the height of the application’s frame window.	程序窗体的高度
Interactive	Returns or sets the application sensitivity to end user interactions.	返回或设置程序对用户交互的敏感性
Left	Returns or sets the distance from the application’s frame window left side to the left side of the screen.	程序窗体的左边距
LocalCache	Returns or sets the default local cache path used by the application.	返回并设置程序在本地的缓存路径
Path	Returns the path of the application’s executable files.	返回程序所在的文件夹
Printers	Returns the collection of the printers currently managed by the application.	返回程序所有的打印机
RefreshDisplay	Returns or sets whether the update of the display is enabled during the script replay.	是否刷新显示
ScriptCommand	Enables the scripter to make his script behave as a CATIA command.	设置脚本执行状态
StatusBar	Returns or sets the text displayed in the application’s window status bar.	返回或设置提示栏的文字
SystemConfiguration	Returns the system configuration object.	返回CATIA版本和系统信息（Release：小版本号；ServicePack：补丁包编号；Version：大版本号）
SystemService	Returns system services.	返回系统服务，可进一步获得CATIA环境变量、执行脚本程序
Top	Returns or sets the distance from the application’si frame window top to the top of the screen.	程序窗体的上边距
UndoRedoLock	Returns or sets the application status about Undo/Redo.	返回或设置撤销和回滚的开关
UserInterfaceLanguage	Returns the user interface language.	返回用户界面的语言
Visible	Returns or sets the application’s window visibility.	返回或设置程序是否可见
Width	Returns or sets the width of the application’s frame window.	程序窗体的宽度
Windows	Returns the collection of windows currently managed by the application.	获取程序中打开的所有窗口

2.3.2 方法

Method Index		译文
DisableNewUndoRedoTransaction	Prevents new Undo/Redo transaction creation.	阻止撤销和回滚事务的创建
EnableNewUndoRedoTransaction	Allows new Undo/Redo transaction creation.	允许撤销和回滚事务的创建
FileSelectionBox	Displays a modal dialog box.	文件选择和保存对话框
FolderSelectionBox	Displays a modal dialog box.	文件夹选择对话框
GetSessionService	Returns the specified service.	返回会话框服务对象
GetWorkbenchId	Returns the identifier of the current workbench.	获取当前工作台的 ID 标识
Help	Displays application’s online help.	帮助
Quit	Exits the application and closes all open windows.	退出程序
StartCommand	Starts a command.	启动命令（可用的字符串见下面的代码）
StartWorkbench	Starts a workbench.	启动工作台

CATIA.StartCommand "Search..."
CATIA.StartCommand "Disassemble" 
CATIA.StartCommand "* Iso"
CATIA.StartCommand "undo" // 撤销
CATIA.StartCommand "Isolate" // 隔离
CATIA.StartCommand "Front View"
CATIA.StartCommand "Generate CATPart from Product..."
CATIA.StartCommand "Collapse all"
CATIA.StartCommand "Load"
CATIA.StartCommand "Reset Compass"
CATIA.StartCommand "testvisuperfodraw"
CATIA.StartCommand "Center graph"
CATIA.StartCommand "Points And planes Repetition"
CATIA.StartCommand "Options"
CATIA.StartCommand "Axis System"

三、参考资料

《3DEXPEROENCE Automation Help》

《CATIA VBA 二次开发入门与提高》—Docker

本人新建一个CATIA 二次开发的交流学习群，有兴趣的可以加一下，大家一起交流共同进步，我会把自己收集到的一些学习资料放在里面，供大家免费下载。