5. Revit API: Application

5. Revit API: Application

前言

上一篇中，讲到了UI篇的Ribbon（界面），并提到要创建 RibbonPanel，需要使用UIControlledApplication.CreateRibbonPanel(..)方法，还在结尾说到要写“UI”开头的那些个类，本来呢是这么想的，但写的时候，发现单独写UI类不好，与它们关联的类有不少呢，所以想想，还是把相关的内容都放一块儿，一起写了得了。

---

Application 相关类

Application 的翻译是“应用/应用程序”，也就是APP的简写。在程序中，一般与配置、操作、框架之类的相关。在Revit中，就是①本身表示某类应用，②提供某类操作的入口，并且都定义了不少事件。

这一篇标题是Application，与之直接关联的类或接口有哪些呢？我整了个图，一起看看。

IExternalApplication（外部应用）接口 -> 其方法提供了UIControlledApplication参数 -> 该参数有属性ControlledApplication -> 又能从该属性中拿到Creation命名空间下的另一个Application类。

IEcternalCommand（外部命令）部分的图也这样看下去。

根据它们之间的关联，这一篇，我们就讲一讲这4个：

• UIApplication 与 UIControlledApplication
• UIxxx 到 XXX
• Application 与 ControlledApplication
• Autodesk.Revit.Creation.Application：这个先简单提一下，后面专门写Creation相关的东西。

一、UIApplication 与 UIControlledApplication

UIApplication 与UIControlledApplication 都是 Autodesk.Revit.UI 命名空间下的类，也都是直接派生自 System.Object ，尽管它们之间**共享**大部分属性、方法和事件，但它们之间并不存在继承关系，我们带着问题来了解它们。

1.1. 是做什么的

UIApplication 和 UIControlledApplication 都是用来操作界面的，它们之间共享了大部分属性、方法和事件，可以当作是同一个来使用。

我们来看看方法：

Methods	Description	UIApp	UIC..App
CanPostCommand PostCommand	主动触发一些命令	✔	✔
CreateAddInCommandBinding RemoveAddInCommandBinding LoadAddIn	重绑定按钮和外部命令 加载外部命令	✔	✔
CreateRibbonPanel x3 CreateRibbonTab GetRibbonPanels x3	创建/查询工具栏处的界面。 x3表示有3个重载	✔	✔
DoDragDrop x2	文件拖入Revit时会执行的操作。Revit有默认行为	✔	❌
GetDockablePane RegisterDockablePane	获取/注册 可停靠界面DockablePane	✔	✔
OpenAndActivateDocument x2	更改活动文档	✔	❌

可以看到，UIApplication只多了文件拖入和更改活动文档这两类方法。

属性上，提供一些指向具体操作的实例， 如下图。

而事件呢，则是完全一样。

从事件上看，UIApplication与UIControlledApplication的管理范围，基本就限定在展示上（文档操作之外）。

结合方法，基本就是一些“准备/前置”工作。

Events	Description
ApplicationClosing	应用关闭时触发
DialogBoxShowing DisplayingOptionsDialog	对话框、对话选项
DockableFrameFocusChanged DockableFrameVisibilityChanged	可停靠界面 聚焦/显影变化
Idling	空闲事件
ViewActivated ViewActivating	视图切换
FabricationPartBrowserChanged TransferredProjectStandards TransferringProjectStandards	不看

1.2. 差异与产生原因

最直接的导致差异的原因，应该是这两者的来源不同吧。

UIControlledApplication是实现外部应用接口时，由方法OnStartup/OnShutdown提供，此时Revit刚刚启动，未打开任何Revit项目。

UIApplication 主要是实现外部命令接口时，由方法Execute(ExternalCommandData..)提供，此时【已打开】了Revit项目。

从这儿，我们也就理解了，为什么方法和属性略有差异，而事件则完全相同了。

比如 UIApplication 多出的那几个方法，总得Revit打开了，能交互了，才能拖拽文件进去，才有视图能切换嘞。

注：【已打开】
启动Revit后停在欢迎界面，没有打开具体的项目呢，此时插件的不可用的。我就是要点点试试怎么办？上一篇提到的按钮的AvailabilityClassName属性，可以改变按钮可用状态。效果嘛，没试过，猜测拿文档会报错。

---

二、UIApplication 与 Application

在上面，我们已经知道，UIApplication 持有 Application 属性，因此我们可以从前者对象获取到后者的实例。而作为贡献了大部分方法、属性、事件的UIControlledApplication 与 ControlledApplication 显然也是类似的，只不过多提供了几个实例（上面的属性图）。

它们之间的关系，似乎仅此而已。真的仅此而已。

那么，意义呢？

UIControlledApplication 提供 ControlledApplication的入口，UIApplication 提供 Application 的入口，两个UI类本身对同一事物进行操作。

（UI)ControlledApplication 到 (UI)Application 基本就提供一个实例.

类似的还有UIDocument与Document。

虽然名称类似，功能类似，但又如上面 1.1 里说的俩UI类范围被限定到展示相关，而不带UI的显然就是对文档，对Revit项目的操作了。

逻辑清晰，结构分明，就是意义了。

2.1. 创建一个UIApplication?

UIApplication 存在一个接收 Application 的构造函数，那么，我们能够创建出一个UIApplication吗？

public Result Execute(ExternalCommandData commandData, ref string message, ElementSet elements)
{
    UIApplication uiApp = new UIApplication(commandData.Application.Application);

    TaskDialog.Show("UIAPP", $"{uiApp.LoadedApplications.Size}");

    return Result.Succeeded;
}

显然是可以的，但这又做的目的是啥呢。

P.S. 在Revit2016以及更早，还有一种错误的创建方式。

// 该构造函数于2017版本移除，此时会报错
Autodesk.Revit.ApplicationServices.Application app = new Autodesk.Revit.ApplicationServices.Application();
Autodesk.Revit.UI.UIApplication uiApp = new Autodesk.Revit.UI.UIApplication(app);
TaskDialog.Show("UIAPP", $"{uiApp.LoadedApplications.Size}");

---

三、Application 与 ControlledApplication

Application 与 ControlledApplication 都是 Autodesk.Revit.ApplicationServices 命名空间下的类，该命名空间下就这2个类，还有2枚举，都是没啥用的，一个显示当前Revit的语言（LanguageType ），一个表示当前Revit产品分类（ProductType ）。

同带UI的，这俩之间有相当一部分属性、方法、事件相同。

与UI不同的是，这里就涉及到项目、文档的修改了，大部分事件与此有关。

P.S. 类成员有点多，建议直接复制，丢给GPT，让它解释。

3.1. ControlledApplication

ControlledApplication 成员较少，除了事件较为全面要看看，方法/属性上值得注意的就2点：

• 共享属性
• 失败处理程序

讲到共享属性，就得讲可扩展存储了；讲失败处理程序，就得提那些个警告/错误 的触发与处理了。后面再说、

以我这摸鱼写的样子，什么时候是个头哇(⓿_⓿)

话说今天法环DLC发售了，传火传火，赐福赐福！！

事件：

事件也简单，扫一眼就那么几类：Revit程序初始化时，文档的增删改、开关存，打印前后，文件/族/链接资源的导入导出，失败通知，还有其它几个杂鱼，无了，就这么简单。

还有上面需要注意的吗，我看看…没了，就这些。

3.2. Application

比起ControlledApp多了不少，定睛一看：

• 方法上：多了创建族文档，创建文档，打开IFC文档，和其它看起来没啥用的
• 属性上：Documents，Create，其它的太长不看
• 事件上：视图导出(ed/ing)，共享状态变更，有啥用？不知道，没啥用。

啪啪啪，鼓掌，学会了，下一个。

四、Autodesk.Revit.Creation.Application

看Application看得我脑壳疼了都，这又是个啥玩意儿？

哦，一个用于创建 其它对象实例 的这么个类，没有构造函数，从UIApplication.Application.Creat中拿到。里头全是Newxxx方法。

那么，都New了些上面东西呢，好像看不懂唉，不知道干啥用的。

这就对了，开发时，某些方法需要奇奇怪怪的参数，这些个参数又没有构造函数时，说不准就可以在这里New出来。

好了，我们发现Creation下也没几个类呐、

---

结尾

UI都还没写完，下篇写啥，Events总结要不要来一个，Creation就一点点也想先写了，UI上还有预览界面和可停靠界面，AdWindows.dll往后稍稍。

还是写UI吧，就一丢丢了