Thursday, March 25, 2010

Revit API 2011: User Interface Changes/Improvements

(Part of our Revit API 2011 Series)
The 2011 API has a variety of interesting enhancements in the ribbon user interface – making it possible to build applications which more closely match the look, feel and capability of native Revit commands (aside from being relegated to the Add-Ins tab).

In 2010, the first Ribbon release, the API already had access to controls such as:

  • RibbonPanel
  • Pushbutton
  • Stacked Pushbutton
  • Pulldown Button

What is new in 2011 are a wide variety of new controls and constructs in the ribbon:

  • Combo Box
  • SplitButton (like a Pulldown button, but it has a default action)
  • TextBox
  • SlideOut

I created the following sample ExternalApplication which illustrates the different controls now possible:

Figure 1
Figure 1

If the user has added a SlideOut to the RibbonPanel, any additional controls will be only available on the SlideOut panel – available when you click the down-arrow to the right of the Ribbon Panel name.

Figure 2

Note that the slide out is “pinnable” to keep it open. That, combined with the ability to “tear off” the panel (also available in 2010) – makes for some interesting capabilities.

Going Deeper

Beyond the new controls, there are some new capabilities a level deeper:

  • Images on Pulldown buttons
  • Tooltips and Long Descriptions – to provide more detail on how to run your command.
  • Tooltip Images – to provide a graphic for your command – a picture is worth a thousand words


General Availability

Another new feature in 2011 is the ability to have an interface (IExternalCommandAvailability) which implements a check for whether your command should be enabled or disabled.

This is useful if your command should only be available in a 3D View, or only if the user has filled out the setup/preferences dialog, or only if they user has pre-selected a certain category of elements. The command will be automatically enabled/disabled as appropriate.

The TaskDialog

One of the new core capabilities of Windows (starting in Vista) is an upgrade for the venerable MessageBox – called the TaskDialog. Revit now provides the TaskDialog on a platform-independent basis. The TaskDialog has all of the capabilities of the old MessageBox, but also has new and interesting capabilities like:

  • Expanded Content (visible when the user expands it)
  • As many or few buttons as you’d like (Yes/No/Close/Retry/About/etc).
  • Up to 4 Command Link buttons with supporting text.
  • Checkbox with verification text
  • Footer text

Here’s an example showing a bit of everything:


The code required to do a TaskDialog is pretty straightforward:

TaskDialog td = new TaskDialog("Hello World");
td.MainContent = "This is main content";
td.ExtendedContent = “This is shown on demand”;

// or, alternatively – you can use a static method, if you only need the basics:
TaskDialog.Show("The Title", "The Main Instruction");


Revit 2011 provides a good number of new controls and capabilities – it’s nice to be able to make applications that have the feel of native Revit commands.

No comments: