Download Revit 2013 API Developer Guide - The Building Coder

Managing Changes
Updaters need to be able to handle complex issues that may arise from their use, possibly reconciling subsequent changes to an element. Elements modified by an updater
may change by the time the updater is next invoked, and those changes may impact information modified by the updater. For example, the element may be explicitly
edited by the user, or implicitly edited due to propagated changes triggered by a regeneration.
It is also possible that the same element may be modified by another updater, possibly even within the same transaction. Although explicit changes of exactly the same
data is tracked and prohibited, indirect or propagated changes are still possible. Perhaps the most complex case is that an element could be changed by the user and/or the
same updater in different versions of the file. After the user reloads the latest or saves to central, the modified target element will be brought from the other file and the
updater will need to reconcile changes.
It is also important to realize that when a document synchs with the central file, the ElementId of elements may be affected. If new elements have been added to two
versions of the same file and the same ElementId is used in both places, this will be reconciled when the files are synched to the central database. For this reason, when
using updaters to cross-reference one element in another element, they should use Element.UniqueId which is guaranteed to be unique.
Another issue to consider is if an updater attaches some data (i.e. as a parameter) to an element, it not only must be sure to maintain that information in the element to
which it was added, but also to reconcile data in cases when that element is duplicated via copy/paste or group propagation. For example, if an updater adds a parameter
"Total weight of rebar" to a rebar host, that parameter and its value will be copied to the duplicated rebar host even though the rebar itself may be not copied with the
host. In this case the updater needs to ensure the parameter value is reset in the newly copied rebar host.
Registering Updaters
Updaters must be registered in order to be notified of changes to the model. The application level UpdaterRegistry class provides the ability to register/unregister and
manipulate the options set for Updaters. Updaters may be registered from any API callback. In order to use the UpdaterRegistry functionality, the Revit add-in must be
registered in a manifest file and the Id returned by UpdaterId.GetAddInId() for any Updater (obtained from GetUpdaterId()) must match the AddInId field in the add-in's
manifest file. An add-in cannot add, remove, or modify Updaters that do not belong to it.
Triggers
In addition to calling the UpdaterRegistry.RegisterUpdater() method, Updaters should add one or more update triggers via the AddTrigger() methods. These triggers
indicate to the UpdaterRegistry what events should trigger the Updaters Execute() method to run. They can be set application-wide, or can apply to changes made in a
specific document. Update triggers are specified by pairing a change scope and a change type.
The change scope is one of two things:
• An explicit list of element Ids in a document - only changes happening to those elements will trigger the Updater
• An implicit list of elements communicated via an ElementFilter - every changed element will be run against the filter, and if any pass, the Updater is triggered
There are several options available for change type. ChangeTypes are obtained from static methods on the Element class.
• Element addition - via Element.GetChangeTypeElementAddition()
• Element deletion - via Element.GetChangeTypeElementDeletion()
• Change of element geometry (shape or position) - via Element.GetChangeTypeGeometry()
• Changing value of a specific parameter - via Element.GetChangeTypeParameter()
• Any change of element - via Element.GetChangeTypeAny().
Note that geometry changes are triggered due to potentially many causes, like a change of element type, modification of properties and parameters, move and rotate, or
changes imposed on the element from other modified elements during regeneration.
Also note that the last option, any change of element, only triggers the Updater for modifications of pre-existing elements, and does not trigger the Updater for newly
added or deleted elements. Additionally, when using this trigger for an instance, only certain modifications to its type will trigger the Updater. Changes that affect the
instance itself, such as modification of the instance's geometry, will trigger the Updater. However, changes that do not modify the instance directly and do not result in any
discernable change to the instance, such as changes to text parameters, will not trigger the Updater for the instance. To trigger based on these changes, the Type must also
be included in the trigger's change scope.
Order of Execution
The primary way that Revit sorts multiple Updaters to execute in the correct order is by looking at the ChangePriority returned by a given Updater. An Updater reporting a
priority for a more fundamental set of elements (e.g. GridsLevelsReferencePlanes) will execute prior to Updaters reporting a priority for elements driven by these
fundamental elements (e.g. Annotations). Reporting a proper change priority for the elements which your Updater modifies benefits users of your application: Revit is less
likely to have to execute the Updater a second time due to changes made by another Updater.
For Updaters which report the same change priority, execution is ordered based on a sorting of UpdaterId. The method UpdaterRegistry.SetExecutionOrder() allows you set
the execution order between any two registered Updaters (even updaters registered by other API add-ins) so long as your code knows the ids of the two Updaters.
Exposure to End-User
When updaters work as they should, they are transparent to the user. In some special cases though, Revit will display a warning to the user concerning a 3rd party updater.
Such messages will use the value of the GetUpdaterName() method to refer to the updater.
Updater not installed
If a document is modified by a non-optional updater and later loaded when that updater is not installed, a task dialog similar to the following is displayed: