Dynamic Model Update

Dynamic model update offers the ability for a Revit API application to modify the Revit model as a reaction to changes happening in the model. This facility is offered through implementation of updaters. The updater interface offers the ability to implement a method that is informed of the scope of changes that triggered the update.

In order to “subscribe” an updater to the right set of changes, the updater should be assigned one or more update triggers. Update triggers are combinations of “Change Scope” and “Change Type”. Change Scope may be either an explicit list of element ids in a document, or an implicit list of elements communicated via an ElementFilter. Change Type represents one of an available list of possible changes, including element addition, deletion, and modification of geometry, parameters, or any property of the element.

For a more detailed introduction to the Dynamic Model Update capabilities, consult the “Introduction to Dynamic Model Update” document in the SDK.

Elements changed event

The new event

  • Application.DocumentChanged

is raised after every transaction gets committed, undone, or redone. This is a readonly event, designed to allow you to keep external data in synch with the state of the Revit database. To update the Revit database in response to changes in elements, use the Dynamic Model Update framework.

Failure API

There are two capabilities offered by the new failure API:

  1. The ability to define and post failures from within API code when a user-visible problem has occurred.
  2. The ability to respond to failures posted by Revit and by API code through code in your application.

This section offers a high level overview of both capabilities; more detail about the failures API is provided in the “Failure API” document in the Revit API help file.

As a part of exposing these new capabilities, all overloads accepting “PostedErrors” have been removed from the API.

Failure posting

If you are using the failure posting mechanism to report your problem, all you need to do is:

  1. If you are creating a new failure not already existing in Revit, define the new failure and register it in the FailureDefinitionRegistry during the OnStartup() call of your ExternalApplication (new failures must be registered at Revit startup)
  2. Find the failure definition id, either from the BuiltInFailures classes or from your pre-registered custom failure using the class related to FailureDefinition
  3. Post a failure to a document that has a problem – using the classes related to FailureMessage to set options and details related to the failure

Failure handling

Normally posted failures are processed by Revit’s standard failure resolution UI at the end of transaction. The user is presented information and options in the UI to deal with the failures.

However, if your operation (or set of operations) on the document requires some special treatment for certain errors (or even all possible errors), you can customize failure resolution. Custom failure resolution can be supplied:

  • For a given transaction using the interface IFailuresPreprocessor.
  • For all possible errors using the FailuresProcessing event.

Finally, the API offers the ability to completely replace the standard failure processing user interface using the interface IFailuresProcessor.

Select element(s), point(s) on element(s), face(s) or edge(s)

  • Selection.PickObject
  • Selection.PickObjects

New methods have been added to prompt the user to select items from the Revit model. When using the new selection methods from your application you can:

  • Allow users to make one or multiple selections
  • Allow users to make multiple selections via box select
  • Provide a custom status prompt to direct the user what to select
  • Provide a custom selection filter (Autodesk.Revit.UI.ISelectionFilter) to accept only those items which your application supports
  • Provide a list of preselected items which will be selected and highlighted when the selection activity starts
  • Reference(Element) – This new constructor allows you to obtain a Reference for an Element; it can be useful when adding preselected elements to the PickObjects() call.

Pick point on the view active workplane

  • Selection.PickPoint()

New methods have been added to prompt the user to pick a point on the view active workplane. When using these methods you have the option of overriding the user’s default snap settings and providing a custom status prompt to direct the user what to pick. The method returns an XYZ location corresponding to the user’s pick.

For 2D and 3D views, you can set the active workplane via the new setter property for View.SketchPlane. This allows you to control the plane used for calls to the PickPoint() method.

For 2D views where the active workplane cannot be changed, such as drafting and sheet views, the method picks a point in the default coordinate system of the view.

Additional options for Ribbon customization

There are new Ribbon components supported via the Ribbon API:

  • SplitButton – a pulldown button with a default pushbutton attached
  • RadioGroup – a set of ToggleButtons, where only one of the set can be active at a time
  • ComboBox – a pulldown containing a set of selectable items, which can be grouped optionally
  • TextBox – an input field for users to enter text
  • SlideOut panel – an extra panel can optionally slide down from a Ribbon panel; this panel can contain any of the standard Ribbon components

For ComboBox and TextBox, events are included; these events call your API code when the component is changed by the user.

The new property:

  • RibbonItem.Visible

provides control over whether a particular item is visible.

The new properties:

  • RibbonItem.LongDescription
  • RibbonItem.ToolTipImage

allow you to set up an extended tooltip for the Ribbon item.  This tooltip can display a longer set of text, and/or a single image.

The new property:

  • PushButton.AvailabilityClassName

allows assignment of an availability class to controlled whether or not the button is available, similar to the option provided for ExternalCommands registered by manifest.

There is also a new option supported for PulldownButton – a separator can now be added between buttons this component.

There is also a new option to add custom panels to the Analyze tab in Revit as well as the Add-Ins tab, via a new overload of Application.CreateRibbonPanel().

As a result of these enhancements, some pre-existing APIs have changed:

  • RibbonPanel.AddButton() has been replaced with RibbonPanel.AddItem()
  • RibbonPanel.AddStackedButtons() overloads have been replaced with RibbonPanel.AddStackedItems() overloads
  • Property RibbonPanel.Items has been replaced with method RibbonPanel.GetItems()
  • Property PulldownButton.Items has been replaced with method PulldownButton.GetItems()
  • Methods RibbonPanel.AddPushButton() and RibbonPanel.AddPulldownButton() have been removed. Use RibbonPanel.AddItem() for this operation.
  • RibbonPanel.AddToPulldown() has been removed. Use PulldownButton.AddItem() for this operation.
  • PulldownButton.AddPushButton() has been removed. Use PulldownButton.AddItem() for this operation.

Create and display Revit-style Task Dialogs

The API now offers the ability to create and display Revit-style Task Dialogs. It is intended to provide capabilities similar to System.Windows.Forms.MessageBox with a Revit look-and-feel.

Construct an instance of the class:

  • Autodesk.Revit.UI.TaskDialog

and use the members of that class to set the instructions, detailed text, icons, buttons and command links to be displayed in the task dialog. Then display the dialog using the Show() method. After the user responds to the dialog by clicking one of the buttons or links, the Show() method returns an identifier indicating the user’s preferred choice.

There are also shortcut static Show() methods on this class providing a quick way to show simple task dialogs.

Idling event

The new event

  • UIApplication.Idling

is raised when it is safe for the API application to access the active document between user interactions. The event is raised only when the Revit UI is in a state where the user could successfully click on an API command button. The event allows changes to a document if a new transaction is opened.

Because this event is invoked between user actions in the Revit UI, if the handler for this event requires a significant amount of processing time, users will perceive a slowdown in the responsiveness of Revit. If the execution for updates can be safely split across multiple calls to this event, the user perception of Revit responsiveness will be improved.

You can also find this in “Revit Platform API Changes and Additions” file if you install the Revit software development kit.