Revit 2010 Ribbon API

I am currently sitting in Stockholm, preparing a visit to a Revit developer here and enjoying the wonderful Swedish nature in May. On Saturday I cut a couple of cubic meters of beautiful birch wood for heating with my friend Alexander in Huddinge, and on Sunday we went together with another class mate Lasse for a walk in the woods and around the lakes and marshes in Roslagen north of Stockholm, specifically to the three lakes Stora Harsjön, Lilla Harsjön and Tärnan, where we used to go camping on the weekends as school boys thirty-five years ago. We saw lots of rare birds and plants and enjoyed the wonderful clear blue Scandinavian air and sky and stillness, so unlike anything you can see and feel in central Europe. Now I am back to setting up my development system again on my temporary replacement computer, and getting ready for the training I am giving in the next few days.

The topic of accessing and modifying the Revit ribbon user interface was addressed by a comment from Jake and the ensuing discussion. Here, we will just discuss the basic Revit ribbon API functionality.

Revit 2010 has a completely new look and feel due to the ribbon based user interface, familiar to many from the Microsoft Office and AutoCAD 2009 and 2010 products. The ribbon interface simplifies the usage for new users and reacts to the design context to provide immediate access to suitable functionality based on the current modelling requirements. Unlike AutoCAD based products, this change is not optional. There is no way to turn this off and switch back to the old UI.

The Revit API has been extended in order to enable Revit external applications to make use of the ribbon. Here is an overview of the Revit 2010 ribbon API, which was also discussed in the recent Revit programming webcast, and a few related questions that cropped up.

The ribbon contains a number of tabs, which are automatically activated depending on the current design context. This is helpful both for new users to discover relevant commands and for experienced users to have convenient access to them. Each tab can contain any number of panels, which in turn can host various user interface widgets.

All external application and external command related user interface items are located in the Add-Ins tab. This tab is displayed as soon as an external application or command is added to the Revit.ini file. External commands are listed under the 'External Tools' button. External applications can create their own ribbon panels and populate them with push buttons and pull-down buttons in either a normal, single or stacked fashion with the option of two or three layers.

Existing external application will need to migrate their old toolbar or menu based user interface to the ribbon. The ribbon API is the only GUI customization API in Revit 2010. It is quite straight-forward to use. Although the ribbon is based on the Windows Presentation Foundation WPF, no WPF knowledge is needed to make use of the Revit ribbon API.

The API enables you to add your custom ribbon panels and populate them with various types of buttons. The buttons can be push or pull-down ones, in a single row or in a stacked layout with two or three rows. Unfortunately, you cannot currently create your own separate ribbon tabs.

In addition to the programming aspect, the Revit SDK also includes documentation with guidelines for designing your custom ribbon and icons. This is to ensure that your application integrates well with the standard Revit UI. The documents are located in the SDK folder and also explain the terminology used in the ribbon API:

• Ribbon design guidelines.pdf
• Autodesk Icon Guidelines.pdf

The new ribbon related classes in Revit are:

• RibbonPanel, a ribbon panel in the Add-Ins tab containing ribbon items.
• RibbonItem, a button, push or pull-down.
• PushButton and PushButtonData to manage push button information.
• PulldownButton and PulldownButtonData to manage pull-down button information

The usage of the ribbon API is demonstrated by the Ribbon SDK sample application, which is an external application creating its own ribbon panel and showing how to create the various types of ribbon items programmatically. It adds the following elements to the Add-Ins tab:

• Two add-in application ribbon panels.
• A push button 'Create Wall'.
• A three-layered stacked button.
• A pull-down button 'Move Walls'.
• Push buttons used to display add-in panel info.
• Separators.
• Tooltips.

This is what the result looks like in the user interface:

The figure shows the two ribbon panels called 'Ribbon Sample' and 'Add-in Panel Info'. The first panel, on the left, has one push button called 'Create Wall', and a three-layered stacked button next to it showing 'Delete Last Wall' at the top. Notice that the third stacked button, 'Move Walls', is a pull-down button.  You can also add tooltips to and separators between buttons.

Here is the relevant part of the code, the method CreateRibbons, which is called from the external application OnStartup method:

private void CreateRibbons(
  ControlledApplication application )
{
  // application path
  string pathRibbon
    = GetType().Assembly.Location;
 
  string pathAddIn
    = pathRibbon.Replace("Ribbon.dll",
      "AddInCommands.dll");
 
  string bitmapFolder
    = Path.GetDirectoryName(pathRibbon);
 
  # region create RibbonPanel with PushButtons, 'create wall' and 'delete walls'
 
  string firstPanelName = "PushButtons";
 
  RibbonPanel ribbonPanelPushButtons
    = application.CreateRibbonPanel(
      firstPanelName );
 
  PushButton pushButtonCreateWall
    = ribbonPanelPushButtons.AddPushButton(
    "createWall", "Create Wall", pathAddIn,
    "Revit.SDK.Samples.Ribbon.CS.CreateWall" );
 
  pushButtonCreateWall.ToolTip
    = "Create a wall on level 1.";
 
  pushButtonCreateWall.LargeImage
    = new BitmapImage(
      new Uri( Path.Combine( bitmapFolder,
        "CreateWall.bmp"), UriKind.Absolute ) );
 
  ribbonPanelPushButtons.AddSeparator();
 
  PushButton pushButtonDeleteWalls
    = ribbonPanelPushButtons.AddPushButton(
    "deleteWalls", "Delete Walls", pathAddIn,
    "Revit.SDK.Samples.Ribbon.CS.DeleteWalls" );
 
  pushButtonDeleteWalls.ToolTip
    = "Delete all the walls in active document.";
 
  pushButtonDeleteWalls.LargeImage
    = new BitmapImage(
      new Uri( Path.Combine( bitmapFolder,
        "DeleteWalls.bmp"), UriKind.Absolute ) );
 
  # endregion
 
  # region create RibbonPanel with a pulldownButton which contains two MenuItems, 'move walls'
 
  string secondPanelName = "PulldownButtons";
 
  RibbonPanel ribbonPanelPulldowns
    = application.CreateRibbonPanel(
      secondPanelName );
 
  PulldownButton pulldownMoveWall
    = ribbonPanelPulldowns.AddPulldownButton(
      "moveWall", "Move Walls");
 
  pulldownMoveWall.ToolTip
    = "Move all the walls in X or Y direction";
 
  pulldownMoveWall.LargeImage
    = new BitmapImage(
      new Uri( Path.Combine(
        bitmapFolder, "MoveWall.bmp" ),
        UriKind.Absolute ) );
 
  RibbonMenuItem moveX
    = pulldownMoveWall.AddItem(
    "X Direction", pathAddIn,
    "Revit.SDK.Samples.Ribbon.CS.XMoveWalls" );
 
  moveX.ToolTip
    = "move all walls 10 feet in X direction.";
 
  RibbonMenuItem moveY
    = pulldownMoveWall.AddItem(
    "Y Direction", pathAddIn,
    "Revit.SDK.Samples.Ribbon.CS.YMoveWalls" );
 
  moveY.ToolTip
    = "move all walls 10 feet in Y direction.";
 
  # endregion
 
  # region create RibbonPanel with "Add-in Panel Info" button
 
  string thirdPanelName
    = "Add-in Panel Info";
 
  RibbonPanel ribbonPanelOutputlInfo
    = application.CreateRibbonPanel(
      thirdPanelName );
 
  PushButton pushButtonOutputlInfo
    = ribbonPanelOutputlInfo.AddPushButton(
    "outputlInfo",
    "Output Add-in Panel Info",
    pathAddIn,
    "Revit.SDK.Samples.Ribbon.CS.OutputPanelInfo" );
 
  pushButtonOutputlInfo.ToolTip
    = "Output info of all the Add-In RibbonPanels.";
 
  pushButtonOutputlInfo.LargeImage
    = new BitmapImage(
      new Uri(Path.Combine(
        bitmapFolder,
        "OutputAddInPanelInfo.bmp" ),
        UriKind.Absolute ) );
 
  # endregion
}

Here is another question regarding the ribbon user interface and its customisation facilities:

User Interface Customisation

Question: Is there a way to customize the ribbon toolbars in Revit 2010? There is no right-click menu item for 'Customize' like in AutoCAD Architecture.

Answer: The only customization possibility I see in the user interface is provided by the 'User Interface' button in the View tab. This provides control of the visibility of the navigation bar, project browser, status bar, recent files list and project browser settings:

As stated above, the Revit API allows applications to add UI elements to the ribbon, but only in the Add-Ins tab, and only certain types of ribbon items, as illustrated by the Ribbon SDK sample.

Many thanks to my colleagues Adam Nagy and Saikat Bhattacharya for providing the basis for this summary.

Comments

[anthony]

The rumours are spreading that you can turn the new UI off and have the old one, If only I knew how

See:
http://architechure.blogspot.com/2009/06/nein-nein-nein-nein-nein-nein-nein.html

And
http://forums.augi.com/showthread.php?t=92112&page=20

[Jeremy Tammik]

Dear Anthony,

Thank you for the pointers. I was not aware of this possibility before, so I cannot provide any additional advice. Very interesting, however.

Cheers, Jeremy.

[Martino Salvato]

Dear Mr. Tammik, thanks for this post, it was very usefull for my job...
I have only one question to ask you. Could be possible to add an horizontal separator in a PullDownButton object, for example in yours pulldownMoveWall object?

thanks again
Martino

[Jeremy Tammik]

Dear Martino,

Looking through the Revit ribbon bar, I cannot see a single example of such a horizontal separator. Therefore, I would say that even if you could insert such a thing, I would recommend you not to do so. But of course the API does not provide this possibility anyway. Basically, the example above demonstrates everything that can be done. The AddSeparator method adds a separator, and it is vertical. To my knowledge, horizontal separators do not exist in the ribbon.

Cheers, Jeremy.

[Martino Salvato]

Dear Mr. Tammik, thanks for your answer. I post you this question because I saw the Revit Ribbon pulldown button relative to the add new wall, for example, where there is also an horizontal separator, so I thought that it was also possible with the API.
But if it doesn't I will find another way...
Thanks
Cheers, Martino.

[NAyche]

Jeremy,

I have the same question. There is a horizontal separator button in a PullDownButton. See Home tab, Component pulldownbutton or Model Group pulldownbutton.

How can we do this?

Regards,
Nadim

[Jeremy Tammik]

Dear Nadim,

As I said above to Martino, as far as I know, the API currently does not provide this possibility. Basically, the example above demonstrates everything that can be done with ribbons through the API. The AddSeparator method adds a separator, but only a vertical one.

Cheers, Jeremy.

[Jamie Johnson]

Here's a good question. Does the API support a method to add an Extended tool tip? The regular text tool tip is nice, but the Interface shows it's own commands using an extended tool tip for the user that contains a help file like image and text snippit. Can this be done in 2010?

[Jeremy Tammik]

Dear Jamie,

Sorry, I have not seen anything in the Revit API supporting that.

Cheers, Jeremy.

[pnavarra]

Hi Jeremy,
Iv'e got problems when I create a PulldownButtonData.
It is grayed out...do you know why.
When I create separated PushButtons, it works....

Cheers!

[Jeremy Tammik]

Dear Pierre,

Are you talking about Revit 2010 or 2011? In 2011, I have not really had a look at that area yet, so I don't know what the problem might be. In 2010, there has been some discussion on the topic of greyed out commands now and then, which we summarised in

http://thebuildingcoder.typepad.com/blog/2009/06/rfa-version-grey-commands-family-context-and-rdb-link.html#2

Jean-François Breton added some explanations to the comments there as well.

Furthermore, Mr. Navarra already asked this question repeatedly:

http://thebuildingcoder.typepad.com/blog/2009/10/revit-2010-web-update-2.html

http://thebuildingcoder.typepad.com/blog/2009/04/addin-keyboard-shortcut.html

Are you still stuck with that? How terrible!

Cheers, Jeremy.

[Marc Goldman]

Is it possible to add Ribbon elements to an area other than the AddIns area?

For example, can I add a DropDown or similar simple UI element to the INSERT or HOME ribbon?

Thanks,

MarcG

[Jeremy Tammik]

Dear Marc,

Thank you for your query. Please do not double post queries to both the blog and the ADN DevHelp Online, since that causes extra work for us. As an ADN member, I would recommend that you use ADN DevHelp Online, since that guarantees you an answer from either me or one of my colleagues in the AEC workgroup. It also assigns a case number which makes it easier to coordinate with our internal knowledgebase and other databases.

Regarding your question, add-ins are indeed restricted to adding controls to two of the ribbon tabs: the Add-Ins and the Analyse tabs. Here are some quotes from the developer guide "Revit 2011 API Developer Guide.pdf" regarding this:

- 3.2.1 Loading and Running External Commands: You can add External Commands to the External Tools Panel under the External Tools menu-button, or as a custom ribbon panel on the Add-Ins tab.

- 3.8 Ribbon Panels and Controls: Custom ribbon panels will appear on the Add-Ins tab in Revit by default, but they can also be added to the Analyze tab.

- 3.8.2 Ribbon Panel: Custom ribbon panels can be added to the Add-Ins tab (the default) or the Analyze tab.

To add a panel to the Analyze tab, use the CreateRibbonPanel method overload taking an additional Tab enumeration argument.

Cheers, Jeremy.

[Hardik Jadeja]

Hi Jeremy,

I had developed a ribbon panel under Add-Ins Tab. which is used to Export the current File to IFC Format. (Overriding Default IFC Export Functionality). My Problem is, when I open and Advance Sample from Revit Start-Up Menu, My Add-Ins gets disabled. I am using .Net 4.0 and Revit 2012. Could you pls guide me on possible solutions.

Thanks,

Hardik

[Hardik Jadeja]

Hi Jeremy,

To explain the above scenario....when I open any file and goes to View Menu -> 3D View -> Camera and creates View using Camera....at that time Revit disables the Add-Ins Panel and My Add-Ins gets disabled.....while I can still export the same view using IFC Option from Menu. Could you please help in this.

Thanxs

Hardik

[Hardik Jadeja]

Hi Jeremy,

still waiting for your response. If you are able to guide me on this it would be great. Thank you

[Jeremy Tammik]

Dear Hardik,

There is never any guarantee whatsoever that I will ever respond to any comment.

However, in this case, I already have, several times :-)

The default view of the advanced sample is in perspective mode. All add-ins are disabled in persepctive views.

There are a few conditions where the Revit API framework always prevents commands from being available:

- Another Revit command is active.

- The active view is in perspective mode, or when the view is a Legend, Walkthrough, Material Takeoffs, Drawings Lists, View Lists, Note Blocks, View Lists, etc.

- The user is editing an in-place family.

I mentioned this fact a couple of times in the past, most lately a while back, in May 2010, in

http://thebuildingcoder.typepad.com/blog/2010/05/addin-visibility-mode.html

Cheers, Jeremy.

[Hardik Jadeja]

Dear Jeremy,

Thanks for your reply. Its useful.

Cheers, Hardik