The Building Coder

External Command Lister and Adding Ribbon Commands

I have been asked a couple of times how you can integrate multiple Revit add-ins from different sources together into a single ribbon panel.

This topic has also been discussed on the web, e.g. towards the end of whether to install to the add-ins tab or make new ribbon tab, and at Autodesk University, where Jose Guia presented CP3766 – Tying All of Your Revit Add-ins into a Pretty Little Ribbon.

Unfortunately, none of these offer any very useful solution, or show or share any code.

I have a very simple approach to suggest, though, which has been around for several years already:

The RvtSamples SDK application reads a text file listing any number of .NET assemblies defining any number of external commands and generates a ribbon panel populated with buttons to launch them all.

Each entry in that file occupies seven lines specifying a group, menu text, description, large image, small image, .NET assembly path and full name of the external command to launch. Here is the first entry in that file:

  Analysis
  EnergyAnalysis Model
  Demonstrates how to use EnergyAnalysisModel API.
  LargeImage: 
  Image: 
  Z:\...\bin\Debug\EnergyAnalysisModel.dll
  Revit.SDK.Samples.EnergyAnalysisModel.CS.Command

Only the two last lines of the entry are really relevant. Al the rest is decorative, and hopefully informative as well.

In fact, that is the one and only method that I use myself to launch both SDK sample external commands and all The Building Coder sample code.

Furthermore, the text file read by RvtSamples includes support for include files that I implemented back in 2008, similar to the standard C #include pre-processor directive.

The only important information required to populate the RvtSamples text file is the .NET assembly filename of the DLL implementing the external command, and the full external command implementation class name, including its namespace prefix.

Here is the complete EnergyAnalysisModel Revit SDK sample add-in manifest, showing the information corresponding to the RvtSamples.txt entry above:

<?xml version="1.0" encoding="utf-8"?>
<RevitAddIns>
  <AddIn Type="Command">
    <Assembly>EnergyAnalysisModel.dll</Assembly>
    <ClientId>6f559488-4285-40b7-bfca-043bb69ea0a7</ClientId>
    <FullClassName>Revit.SDK.Samples.EnergyAnalysisModel.CS.Command</FullClassName>
    <Text>EnergyAnalysis Model</Text>
    <Description>Demonstrates how to use EnergyAnalysisModel API.</Description>
    <VisibilityMode>AlwaysVisible</VisibilityMode>
    <VendorId>ADSK</VendorId>
    <VendorDescription>Autodesk, www.autodesk.com</VendorDescription>
  </AddIn>
</RevitAddIns>

As you can see, the content of the Assembly and FullClassName tags correspond exactly to the two last lines specified in RvtSamples.txt.

Where can this information be obtained?

Well, the simplest and most direct source would the add-in manifest, if one is available.

To load an external command on its own, the assembly path and implementation class name are listed in the Assembly and FullClassName add-in manifest tags.

Unfortunately, if the add-in you wish to integrate defines an external application to create a custom panel, it may not list all its command names in the manifest file.

Where can they be obtained from then?

Well, several tools exist which can read .NET assemblies and display their contents.

I talked about Reflector way back in the early days of the blog. It since became commercial. Victor Chekalin mentioned using dotPeek, and my colleague Adam added that he uses the ILSpy .NET decompiler and is perfectly happy with that.

Basically, the information is made accessible via the .NET Reflection namespace functionality.

To make things really simple for you non-programmer guys, I went and implemented a little Revit add-in external command which does nothing but list the full class names of all other external commands defined in any assembly you care to point it at.

It can be run in Revit without even opening a document, in zero document state.

It prompts you to select a DLL file, opens it as a .NET assembly, and uses reflection to determine all the classes defined in it derived from the IExternalCommand interface.

These are listed in a read-only dynamically generated resizable form.

Here is the result of pointing it at the simpler DockableDialog sample I published last week:

The code is very simple.

The ExternalCommandLister class is instantiated with a .NET assembly filename and extracts all external command definitions from it like this:

class ExternalCommandLister
{
  string _assembly_filename;
  string[] _external_commmand_class_names;
 
  /// <summary>
  /// Display error message
  /// </summary>
  /// <param name="msg">Message to display</param>
  void ErrorMsg( string msg )
  {
    Debug.WriteLine( "External Command Lister: "
      + msg );
 
    TaskDialog.Show( "External Command Lister",
      msg );
  }
 
  public ExternalCommandLister(
    string assembly_filename )
  {
    _assembly_filename = assembly_filename;
    _external_commmand_class_names = null;
 
    if( !File.Exists( assembly_filename ) )
    {
      throw new ArgumentOutOfRangeException(
        "assembly_filename", "file not found" );
    }
    try
    {
      // No need to load the Revit API assemblies, 
      // because we are ourselves a Revit API add-in 
      // inside of Revit, so they are guaranteed to
      // be present.
 
      //Assembly revit = Assembly.LoadFrom( "C:/Program Files/Autodesk/Revit Architecture 2014/RevitAPI.dll" );
      //string root = "C:/Program Files/Autodesk Revit Architecture 2014/";
      //Assembly adWindows = Assembly.LoadFrom( root + "AdWindows.dll" );
      //Assembly uiFramework = Assembly.LoadFrom( root + "UIFramework.dll" );
      //Assembly revit = Assembly.LoadFrom( root + "RevitAPI.dll" );
 
      // Load the selected assembly into 
      // the current application domain:
 
      Assembly asm = Assembly.LoadFrom(
        assembly_filename );
 
      if( null == asm )
      {
        ErrorMsg( string.Format(
          "Unable to load assembly '{0}'",
          assembly_filename ) );
      }
      else
      {
        IEnumerable<Type> types = asm.GetTypes()
          .Where<Type>( t =>
            null != t.GetInterface(
              "IExternalCommand" ) );
 
        _external_commmand_class_names = types
          .Select<Type,string>( t => t.FullName )
          .ToArray();
      }
    }
    catch( Exception ex )
    {
      ErrorMsg( string.Format(
        "Exception '{0}' processing assembly '{1}'",
        ex.Message, assembly_filename ) );
    }
  }
 
  public string AssemblyFilename
  {
    get
    {
      return Path.GetFileName( _assembly_filename );
    }
  }
 
  public string[] CommandClassnames
  {
    get
    {
      return _external_commmand_class_names;
    }
  }
}

The one single important line is really just

  IEnumerable<Type> types = asm.GetTypes()
    .Where<Type>( t =>
      null != t.GetInterface(
        "IExternalCommand" ) );

It asks the assembly for all the types it defines and extracts the ones derived from IExternalCommand, i.e. the external command implementation classes.

The external command mainline Execute implementation prompts the user to select a DLL file, instantiates an ExternalCommandLister instance, queries the command names and displays them in a form created on the fly like this:

[Transaction( TransactionMode.Manual )]
public class Command : IExternalCommand
{
  /// <summary>
  /// Define the initial .NET assembly folder.
  /// </summary>
  const string _assembly_folder_name
    = "C:\\ProgramData\\Autodesk\\Revit\\Addins\\2014";
 
  /// <summary>
  /// Select a .NET assembly file in the given folder.
  /// </summary>
  /// <param name="folder">Initial folder.</param>
  /// <param name="filename">Selected filename on success.</param>
  /// <returns>Return true if a file was successfully selected.</returns>
  static bool FileSelect(
    string folder,
    out string filename )
  {
    OpenFileDialog dlg = new OpenFileDialog();
    dlg.Title = "Select .NET Assembly or Cancel to Exit";
    dlg.CheckFileExists = true;
    dlg.CheckPathExists = true;
    dlg.InitialDirectory = folder;
    dlg.Filter = ".NET Assembly DLL Files (*.dll)|*.dll";
    bool rc = ( DialogResult.OK == dlg.ShowDialog() );
    filename = dlg.FileName;
    return rc;
  }
 
  void DisplayExternalCommands(
    string filename,
    IWin32Window owner )
  {
    ExternalCommandLister lister
      = new ExternalCommandLister( filename );
 
    string[] a = lister.CommandClassnames;
    int n = a.Length;
 
    System.Windows.Forms.Form form
      = new System.Windows.Forms.Form();
 
    form.Size = new Size( 400, 150 );
 
    form.Text = string.Format(
      "{0} defines {1} external command{2}",
      lister.AssemblyFilename, n,
      ( 1 == n ? "" : "s" ) );
 
    form.FormBorderStyle
      = FormBorderStyle.SizableToolWindow;
 
    System.Windows.Forms.TextBox tb
      = new System.Windows.Forms.TextBox();
 
    tb.Dock = System.Windows.Forms.DockStyle.Fill;
    tb.Location = new System.Drawing.Point( 0, 0 );
    tb.Multiline = true;
    tb.TabIndex = 0;
    tb.WordWrap = false;
    tb.ReadOnly = true;
    tb.Text = string.Join( "\r\n",
      lister.CommandClassnames );
 
    form.Controls.Add( tb );
    form.ShowDialog( owner );
  }
 
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    IWin32Window revit_window
      = new JtWindowHandle(
        ComponentManager.ApplicationWindow );
 
    string filename;
 
    while( FileSelect(
      _assembly_folder_name,
      out filename ) )
    {
      DisplayExternalCommands( filename,
        revit_window );
    }
    return Result.Succeeded;
  }
}

The reason I implemented this as a Revit command instead of a stand-alone command-line console application was simply to be sure that the Revit API assemblies are already present before I try to load the add-in assemblies.

I implemented such a stand-alone console application in the past that loaded RevitAPI.dll itself, but that was a long time ago. Now the number of Revit API assemblies is larger, and other restrictions may have been added as well.

A complex external command may obviously depend on additional dependencies in addition to the Revit API assemblies. In that case, it might be harder or impossible to simply load it as shown above. One option then might be to load the other add-in into Revit first using its own loading mechanism, and then try to access its assembly data.

Another caveat is the ClientId tag in the external add-in manifest. For the simple add-ins that I create, it is hardly used, except for extensible storage access. It might be important for other applications as well, though.

Here is JtExternalCommandLister.zip containing the complete source code, Visual Studio solution and add-in manifest of this external command.

I hope you find this useful and that it helps resolves discussions such as the one pointed to above.

Addendum by Rudolf Honke of Mensch und Maschine acadGraph GmbH:

If different add-ins create custom ribbon panels in the same tab, whichever one of them arrives last will obviously run into a collision attempting to create a tab that already exists.

Worse still: the Revit API provides no method to query the existence of a specific tab. It may be possible using the .NET UI Automation library.

However, you can always attempt to retrieve a tab with a specific name using GetRibbonPanels(tabName). If the tab does not exist, this method will throw an exception.

The two add-ins could therefore safely add their panels to the same tab using the following approach:

public Autodesk.Revit.UI.Result OnStartup(
  UIControlledApplication application )
{
  string tabName = "TBC";
  string panelName = "TBC";
 
  try
  {
    List<RibbonPanel> panels = application
      .GetRibbonPanels( tabName );
  }
  catch
  {
    // Tab "TBC" does not yet exist, 
    // so create new
 
    application.CreateRibbonTab( tabName );
  }
 
  RibbonPanel panel = application
    .CreateRibbonPanel( tabName, panelName );
 
  // Add your buttons here
 
  return Result.Succeeded;
}

In principle, this approach may be regarded as bad coding style, because exceptions are and should remain exceptional.

Since there is no other way to obtain the required information in this case, though, one is left no choice.

Actually an alternative might exist using the .NET UIAutomation library, but such an approach may be awfully slow.

A Simpler Dockable Panel Sample

Here is a very nice little sample on using the new Revit 2014 dockable panels by Håkan Wikemar of AEC, Sweden.

In Håkan's words, it is close to the DockableDialogs SDK sample but easier to follow.

The DockableDialogs SDK sample demonstrates modeless dialog design, external events, and the new dockable dialogs UI API framework.

Håkan's DockableDialog sample described here focuses purely on the dockable panel functionality and nothing else.

One thing to note is that you need to register the panel before it can be displayed, and this needs to happen in a zero document state, i.e. with no project open.

In order for the external application ribbon panel to be accessible at all in zero document state, it needs to implement and register an availability class, and the associated command has to use manual transaction mode, as explained in enabling ribbon items in zero document state.

Once this is done, the panel appears like this:

If you try to register it twice, an exception is thrown, naturally, saying "Cannot register the same dockable pane ID more than once. Parameter name: id".

Once the panel has been registered and a project activated, the commands to show and hide the dockable panel are presented:

Those two commands can happily use read-only transaction mode, since they do not modify the database in any way.

The dockable panel is initially displayed sharing the same floating window as the project browser:

It can be dragged off that pane to its own individual floating window:

Clicking 'Hide' removes it again.

Here is the full source code, which unfortunately sports rather long lines. You can copy to a text editor or view the HTML source to see them in full, or simply download the zip file below:

public class Ribbon : IExternalApplication
{
  public Result OnStartup(
    UIControlledApplication a )
  {
    a.CreateRibbonTab( "AEC LABS" );
 
    RibbonPanel AECPanelDebug
      = a.CreateRibbonPanel( "AEC LABS", "AEC LABS" );
 
    string path = Assembly.GetExecutingAssembly().Location;
 
    #region DockableWindow
    PushButtonData pushButtonRegisterDockableWindow = new PushButtonData( "RegisterDockableWindow", "RegisterDockableWindow", path, "DockableDialog.RegisterDockableWindow" );
    pushButtonRegisterDockableWindow.LargeImage = GetImage( Resources.green.GetHbitmap() );
    pushButtonRegisterDockableWindow.AvailabilityClassName = "DockableDialog.AvailabilityNoOpenDocument";
    PushButtonData pushButtonShowDockableWindow = new PushButtonData( "Show DockableWindow", "Show DockableWindow", path, "DockableDialog.ShowDockableWindow" );
    pushButtonShowDockableWindow.LargeImage = GetImage( Resources.red.GetHbitmap() );
    PushButtonData pushButtonHideDockableWindow = new PushButtonData( "Hide DockableWindow", "Hide DockableWindow", path, "DockableDialog.HideDockableWindow" );
    pushButtonHideDockableWindow.LargeImage = GetImage( Resources.orange.GetHbitmap() );
    //IList<RibbonItem> ribbonpushButtonDockableWindow = AECPanelDebug.AddStackedItems(pushButtonRegisterDockableWindow, pushButtonShowDockableWindow, pushButtonHideDockableWindow);
 
    RibbonItem ri1 = AECPanelDebug.AddItem( pushButtonRegisterDockableWindow );
    RibbonItem ri2 = AECPanelDebug.AddItem( pushButtonShowDockableWindow );
    RibbonItem ri3 = AECPanelDebug.AddItem( pushButtonHideDockableWindow );
    #endregion
 
    return Result.Succeeded;
  }
 
  public Result OnShutdown(
    UIControlledApplication a )
  {
    return Result.Succeeded;
  }
 
  private System.Windows.Media.Imaging.BitmapSource GetImage(
    IntPtr bm )
  {
    System.Windows.Media.Imaging.BitmapSource bmSource
      = System.Windows.Interop.Imaging.CreateBitmapSourceFromHBitmap(
        bm,
        IntPtr.Zero,
        System.Windows.Int32Rect.Empty,
        System.Windows.Media.Imaging.BitmapSizeOptions.FromEmptyOptions() );
 
    return bmSource;
  }
}
 
/// <summary>
/// You can only register a dockable dialog in "Zero doc state"
/// </summary>
public class AvailabilityNoOpenDocument
  : IExternalCommandAvailability
{
  public bool IsCommandAvailable(
    UIApplication a,
    CategorySet b )
  {
    if( a.ActiveUIDocument == null )
    {
      return true;
    }
    return false;
  }
}
 
/// <summary>
/// Register your dockable dialog
/// </summary>
[Transaction( TransactionMode.Manual )]
public class RegisterDockableWindow
  : IExternalCommand
{
  MainPage m_MyDockableWindow = null;
 
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    DockablePaneProviderData data
      = new DockablePaneProviderData();
 
    MainPage MainDockableWindow = new MainPage();
 
    m_MyDockableWindow = MainDockableWindow;
 
    //MainDockableWindow.SetupDockablePane(me);
 
    data.FrameworkElement = MainDockableWindow
      as System.Windows.FrameworkElement;
 
    data.InitialState = new DockablePaneState();
 
    data.InitialState.DockPosition
      = DockPosition.Tabbed;
 
    //DockablePaneId targetPane;
    //if (m_targetGuid == Guid.Empty)
    //    targetPane = null;
    //else targetPane = new DockablePaneId(m_targetGuid);
    //if (m_position == DockPosition.Tabbed)
 
    data.InitialState.TabBehind = DockablePanes
      .BuiltInDockablePanes.ProjectBrowser;
 
    DockablePaneId dpid = new DockablePaneId(
      new Guid( "{D7C963CE-B7CA-426A-8D51-6E8254D21157}" ) );
 
    commandData.Application.RegisterDockablePane(
      dpid, "AEC Dockable Window", MainDockableWindow
      as IDockablePaneProvider );
 
    commandData.Application.ViewActivated
      += new EventHandler<ViewActivatedEventArgs>(
        Application_ViewActivated );
 
    return Result.Succeeded;
  }
 
  void Application_ViewActivated(
    object sender,
    ViewActivatedEventArgs e )
  {
    m_MyDockableWindow.lblProjectName.Content
      = e.Document.ProjectInformation.Name;
  }
}
 
/// <summary>
/// Show dockable dialog
/// </summary>
[Transaction( TransactionMode.ReadOnly )]
public class ShowDockableWindow : IExternalCommand
{
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    DockablePaneId dpid = new DockablePaneId(
      new Guid( "{D7C963CE-B7CA-426A-8D51-6E8254D21157}" ) );
 
    DockablePane dp = commandData.Application
      .GetDockablePane( dpid );
 
    dp.Show();
 
    return Result.Succeeded;
  }
}
 
/// <summary>
/// Hide dockable dialog
/// </summary>
[Transaction( TransactionMode.ReadOnly )]
public class HideDockableWindow : IExternalCommand
{
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    DockablePaneId dpid = new DockablePaneId(
      new Guid( "{D7C963CE-B7CA-426A-8D51-6E8254D21157}" ) );
 
    DockablePane dp = commandData.Application
      .GetDockablePane( dpid );
 
    dp.Hide();
    return Result.Succeeded;
  }
}

In case you overlooked any of the following aspects, here is a list of the functionality demonstrated in the relatively few lines of code above:

• Implementation of an external application and several external commands in the same assembly
• Creation and population of a custom ribbon tab
• Creation and population of a custom ribbon panel with command buttons
• Loading of button images from .NET assembly resources
• Implementation of a command availability class
• Static enabling a command in zero document state
• Dynamic toggling of command availability based on document state

Here is DockableDialog.zip containing the complete source code, Visual Studio solution and add-in manifest of this external application.

Many thanks to Håkan for this nice sample!

Addendum: Guy Robinson of redbolts.com adds to this and says:

I noticed the post on DockablePanes and Håkan's comment about finding the SDK sample confusing. I did too. I've been testing some UI ideas for a new app today and posted a basic version of something similar if interested.

I didn't want a register command on the ribbon and wanted more abstraction. For instance, I didn't want the Page inheriting IDockablePaneProvider.

Therefore, registration is in the external application and uses some extension methods.

It is not perfect; it would require use of the Win32 API to capture the dock hiding/showing state if hidden from the dock itself.

Anyway, anyone interested can have a look at my DockableUITest project on GitHub.

Adding a Button to Existing Ribbon Panel

Here is an interesting user interface contribution from Eduardo Teixeira of Autodesk:

Question: I am building a Revit add-in using the Revit API.

I would like to add a button for it to an existing out-of-the-box Revit ribbon panel using the Revit API in C#.

I could not find any documentation that shows how to do that.

Is it possible at all?

Answer: Yes, this can be done. I am not certain whether it is officially supported, though. You will have to explore on your own a bit.

The official API is limited. You can however also use functionality from the .NET UI Automation library and from the AdWindows.dll .NET assembly included with Revit, similar to the one provided with AutoCAD.

Here are some previous discussion exploring related issues that might help:

• Pimp my ribbon
• Roll a toggle button
• Enable button in zero document state
• Add non-command button to the ribbon

Response: Thanks for the tip. The article that really helped me was the first one you list. I was able to add a button to the existing out-of-the-box Energy Analysis panel under the Analyze tab.

There are just two simple steps required achieve the desired result:

To add a custom button to the Analyze tab in the Revit Energy Analysis ribbon panel:

1. Add a reference to the AdWindows.dll .NET assembly provided with Revit.
2. Add the two snippets of source code listed below to the external application implementation:
   1. In OnStartup, create and add the button.
   2. Handle the UIElementActivated event.

Adding the References

Add a reference to the AdWindows.dll .NET assembly provided with Revit.

Don't forget to set the copy local flag to false on that.

This will also require references to the .NET WindowsBase and PresentationFramework assemblies, which in turn require PresentationCore and System.Xaml.

Creating and Adding the Button

In OnStartup, localise the existing tab and panel, instantiate a new ribbon button, add it to the tab, and subscribe to the UIElementActivated event.

Here is a simplified version of Eduardo's code set up to run on Jeremy's system and open the browser to display The Building Coder home page:

public Result OnStartup( UIControlledApplication a )
{
  adWin.RibbonControl ribbon
    = adWin.ComponentManager.Ribbon;
 
  foreach( adWin.RibbonTab tab in ribbon.Tabs )
  {
    if( tab.Id == "Analyze" )
    {
      foreach( adWin.RibbonPanel panel
        in tab.Panels )
      {
        if( panel.Source.Id == "cea_shr" )
        {
          adWin.RibbonButton button
            = new adWin.RibbonButton();
 
          button.Name = "TbcButtonName";
          //button.Image = image;
          //button.LargeImage = image;
          button.Id = "ID_TBC_BUTTON";
          button.AllowInStatusBar = true;
          button.AllowInToolBar = true;
          button.GroupLocation = Autodesk.Private
            .Windows.RibbonItemGroupLocation.Middle;
          button.IsEnabled = true;
          button.IsToolTipEnabled = true;
          button.IsVisible = true;
          button.ShowImage = false; //  true;
          button.ShowText = true;
          button.ShowToolTipOnDisabled = true;
          button.Text = "The Building Coder";
          button.ToolTip = "Open The Building "
            + "Coder blog on the Revit API";
          button.MinHeight = 0;
          button.MinWidth = 0;
          button.Size = adWin.RibbonItemSize.Large;
          button.ResizeStyle = adWin
            .RibbonItemResizeStyles.HideText;
          button.IsCheckable = true;
          button.Orientation = System.Windows
            .Controls.Orientation.Vertical;
          button.KeyTip = "TBC";
 
          adWin.ComponentManager.UIElementActivated
            += new EventHandler<
              adWin.UIElementActivatedEventArgs>(
              ComponentManager_UIElementActivated );
 
          panel.Source.Items.Add( button );
 
          return Result.Succeeded;
        }
      }
    }
  }
  return Result.Succeeded;
}

As you can see, I am triggering the reaction to the button click by subscribing to the UIElementActivated event. Not sure if this is the correct way of doing it, but it works.

Handling the Event

In the event handler, check that the custom button was actually clicked and act on that, e.g. opening the browser at a specified URL.

void ComponentManager_UIElementActivated(
  object sender,
  adWin.UIElementActivatedEventArgs e )
{
  if( e != null
    && e.Item != null
    && e.Item.Id != null
    && e.Item.Id == "ID_TBC_BUTTON" )
  {
    // Perform the button action
 
    // Local file
 
    string path = System.Reflection.Assembly
      .GetExecutingAssembly().Location;
 
    path = Path.Combine(
      Path.GetDirectoryName( path ),
      "test.html" );
 
    // Internet URL
 
    path = "http://thebuildingcoder.typepad.com";
 
    Process.Start( path );
  }
}

Note that this requires no interaction with the Revit database, so there is no need to worry about a valid API context or transactions or any of that stuff.

Many thanks to Eduardo for sharing this!

Sample Run

Jeremy adds: for your convenience, here is AddButton.zip containing the source code, Visual Studio solution and add-in manifest for my version of this external application.

On my system, however, the button appears in the expected location but is disabled, so no action is triggered:

I am not sure why that happens. Maybe Eduardo or somebody else can help resolve this.

Implement a Progress Bar and Abort a Lengthy Process

The time has come to talk of many things: of shoes and ships, and sealing-wax, of cabbages and kings [^]... or no, let's continue sticking to the Revit API for now, more or less; today's topics are:

• A walk in the snow and a crystal covered baby tree
• Implementation of a Revit add-in progress bar
• Aborting a lengthy process from the progress bar
• Harry's image generation video competition

A Walk in the Snow

I went for a walk in snow and fog on a local hill and appreciated this wind-driven ice crystal covered baby tree that:

I thought I would like to share that with you. Sorry that it is so dark, but that's the way it was.

Implementing a Revit Add-in Progress Bar

I chatted with Harry Mattison on various topics during the winter break. One of them was the implementation of a Revit add-in progress bar:

Question: I am trying to make a simple progress dialog based on your post on modeless dialogues. It seems to work well basically but has a few problems:

1. The first time I run the command, the progress dialog flashes briefly on the screen and then disappears.
2. The text label does not display properly.
3. Sometimes the entire progress dialogue content turns white and the title bar says 'Not Responding'.

Could you help me figure out if my approach is flawed or if it just needs some small adjustments?

Answer: Thank you, but no thank you... :-)

Instead, I propose that you look at my existing modeless progress bar implementation in the ADN Revit MEP sample add-in, which has worked flawlessly for years now.

Response: Your progress bar is great! I wish I had found it earlier.

Aborting a Lengthy Process

Here's hopefully one last question about the progress bar:

How can the user cancel the operation from the progress bar?

Answer: You could implement some standard .NET stuff on the progress bar; maybe simply add a cancel button to it, and an event handler for that.

Response: After spending some time thinking about events and the like, I realized the progress bar cancel solution is almost trivial.

An idle event wouldn't work in my case, because Revit was never going idle. It was too busy doing hard work of exporting images for my Image-O-Matic application. Instead, all I needed to do is add the Abort button to the progress dialog, and put this little bit of code in the progress bar class:

  private void btnAbort_Click(
    object sender,
    EventArgs e )
  {
    btnAbort.Text = "Aborting...";
    abortFlag = true;
  }
 
  public bool getAbortFlag()
  {
    return abortFlag;
  }

Then, inside my foreach loops, I just need to check the status of the flag:

  foreach( string phaseName in phaseList )
  {
    if( progressForm.getAbortFlag() )
      break;
 
    // . . .
  }

Many thanks to Harry for the fruitful discussion and helpful hint!

Image Generation Video Competition

Yet another item from Harry, this time a rather shameless plug, but I guess he earned it :-)

Harry announced a competition in which you can win a free, custom-built Revit API add-in according to your own specifications for downloading his Image-O-Matic application, generating a video with it, and uploading that to YouTube.

Have fun, and good luck to you!

Determine Revit Demo Mode Revisited

Almost a year back, we talked about how to determine whether the current running Revit application is a demo version or not.

The initial suggestion was to test this by trying to execute real functionality modifying the model and then save it. That obviously incurs significant overhead and may cause other problems as well.

Rudolf Honke suggested simply reading and evaluating the Revit main window title text instead.

Now Madmed created and posted an implementation of Rudolf's idea. I took the opportunity of both adding that as a new command CmdDemoCheck to The Building Coder samples and simultaneously incrementing all the year number references in the source code comments from 2012 to 2013, so that that trivial yearly update step is over and done with.

Another obvious step to be performed is the elimination of all warning messages when compiling the code, since they indicate obsolete API usage that needs to be cleaned up. Stay tuned for that anon.

Rudolf suggested checking whether the main window caption contains the words "VIEWER" and "MODE". This is language dependent, of course, and would be "MODUS" in the German Revit, for instance. He provided a link to C# and VB GetWindowText implementations and pointed out that this approach works in a zero-document scenario and will fail if the current document is named something like "VIEWER-MODE". That problem could be worked around by more intelligent parsing of the string to extract the document name, for instance, before searching for the demo mode trigger string.

To begin with, here is Madmed's implementation:

  [DllImport( "user32.dll", SetLastError = true,
    CharSet = CharSet.Auto )]
  static extern int GetWindowText(
    IntPtr hWnd,
    StringBuilder lpString,
    int nMaxCount );
 
  [DllImport( "user32.dll", SetLastError = true,
    CharSet = CharSet.Auto )]
  static extern int GetWindowTextLength(
    IntPtr hWnd );
 
  static StringBuilder GetStatusTextMadmed(
    IntPtr mainWindow )
  {
    StringBuilder s = new StringBuilder();
    if( mainWindow != IntPtr.Zero )
    {
      int length = GetWindowTextLength( mainWindow );
      StringBuilder sb = new StringBuilder( length + 1 );
      GetWindowText( mainWindow, sb, sb.Capacity );
      sb.Replace( "Autodesk Revit Architecture 2013 - ", "" );
      return sb;
    }
    return s;
  }

He suggests using it like this:

  IntPtr revitHandle = System.Diagnostics.Process
    .GetCurrentProcess().MainWindowHandle;
 
  StringBuilder sb = GetStatusText(revitHandle);
 
  bool isDemo = sb.ToString()[0] != '['

When trying that out on my system, I noticed that I my Revit window title does not include the "Architecture" sub-string, since I am running the one-box version.

I also thought that it might be handy and cleaner to start off by implementing a method which simply returns the entire Revit main window caption string unmodified, for the caller to use freely in any desired fashion. I ended up with the following implementation:

  static string GetWindowText( IntPtr mainWindow )
  {
    if( IntPtr.Zero == mainWindow )
    {
      throw new ArgumentException(
        "Expected valid window handle." );
    }
    int len = GetWindowTextLength( mainWindow );
    StringBuilder sb = new StringBuilder( len + 1 );
    GetWindowText( mainWindow, sb, sb.Capacity );
    return sb.ToString();
  }

That returns "Autodesk Revit 2013 - Not For Resale Version - [Floor Plan: Level 1 - rac_empty.rvt]" on my system.

The sample command making use of this currently looks like this:

  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    IntPtr revitHandle = System.Diagnostics.Process
      .GetCurrentProcess().MainWindowHandle;
 
    string s = GetWindowText( revitHandle );
 
    // My system returns:
    // "Autodesk Revit 2013 - Not For Resale Version 
    // - [Floor Plan: Level 1 - rac_empty.rvt]"
 
    bool isDemo = s.Contains( "VIEWER" );
 
    TaskDialog.Show( "Demo Version Check",
      ( isDemo ? "Demo" : "Production")
      + " version." );
 
    return Result.Succeeded;
  }

Here is version 2013.0.100.0 of The Building Coder samples with incremented year numbers throughout and including the new CmdDemoCheck command.

Many thanks to Rudolf for his helpful ideas and to Madmed for prompting me to pick this up again.

Retain or Update External Command GUID

Here are some thoughts by my colleague Joe Ye on whether to retain or update an external command GUID:

It is acceptable to keep the GUID unchanged for different versions of your Revit add-in. If you release several different versions for the same Revit version, e.g. 2013, you obviously have to make sure that only one add-in manifest file to load it is found.

If you prefer, it is also okay to define a different GUID for each version of your add-in. In that case, please note that an external command with the same name from two different versions can be loaded simultaneously.

If the add-in creates its own Ribbon items, trying to create the same items twice over will also cause an error, since ribbon item names are unique.

Thank you, Joe, for these hints.

URL and Other Buttons, XYZ Points and Vectors

Let me summarise a very few of the topics I have been chatting with people about in the past few days:

• Ribbon button identification
• Opening a URL from a ribbon button
• XYZ comparison and point and vector behaviour
• Autodesk API overview
• The Green Building Studio GBS REST API

Actually, to tell the truth, it is just one day, so far, this week. Wow, my days are too full. I am getting nothing else done!

Ribbon Button Identification

Here is a simple question that came up a few times in the past:

Question: I have implemented a ribbon push button. Now I would like to find out which button was pushed in the event handler, i.e. external command, so that I can attach the same external command to handle multiple different buttons. How can this be achieved, please?

I would like to identify the button pushed and access its data in the external command Execute method.

Answer: The official Revit API user interface design expects you to implement a separate command class for each push button.

If you do so, then you can identify the push button clicked by the user by the command class whose Execute method was triggered.

If you choose to circumvent this official approach somehow, e.g. by attaching the same external command implementation to several different push buttons, than you will have to identify them by some other means.

When you define a push button, you also specify its Name via the RibbonItemData.Name property. This name is unique across the entire ribbon, or at least within the panel containing the button, so you could use this to identify the button.

Unfortunately, the Revit API does not provide any support for finding out which push button was used to trigger the external command.

While this functionality is not provided by the Revit API, you may be able to make use of the generic .NET Framework libraries to find out.

For instance, you can subscribe to certain events to receive a notification whenever a ribbon button is pressed by making use of the .NET UI Automation library.

A concrete example of subscribing to a UI Automation event telling you which button was clicked is given by Rudolf Honke to pimp my ribbon, where he shows how to implement an event listener for both Revit and AutoCAD ribbon systems:

ComponentManager.UIElementActivated
  += new EventHandler<Autodesk.Windows
    .UIElementActivatedEventArgs>(
      ComponentManager_UIElementActivated );
 
void ComponentManager_UIElementActivated(
  object sender,
  Autodesk.Windows.UIElementActivatedEventArgs e )
{
  // e.UiElement.PersistId says which item has been pressed
}

You will need to test whether this is of any use to you. This event listener may be pretty inefficient and slow.

The use of these APIs is unsupported and at your own risk. If you wish to use the unsupported UI Automation option, you will have to find out for yourself how to do so using the ample information available on the web and elsewhere.

Probably the easiest way to go is indeed to implement a separate command handler for each button. If you have many commands requiring similar functionality, e.g. an identical initialisation procedure, you can either derive them all from one common base class, or wrap the common functionality in a method that you can call from each separate external command Execute method.

Opening a URL from a Ribbon Button

Another, simpler, question on hooking up ribbon buttons was also happily and rapidly resolved:

Question: I am attempting to create a URL link like this:

How can I enable the user to click on the button and get the link to open in a web browser? I know how to create the ribbon panel and push button, but not how to connect to the URL in a web browser.

Answer: Two options:

1. Official, easy, supported: implement an external command and launch the browser from that.
2. Unofficial, harder, unsupported: use something else, e.g. the .NET framework UI Automation library discussed above.

Response: Option #1 worked and it was very easy indeed. All it required was adding just one line of code in the external command, System.Diagnostics.Process.Start, and then simply implementing it in the external application file.

This enables us to populate a custom ribbon panel that includes URLs linking to PDFs and webpages containing office Revit standards. This provides our staff a quick and easy way to access our standards within the Revit environment.

External command:

External application:

Revit ribbon:

XYZ Comparison and Point and Vector Behaviour

A completely different topic deals with the Revit API XYZ class, its dual use to represent points and vectors, and how to compare them, raised by Graham Cook in the Revit API discussion forum in the thread on a XYZ.IsAlmostEqualTo problem:

Question: Maybe I'm misinterpreting the IsAlmostEqualTo method. I want to determine whether two points are within 4 inches of each other, i.e. 0.3333 feet. I thought the following code would achieve that:

  XYZ a = new XYZ(41.7, -76, 0);
  XYZ b = new XYZ(4.7, -76, 0);
  bool almostEqual = a.IsAlmostEqualTo(b, 0.333);

But even though in this example the two points are 37 feet apart, IsAlmostEqualTo returns true. Am I misunderstanding the tolerance part of the method?

Answer: The behaviour you observe is correct and intended and has a simple explanation:

IsAlmostEqualTo is implemented for vector comparison, not point comparison, and is mostly designed around small tolerances. The default for IsAlmostEqualTo with no tolerance input argument given is 1e-09. At small tolerances, points and vectors are more interchangeable, so I would use the default IsAlmostEqualTo to find "equivalent" points too.

Because this is a directional comparison, not a distance one, 0.333 for the epsilon means to check if the two vectors are within a significant angular range of each other, which the example input points actually pass. Even if the points are treated as vectors and normalized, they will still pass the comparison because of the wide epsilon permitted.

If you want to compare points with a non-tiny epsilon using the allowed distance between them, use XYZ.DistanceTo method instead.

The Util.cs module of The Building Coder samples provides example implementations of point comparison predicate methods. Here is version 2013.0.99.4 from the slab boundary command update.

Autodesk API Overview

Autodesk provides a large number of programming platforms and APIs. An overview is given by the Platform Technologies overview on the Autodesk Developer Network. Just to see and be astounded by their sheer number, here is a list of links to the associated developer pages:

• 3DS Max
• AutoCAD Architecture
• Autodesk Exchange Apps Developer Center
• AutoCAD
• AutoCAD Civil 3D
• Cloud & Mobile
• DWF
• FBX
• Inventor
• AutoCAD Map 3D
• Autodesk Infrastructure Map Server AIMS
• Maya
• MotionBuilder
• Navisworks
• Revit
• Vault
• Wiretap
• ObjectARX
• AutoCAD OEM
• RealDWG

The Green Building Studio GBS REST API

I recently played around with the BIM 360 Glue REST API and showed how to use Python to access it interactively. I also recently mentioned the new building performance analysis blog which discusses topics such as the Project Falcon computational fluid dynamics Revit add-in and GBS, the Autodesk Green Building Studio cloud-based energy analysis web service.

Emile Kfouri now pointed out this discussion of the GBS REST API that will certainly enable you (yes, you!) to achieve very cool things. I am looking forward to hearing about your ideas!

AU Classes on Python, UI, Server and Framework APIs

Thursday was another very full and fruitful day at AU. I gave my third and last class, the most exciting one in my eyes, on some UI and integration aspects. I was unable to attend Iffat May's class introducing Python and using it in Revit and Vasari via RevitPythonShell, but I love her material so much I am including it anyway. Adam Nagy presented a class addressing cloud and mobile development and the Revit Server API. Finally, Arnošt Löbel provided a peek behind the scenes and into the depths of the fundamental frameworks underlying the Revit API.

Here they are in chronological order:

1. CP3837-L Scripting with RevitPythonShell in Vasari by Iffat May.
2. CP4107 Let's Face It: New Revit 2013 User Interface API Functionality by Jeremy Tammik.
3. CP3093 My First Cloud/Mobile App with Revit Server by Adam Nagy.
4. CP3426 Core Frameworks in the Revit API by Arnošt Löbel.

I am including the class materials below, for your and my own convenience, and also to ensure that all this juicy stuff really is picked up and returned by Internet search engines.

1. CP3837-L RevitPythonShell in Vasari

Iffat provides an entire introductory tutorial to the Python programming language, and then shows how to apply it to solve a number of useful tasks in Revit and Vasari. She makes use of Daren Thomas' Revit Python shell, originally implemented for Revit 2010, then for Vasari, Revit 2012 and Vasari 2.1, and now available for Revit 2013.

RevitPythonShell introduces interactive scripting ability to Revit and Project Vasari. Designers now have the ability to interactively design and manipulate Revit elements using algorithms and computational logic. The class explores the Python structures, variables, data types, and flow control, and shows how to use them to create scripts to control Revit elements dynamically.

• Handout
• Presentation
• Sample code and models

2. CP4107 Revit 2013 User Interface API

This class takes a deeper look at the new user interface and add-in integration functionality provided by the Autodesk Revit 2013 API. It covers 2013 features including Options dialogue custom extensions using WPF components, subscription to Revit progress bar notifications, embedding and controlling a Revit view inside an add-in dialogue for preview purposes, the new drag and drop API, and the UIView. This class is complementary to and expands on CP3272, a Snapshot of the Revit UI API:

• Document management and View API
• Revit progress bar notifications
• Options dialogue WPF custom extensions
• Embedding and controlling a Revit view
• UIView and Windows coordinates
• Drag and drop

From my point of view, one of the most exciting new features provided by the Revit 2013 UI API is the possibility to correlate between Windows screen device coordinates and Revit model coordinates provided by the UIView class, which I used to examine and implement my own Revit tooltip, which also makes use of the new ReferenceIntersector class and Idling event. This has never previously been possible. Now you can do anything you like using the Windows API and connect that intelligently with the underlying Revit model.

• Handout
• Presentation
• Sample code

3. CP3093 Cloud/Mobile App with Revit Server

This class has two objectives: to introduce you to the Revit Server REST API and to introduce you to cloud and mobile programming.

Autodesk Revit Server is a server-based file storage system that we can use to store Revit files. It has a public API that uses simple HTTP known as REST (or Representational State Transfer). REST is a "style" for designing network applications, and it is used to communicate between the server and a client machine. REST is simple, yet powerful enough. You can use it from anywhere where HTTP programming is available: from a desktop, a mobile device or a server-side application. In this class, we discuss what REST is, using the context of Revit Server.

We then go one step further and show you how to create your own REST service in .NET. We implement it as a notification system in the cloud and demonstrate with an Apple iPad/iPhone application in Apple iOS. At the end of this class, you will be able to:

• Use HTTP requests to interact with a REST API
• Programmatically access and modify data available on Revit Server
• Create basic iOS applications in Xcode
• Create a basic REST service in .NET
• Use Apple Push Notification

Here is the detailed handout document:

• Handout

4. CP3426 Core Frameworks in the Revit API

A good understanding of core frameworks in the Revit API is a prerequisite for developing well behaved Revit add-ins. Among the most important ones, the following frameworks play key roles in most applications:

• External applications, commands, and events
• Transactions phases
• Regeneration and transaction modes
• Updaters and other call-backs
• Scoped objects and element validity

These concepts have been around for many releases, yet there are still facts about them that may not be completely understood. This class summarizes the necessary basics, and also sheds some light on the behaviour that is normally hidden 'under the hood'. Knowledge acquired during this class will help Revit developers to build more efficient, safer, and robust applications.

• Paper
• Presentation

By the time you read this, I will be sitting in the plane heading back to Europe.

Take care, and walk in beauty.

Happy Bhai Dooj!

Happy Bhai Dooj to you!

This greeting comes from my colleague Sandeep Kumar in Bangalore, who explains:

Bhai Dooj is a festival of prayers from sister to brother, brother's protection for her sister. May we all celebrate this Bhai Dooj with even more love and protection for our sisters and brothers. Best wishes on this Bhai Dooj.

Thus fortified, let us turn to a Revit API issue, based on this excerpt from a useful little chat I had yesterday that might be of general use:

Implementing a Single Command for Multiple Buttons

Question: My external application displays a large number of all kinds of ribbon items. Now I thought I might implement one single handler class for all of the external commands these items can trigger, instead of creating a separate one for each. I would like to create only one CommandHandler class derived from IExternalCommand, and decide which function is required in its Execute method. The problem I have is that the ExternalCommandData instance passed in does not provide any information about the source of the event, so there is no way of knowing which RibbonItem was clicked. Is there a way to get that information, e.g. retrieve the name of the button clicked or something?

Answer: A good idea. It makes perfect sense. Unfortunately, no, this is not possible.

At least, the Revit API does not give you this access. You might possibly have more luck using .NET UI Automation. It probably provides UI Automation events that can let you find out what button was clicked.

Using the standard Revit API functionality, you really do have to implement a separate command for each button. You can easily funnel them all into the same handler yourself afterwards, if you like. That would achieve almost what you want. Implement a separate command for each button, determine which button was clicked, and then funnel all calls into the same command handler method. The handler method can check the source of the event and branch out again appropriately.

Addendum: In his comment below, Rudolf Honke points to the very interesting discussion thread on which pushbutton caused the ExternalCommand where Revitalizer and ollikat expound on various alternative solutions, e.g. subscribing to the UIElementActivated event, creating commands at runtime and implementing one single base class inheriting IExternalCommand and other command classes derived from it.

Roll Your Own Toggle Button

Today I took my first stab at creating, compiling and debugging a new Revit add-in on the Mac.

I cannot run Revit or Visual Studio natively on the Mac, of course, so those have to remain in Windows, hosted by the Parallels environment on the Mac.

I had to fiddle around quite a bit with the Parallels synchronisation, which seems to be breaking more things than it fixes, for me at least. I managed in the end in spite of that, though.

The opportunity to implement a new sample add-in was provided by the following question:

Question: Is there a way to create a ribbon button that can be toggled, e.g. a sort of on/off switch like the Modify > Properties button?

Answer: Yes, sure.

You will have to roll your own, though.

The Revit API just provides radio buttons.

Here is a description of radio buttons from Saikat Bhattacharya's upcoming Autodesk University class CP3272 Snapshot of the Autodesk Revit User Interface API:

Radio Buttons

A radio button group helps toggle between options by letting users select only one ribbon item at a time. After adding a RadioButtonGroup to a panel, use the AddItem and AddItems methods to add radio buttons, which are basically normal PushButtons, to the group. The RadioButtonGroup.Current property can be used to access the currently selected button. Just like SplitButton, tooltips do not apply to radio button groups; instead the tooltip for each toggle button is displayed.

  RadioButtonGroupData radioData =
    new RadioButtonGroupData( "radioGroup" );
 
  RadioButtonGroup radioButtonGroup =
    panel.AddItem( radioData ) as RadioButtonGroup;
 
  ToggleButtonData tb1 = new ToggleButtonData(
    "OverrideCommand1",
    "Override Cmd: Off",
    assemblyPath + "\\" + assemblyName,
    "SnapshotRevitUI_CS.OverrideOff" );
 
  ToggleButtonData tb2 = new ToggleButtonData(
    "OverrideCommand2",
    "Override Cmd: On",
    assemblyPath + "\\" + assemblyName,
    "SnapshotRevitUI_CS.OverrideOn" );
 
  tb2.ToolTip = "Override the Wall Creation command";
 
  tb2.LargeImage = new BitmapImage(
    new Uri( imageFolder + "globe_32.png" ) );
 
  radioButtonGroup.AddItem( tb1 );
  radioButtonGroup.AddItem( tb2 );

However, this is still not quite what you want, is it?

You would really like one single button that changes its state each time it is clicked.

A Real Toggle Button

Well, as said, this can easily be achieved by implementing your own custom button.

Note that the RibbonButton Image, LargeImage and ItemText properties are all read-write.

Therefore, there is nothing to stop you from changing the button appearance any way you like at any time you like. For instance, if you change these properties appropriately each time the button is clicked, it will appear like a toggle button such as you describe.

I implemented a minimal sample illustrating this using just the ItemText property:

It would look more impressive if I switched the image as well, of course. I leave that as a simple exercise to the reader.

The basic framework to achieve this consists of a very small external application and a single-line external command.

The external application sets up the ribbon panel and button, saves a reference to the latter, and provides a public method Toggle that uses the button reference to toggle its text:

class App : IExternalApplication
{
  static string _path = typeof( App ).Assembly.Location;
 
  RibbonItem _button;
 
  /// <summary>
  /// Singleton external application class instance.
  /// </summary>
  internal static App _app = null;
 
  /// <summary>
  /// Provide access to singleton class instance.
  /// </summary>
  public static App Instance
  {
    get { return _app; }
  }
 
  public Result OnStartup( 
    UIControlledApplication a )
  {
    _app = this;
 
    RibbonPanel panel = a.CreateRibbonPanel( 
      "ToggleButton" );
 
    PushButtonData data = new PushButtonData( 
      "Toggle", "On", _path, 
      "ToggleButton.Command" );
 
    data.AvailabilityClassName
      = "ToggleButton.Availability";
 
    _button = panel.AddItem( data );
 
    return Result.Succeeded;
  }
 
  public Result OnShutdown( UIControlledApplication a )
  {
    return Result.Succeeded;
  }
 
  public void Toggle()
  {
    string s = _button.ItemText;
 
    _button.ItemText = s.Equals( "On" ) ? "Off" : "On";
  }
}

The button images could be toggled in a similar fashion.

The Toggle method is public, and used by the command to toggle the button state each time it is launched:

  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    App.Instance.Toggle();
 
    return Result.Succeeded;
  }

Probably one of the simplest command implementations you have ever seen, isn't it?

This command was initially read-only, and that makes sense, but I had to change it to manual transaction mode for reasons explained below.

Zero Document State Support

I made the whole sample a little bit more complicated in order to enable its use in a zero document context as well as when a project is opened.

I implemented a trivial availability class that I use to set the button availability. In this case, I want it to be available always:

  public class Availability
    : IExternalCommandAvailability
  {
    public bool IsCommandAvailable(
      UIApplication a,
      CategorySet b )
    {
      return true;
    }
  }

Enabling the command in zero document context also requires changing its transaction mode from read-only to manual, because Revit only allows manual transaction mode commands in zero document state. Violation of this rule causes the following error:

As you can see from the recording above, all is well now, and this is a viable solution.

Here is ToggleButton.zip containing the complete source code, Visual Studio solution and add-in manifest for this add-in.

While I've been having fun creating this sample, let's look at some examples of cool stuff other people are doing as well.

IDAT Revit Structure Slab Add-In

The German company IDAT presents a neat example of using the Revit API implement an add-in for the design, fabrication and construction logistics of precast hollow core slabs. This video shows their precast module for hollowcore slabs inside Revit Structure:

Ab in den Hafen by Allerdings

Completely unrelated to Revit and its API, but closely related to me, my son Christopher aka Allerdings has been composing and publishing music on SoundCloud for some time now.

Here is his most recent oevre, Ab in den Hafen:

Enjoy.

AUGI Wish List

Another cool and important thing, albeit more administrative, is the AUGI wish list providing a unified independent voice back to Autodesk on how to improve its products.

Please vote now for your most important wish.

Ensure WPF Add-in Remains in Foreground

Autumn arrived and passed in a flash. The woods are beautifully coloured, and, unusually, the first snow is already lying on the surrounding hills.

Here are some items of interest from cases we looked at last week:

1. Ensure WPF add-in remains in foreground
2. Retrieve all model lines
3. Set linked file visibility
4. Access linked file elements and data
5. Visual Studio 2012 Model Editor Supports OBJ and FBX
6. Sie Mögen Sich

Ensure WPF Add-in Remains in Foreground

Here is an issue concerning an interaction between a WPF add-in and the Revit TaskDialog, raised and solved by Simon Hooper of Bestech Systems Ltd:

Question: I have a modal WPF Revit add-in application.

If I show a TaskDialog, e.g. call TaskDialog.Show("Global", "Hello World"), my WPF add-in is sent to 'the back' behind Revit, in spite of being modal!

If I use MessageBox.Show(""), the problem does not occur.

How can this be resolved, please?

Answer: I ensured that the WPF form properly parented, i.e. is it a child form of the Revit main application window.

Googling for "JtWindowHandle wrapper class" provides lots of examples of how to parent a normal .NET modeless form.

The procedure is applicable to WPF forms as well.

It seems like the problem is solved by using the following lines:

  exportForm = new ExportForm();
 
  System.Windows.Interop.IWin32Window revit_window 
    = new JtWindowHandle( Autodesk.Windows
      .ComponentManager.ApplicationWindow );
 
  System.Windows.Interop.WindowInteropHelper helper 
    = new System.Windows.Interop.WindowInteropHelper(
      exportForm );
 
  helper.Owner = revit_window.Handle;

The helper line was the key.

Retrieve all Model Lines

Question: I have a very simple question.

I want to scan my Revit model for all Model Line instances.

RevitLookup tells me I should use the built-in category OST_Lines in my filter, but it does not find the lines.

Here is my logic:

  FilteredElementCollector collector
    = new FilteredElementCollector( doc );
 
  ElementClassFilter familyInstanceFilter
    = new ElementClassFilter(
      typeof( FamilyInstance ) );
 
  ElementCategoryFilter oCategoryFilter
    = new ElementCategoryFilter(
      BuiltInCategory.OST_Lines );
 
  LogicalAndFilter andFilter
    = new LogicalAndFilter(
      familyInstanceFilter,
      oCategoryFilter );
 
  ICollection<Element> oElements
    = collector.WherePasses( andFilter )
      .ToElements();

However, this returns nothing at all!

What is wrong?

Answer: Yes, this is indeed a rather simple question.

Model lines are model curves. Model curves are not family instances.

Your collector includes a family instance filter. The family instance filter will eliminate all model curves, preventing any model lines from being found.

Simply remove the family instance class filter, or replace it by a model curve class filter.

By the way, the most common quick filters are all available using shortcut methods on the collector class itself.

Using the shortcut methods saves you from having to instantiate a separate filter instance, and ensures that all the filters you apply are quick filers.

All the following three variants should work, and presumably produce identical results:

  FilteredElementCollector collector
    = new FilteredElementCollector( doc )
      .OfClass( typeof( ModelCurve ) )
      .OfCategory( BuiltInCategory.OST_Lines );
 
  FilteredElementCollector collector
    = new FilteredElementCollector( doc )
      .OfCategory( BuiltInCategory.OST_Lines );
 
  FilteredElementCollector collector
    = new FilteredElementCollector( doc )
      .OfClass( typeof( ModelCurve ) );

Set Linked File Visibility

Saikat Bhattacharya demonstrates the use of the View class HideElements and UnhideElements methods to control the visibility of linked files, and points out that the SetVisibility method cannot be used for this purpose.

Access Linked File Elements and Data

On a still more exciting and ever recurring linked file topic, Saikat shows how easy it is to access the elements and data contained in a linked file, e.g. to read the level information of all walls in a linked file.

Visual Studio 2012 Model Editor Supports OBJ and FBX

Visual Studio 2012 includes a Model Editor that enables you to inspect the 3-D model formats OBJ, Autodesk FBX and COLLADA. You can also use built-in 3-D primitive generation and materials to create placeholder art for 3-D games and applications.

That sounds handy, doesn't it?

I recently had a look at the OBJ format to implement Revit model export to OBJ, and obviously Revit already provides built-in support for FBX export (LT, Vasari).

If you wanted to work in depth with FBX yourself, you would presumably use the FBX SDK, currently at version 2013.3, supporting C++ development in Visual Studio 2005, 2008, and 2010.

Sie Mögen Sich

For something completely unrelated to computers and technology, here is a seven minute video, Sie mögen sich, a quite deep philosophical relationship analysis by Shaban & Käptn Peng that my son Christopher pointed out and that I enjoyed a lot:

It is in German, however, and probably makes no sense at all unless you understand the language.

Point Cloud Request Batching

Here is some important information for point cloud engine developers, who may be confused by the SDK samples provided.

Question: We have taken the Revit point cloud engine example provided and modified it to create three cells, each loading its points from an ASCII file. The cell boundary is then drawn as blue random points.

We noticed that the maximum number of points ever requested is 512 * 512 and decreases as you zoom out. This number is applied to all cells, so the third and second cells disappear rather that fewer points being drawn in each cell.

This of course prompts some questions:

1. What sets the size of the buffer that is to be filled with points?
2. How does the point engine pass the buffer to each cell such that a closer cell would be requesting more points than one in the distance?

Answer: An instance of the IPointCloudAccess class will be requested by Revit when drawing the point cloud in the view. For performance reasons, when rendering every frame, Revit asks the engine to fetch the necessary points split into multiple batches. The number of batches requested depends on the view: the smaller the projection of the cloud bounding box on the screen the fewer batches Revit requests. Revit assumes that each batch contains points uniformly distributed over the visible part of the cloud ('visible' as defined by the filter). Thus, the points supplied by the engine should not be geometrically distinct, e.g. divided into multiple independent volumes, because otherwise, at distant zoom levels, Revit will only request a few batches and only part of the cloud will be displayed.

In other words, on every frame, Revit asks the engine to fetch some number of points in a few batches. Each batch is 256K points. The number of batches requested depends on the frame: the smaller the projection of the cloud bounding box on the screen, e.g. when you zoom out or orbit, the fewer batches Revit requests. Revit assumes that each batch contains points uniformly distributed over the visible part of the cloud, where 'visible' is defined by the filter.

In the sample code, the plug-in does the complete opposite: it groups points in a few cubes, 256K each, and returns one cube per requested batch. So if Revit requests 3*256K points, it gets three cubes, but if you zoom out and Revit requests only 2*256K points, it receives only 2 cubes. In this example Revit expects to get 2*256K points uniformly distributed over the 3 cubes.

This assumption is currently not reflected adequately in the documentation. Sorry! It should say something like:

The main purpose of the engine is to quickly fetch points from one point cloud file satisfying certain conditions described in the client query. Typical request would be to get specified number of representative points within specified volume, e.g. a view frustum. By representative we mean that it is responsibility of the engine to make sure that the points being returned give a good idea of the distribution of all points satisfying the query rather than, e.g. concentrating all in one area.

This simply shows how a contrived SDK engine sample may not provide the best example for real-world usage, not having a database of points which can be queried representatively.

Programmatically Flip Work Plane

Saikat Bhattacharya provided a very clear and succinct explanation on flipping the the work plane for a family instance, and a code sample using the IsWorkPlaneFlipped property to achieve this programmatically.

UIView, Windows Coordinates, ReferenceIntersector and My Own Tooltip

Here is my well-meant contribution to making this the most exciting Wednesday of your entire week.

For the first time in history, the Revit 2013 UIView class provides a possibility to convert back and forth between Revit model coordinates and Windows device screen points.

I imagined making use of that right away when I read about the UIView class, and mentioned it when discussing UIView and Windows device coordinates.

I am still a bit surprised that I have not yet received any questions about these exciting possibilities. Well, anyway, that gives me a chance to finally dive into this exploration free of preconceptions.

Another Revit 2013 topic that I wanted to talk about for a long time is the new ReferenceIntersector class. My previous attempts at publishing anything on it were thwarted by running into some unintended features which have meanwhile been attended to.

Now I can combine both of these topics into a single nice example, presenting my very own tooltips displaying any information I like based on the cursor location in the Revit BIM.

Does that sound cool, or what?

To give you an idea of what I am talking about, here is a two-minute video depicting a sample run demonstrating the final result, with the normal Revit tooltips and my own specialised ones displayed side by side.

To run the demo, I open up the basic architectural sample project, switch away from the perspective view, since add-ins are disabled there, select Level 2, turn on my own tooltips, hover around different elements to compare the Revit tooltip with my own one, and turn off my tooltips again:

Table of Contents

To display a useful tooltip, the user needs to be free to play around in the model.

Simultaneously, my add-in needs to be able to access the Windows cursor location, determine the corresponding Revit model coordinates from it, and query the Revit BIM to determine the information I would like to display.

This calls for an Idling event handler, adding a third topic to the two already mentioned above.

We thus end up with the following list, including hints on the respective approaches, solutions, and helper methods:

• Top-level form and Idling event management: ModelessForm_IdlingEvent.
• Helper methods: GetActiveUiView, GetView3d, ElementDescription.
• Idling event handler:
  • Access Windows cursor location: System.Windows.Forms.Cursor.Position.
  • Determine Revit model coordinates: UIView.
  • Query Revit BIM for information: ReferenceIntersector.
  • Display tooltip: JtTooltipForm.
  • Entire implementation.
• Toggle tooltip on and off commands.
• Conclusion and download.

Before closing, I also mention Saikat's new posts on multi-image naming conventions and text file TaskDialog command links, DesignScript availability on Autodesk Labs, and a nice video of my friend Falk on the Schafberg.

Top-level Form and Idling Event Management

As you hopefully know by now, the implementation to handle the Idling event needs to be really clean and clear and is a little bit tricky.

I strongly suggest basing anything you do on the ModelessForm_IdlingEvent SDK sample.

If you implemented your Idling event handler in any other way in the past, it might be a good idea revisiting it now and comparing notes with that sample.

I based my WinTooltip external application on it, anyway.

It handles all the modeless form interaction in the external application implementation.

In my case, the modeless form is either a Visual Studio designer generated JtTooltipForm or a hand-built JtTooltipForm2.

The external application is instantiated as a singleton instance, and provides public access to that instance so that external commands can access it and use its functionality to show and hide the modeless form.

It implements an internal CloseForm method, public methods ShowForm and HideForm, called by the external commands, and the standard interface methods OnStartup and OnShutdown, like this:

  /// <summary>
  /// Singleton external application class instance.
  /// </summary>
  internal static App _app = null;
 
  /// <summary>
  /// Provide access to singleton class instance.
  /// </summary>
  public static App Instance
  {
    get { return _app; }
  }
 
  /// <summary>
  /// The tooltip form to display.
  /// </summary>
  internal static JtTooltipForm2 _form = null;
 
  /// <summary>
  /// Dispose and null out form.
  /// Return true if it was previously not disposed.
  /// </summary>
  static bool CloseForm()
  {
    bool rc = _form != null;
 
    if( rc )
    {
      if( !_form.IsDisposed )
      {
        _form.Dispose();
      }
      _form = null;
    }
    return rc;
  }
 
  /// <summary>
  /// Create and show the form, 
  /// unless it already exists.
  /// </summary>
  /// <remarks>
  /// The external command invokes 
  /// this on end-user request.
  /// </remarks>
  public void ShowForm( UIApplication uiapp )
  {
    // If we do not have a form yet, create and show it
 
    if( _form == null || _form.IsDisposed )
    {
      // Instantiate JtTooltipForm to use 
      // the designer generated form.
 
      _form = new JtTooltipForm2();
 
      _form.Show();
 
      // If we have a form, we need Idling too
 
      uiapp.Idling += IdlingHandler;
    }
  }
 
  /// <summary>
  /// Hide the form.
  /// </summary>
  /// <remarks>
  /// The external command invokes 
  /// this on end-user request.
  /// </remarks>
  public void HideForm( UIApplication uiapp )
  {
    if( CloseForm() )
    {
      // If the form was showing, we had subscribed
 
      uiapp.Idling -= IdlingHandler;
    }
  }
 
  public Result OnStartup( UIControlledApplication a )
  {
    _app = this;
    _form = null;
 
    return Result.Succeeded;
  }
 
  public Result OnShutdown( UIControlledApplication a )
  {
    if( CloseForm() )
    {
      a.Idling -= IdlingHandler;
    }
    return Result.Succeeded;
  }

Helper Methods

Apart from the top-level management, the Idling event handler does all the rest of the work.

Before we get to the event handler itself, I'll present the three helper methods it uses:

• GetActiveUiView: retrieve the active UIView.
• GetView3d: retrieve the 3D view named "{3D}".
• ElementDescription: return a descriptive text for a given Revit element.

We can get the active document view directly, but need some additional coding to determine the associated UIView, for example like this:

/// <summary>
/// Return currently active UIView or null.
/// </summary>
static UIView GetActiveUiView( 
  UIDocument uidoc )
{
  Document doc = uidoc.Document;
  View view = doc.ActiveView;
  IList<UIView> uiviews = uidoc.GetOpenUIViews();
  UIView uiview = null;
 
  foreach( UIView uv in uiviews )
  {
    if( uv.ViewId.Equals( view.Id ) )
    {
      uiview = uv;
      break;
    }
  }
  return uiview;
}

The ReferenceIntersector constructor requires a 3D view argument in which the ray tracing takes place. In this sample, I assume that a suitable 3D view named "{3D}" is available and retrieve that using one single line of filtered element and LINQ driven code:

/// <summary>
/// Return the 3D view named "{3D}".
/// </summary>
View3D GetView3d( Document doc )
{
  return new FilteredElementCollector( doc )
    .OfClass( typeof( View3D ) )
    .Cast<View3D>()
    .FirstOrDefault<View3D>( 
      v => v.Name.Equals( "{3D}" ) );
}

You can obviously modify this in any way you like and set up a suitable 3D view to suit your specific view setting, sectioning and filtering needs.

The location dependent BIM information displayed in the tooltip can be determined completely freely. In my case, I simply detect what element the cursor is hovering over and use the ElementDescription method to put together a descriptive text for it:

/// <summary>
/// Return a string describing the given element:
/// .NET type name,
/// category name,
/// family and symbol name for a family instance,
/// element id and element name.
/// </summary>
static string ElementDescription(
  Element e )
{
  if( null == e )
  {
    return "<null>";
  }
 
  // For a wall, the element name equals the
  // wall type name, which is equivalent to the
  // family name ...
 
  FamilyInstance fi = e as FamilyInstance;
 
  string typeName = e.GetType().Name;
 
  string categoryName = ( null == e.Category )
    ? string.Empty
    : e.Category.Name + " ";
 
  string familyName = ( null == fi )
    ? string.Empty
    : fi.Symbol.Family.Name + " ";
 
  string symbolName = ( null == fi
    || e.Name.Equals( fi.Symbol.Name ) )
      ? string.Empty
      : fi.Symbol.Name + " ";
 
  return string.Format( "{0} {1}{2}{3}<{4} {5}>",
    typeName, categoryName, familyName,
    symbolName, e.Id.IntegerValue, e.Name );
}

This is somewhat similar to and yet does not exactly match the information displayed by the standard Revit tooltip and other parts of the user interface, as you might have noticed in the video recording.

Idling Event Handler

The Idling event handler implements the following steps, which we first discuss one by one before presenting the entire code in context:

• Access Windows cursor location: System.Windows.Forms.Cursor.Position.
• Determine Revit model coordinates: UIView.
• Query Revit BIM for information: ReferenceIntersector.
• Display tooltip: JtTooltipForm.
• Entire implementation.

Access Windows Cursor Location

Converting from the cursor position retrieved in Windows device coordinates to Revit model coordinates is possible by calculating the relative position in the UIView.

Here is an illustration assuming a screen resolution of 1600 x 1200 with a Revit view located at the rectangle 800,150 to 1500,650, displaying a plan view of part of the Revit model, with model coordinates ranging from 10,40,0 to 220,120,0. The current cursor location is represented by the green spot:

The Windows device coordinate origin 0,0 is at the upper left, and Y values increase downwards, whereas the Revit model coordinate Y values increase upwards.

You can easily query the cursor position in device coordinates on the Windows screen from .NET framework at any time using the System.Windows.Forms.Cursor.Position property:

  Point p = System.Windows.Forms.Cursor.Position;

Determine Revit Model Coordinates

The cursor location is obviously returned in Windows device coordinates, stored in the point (or vector) variable 'p'.

The aim is to determine the location indicated by this point in Revit model coordinates, for example by determining the vector v from the lower left corner of the Revit view to that location.

We can easily determine the relative position of p between the two corners of the UIView in Windows device coordinates by subtracting the lower left hand corner and dividing by the total width and height to obtain the relative width and height location values dx and dy like this:

  UIView uiview = GetActiveUiView( uidoc );
 
  Rectangle rect = uiview.GetWindowRectangle();
 
  Point p = System.Windows.Forms.Cursor.Position;
 
  double dx = (double) ( p.X - rect.Left )
    / ( rect.Right - rect.Left );
 
  double dy = (double) ( p.Y - rect.Bottom )
    / ( rect.Top - rect.Bottom );

From the UIView, we can also determine model coordinates of the view corners. They are stored in a and b, respectively.

Now it is easy to calculate the cursor point 'q' in model coordinates from the two relative values like this:

  IList<XYZ> corners = uiview.GetZoomCorners();
  XYZ a = corners[0];
  XYZ b = corners[1];
  XYZ v = b - a;
 
  XYZ q = a
    + dx * v.X * XYZ.BasisX
    + dy * v.Y * XYZ.BasisY;

Query Revit BIM for Information using ReferenceIntersector Ray Casting

Once we have the model space cursor location 'q', we can calculate a point beyond the model extents (hopefully) from which one can picture the user looking into the model.

The first element intersected by a ray cast from that point in the view direction should be the one we are interested in displaying information about.

Initially, the sample run was a bit boring, because the only element encountered when looking from straight above was always the roof.

I tweaked that to make the example more interesting, not by modifying the model itself – I use the standard architectural basic sample project rac_basic_sample_project.rvt – but by adding a filter to remove all roof category elements from the reference intersector results instead. The exact elements of interest and information to display are entirely up to you and your needs to determine, of course.

The ray casting requires a 3D view to operate in. In this case, I simply pick the one named "{3D}" returned by the GetView3d helper method. You can set up your own view with specific graphics properties, section cuts, and only certain elements visible, if that better suits your requirements.

Here is the code determining the view, view direction and ray origin, setting up the intersector, determining the target element, and defining the tooltip text to display in the variable 's':

  View3D view3d = GetView3d( doc );
 
  XYZ viewdir = view.ViewDirection;
 
  XYZ origin = q + 1000 * viewdir;
 
  // Find all elements:
 
  //ReferenceIntersector ri
  //  = new ReferenceIntersector( view3d );
 
  // Find all elements except roofs:
 
  ElementFilter f = new ElementCategoryFilter( 
    BuiltInCategory.OST_Roofs, true );
 
  ReferenceIntersector ri 
    = new ReferenceIntersector( f, 
      FindReferenceTarget.Element, view3d );
 
  ReferenceWithContext rc
    = ri.FindNearest( origin, -viewdir );
 
  string s = "Element not found";
 
  if( null != rc )
  {
    Reference r = rc.GetReference();
 
    Element e = doc.GetElement( r );
 
    s = ElementDescription( e );
  }

Display Tooltip and the JtTooltipForm class

I originally used the Visual Studio designer to create a simple tooltip form named JtTooltipForm for me, then tweaked that auto-generated code to create one named JtTooltipForm2 myself programmatically from scratch.

Besides the constructor setting up the form and the Label object to display the tooltip text, it also manages an offset from the cursor position at which to display itself, provides a method to set the tooltip text, and overrides the OnShown and OnVisibleChanged methods to react appropriately to position changes:

/// <summary>
/// A tooltip window designed to move 
/// around with the cursor position.
/// </summary>
class JtTooltipForm2 : Form
{
  /// <summary>
  /// The offset from the mouse pointer 
  /// at which to show the form.
  /// </summary>
  public Point Offset { get; set; }
 
  /// <summary>
  /// Tooltip text.
  /// </summary>
  Label _label;
 
  /// <summary>
  /// Set the tooltip text.
  /// </summary>
  public void SetText( string s )
  {
    _label.Text = s;
  }
 
  /// <summary>
  /// Move the window to an offset of mouse pointer.
  /// </summary>
  protected override void OnShown( EventArgs e )
  {
    base.OnShown( e );
 
    Location = new Point(
      MousePosition.X + Offset.X,
      MousePosition.Y + Offset.Y );
  }
 
  /// <summary>
  /// Move the window to an offset of mouse pointer.
  /// </summary>
  protected override void OnVisibleChanged(
    EventArgs e )
  {
    base.OnVisibleChanged( e );
 
    if( Visible )
    {
      Location = new Point(
        MousePosition.X + Offset.X,
        MousePosition.Y + Offset.Y );
    }
  }
 
  public JtTooltipForm2()
  {
    Size = new Size( 200, 20 );
 
    _label = new Label();
 
    SuspendLayout();
 
    _label.AutoSize = false; // the label will not change its height automatically, only width, so switch off AutoSize to wrap text
    _label.CausesValidation = false;
    _label.Dock = DockStyle.Fill;
    _label.Location = new Point( 0, 0 );
    _label.Size = new Size( 35, 13 );
    _label.Parent = this;
 
    AutoScaleDimensions = new SizeF( 6F, 13F );
    AutoScaleMode = AutoScaleMode.Font;
    BackColor = SystemColors.Info;
    ClientSize = new Size( 200, 12 );
    Controls.Add( _label );
    FormBorderStyle = FormBorderStyle.None;
    Name = "JtTooltipForm";
    Opacity = 0.8D;
    ShowInTaskbar = false;
    TopMost = true;
    TransparencyKey = Color.White;
 
    ResumeLayout( false );
    PerformLayout();
 
    Offset = new Point( 10, 0 );
  }
}

You may note that I switched off the AutoSize property. Setting it to true enables the label to automatically expand, and that just means getting wider to fit the text length. The label will not change its height automatically, only width.

A neat trick to wrap text before putting it into the label that I spotted and did not make use of employs a regular expression to do the job:

  WrappedMessage := RegExReplace( 
    LongMessage, "(.{50}\s)", "$1`n" );

Controlling the text and position from the Idling event handler is a trivial two-liner:

  // Move tooltip to current cursor 
  // location and set tooltip text.
 
  _form.Location = p + new Size( _form.Offset );
  _form.SetText( s );

Entire Idling Event Handler Implementation

For better readability, here is the entire Idling event handler implementation in all its glory.

It even includes one slight improvement that is not demonstrated by the ModelessForm_IdlingEvent SDK sample implementation:

If the Revit project is closed while the Idling event is still subscribed to, the UI document may be null. One needs to add a check for that situation as well in the Idling handler, in case the hander relies on an open document.

/// <summary>
/// Idling event handler.
/// </summary>
/// <remarks>
/// We keep the handler very simple. First check
/// if we still have the form. If not, unsubscribe 
/// from Idling, for we no longer need it and it 
/// makes Revit speedier. If the form is around, 
/// check if it has a request ready and process 
/// it accordingly.
/// </remarks>
public void IdlingHandler( 
  object sender, 
  IdlingEventArgs args )
{
  UIApplication uiapp = sender as UIApplication;
  UIDocument uidoc = uiapp.ActiveUIDocument;
 
  if( null == uidoc || _form.IsDisposed )
  {
    uiapp.Idling -= IdlingHandler;
  }
  else // form still exists
  {
    Document doc = uidoc.Document;
    View view = doc.ActiveView;
 
    UIView uiview = GetActiveUiView( uidoc );
 
    Rectangle rect = uiview.GetWindowRectangle();
 
    Point p = System.Windows.Forms.Cursor.Position;
 
    double dx = (double) ( p.X - rect.Left )
      / ( rect.Right - rect.Left );
 
    double dy = (double) ( p.Y - rect.Bottom )
      / ( rect.Top - rect.Bottom );
 
    IList<XYZ> corners = uiview.GetZoomCorners();
    XYZ a = corners[0];
    XYZ b = corners[1];
    XYZ v = b - a;
 
    XYZ q = a
      + dx * v.X * XYZ.BasisX
      + dy * v.Y * XYZ.BasisY;
 
    // If the current view happens to be a 3D view, 
    // we could simply use it right away. In 
    // general we have to find a different one to 
    // run the ReferenceIntersector in.
 
    View3D view3d = GetView3d( doc );
 
    XYZ viewdir = view.ViewDirection;
 
    XYZ origin = q + 1000 * viewdir;
 
    // Find all elements:
 
    //ReferenceIntersector ri
    //  = new ReferenceIntersector( view3d );
 
    // Find all elements except roofs:
 
    ElementFilter f = new ElementCategoryFilter( 
      BuiltInCategory.OST_Roofs, true );
 
    ReferenceIntersector ri 
      = new ReferenceIntersector( f, 
        FindReferenceTarget.Element, view3d );
 
    ReferenceWithContext rc
      = ri.FindNearest( origin, -viewdir );
 
    string s = "Element not found";
 
    if( null != rc )
    {
      Reference r = rc.GetReference();
 
      Element e = doc.GetElement( r );
 
      s = ElementDescription( e );
    }
 
    // Move tooltip to current cursor 
    // location and set tooltip text.
 
    _form.Location = p + new Size( _form.Offset );
    _form.SetText( s );
  }
}

Toggle Tooltip On and Off Commands

To simplify the usage and cooperation with other add-ins, I implemented two trivial read-only external commands calling the external application ShowForm and HideForm methods to toggle my personal tooltips on and off:

[Transaction( TransactionMode.ReadOnly )]
public class CmdTooltipOn : IExternalCommand
{
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    App.Instance.ShowForm( 
      commandData.Application );
 
    return Result.Succeeded;
  }
}
 
[Transaction( TransactionMode.ReadOnly )]
public class CmdTooltipOff : IExternalCommand
{
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    App.Instance.HideForm(
      commandData.Application );
 
    return Result.Succeeded;
  }
}

Conclusion and Download

I hope you find this as useful as I imagine it might become, and look forward to your feedback.

By the way, I will be talking about this sample and the possibilities it demonstrates along with many other topics in my Autodesk University presentation CP4107 on the new Revit 2013 UI API functionality, probably making this the most exciting one of my three AU sessions.

Here is a current snapshot of the entire source code, Visual Studio solution and add-in manifest of the WinTooltip sample application, together the rest of my CP4107 sample material. The latter is based on my DevCamp Revit 2013 UI API samples.

Here are a couple of other items of interest before I wrap up, related to the Revit API, technology and purely human interst.

DWG and Image Export Naming Convention

Saikat Bhattacharya points out that the naming convention for exporting multiple images follows the one used for DWG export: [FileName]-[ViewType]-[ViewName].[image format].

Displaying a Text File from a TaskDialog Command Link

I recently mentioned the order of TaskDialog command links.

Now Saikat Bhattacharya picked up a related issue, on how to define a TaskDialog command link to open up a text file in the local system.

URLs and local system HTML links work fine out of the box. A text file, however, needs special processing. One way to launch it is by using the Process.Start method in the .NET System.Diagnostics namespace. Saikat provides the source.

DesignScript

A very exciting new technology is now publicly available on Autodesk Labs: DesignScript:

• A powerful scripting language for exploratory programming.
• Managing and distinguishing between a generative description of a design (as a script) and the resulting generated model.
• A language to help designers build and analyze complex geometric models that would be difficult to model with interactive techniques.
• Integrated into a host geometry application (currently AutoCAD).

The designer no longer directly models the resulting design: instead she develops a script whose execution generates the model. This enables a completely different kind of design model to be created. The design process is also different. An apparently minor edit to the script can have a profound effect on the generated model, enabling the exploration of a vast array of alternatives, with much less effort than manual interactive modeling. Here is a five-minute video explanation of Design Computation by Robert Aish for Autodesk University last year:

Kean Walmsley provides a very nice explanation and description of the DesignScript sample he implemented for it together with Robert in 2008 for the Design Computation Symposium and AU mainstage presentation.

Now you can try it for yourself. Unfortunately, DesignScript is not yet available for Revit...

Falk on Schafberg

For something completely unrelated to any technology at all, here is a nice little video of my friend Falk recently when we hiked over the Wildhauser Schafberg (sheep mountain) together, clearly illustrating some basic and sympathetic human and ovine commonalities :-)

Detach Workset and TaskDialog Command Link Order

Here is a neat and simple solution using the DialogBoxShowing event to detach and discard worksets by Erik Eriksson of White Arkitketer AB, who already provided a useful workaround to synchronize with central using SendKeys in combination with the Idling and DocumentSynchronizedWithCentral events.

Here is the issue:

Question: We have a need to detach project files without worksets.

For instance, it would be great to just have an option to detach and discard worksets.

Why do we need this?

This would be useful for our in-house tools to diagnose project files. For this to work, we need to have the project files without worksets, because we delete different types of elements and check the file size before and afterwards. To determine a correct file size, we need to compact the files after every operation. This cannot be done programmatically, but, for non-workshared files, it is performed automatically each time the project file is saved.

Currently, we execute the detach and discard operation manually. However, with big projects containing many files, it would be nice to do less of these things manually.

Answer: The API currently does not provide this functionality directly.

However, the Revit 2013 API added some new document handling and worksharing changes which may help. Here is the description from the What's New section in the Revit API help file RevitAPI.chm:

Worksharing properties

The information required to identify a workshared file on the central or local locations has changed due to changes to RevitServer. As a result, the members

• Application.GetRevitServerNetworkHosts
• Application.CurrentRevitServerAccelerator
• Document.WorksharingCentralFilename

replace the properties

• Application.CentralServerName
• Application.LocalServerName
• Document.GetWorksharingCentralModelPath

The new members:

• Application.GetWorksharingCentralGUID(ServerPath serverModelPath)
• Document.WorksharingCentralGUID

provide read access to the worksharing central GUID of the given server-based model. This is applicable only to workshared models saved in Revit 2013 or later.

New overloads for Application.OpenDocumentFile and UIApplication.OpenAndActivateDocument

The new overloads support parameters OpenOptions and OpenOptionsForUI, respectively, to specify how a Revit document should be opened. Both options classes currently offer the ability to detach the opened document from central if applicable.

• The OpenOptions.DetachFromCentralOption property can be set to the default DoNotDetach or to DetachAndPreserve.
• The OpenOptionsForUI.DetachFromCentralOption property can be set to the default DoNotDetach, DetachAndPreserveWorksets or DetachAndPrompt.

In other words, the OpenOptions argument that you pass in to the OpenDocumentFile and OpenAndActivateDocument methods can now use the DetachFromCentral option to specify whether or not a workset-enabled document is detached from its central document.

Response: The new API functionality still does not provide the option of discarding the worksets.

I want the file to be a normal project file again.

OpenOptions holds the same options as OpenOptionsForUI (besides DetachAndPrompt). However, maybe I can catch that dialogue programmatically using the DialogBoxShowing event and override the result...

Success!

This is the code I used to fix it:

  public void OnDialogBoxShowing(
    object sender,
    DialogBoxShowingEventArgs e )
  {
    TaskDialogShowingEventArgs e2 
      = e as TaskDialogShowingEventArgs;
 
    if( null != e2 && e2.DialogId.Equals( 
      "TaskDialog_Detach_Model_From_Central" ) )
    {
      e.OverrideResult( 
        (int) TaskDialogResult.CommandLink2 );
    }
  }

The full implementation of this method actually includes a few more statements taking care of other dialogue boxes, which I omitted here.

I checked the IsWorkshared property after opening the file, and it was set to false. This indicates that it is no longer workshared, which means that the operation to discard the worksets succeeded. When you discard worksets, the workshared central file goes back to being a normal non-workshared project file, just like what you obtain when starting from a normal project template.

One thing I do wonder about is whether CommandLink2 is always below CommandLink1 and above CommandLink3?

Answer: It would appear so, since the description of the TaskDialog.AddCommandLink method clearly states that "CommandLinks will always be shown in the dialog in the order of their ids".

Also, as always, keep in mind that there is no guarantee that this will continue working in future releases. The order of these options can change at any time, and the required functionality might even be added to the official API one of these days.

Congratulations on solving this, Erik, and thank you for sharing it and providing this helpful explanation!

Setting IndependentTag Label to Pick Up a Parameter Value

I'll wrap up with a quick pointer to another AEC DevBlog article by Saikat Bhattacharya on defining the label displayed by an IndependentTag. Unfortunately this does not seem to be possible programmatically. It can however easily be achieved using an appropriate template or tag family configuration.

Ribbon Creation Utility

Creating and populating a ribbon panel is not a very complicated matter, although it normally does require instantiating and manipulating quite a number of different cooperating class instances.

Now Victor Chekalin, or Виктор Чекалин, presents a much simpler solution for this using dedicated wrapper classes.

In his own words:

Create Buttons without Effort

As you know, you can create your own buttons or even your own tab in the Revit ribbon to perform a command.

For me, creating button always wasn't easy. Especially I didn't like to pass the assembly location and name of the external Command class to perform when I click the button. Also, the standard API requires me to create an ImageSource for each button image while I have an image stored in the assembly resources.

To avoid these troubles and ease my life I decided to create a utility which helps me to create my Revit ribbon buttons. The utility I created is really useful for me and I want to share it with everybody.

Here are the main features:

• Fluent interface: You can create all your buttons in one single line of code.
• Command name as generic parameter: You don't need to write the command name as text and set the assembly location.
• Images from resource: You can easily use images from resources.

The sample below illustrates all this.

This is the result in the Revit ribbon:

Look at the source code generating it:

  Ribbon ribbon = new Ribbon( a );
 
  ribbon.Tab( "MyTab" )
    .Panel( "Panel1" )
 
    .CreateButton( "btn1", "Button1", 
      typeof( Command1 ),
      btn => btn
        .SetLargeImage( 
          Resources._1348119708_face_monkey_32 )
        .SetSmallImage( 
          Resources._1348119708_face_monkey_16 ) )
 
    .CreateSeparator()
 
    .CreateButton<Command2>( "btn2", "Button2",
      btn => btn
        .SetLongDescription( 
          "This is a description of the button2" )
        .SetLargeImage( 
          Resources._1348119643_face_glasses_32 ) )
 
    .CreateStackedItems( si => si
 
      .CreateButton<Command3>( "btn3", "Button3",
        btn => btn.SetSmallImage( Resources
          ._1348119594_preferences_system_16 ) )
 
      .CreateButton<Command4>( "btn4", "Button4",
        btn => btn.SetSmallImage( Resources
          ._1348119621_internet_web_browser_16 ) ) )
 
    .CreateSeparator()
 
    .CreateStackedItems( si => si
 
      .CreateButton<Command3>( "btn3_1", "Button3",
        btn => btn.SetSmallImage( Resources
          ._1348119594_preferences_system_16 ) )
 
      .CreateButton<Command4>( "btn4_1", "Button4",
        btn => btn.SetSmallImage( Resources
          ._1348119621_internet_web_browser_16 ) )
 
      .CreateButton<Command1>( "btn1_1", "Button1",
        btn => btn.SetSmallImage( Resources
          ._1348119553_face_smile_big_16 ) ) );

Pretty easy, isn't it?

At first I set the tab, where I want to create my buttons. I can specify my own tab or one of the system tabs, e.g. Autodesk.Revit.UI.Tab.AddIns. If the tab doesn't exist, it will be created. So, you can easily use a tab from a different add-in. You specify a panel to group the buttons on the tab. Next, the most important part, create the buttons. I won't describe how to create the buttons. The code is self-explanatory.

My utility currently supports push button, push button as stacked item and separator.

Here is the compiled assembly.

The source code is available on GitHub. You can also download it as a zip archive file.

It provides the namespaces VCRevitRibbonUtil and VCRevitRibbonUtil.Helpers containing the following classes:

• StackedItem
• Button
• Panel
• Ribbon
• Tab
• Helpers.BitmapSourceConverter

Many thanks to Victor for this neat time and labour saving utility!

Picking Two Points Consecutively

Here is a question on picking points while interacting with a modeless dialogue:

Question: I want to pick two points consecutively using PickPoint.

I am using a modeless dialog, and have a section of code that is called when a button is pressed.

However, after picking the first point, an exception is thrown saying "The user aborted the pick operation".

Do you have a solution for this?

Answer: I implemented a sample application providing an external command PickTwoPoints for you to demonstrate one possible solution.

I use the following code to generate and display a modeless dialogue to the user before the picking is initiated:

  Form DisplayModelessForm( IWin32Window owner )
  {
    System.Windows.Forms.Form form
      = new System.Windows.Forms.Form();
    form.Size = new Size( 300, 100 );
    form.Text = "Pick Two Points Modeless Form";
    form.Show( owner );
    return form;
  }

The form is initially displayed, then hidden again before calling PickPoint.

As always when displaying a modeless form, I define its owner window to be the Revit main frame.

I use my JtWindowHandle wrapper class to convert the IntPtr returned by the Autodesk.Windows.ComponentManager ApplicationWindow property to an IWin32Window, which can be passed in to the form Show method to set its owner:

  /// <summary>
  /// Wrapper class for converting 
  /// IntPtr to IWin32Window.
  /// </summary>
  public class JtWindowHandle : IWin32Window
  {
    IntPtr _hwnd;
 
    public JtWindowHandle( IntPtr h )
    {
      Debug.Assert( IntPtr.Zero != h,
        "expected non-null window handle" );
 
      _hwnd = h;
    }
 
    public IntPtr Handle
    {
      get
      {
        return _hwnd;
      }
    }
  }

The external command Execute method performs the following steps:

• Determine the main Revit application window handle.
• Display the dynamically generated modeless form.
• Hide the form.
• Select the two points.
• Process the two resulting points, in this case by displaying them in the Visual Studio debug output window.
• Redisplay the modeless form.
• Close and terminate.

Here is the whole resulting Execute method mainline code implementing this:

public Result Execute(
  ExternalCommandData commandData,
  ref string message,
  ElementSet elements )
{
  IWin32Window revit_window
    = new JtWindowHandle(
      ComponentManager.ApplicationWindow );
 
  UIApplication uiapp = commandData.Application;
  UIDocument uidoc = uiapp.ActiveUIDocument;
  Selection sel = uidoc.Selection;
 
  using( Form form = DisplayModelessForm( 
    revit_window ) )
  {
    form.Hide();
 
    try
    {
      XYZ p = sel.PickPoint( "Point 1" );
 
      XYZ q = sel.PickPoint( "Point 2" );
 
      Debug.Print( string.Format(
        "The two points you selected are {0} and {1}.",
        PointString( p ), PointString( q ) ) );
    }
    catch( Exception e )
    {
      Debug.Print( e.Message );
    }
 
    form.Show();
  }
  return Result.Succeeded;
}

As it now stands, this can obviously be packaged in an external command using read-only transaction mode, since the database is not affected in any way.

Here is PickTwoPoints.zip containing the complete source code, entire Visual Studio solution and add-in manifest of the PickTwoPoints external command.

Automatically Store Revit Model as Blob in the Cloud

On the cloud and mobile front, Saikat Bhattacharya published an article describing his GbXmlCloudSync add-in demonstrating how to use the DocumentSaved event and the Windows Azure blob storage service to automatically upload each new version of a Revit model to the cloud, for instance for environmental analysis.

This is part of his Windows Azure experiential learning series.

Autodesk 360 Videos for MEP and Structure

On the same topic, here are two new short videos about the use of Autodesk BIM 360 for MEP and structural engineers.

For MEP, this can provide insight into energy consumption, improve visualisation, photorealistic presentation, and CFD simulation. Structural enhancement possibilities include access to simulation tools for more informed decisions, conducting computational heavy simulation earlier and more often, and optimising structural workflows with static and finite analysis tools.

This could be the first step of a move towards the next generation of BIM for anyone, anywhere, at any time, with access to intelligent, model-based workflows through a broad range of cloud-based services providing mobility, accessibility, and infinite computing power.

Here is a freshly published 1 minute and 20 seconds video on Autodesk BIM 360 for MEP engineers:

Here is an even more succinct 1 minute video on Autodesk BIM 360 for structural engineers:

According to some, start-ups rejoice at the reduced simulation costs.

Updating Properties and Announcing Revit LT

Today, exceptionally, a second post, partly to highlight an interesting comment submitted by Jinshou on how to programmatically trigger a refresh of the Revit element properties window, and partly to announce a non-API issue, totally non-API, the imminent arrival of Autodesk Revit LT.

Refreshing Revit Element Properties

If I first invoke the UIApplication OpenAndActivateDocument method, then highlight elements as described in a previous post, the 'properties' window is updated.

The trick is that in order to call OpenAndActivateDocument on the document containing the elements to highlight, you have to first ensure that it is not the active document. To achieve this, I:

• Create an empty RVT file.
• Invoke OpenAndActivateDocument to activate that.
• Invoke OpenAndActivateDocument again on the document of interest.
• Highlight the elements.
• Don't forget to close the empty RVT file when finished.

Many thanks to Jinshou for this interesting hint.

Announcing Autodesk Revit LT

For the nonce, here is an announcement completely unrelated to the Revit API. In fact, the product announced is specifically designed to not be customisable.

Autodesk today announced Autodesk Revit LT software, a new addition to its award winning family of Revit software products. Designed for architects, designers and building industry professionals using 2D workflows who are looking to transition to the Building Information Modeling (BIM) process, Autodesk Revit LT software delivers a focused 3D application to help users create higher-quality and more accurate designs and documentation.

"Autodesk Revit LT reflects our commitment to provide architects, designers and building professionals, particularly those in small firms, the tools they need to ease the transition to get started with – and take advantage of – a BIM workflow," said Amar Hanspal, Autodesk senior vice president, information modeling products. "With Revit LT, customers can deliver higher-quality, more accurate designs and documentation – allowing them to bring projects to market faster and save time and money."

Autodesk Revit LT is built on the Revit platform for BIM and allows users to create designs efficiently with 3D, real-world building objects to produce reliable, coordinated documentation faster. Revit-based applications help deliver better coordination and quality, and can contribute to higher profitability for architects, design professionals and the rest of the building team. Some of the benefits of Revit LT include:

• Work more efficiently with a single, coordinated model that allows users to concurrently design and document building projects. Autodesk Revit LT automatically manages iterative changes to building models throughout the documentation process. As a result, a consistent representation of the building is maintained, helping to improve drawing coordination and reducing errors.
• Design and visualize in 3D. Revit LT allows users to see their designs virtually, improving their understanding of the building and its spaces, and helping them communicate design ideas to clients more clearly and effectively.
• Create photorealistic renderings in the cloud. Users who purchase Autodesk Subscription with Revit LT can render in the cloud directly from the Revit LT interface, enabling them to produce compelling, photorealistic visualizations without tying up their desktop
• Exchange designs in the DWG or RVT file formats. Produce designs in the DWG file format, and experience fluid file exchange with project team members using other Autodesk Revit software applications.

Availability

Autodesk Revit LT 2013 is scheduled to be available within the month in North America and in select countries worldwide. The product is available as a standalone version and as part of the new AutoCAD Revit LT Suite 2013, which includes both Autodesk Revit LT 2013 and AutoCAD LT 2013. Product availability varies by country. Details and purchasing options are available at www.autodesk.com/revitlt

Group My Own Commands in the Ribbon

Here is an issue that has been presented numerous times in the past, and apparently needs to be highlighted again for newbies.

Question: I have implemented a Revit add-in which implements several commands.

Currently, I have added all my commands to the add-in manifest file, as recommended by various examples I found on the Internet. It works and they do indeed appear in the Add-Ins ribbon tab under the 'External Tools' pull-down menu.

The problem with this is that other commands from other companies' add-ins appear in the same place and are mixed up with mine.

Is there some possibility to group my own commands somehow?

I would like to have my commands separated from the other companies' ones.

For example, is it possible to add a parent category for my commands in the 'External Tools' category, or to group them in some other way, for instance by creating a special ribbon category other than 'External Tools'?

Answer: Yes, there are several simple ways to group your commands separately.

You can define your own panel in the Add-Ins tab using the CreateRibbonPanel method. This is the recommended approach.

If you really want, you can also define your own ribbon tab. However, this is not recommended.

The former approach is demonstrated by many examples. For instance, I implemented an absolutely minimal separate add-in tab providing one single button to demonstrate enabling ribbon items in zero document state.

The structural concrete setout point add-in is very slightly more complex, providing two buttons :-)

The ADN training material on the Revit UI includes an entire class on the topic of ribbon customisation which covers almost every possibility provided for creating your own ribbon items. You can either look at the Xtra version (recently updated) or the standard material from the Revit Developer Center.

Read the documentation explaining the ribbon UI exercise, "Revit Ui Lab1 - Ribbon.doc", provided separately for C# and VB in the subdirectories DocsCS and DocsVB of the 2_Revit_UI_API folder.

Sample source code is also provided separately for both C# and VB, respectively:

• 2_Revit_UI_API/SourceCS/1_Ribbon.cs
• 2_Revit_UI_API/SourceVB/1_Ribbon.vb

Read-Only Parameter Workaround

To add a little hint for more advanced Revit API users, another frequently asked question has to do with read-only parameters.

Developers would often like to add parameters that cannot be modified to a family definition. However, the Revit API currently does not provide any support for creating read-only parameters, unfortunately.

One way to make a parameter a little bit harder to modify anyway is to define its value via a formula instead of setting the value directly:

  FamilyParameter p 
    = famMgr.get_Parameter( name );

  if( null == p )
  {
    p = famMgr.AddParameter( name, 
      BuiltInParameterGroup.PG_GENERAL, 
      ParameterType.Text, false );
  }
 
  if( p.StorageType 
    == StorageType.String )
  {
    if( '\"' != val[0] )
    {
      val = "\"" + val + "\"";
    }
    famMgr.SetFormula( p, val );
  }

Video Animated Ribbon Item Tooltip

We already discussed a number of interesting things you can do with the Revit ribbon and user interface, many inspired by Rudolf Honke's exploration of uses of the .NET UI Automation functionality.

Here is a related contribution by Victor Chekalin, or Виктор Чекалин, fleshed out from his answer to Rudolf's question on animating a ribbon item tooltip, discussing the retrieval of embedded resource images:

It is possible to add your own video to a Revit ribbon button tool tip, and I've found a way to achieve this.

This can be achieved using the undocumented AdWindows.dll and UIFramework.dll assemblies located in the Revit program folder.

They provide many interesting classes, as Rudolf Honke already pointed out in his examples using UI Automation.

There is a RibbonToolTip class in the AdWindows.dll assembly. The class provides a property named ExpandedVideo. The next step is to find a class which can contain ToolTip property. This class is Autodesk.Windows.RibbonItem.

So, the idea is to find the correct RibbonItem in the ribbon control and set RibbonToolTip to it.

But here there is the trouble. We can create a PushButton on a Panel using Application.CreatePanel().AddItem(RevitItem) to obtain a Autodesk.Revit.UI.RibbonItem. But we need Autodesk.Windows.RibbonItem.

There are several ways.

The first one – use RevitControl class and iterate all tabs, panels and buttons and find button by name.

We can get RevitControl instance using static property RibbonControl UIFramework.RevitRibbonControl class.

RibbonControl contains exactly Autodesk.Windows.RibbonItem items not a Autodesk.Revit.UI.RibbonItem. It's look like we need.

Here is the code implementing this:

  public Autodesk.Windows.RibbonItem GetRibbonItem( 
    RibbonItem item )
  {
    RibbonControl ribbonControl 
      = RevitRibbonControl.RibbonControl;
 
    foreach( var tab in ribbonControl.Tabs )
    {
      foreach( var panel in tab.Panels )
      {
        foreach( var ribbonItem 
          in panel.Source.Items )
        {
          if( ribbonItem.AutomationName
            == item.Name )
          {
            return ribbonItem as
              Autodesk.Windows.RibbonItem;
          }
        }
      }
    }
    return null;
  }

But there is a second way. The Autodesk.Revit.UI.RibbonItem class has an internal method getRibbonItem which returns Autodesk.Windows.RibbonItem. Interesting. Try to use this method. The reflection helps us.

Here is the code:

  public Autodesk.Windows.RibbonItem GetRibbonItem( 
    RibbonItem item )
  {
    Type itemType = item.GetType();
 
    var mi = itemType.GetMethod( "getRibbonItem", 
      BindingFlags.NonPublic | BindingFlags.Instance );
 
    var windowRibbonItem = mi.Invoke( item, null );
 
    return windowRibbonItem 
      as Autodesk.Windows.RibbonItem;
  }

So, after we get a Autodesk.Windows.RibbonItem we can set RibbonToolTip to it.

For example like this:

  RibbonToolTip toolTip1 = new RibbonToolTip()
  {
    Title = "This is important button1",
    ExpandedContent = 
@"Here you can see swf video from local file. 
The file path is C:/Program Files
/Autodesk/Revit Structure 2013/Program/videos
/GUID-053F3A19-7EFF-48D5-A0FA-AF0C2CC4BD9D-low.swf",        
    ExpandedVideo = new Uri( "C:/Program Files"
      + "/Autodesk/Revit Structure 2013/Program/videos"
      + "/GUID-053F3A19-7EFF-48D5-A0FA"
      + "-AF0C2CC4BD9D-low.swf" ),
    ExpandedImage = BitmapSourceConverter
      .ConvertFromImage( Resources.logoITC_16 )
  };

PROFIT!!!

Also there is a third way to get a Autodesk.Windows.RibbonItem. Create a tab, panel and button directly via RevitControl class. But I didn't find how to set IExtenalCommand to a button.

RevitToolTip.ExpandedVideo supports SWF video. Also I tried a GIF image. The image was shown but didn't animate. Also I tried to set Internet URL. On my computer it doesn't work. Maybe it doesn't work via proxy, or maybe access is denied on video in the internet. Please try and tell me.

To wrap this up, here is the full source code of my solution with test projects displaying video tool tip buttons for both Revit 2012 and 2013.

You may need to re-reference the Revit assemblies to compile them.

The first button loads a video from Revit Structure 201X\Program\videos. If you have not installed RST you won't see the video on the first button. The second button loads a video from the internet, and the third button loads one from the embedded resources. So everyone should be able to see the video on the Button3.

Hope this information is useful for you.

Many thanks to Victor for exploring and explaining this exciting possibility!

Adjusting Beam Cutback

By the way, here is a yet another topic that I wanted to address for a long time, and now Mikako beat me to it: the FamilyInstance ExtensionUtility property allows you to control the joining, cutback and extension behaviour of beams, columns, girders etc. Mikako shows how in her discussion and real-world sample on adjusting cutback programmatically.

Structural Concrete Setout Point Add-in

I am back from my vacation now, having spent a wonderful relaxing time doing all kinds of things not related to the Revit API or computers at all, such as talking, walking, singing, playing music, painting, swimming, meditating, climbing, caving, canoeing and sharing time with friends...

Meanwhile, a whole bunch of interesting issues to share with you have been piling up, new ones keep pouring in, and I still have some long-standing pending posts to get around to as well.

One important utility that I have been wanting to publish for months now is for the automatic placement and management of structural concrete setout points which I implemented together with Paul Hellawell of GHD at the Melbourne DevLab back in March, thus also finally answering Ishfak's request for the full Revit 2013 source code to retrieve real world concrete coordinates.

This is a full-blown end-user-capable little application for the automatic creation of setout points for on-site location and construction of structural elements.

One of the most fascinating aspects of the implementation for me was the amount of choices that we were forced to make between implementing something ourselves programmatically versus discovering the proper way to use built-in Revit functionality to do it automatically for us instead with no work at all on our part.

For instance, we originally defined one single setout point marker type, and started implementing API functionality to select the main points and change their colour.

Happily, we soon found a much simpler solution which requires no programming at all: simply define two separate family types for the minor and major setout point markers with different colours, and let the user select which one to use through the standard Revit user interface. Several other equally important design decisions cropped up, demonstrating the importance of knowing the product well, which Paul luckily does.

They really highlighted the fact how important it is to know the user interface and best standard practices in depth before embarking on a serious programming project, however simple it may seem.

Let's start at the beginning, and reiterate the motivation for this undertaking:

Almost every construction professional has experienced the following kind of situation at some time in their career:

A large complex structure is constructed off-site. When assembled on site, it does not fit exactly. The workers continue nonetheless and force it into place. The error is discovered later and corrected using brute force and post adaption. Overall cost of exercise: days or weeks of delay and painful cost overruns.

This leads to the following important prophylactic task:

The Challenge: Provide a way to find the real world coordinates of the corners of potential elements to be set out in the field, automatically extracting relevant setout points from the model. In this example, we are dealing with concrete structural elements. Ideally, we would like to display these points in a Revit schedule, so that they can be formatted and placed on a drawing sheet. We would like to then define which of the points should be used as main setout points and list them in a schedule, preferably numbered sequentially for readability.

In Practice: Retrieved all the concrete corner point data via the API is not hard, and I presented the solution to retrieve real world concrete coordinates separately in the following three steps:

• Filtering for structural concrete elements.
• Retrieving their corners, i.e. geometry traversal to retrieve unique vertices.
• Converting from Revit model to real-world coordinates.

However, transferring this information directly into a schedule proved to be impossible. Instead we created a family definition containing shared parameters to hold the data required for scheduling. We then place instances of the family at the points extracted from the geometry. Through the API it is now possible to populate the parameters with the X, Y, Z coordinates extracted from the geometry, and add these values to the extracted project location, to convert them to real world coordinates.

Initially, we defined a setout point family with one single type in it. This did not enable the ability to select which points to schedule as main setout points. For this, we created two different family types, SetoutPoint_Major and SetoutPoint_Minor. This allows two separate schedules to be created, one capturing all the points, the other only points defined as major points for use on a drawing sheet for setout.

The schedule listing all points is useful, e.g. for export to a CSV file and subsequent import into a surveying device such as a Trimble, allowing site set-out directly from the model.

The setout point tool extracts the X, Y, Z coordinates of all concrete edges. The generated points can then be interactively marked as Major points (setout point) and renumbered sequentially to provide a schedule of key setout points. The remaining point are schedules as well, e.g. to be saved as a comma delimitated file CSV file to be sent to surveying equipment for site setout.

Usage

Ensure your project contains some elements whose structural material is set to concrete or precast concrete.

You can then click the Get Concrete Corners tool:

The tool automatically analyses al the concrete structural elements' geometry and placed setout point family instances representing a 3D pointer on all the concrete element corner vertices:

The family is defined using the Generic Model family template. The green indicators represent general setout points. You can select the ones you want to change to main setout points, also known as major or key, by simply selecting them and swapping their type to SetoutPoint_Major:

Major setout points are displayed in red instead of green:

The sample project provided below defines two schedules. One of them is populated with all setout points, marking every corner of every piece of concrete:

The second schedule lists only the selected main or major setout points and their coordinates:

Once you have all your key setout points defined, a separate 'Renumber setout Points' external command renumbers them sequentially and adds a SOP (Set Out Point) prefix to their number to differentiate them from the minor points.

The renumbered schedule can now be used on a drawing sheet.

Many thanks to Paul for our initiating this project, his deep Revit knowledge and experience, all the support he provided during the Melbourne Revit API training, and the great evening we had together in Melbourne after the training!

Implementation Details

I already pointed to the discussion of the main technical underpinnings for the retrieval of the concrete corners above, i.e.

• Filtering for structural concrete elements.
• Retrieving their corners, i.e. geometry traversal to retrieve unique vertices.
• Converting from Revit model to real-world coordinates.

Now let's look at some of the aspects of putting this functionality to use and wrapping it into a full-blown end-user application:

• External application and CmdData class
• Shared parameters
• Importance of product usage experience, content and best practices
• Marking all geometry vertices
• Major setout point renumbering

External Application and CmdData Class

The application defines two commands:

• CmdGeomVertices: filter for all relevant concrete structural elements, analyse their geometry, create the setout point markers, and populate their shared parameters to be reflected in the predefined schedules.
• CmdRenumber: renumber the main or major setout points consecutively.

They are presented in a custom ribbon panel defined by an external application.

In order to encapsulate all the information required to populate the ribbon panel push buttons, I define the following CmdData class defining the external command implementation class name, description and tool tip text:

  class CmdData
  {
    public CmdData( 
      string name, 
      string text, 
      string tip )
    {
      Name = name;
      Text = text;
      Tip = tip;
    }
    public string Name { get; set; }
    public string Text { get; set; }
    public string Tip { get; set; }
  }

The two instances can be populated like this:

  static CmdData[] data = new CmdData[] {
 
    new CmdData( 
      "GeomVertices", 
      "Mark Concrete Corners",
      "Place a setout point marker on every concrete corner." ),
 
    new CmdData( 
      "Renumber", 
      "Renumber major", 
      "Renumber major setout points" )
  };

The external application OnStartup method making use of this ends up very simple:

  public Result OnStartup( 
    UIControlledApplication a )
  {
    string path = System.Reflection.Assembly
      .GetExecutingAssembly().Location;
 
    // Create ribbon panel
 
    RibbonPanel p = a.CreateRibbonPanel( Caption );
 
    // Create buttons
 
    List<PushButtonData> buttonData 
      = new List<PushButtonData>( 
        data.Length );
 
    foreach( CmdData cd in data )
    {
      PushButtonData pbd = new PushButtonData(
        cd.Name, cd.Text, path,
        _class_name_prefix + cd.Name );
 
      pbd.ToolTip = cd.Tip;
 
      buttonData.Add( pbd );
    }
 
    p.AddStackedItems( buttonData[0], 
      buttonData[1] );

    return Result.Succeeded;
  }

Lacking icons, my panel does not look quite as impressive as Paul's one shown above, but it does the job:

Shared Parameters

As mentioned above, the functionality to retrieve the concrete corners geometry data has already been described in previous posts.

The question is how to handle this information in order to make it available to the user, populate schedules, etc. We ended up inserting family instances marking all concrete corners as minor setout points, and populating shared parameters on each to encapsulate the required data specifying the host element and its point coordinates. Here is the shared parameter file, slightly simplified for readability:

# This is a Revit shared parameter file.
# Do not edit manually.
*META VERSION MINVERSION
META 2 1
*GROUP ID NAME
GROUP  1 SetOut
*PARAM GUID NAME             DATATYPE ... GROUP VISIBLE
PARAM  .... Key_Setout_Point YESNO        1     1
PARAM  .... Host_Type        TEXT         1     1
PARAM  .... Host_Id          INTEGER      1     1
PARAM  .... X                LENGTH       1     1
PARAM  .... Y                LENGTH       1     1
PARAM  .... Z                LENGTH       1     1
PARAM  .... Point_Number     TEXT         1     1

Shared parameter access is implemented using their GUIDs throughout the code.

Importance of Product Usage Experience, Content and Best Practices

We initially defined a parameter in the setout point family to distinguish between minor and major points, and started working on a separate user interface to toggle between the two and change the family instance colour depending on its current setting.

At a certain point, we discovered that it was vastly simpler to define two separate types within the family instead and use the standard Revit user interface to toggle between those.

It is so important for every add-in developer to know the standard Revit possibilities and best-practice workflows.

That can save huge amounts of unnecessary programming effort, sometimes wasted to fight against the product and its standard paradigms instead of making optimal use of it.

Marking All Geometry Vertices

As said, most of the underlying functionality to retrieve the concrete corner geometry was already presented and discussed.

One additional helper method GetFamilySymbols loads the setout point family, if it is not already present, and retrieves the major and minor setout point symbols:

public static FamilySymbol [] GetFamilySymbols( 
  Document doc, 
  bool loadIt )
{
  FamilySymbol [] symbols = null;
 
  Family family 
    = new FilteredElementCollector( doc )
      .OfClass( typeof( Family ) )
      .FirstOrDefault<Element>( 
        e => e.Name.Equals( FamilyName ) ) 
      as Family;
 
  // If the family is not already loaded, do so:
 
  if( null == family && loadIt )
  {
    // Load the setout point family
 
    using( Transaction tx = new Transaction( 
      doc ) )
    {
      tx.Start( "Load Setout Point Family" );
 
      if( doc.LoadFamily( _family_path, 
        out family ) )
      {
        tx.Commit();
      }
      else
      {
        tx.RollBack();
      }
    }
  }
 
  if( null != family )
  {
    symbols = new FamilySymbol[2];
 
    int i = 0;
 
    foreach( FamilySymbol s in family.Symbols )
    {
      symbols[i++] = s;
    }
 
    Debug.Assert( 
      symbols[0].Name.EndsWith( "Major" ), 
      "expected major (key) setout point first" );
 
    Debug.Assert( 
      symbols[1].Name.EndsWith( "Minor" ), 
      "expected minor setout point second" );
  }
  return symbols;
}

Then, finally, here is the external command mainline pulling it all together, i.e.

• Determine project location transformation to real world coordinates.
• Load or retrieve setout point family symbols.
• Retrieve the relevant structural concrete elements.
• Retrieve element geometry.
• Place a setout point marker family instance on each geometry vertex.
• Check to see whether the required shared parameters have been bound.

Setout points are numbered starting at one each time the command is run with no decoration or prefix.

Here is Execute method implementation performing these tasks:

  UIApplication uiapp = commandData.Application;
  UIDocument uidoc = uiapp.ActiveUIDocument;
  Application app = uiapp.Application;
  Document doc = uidoc.Document;
 
  Transform projectLocationTransform 
    = GetProjectLocationTransform( doc );
 
  // Load or retrieve setout point family symbols:
 
  FamilySymbol [] symbols 
    = GetFamilySymbols( doc, true );
 
  if( null == symbols )
  {
    message = string.Format(
      "Unable to load setout point family from '{1}'.",
      _family_path );
 
    return Result.Failed;
  }
 
  FilteredElementCollector col 
    = GetStructuralElements( doc );
 
  // Retrieve element geometry and place a
  // setout point on each geometry corner.
 
  // Setout points are numbered starting at 
  // one each time the command is run with
  // no decoration or prefix whatsoever.
 
  using( Transaction tx = new Transaction( doc ) )
  {
    tx.Start( "Place Setout Points" );
 
    Options opt = app.Create.NewGeometryOptions();
 
    // On the very first attempt only, run an error 
    // check to see whether the required shared 
    // parameters have actually been bound:
 
    bool first = true;
 
    foreach( Element e in col )
    {
      Solid solid = GetSolid( e, opt );
 
      string desc = ElementDescription( e );
 
      if( null == solid )
      {
        Debug.Print(
          "Unable to access element solid for element {0}.",
          desc );
 
        continue;
      }
 
      Dictionary<XYZ, int> corners
        = GetCorners( solid );
 
      int n = corners.Count;
 
      Debug.Print( "{0}: {1} corners found:", desc, n );
 
      foreach( XYZ p in corners.Keys )
      {
        ++_point_number;
 
        Debug.Print( "  {0}: {1}",
          _point_number, PointString( p ) );
 
        FamilyInstance fi
          = doc.Create.NewFamilyInstance( p,
            symbols[1], StructuralType.NonStructural );
 
        // Add shared parameter data immediately 
        // after creating the new family instance.
        // The shared parameters are indeed added 
        // immediately by Revit, so we can access and
        // populate them.
        // No need to commit the transaction that 
        // added the family instance to give Revit 
        // a chance to add the shared parameters to 
        // it, nor to regenerate the document, we 
        // can write the shared parameter values 
        // right away.
 
        if( first )
        {
          Parameter q = fi.get_Parameter(
            _parameter_x );
 
          if( null == q )
          {
            message = 
              "The required shared parameters "
              + "X, Y, Z, Host_Id, Host_Type and "
              + "Point_Number are missing.";
 
            tx.RollBack();
 
            return Result.Failed;
          }
          first = false;
        }
 
        // Transform insertion point by applying
        // project location transformation.
 
        XYZ r2 = projectLocationTransform.OfPoint( p );
 
        fi.get_Parameter( _parameter_host_type ).Set(
          GetHostType( e ).ToString() );
 
        fi.get_Parameter( _parameter_host_id ).Set(
          e.Id.IntegerValue );
 
        fi.get_Parameter( _parameter_point_nr ).Set(
          _point_number.ToString() );
 
        fi.get_Parameter( _parameter_x ).Set( r2.X );
        fi.get_Parameter( _parameter_y ).Set( r2.Y );
        fi.get_Parameter( _parameter_z ).Set( r2.Z );
      }
    }
 
    tx.Commit();
  }
  return Result.Succeeded;

That's about it... one more little thing:

Major Setout Point Renumbering

Such irrational creatures, these human beings.

Users apparently insist on consecutive numbering of items they deal with.

We therefore implemented a second command named CmdRenumber to renumber the major points.

They are basically renumbered randomly, since all major points are selected using a filtered element collector. We iterate over the result, assign a consecutive number to each instance, and store it in the Point_Number text-valued shared parameter with a "SOP " prefix string _sop_prefix.

The key setout points are family instances with the generic model category and the major setout point type.

The external command Execute implementation thus ends up looking like this:

  UIApplication uiapp = commandData.Application;
  UIDocument uidoc = uiapp.ActiveUIDocument;
  Document doc = uidoc.Document;
 
  FamilySymbol[] symbols
    = CmdGeomVertices.GetFamilySymbols( 
      doc, false );
 
  if( null == symbols )
  {
    TaskDialog.Show( "Setout Points",
      "Setout point family not loaded, "
      + "so no setout points present." );
 
    return Result.Succeeded;
  }
 
  FamilyInstanceFilter instanceFilter
    = new FamilyInstanceFilter( doc, symbols[0].Id );
 
  FilteredElementCollector col
    = new FilteredElementCollector( doc )
      .OfCategory( BuiltInCategory.OST_GenericModel )
      .OfClass( typeof( FamilyInstance ) )
      .WherePasses( instanceFilter );
 
  Guid guid = CmdGeomVertices._parameter_point_nr;
 
  using( Transaction tx = new Transaction( doc ) )
  {
    tx.Start( "Renumber Setout Points" );
 
    int i = 0;
    string s;
 
    foreach( Element p in col )
    {
      s = _sop_prefix + ( ++i ).ToString();
 
      p.get_Parameter( guid ).Set( s );
    }
 
    tx.Commit();
  }
  return Result.Succeeded;

For all further details, please refer to the one and only really trustworthy reference, the full source code.

Here is SetoutPoints.zip including the complete source code, Visual Studio solution, add-in manifest and setout point marker family.

For easier testing, here is also a sample project based on the standard rst_basic_sample_project.rvt with a non-standard project location and the setout point schedules added.

Multi-Version Add-in

This is blog post number 800, in case you are interested. I'll celebrate that fact by going out for a run in the woods after posting.

As we all saw when migrating add-ins from Revit 2012 to Revit 2013, the new version requires an add-in to be compiled using the .NET framework version 4.0. In spite of this, a Revit 2012 add-in can still be loaded into Revit 2013. I created a sample to prove this.

Not only can a Revit 2012 add-in be loaded into Revit 2013, it can even use .NET reflection to access new Revit 2013 API functionality, provided you know what you are doing.

Here is the question that motivated me to look into this topic again:

Question: While migrating to the Revit 2013 API, I ran into problems similar to the ones encountered while migrating The Building Coder samples.

I would like to develop an add-in which is backwards compatible with the previous version of Revit, supporting for example both Revit 2012 and Revit 2013 in one .NET assembly DLL.

Is that possible at all?

Answer: Yes, this is absolutely possible.

This is the complete short answer: in general, the Revit API assemblies are upwards compatible. If you create an add-in using the Revit 2012 API assemblies and make no use of Revit 2013 API features, and all the Revit 2012 API features that you do make use of remained unchanged in Revit 2013, then you can load and execute your 2012 add-in in Revit 2013.

I created a sample to prove this, as part of my eStorage for Revit EstoreFile sample application, available from the Autodesk Labs ADN Plugin of the Month Catalog.

EstoreFile stores and manages the contents of external files in Revit extensible storage on selected elements in the BIM model.

It was originally created and described as part of the samples for the Autodesk University 2011 extensible storage class and lab, as explained in the overview of the AU 2011 Revit and AEC API sessions, and updated for the AEC DevCamp with an additional external command added to support the new Revit 2013 DataStorage element.

Two important requirements were added when packaging the EstoreFile command as a separate plug-in of the month for the labs:

• Support for both Revit 2012 and Revit 2013.
• Support for a help file.

One of the new Revit 2013 add-in integration features is support for contextual help: the user can simply hit F1 on an add-in command button to bring up an Internet URL or a local help file entry.

The contextual help functionality is provided by the ContextualHelp class in the Autodesk.Revit.UI namespace. I can therefore use the presence of this class to determine whether my add-in is running in Revit 2013 (or later), or an earlier release. At the same time, I can store the System.Type of this class to use reflection to access its functionality:

  /// <summary>
  /// Retrieve the Revit 2013 ContextualHelp class 
  /// type if it exists.
  /// </summary>
  static Type _contextual_help_type = null;
 
  /// <summary>
  /// Call this method once only to set the 
  /// ContextualHelp class type if it exists.
  /// This can be used for a runtime detection 
  /// whether we are running in Revit 2012 or 2013.
  /// </summary>
  static void SetContextualHelpType()
  {
    // Create an instance of the RevitAPIUI.DLL 
    // assembly to query its type information:
 
    Assembly rvtApiUiAssembly 
      = Assembly.GetAssembly( typeof( UIDocument ) );
 
    _contextual_help_type = rvtApiUiAssembly.GetType( 
      "Autodesk.Revit.UI.ContextualHelp" );
  }

Now, seeing as I compile this application using the Revit 2012 API, I have no direct access to the new Revit 2013 functionality.

If I wish to make use of it anyway, I can do so using .NET reflection to determine the methods and properties on the system type and making calls to those.

In this case, given a PushButtonData instance 'd', I want to instantiate a new ContextualHelp instance 'ch' and set it on 'd'. The code to achieve this in Revit 2013 looks like this:

  ContextualHelp ch = new ContextualHelp(
    ContextualHelpType.ChmFile, helppath );
 
  d.SetContextualHelp( ch );

The same thing can be achieved using reflection like this:

  /// <summary>
  /// Assign the add-in help file to the 
  /// given ribbon push button contextual help.
  /// This method checks for Revit 2013 at runtime
  /// and uses .NET Reflection to access the 
  /// ContextualHelp class and SetContextualHelp
  /// method which are not available in the 
  /// Revit 2012 API.
  /// </summary>
  void AddContextualHelp( PushButtonData d, int i )
  {
    // Invoke constructor:
 
    ConstructorInfo[] ctors 
      = _contextual_help_type.GetConstructors();
 
    const int contextualHelpType_ChmFile = 3;
 
    object instance = ctors[0].Invoke(
      new object[] { 
      contextualHelpType_ChmFile, 
      HelpPath } ); // + "#" + i.ToString()
 
    // Set the help topic URL
 
    PropertyInfo property = _contextual_help_type
      .GetProperty( "HelpTopicUrl" );
 
    property.SetValue( instance, i.ToString(), null );
 
    // Invoke SetContextualHelp method:
 
    Type pbdType = d.GetType();
 
    MethodInfo method = pbdType.GetMethod( 
      "SetContextualHelp" );
 
    method.Invoke( d, new object[] { instance } );
  }

The external application OnStartup method makes use of this by performing the following steps:

• Determine the contextual help System.Type and infer from its presence whether we are running in Revit 2012 or 2013.
• If we are running in 2013, we can use the contextual help functionality to display the help file, so the separate help command implemented for Revit 2012 is removed. Therefore, I also remove the reference to that command in the help text displayed by the expanded tooltip text.
• Determine the help file path.
• Create the ribbon panel and populate it with buttons for all the commands.
• If we are in 2013, skip adding the help command and add contextual help to each of the other commands instead.

Here is the entire OnStartup method source code:

public Result OnStartup( UIControlledApplication a )
{
  int i;
 
  SetContextualHelpType();
 
  if( HasContextualHelp )
  {
    // Remove the description of the help command 
    // from the long tooltip add-in overview
 
    i = _long_description_tooltip_overview
      .IndexOf( "\r\n\r\nHelp: " );
 
    Debug.Assert( 0 < i, "expected to find "
      + "description of help command in long "
      + "description tootip overview" );
 
    _long_description_tooltip_overview 
      = _long_description_tooltip_overview
        .Substring( 0, i );
  }
 
  ControlledApplication c = a.ControlledApplication;
 
  Debug.Print( string.Format( 
    "EstoreFile: Running in {0} {1}.{2}, "
    + "so contecxtual help is {3}available.", 
    c.VersionName, c.VersionNumber, c.VersionBuild, 
    (HasContextualHelp ? "" : "not ") ) );
 
  Assembly exe = Assembly.GetExecutingAssembly();
  string dllpath = exe.Location;
  string dir = Path.GetDirectoryName( dllpath );
  _help_path = Path.Combine( dir, _help_filename );
 
  if( !File.Exists( _help_path ) )
  {
    string s = "Please ensure that the EstoreFile "
      + "help file {0} is located in the same "
      + " folder as the add-in assembly DLL:\r\n"
      + "'{1}'.";
 
    System.Windows.MessageBox.Show( 
      string.Format( s, _help_filename, dir ),
      _name, System.Windows.MessageBoxButton.OK, 
      System.Windows.MessageBoxImage.Error );
 
    return Result.Failed;
  }
 
  string className = GetType().FullName.Replace(
    "App", "Cmd" );
 
  RibbonPanel rp = a.CreateRibbonPanel( _text );
 
  i = 0;
 
  foreach( string cmd in _commands )
  {
    if( HasContextualHelp && cmd.Equals( "Help" ) )
    {
      break;
    }
 
    PushButtonData d = new PushButtonData(
      cmd, cmd, dllpath, className + cmd );
 
    d.ToolTip = _tips[i];
 
    d.Image = NewBitmapImage( exe, 
      cmd + "16.png" );
 
    d.LargeImage = NewBitmapImage( exe, 
      cmd + "32.png" );
 
    d.LongDescription = _long_tips[i] 
      + _long_description_tooltip_overview;
 
    if( HasContextualHelp )
    {
      AddContextualHelp( d, ++i );
    }
 
    rp.AddItem( d );
  }
  return Result.Succeeded;
}

For the complete source code, Visual Studio solution, and add-in manifest, please refer to the Autodesk Labs eStorage for Revit download.

I trust this answers your question and provides a neat sample to boot.