Building Coder（Revit 二次开发） - 元素层级事件（上）

Building Coder 链接：http://thebuildingcoder.typepad.com/blog/2010/04/element-level-events.html#2

Revit 二次开发论坛链接：http://revit.5d6d.com/viewthread.php?tid=1316&extra=

个人认为对元素层级事件的开放是 Revit API 最重要的新特性之一。该特性允许应用程序对 Revit 数据库的改变（包括对特定元素的更改）进行响应。
实际上 Revit 2011 API 为此提供了两种机制：
1. 元素改变事件（Elements Changed Event）
2. 动态模型更新（Dynamic Model Update）

元素改变事件
在每次事务（Transaction）被提交（Committed）、撤消（Undone）或者重新执行（Redone）之后，Revit 会触发一个新的 Application.DocumentChanged 事件。
这是一个只读的事件，设计目的是允许应用程序捕捉 Revit 数据库的变化，并同步需要的外部数据。如果想要根据元素的变化更新 Revit 数据库本身的话，则应该
使用之后会介绍的动态模型更新框架。

事件处理器（Event Handler）会接收到一个 DocumentChangedEventArgs 对象，包含被执行的操作、涉及的文档和元素等信息。下面是其中一些常用的属性和方法：
1. Operation: 触发事件的操作
2. GetDocument: 事件涉及的文档对象
3. GetAddedElementIds: 文档中新增的元素ID集合
4. GetDeletedElementIds: 文档中删除的元素ID集合
5. GetModifiedElementIds: 文档中被修改的元素ID集合
6. GetTransactionNames: 事件所在的事务（可能多个）名称集合

SDK 例程 ChangesMonitor 展示了如何使用元素改变事件。该例程使用一个数据表来记录 Revit 数据库的所有变化，并将其显示在一个无模式对话框 ChangesInformationForm
中。该源码项目包含两个主要类：
1. ChangesMonitor.cs
   实现了一个外部程序（ExternalApplication）和一个外部命令（External Command）。外部程序会创建一个无模式对话框，并在其 OnStartup() 方法中注册
   Application.DocumentChanged 事件。外部命令会在对话框被关闭时再重新打开它。

    public Result OnStartup(
      UIControlledApplication application )
    {
      // initialize member variables.
    
      m_CtrlApp = application.ControlledApplication;
      m_ChangesInfoTable = CreateChangeInfoTable();
    
      m_InfoForm = new ChangesInformationForm(
        ChangesInfoTable );
    
      // 注册事件
    
      m_CtrlApp.DocumentChanged += new EventHandler<
        Autodesk.Revit.DB.Events.DocumentChangedEventArgs>(
        CtrlApp_DocumentChanged );
    
      // Form.Show() 无模式显示；
      // Form.ShowDialog() 模式显示
    
      m_InfoForm.Show();
    
      return Result.Succeeded;
    }

  
2. ChangesInfoForm.cs
   实现了一个包含 DataGridView 的窗口，用于显示 Revit 数据库的所有改变。

动态模型更新
由于 Application.DocumentChangedEvent 事件是只读的，所以我们不能在其事件响应函数中对其涉及的 Revit 数据库进行修改。而想要实现这一目标，就必须使用更
强大的动态模型更新机制。下面是 Revit API 帮助文档中对后者的描述：

动态模型更新机制允许程序在响应模型的变化时对 Revit 数据库进行修改。该机制是通过若干个更新器（Updater）来实现的。更新器接口允许程序对指定范围的模型
变化进行监听。为了将一个更新器注册到合适范围的 Revit 数据变化，需要为更新器指定若干个更新触发器，而后者又是“变化范围”和“变化类型”的组合。变化范围既
可以是一组指定的元素ID，也可以是由一个元素过滤器（ElementFilter）限制的元素集合。变化类性则由一组可能的变化构成，包括元素的添加、删除；或者是几何信息、
参数以及其它任何有效的元素属性的改变。关于动态模型更新，Revit API 开发指南的第25章有更详细的说明。

需要强调的是：动态模型更新允许程序在同一个事务中捕捉模型更新、并针对更新对 Revit 数据库进行进一步的改变。
由于可能同时存在多个更新器，所以某个更新器所执行的修改可能会导致其它的更新器被触发。所在使用时需要特别注意执行顺序（译者注：比方说不要出现死循环）。