Revit 2013 UI API

Jeremy Tammik
Principal Developer Consultant

© 2012 Autodesk
About the Presenter

Jeremy Tammik
Principal Developer Consultant
Developer Technical Services
EMEA, Autodesk SARL
Jeremy is a member of the AEC workgroup of the Autodesk Developer Network ADN
team, providing developer support, training, conference presentations, and blogging on
the Revit API.
He joined Autodesk in 1988 as the technology evangelist responsible for European
developer support to lecture, consult, and support AutoCAD application developers in
Europe, the U.S., Australia, and Africa. He was a co-founder of ADGE, the AutoCAD
Developer Group Europe, and a prolific author on AutoCAD application development.
He left Autodesk in 1994 to work as an HVAC application developer, and then rejoined
the company in 2005.
Jeremy graduated in mathematics and physics in Germany, worked as a teacher and
translator, then as a C++ programmer on early GUI and multitasking projects. He is
fluent in six European languages, vegetarian, has four kids, plays the flute, likes
reading, travelling, theatre improvisation, yoga, carpentry, loves mountains, oceans,
sports, dancing, and especially climbing.
© 2012 Autodesk
Class Summary
 Revit 2013 API add-in integration functionality
 Continue Saikat's 1-3 Revit UI API snapshot which covered
 Control of disciplines and add-in availability
 Assigning commands to keyboard shortcuts
 Moving commands to the quick access toolbar
 Replacing an existing Revit command
 Look in more depth at
 Revit progress bar notifications
 Options dialogue WPF custom extensions
 Embed and control a Revit view
 Drag and drop
 Prerequisites
 .NET programming
 Revit API basics

© 2012 Autodesk
SDK Sample Applications
 ProgressNotifier SDK sample
 Subscribes to progress bar events
 Revit UIAPI SDK sample
 Adding customised tabs to Options dialogue
 Revit preview control
 Drag and drop

© 2012 Autodesk
Agenda
 Revit progress bar notifications
 Options dialogue WPF custom extensions
 Embed and control a Revit view
 Drag and drop

© 2012 Autodesk
Revit progress bar notifications
 Subscribe to ProgressChanged event
 Event handler receives ProgressChangedEventArgs
 Caption – progress bar caption describing operation in progress
 Stage – current stage of the progress bar
 Started, CaptionChanged, RangeChanged, PositionChanged, UserCancelled, Finished
 LowerRange – lower limit of range, always zero
 UpperRange – upper limit of range, any non-zero number
 Position
 Value between zero and UpperRange incremented with "PositionChanged" stage

© 2012 Autodesk
ProgressNotifier SDK Sample
 Display progress information in a stack data structure
 Subscribe to the ProgressChanged event
 Access ProgressChangedEventArgs handler argument properties
 Manage a stack of subtransaction progress information
 Add-Ins > RvtSamples > Basics > ProgressNotifier > Open Document

© 2012 Autodesk
ProgressWatcher DevCamp Sample
public Result Execute(
ExternalCommandData commandData,
ref string message,
ElementSet elements )
{
UIApplication uiapp = commandData.Application;
Application app = uiapp.Application;

app.ProgressChanged
+= new EventHandler<ProgressChangedEventArgs>(
OnProgressChanged );

return Result.Succeeded;
}

void OnProgressChanged(
object sender,
ProgressChangedEventArgs e )
{
double percent = 100.0 * e.Position / e.UpperRange;

Debug.Print( "'{0}' stage {1} position {2} [{3}, {4}] ({5}%)",

e.Caption, e.Stage, e.Position, e.LowerRange, e.UpperRange,
percent.ToString( "0.##" ) );
}
© 2012 Autodesk
Options dialogue WPF custom extensions
 Subscribe to UIApplication DisplayingOptionsDialog event
 Event handler receives DisplayingOptionsDialogEventArgs
 PagesCount property
 Number of Options dialogue tabs including default Revit ones
 AddTab method
 Add a tab with tab name and handler information provided by
TabbedDialogExtension class instance

© 2012 Autodesk
TabbedDialogExtension Class
 Constructor takes two arguments
 WPF user control instance and OK handler
 These cannot be changed
 Methods to get and set contextual help
 Properties to read
 Control – the control
 OnOKAction – the ok handler
 Properties to get and set
 OnCancelAction – the cancel handler
 OnRestoreDefaultsAction – the restore defaults handler

© 2012 Autodesk
public Result Execute(

DevCamp Custom Tab ExternalCommandData commandData,

ref string message,
ElementSet elements )
{
public partial class UserControl1 : UserControl UIApplication uiapp =
{ commandData.Application;
string _name;
uiapp.DisplayingOptionsDialog
public UserControl1( string name ) += new EventHandler<
{ DisplayingOptionsDialogEventArgs>(
_name = name; OnDisplayingOptionsDialog );

InitializeComponent(); return Result.Succeeded;

} }

private void button1_Click( void OnDisplayingOptionsDialog(

object sender, object sender,
RoutedEventArgs e ) DisplayingOptionsDialogEventArgs e )
{ {
TaskDialog.Show( _name, "I was clicked..." ); UserControl1 c = new UserControl1(
} "DevCamp User Control" );

public void OnOK() e.AddTab( "DevCamp Custom Tab",

{ new TabbedDialogExtension(
TaskDialog.Show( _name, "OK" ); c, c.OnOK ) );
} }

public void OnCancel()

{
TaskDialog.Show( _name, "OnCancel" );
}

public void OnRestoreDefaults()

{
TaskDialog.Show( _name, "OnRestoreDefaults" );
}
}

© 2012 Autodesk
Embed and control a Revit view
 PreviewControl Class
 Present a preview control to browse the
Revit model
 Input document and view id
 Form or window host must be modal
 View can be any graphical view, i.e.
printable
 View can be manipulated by view cube
 Visibility and graphical settings are
effective
 User interaction requires an open
transaction (in Quasar RP only?)
 UIAPI SDK sample

© 2012 Autodesk
Using a Revit preview control
 Create a standard .NET form
 Insert WPF host
System.Windows.Forms.Integration.ElementHost

 Populate with Revit preview control

elementHost.Child = new PreviewControl( doc, view.Id );

 Dispose after use

PreviewControl vc = elementHost.Child
as PreviewControl;

if( vc != null ) { vc.Dispose(); }

© 2012 Autodesk
Determine Printable Views
IEnumerable<View> views
= new FilteredElementCollector( doc )
.OfClass( typeof( View ) )
.Cast<View>()
.Where<View>( v => v.CanBePrinted );

© 2012 Autodesk
PreviewControlSimple DevCamp Sample
using( PreviewControl pc
= new PreviewControl( doc, view.Id ) ) using( Transaction tx = new
{ Transaction( doc ) )
{
#if CREATE_FORM_BY_CODE tx.Start(
using( System.Windows.Forms.Form form "Display Simple Revit Preview" );
= new System.Windows.Forms.Form() )
{
ElementHost elementHost = new ElementHost(); View view = doc.ActiveView;

elementHost.Location
DisplayRevitView( doc, view,
= new System.Drawing.Point( 0, 0 );
revit_window );
elementHost.Dock = DockStyle.Fill;
elementHost.TabIndex = 0; tx.Commit();
elementHost.Parent = form;
}
elementHost.Child = pc;

form.Text = _caption_prefix + view.Name;

form.Controls.Add( elementHost );
form.Size = new Size( 400, 400 );
form.ShowDialog( owner );
}
#else // if not CREATE_FORM_BY_CODE
Form1 form = new Form1( pc );
form.ShowDialog( owner );
#endif // CREATE_FORM_BY_CODE

© 2012 Autodesk
Drag and Drop API
 New static UIApplication DoDragDrop method, two overloads
 DoDragDrop( ICollection<string> )
 Initiate standard built-in Revit drag and drop operation
 Collection of file names
 DoDragDrop( object, IDropHandler )
 Initiate drag and drop operation with a custom drop implementation
 Designed for use in a modeless form
 The only Revit API method not requiring valid Revit API context

© 2012 Autodesk
Drag and Drop a List of Files
 One AutoCAD format or image file dragged onto Revit
 A new import placement editor is started to import the file
 More than one AutoCAD format or image files dragged
 A new import placement editor is started for the first file
 One family file dragged onto Revit
 The family is loaded, and an editor started to place an instance
 More than one family file dragged onto Revit
 All the families are loaded
 More than one family file including other format files dragged
 Revit tries to open all the files
 Valid file or list of files is passed
 Revit does its best to use them appropriately
 Any files are not usable
 Failure is signalled to user, no exception is thrown, add-in is not notified

© 2012 Autodesk
Initiating Standard Drag and Drop
private void listBox1_MouseMove(
object sender,
MouseEventArgs e )
{
if( System.Windows.Forms.Control.MouseButtons
== MouseButtons.Left )
{
FamilyListBoxMember member
= (FamilyListBoxMember) listBox1.SelectedItem;

// Use standard Revit drag and drop behavior

List<String> data = new List<String>();

data.Add( member.FullPath );

UIApplication.DoDragDrop( data );
}
}

© 2012 Autodesk
Custom Drag and Drop Handler
public class LoadedFamilyDropHandler : IDropHandler
private void listView_MouseMove(
{
object sender,
public void Execute(
MouseEventArgs e )
UIDocument uidoc,
{
object data )
if( Control.MouseButtons
{
== MouseButtons.Left )
ElementId familySymbolId = (ElementId) data;
{
ListViewItem selectedItem
FamilySymbol symbol = uidoc.Document.GetElement(
= listView1.SelectedItems
familySymbolId ) as FamilySymbol;
.Cast<ListViewItem>()
.FirstOrDefault<ListViewItem>();
if( symbol != null )
{ if( selectedItem != null )
uidoc.PromptForFamilyInstancePlacement( {
symbol ); LoadedFamilyDropHandler myhandler
} = new LoadedFamilyDropHandler();
}
} UIApplication.DoDragDrop(
selectedItem.Tag, myhandler );
}
}
}

© 2012 Autodesk
DevCamp Drag and Drop Sample

© 2012 Autodesk
Summary and
Further Reading

© 2012 Autodesk
Class Summary
 Revit 2013 API add-in integration functionality
 Continue Saikat's 1-3 Revit UI API snapshot
 Look in more depth at
 Revit progress bar notifications
 Options dialogue WPF custom extensions
 Embed and control a Revit view
 Drag and drop

© 2012 Autodesk
Materials
 Sample Code
 ProgressWatcher
 AddOptionsTab
 PreviewControlSimple
 DragDropApi

© 2012 Autodesk
Learning More
 Revit Developer Center: DevTV introduction, SDK, Samples, API Help
 http://www.autodesk.com/developrevit
 Developer Guide and Online Help
 http://www.autodesk.com/revitapi-wikihelp
 Revit API Webcasts and Trainings
 http://www.adskconsulting.com/adn/cs/api_course_sched.php > Revit API
 Discussion Group
 http://discussion.autodesk.com > Revit Architecture > Revit API
 API Training Classes
 http://www.autodesk.com/apitraining
 ADN AEC DevBlog
 http://adndevblog.typepad.com/AEC
 The Building Coder, Jeremy Tammik's Revit API Blog
 http://thebuildingcoder.typepad.com
 ADN, The Autodesk Developer Network
 http://www.autodesk.com/joinadn
 DevHelp Online for ADN members
 http://adn.autodesk.com

© 2012 Autodesk
Autodesk, AutoCAD, Civil 3D, DWG, Green Building Studio, Navisworks, and Revit are registered trademarks or trademarks of Autodesk, Inc., and/or its subsidiaries and/or affiliates in the USA and/or other countries. All other brand names, product names,
or trademarks belong to their respective holders. Autodesk reserves the right to alter product and services offerings, and specifications and pricing at any time without notice, and is not responsible for typographical or graphical errors that may appear in this
document.

© ©2012
2012Autodesk
Autodesk, Inc. All rights reserved.