1. © 2012 Autodesk CP3272 : Snapshot of the Autodesk® Revit® User Interface API Saikat Bhattacharya Senior Developer Consultant Autodesk Developer Network

2. © 2012 Autodesk Class Summary This class aims to take a “snapshot” of the Revit user interface, providing an overview of all the customization possibilities over UI. We shall cover the customization with ribbons, Quick Access Toolbar, task dialogs, replacing Revit commands with custom commands, etc. using the Revit 2013 API. After attending this class, you should have a fair understanding of the possibilities of customizing Revit user interface and be able to better integrate your plug-ins in terms of the look and feel of Revit.

3. © 2012 Autodesk Learning Objectives At the end of this class, you will:  Have a complete overview of the UI customization with Revit API.  Be able to work with the Ribbon API, status bars, task dialogs.  Know about Revit 2013 API including contextual help, replacing Revit commands implementation, discipline controls.  Have some additional inputs on commonly asked UI customization requirements.

4. © 2012 Autodesk About the presenter Saikat Bhattacharya Developer Technical Services Autodesk Developer Network Saikat is a member of the AEC workgroup of the Autodesk Developer Network (ADN) team, providing evangelism, support, trainings and delivering technical presentations to the third party developers who are part of the ADN. He joined Autodesk in 2004 as Technical Consultant with the Autodesk Consulting group and then joined the ADN team. Saikat has prior experience as GIS software developer and as a project architect with the construction industry. He holds a Bachelors degree in Architecture and a Master of Science degree.

5. © 2012 Autodesk Agenda Tabs Panels Controls (UI Widgets) Contextual Help Menu Keyboard Shortcuts Quick Access Toolbar Replacing Revit commands Tabs Panels Controls (UI Widgets) Contextual Help Menu Keyboard Shortcuts Quick Access Toolbar Replacing Revit commands Status Bar Task Dialog

6. © 2012 Autodesk The UI API topics will be continued in … CP4107 - Let's Face It: New Autodesk® Revit® 2013 User Interface API Functionality (By Jeremy Tammik, Autodesk Developer Network)

7. © 2012 Autodesk Ribbon API

8. © 2012 Autodesk Overview  The Ribbon API is the GUI customization API  Easy to use  No WPF knowledge needed  Ribbon and Icon design guidelines:  Ribbon Guidelines section in API Developer Guide  Icon Guidelines.pdf in SDK  Part of Autodesk.Revit.UI (in RevitAPIUI dll)  Used with IExternalApplication

9. © 2012 Autodesk Ribbon Tabs  Can create new custom ribbon tab  Limit to 20 custom ribbon tabs  Ribbon panels can be added to  Add-Ins (default)  Analyze  Custom tab

10. © 2012 Autodesk Persisting Ribbon Tab (locking)  Drag the panel to make it floating OR  Uncheck this setting:

11. © 2012 Autodesk Ribbon Panel  External applications on custom ribbon panel  Panel contains a number of ribbon items or buttons  Push button  Pull down button  Single or stacked layout with two or three rows  Split button  Radio buttons  Combo box  Text box  SlideOut panel  External commands under ‘External Tools’

12. © 2012 Autodesk Ribbon Panel Creation

13. © 2012 Autodesk Panel Name vs Panel Title  Panel.Name  Represents Name  Two panels cannot have same name  Panel.Title  represents text on Panel  Two panels can have same Title  Use UIControlledApplication.GetRibbonPanels()  To check for conflicts

14. © 2012 Autodesk Ribbon Classes  RibbonPanel  A ribbon panel in the Add-Ins/Analyze/Custom tab  A panel contains a number of ribbon items or buttons  RibbonItem  A button, push or pull-down, ComboBox, TextBox, RadioButton, etc  Exposes properties like Visible, Enabled.  PushButton, PushButtonData  Manage push button information  PulldownButton, PulldownButtonData  Manage pull-down button information  SplitButton, SplitButtonData  Manage split button information  ComboBox, ComboBoxData  Manage combo box information  …

15. © 2012 Autodesk Ribbon Class Hierarchy RibbonItem Get/SetContextualHelp(), Enabled, ToolTip, Visible, ItemText, LongDescription, Name, etc ComboBox AddItem(), GetItems(), AddSeparator(), Current, Image ComboBoxMember GroupName, Image RadioButtonGroup AddItem(), GetItems(), Current, RibbonButton Image, IsEnabledByContext, LargeImage, PullDownButton AddPushButton(), AddSeparator(), GetItems(), SplitButton CurrentButton, IsSynchronizedWithCurrentItem, PushButton AssemblyName, AvailabilityClassName, ClassName, LongDescription ToggleButton TextBox Image, PromptText, SelectTextOnFocus, ShowImageAsButton, Value, Width

16. © 2012 Autodesk Ribbon Controls Tooltips  Using ToolTip property  Extended tooltip displayed using LongDescription and ToolTipImage  If no tooltip is set, RibbonItem.ItemText is displayed

17. © 2012 Autodesk Ribbon Controls Associating Images  Using LargeImage property  32 by 32 pixels  Non stacked ribbon items  Pull down buttons  Using Image property  16 by 16 pixels  Used in Quick Access Toolbar  Stacked buttons  Text boxes  Combo boxes  Resolution: 96 DPI

18. © 2012 Autodesk External Command Button Availability IExternalCommandAvailability interface  Controls whether an push or radio button may be pressed  Passes the application and a set of categories of selected items  Controls ExternalCommand via.addin file  Should share same assembly with addin External Command pushButton.AvailabilityClassName = "SnapshotRevitUI_CS.SampleAccessibilityChecker"; class SampleAccessibilityChecker : IExternalCommandAvailability { public bool IsCommandAvailable(Autodesk.Revit.UI.UIApplication applicationData, CategorySet selectedCategories) { View activeView = applicationData.ActiveUIDocument.Document.ActiveView; if (ViewType.ThreeD == activeView.ViewType) { return true; } else { return false; } } }

19. © 2012 Autodesk External Command Availability  For External commands from External Tools drop down list  Use in AddIn Manifest file  Control over flavor, project vs. family editor mode, etc.  Use to control greyed out depending on context  For External Applications  Use ProductType enum to check flavor of Revit  Accessed on StartUp from UIControlledApp.ControlledApplication.Product

20. © 2012 Autodesk Availability of Items in Zero Document State  Button disabled in zero document state  Implement IExternalCommandAvailability to return True  AvailabilityClassName assignment  Before adding ribbon item to panel  Or after adding button to panel

21. © 2012 Autodesk Ribbon API – What’s New Discipline Controls  Determine visibility based on available disciplines  Set discipline status  Available in Autodesk Revit 2013 pushButtonData1.AvailabilityClassName = SnapshotRevitUI_CS.ApplicationAvailabilityChecker"; class ApplicationAvailabilityChecker : IExternalCommandAvailability { public bool IsCommandAvailable(UIApplication applicationData, CategorySet selectedCategories) { Application revitApplication = applicationData.Application; if (revitApplication.IsArchitectureEnabled || revitApplication.IsSystemsEnabled) return true; else return false; }

22. © 2012 Autodesk Ribbon API – What’s New Contextual (F1) help  Usage:  linking to an external URL,  launching a locally installed help file,  linking to a topic on the Autodesk help wiki  RibbonItem.SetContextualHelp()  Invoke the contextual help at any arbitrary time within your add-in  ContextualHelp.Launch() Support for Keyboard Shortcuts and Quick Access Toolbar  assignments preserved if add-ins are added, removed or changed

23. © 2012 Autodesk Replace Command Implementation  Ability to replace the existing Revit command with add-in routine  Located in any tab, application menu and right-click menus  RevitCommandId  Helps look up and retrieve an object representing Revit Command Id  AddInCommandBinding  Provides ability to override the Revit command implementation  Provides Executed and CanExecute events  Executed event contains the alternate implementation

24. © 2012 Autodesk AU Sample - Ribbon API

25. © 2012 Autodesk Task Dialogs

26. © 2012 Autodesk Task Dialogs – Overview  A modal dialog with set of controls  Revit style alternative to simple Windows message box.  Used when system needs to  Provide information  Ask a question  Allow users to select options to perform task

27. © 2012 Autodesk Creation and Purpose  Two ways to create task dialogs:  Construct TaskDialog, set properties and use instance method Show()  Instance of Autodesk.Revit.UI.TaskDialog  Use one of the static Show() methods to show in one step  And use it to get/set  instructions,  detailed text,  icons,  buttons,  command links,  verification text, etc

28. © 2012 Autodesk Methods and Properties  WasVerificationChecked()  TitleAutoPrefix  DefaultButton  CommonButtons  None, Ok, Yes, No, Cancel, Retry, Close

29. © 2012 Autodesk AU Sample - Task Dialogs //' (0) create an instance of task dialog to set more options. TaskDialog myDialog = new TaskDialog("Snapshot of Revit UI Labs - Task Dialog Options"); //' (1) set the main area. these appear at the upper portion of the dialog. //' myDialog.MainIcon = TaskDialogIcon.TaskDialogIconWarning; //' or TaskDialogIcon.TaskDialogIconNone. myDialog.MainInstruction = "Main instruction: This is Snapshot of Revit UI Lab on TaskDialog"; myDialog.MainContent = "Main content: You can add detailed description here."; if (stepByStep) myDialog.Show();

30. © 2012 Autodesk User Selection and Status Bar

31. © 2012 Autodesk User Selection - Overview  Ability to select Object(s), Point, Edge and Face  Add new selection with status prompt message using:  PickObject()  PickObjects()  PickBox()  PickElementsByRectangle()  PickPoint()

32. © 2012 Autodesk User Selection - Overview  Ability to specify type of object  Element, PointOnElement, Edge, Face  Ability to add custom status messages to Status Bar  Pick functions overloads with String parameter  Ability to set the active workplane  View.SketchPlane()

33. © 2012 Autodesk User Selection - Overview  Ability to define snap types for selection public void PickPoint(UIDocument uidoc) { ObjectSnapTypes snapTypes = ObjectSnapTypes.Endpoints | ObjectSnapTypes.Intersections; XYZ point = uidoc.Selection.PickPoint(snapTypes, "Select an end point or intersection"); string strCoords = "Selected point is " + point.ToString(); TaskDialog.Show("Revit", strCoords); }

34. © 2012 Autodesk 3D Point Selection  PickPoint() only works for 2D point selection  For 3D point selection:  Know the plane on which the point has to be picked  Prompt to select face of an element  Use this to create new plane  Create a new sketch plane using this plane  Use this to set the active work plane  Show this sketch plane  Prompt user to select point using PickPoint()

35. © 2012 Autodesk Selection Filter  ISelection interface to help filter objects during selection  AllowElement()  AllowReference()  Pick methods with ISelection overload  PickElementsByRectangle()  PickObject()  PickObjects()

36. © 2012 Autodesk Selection Filter public void SelectPlanarFaces(Autodesk.Revit.DB.Document document) { UIDocument uidoc = new UIDocument(document); ISelectionFilter selFilter = new PlanarFacesSelectionFilter(document); IList faces = uidoc.Selection.PickObjects(ObjectType.Face, selFilter, "Select multiple planar faces"); } public class PlanarFacesSelectionFilter : ISelectionFilter { Document doc = null; public PlanarFacesSelectionFilter(Document document) { doc = document; } public bool AllowElement(Element element) { return true; } public bool AllowReference(Reference refer, XYZ point) { if (doc.GetElement(refer).GetGeometryObjectFromReference(refer) is PlanarFace) { return true; } return false; }

37. © 2012 Autodesk AU Sample - User Selection and Status Bar

38. © 2012 Autodesk SDK Samples

39. © 2012 Autodesk Ribbon SDK Sample  Displays Creation of  RibbonPanel,  PushButton,  PulldownButton,  Stackable Buttons,  RadioButtonGroup,  TextBox,  SplitButton

40. © 2012 Autodesk Selections SDK Sample  Pick Elements to be deleted  Pick a point on wall face, and place window at the point  Pick a face, set the work plane on it, pick a point on the work plane as center for circle  Pick an element and a point from dialog, move element to picked point.

41. © 2012 Autodesk ExternalCommand SDK Sample  RevitAddInUtility  create\edit.addin manifest file,  retrieve information from manifest file  get installed Revit product information  New Features of External Command registration  Visibility Mode  IAvailabilityClass  Icon and Tooltips  Localization

42. © 2012 Autodesk Learn More Resources on your system  Software Development Kit  Samples  Documentation  Tools - Autodesk Revit® LookUp and Add-In Manager

43. © 2012 Autodesk Learn More Resources Online  ADN Open ADN Open  Latest SDK  DevTVs  API Training Material  Blogs  ADN AEC DevBlog ADN AEC DevBlog  The Building Coder: By Jeremy Tammik The Building Coder  Revit API Discussion Forum Revit API Discussion Forum  Autodesk Developer Network Autodesk Developer Network

44. © 2012 Autodesk Thank you! Thank you very much for your interest and attention! Wish you much success with the Revit API and your application development!

45. © 2012 Autodesk Autodesk, AutoCAD* [*if/when mentioned in the pertinent material, followed by an alphabetical list of all other trademarks mentioned in the material] 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 Autodesk, Inc. All rights reserved.