© 2012 autodesk cp3272 : snapshot of the autodesk® revit® user interface api saikat bhattacharya...
TRANSCRIPT
© 2012 Autodesk
CP3272 : Snapshot of the Autodesk® Revit® User Interface API Saikat BhattacharyaSenior Developer ConsultantAutodesk Developer Network
© 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.
© 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.
© 2012 Autodesk
About the presenter
Saikat BhattacharyaDeveloper 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.
© 2012 Autodesk
Agenda • Tabs• Panels• Controls (UI Widgets) • Contextual Help Menu• Keyboard Shortcuts• Quick Access Toolbar• Replacing Revit commands
Status Bar
Task Dialog
© 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)
© 2012 Autodesk
Ribbon API
© 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
© 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
© 2012 Autodesk
Persisting Ribbon Tab (locking)
Drag the panel to make it floating
OR
Uncheck this setting:
© 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’
© 2012 Autodesk
Ribbon Panel Creation
© 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
© 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
…
© 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(),
SplitButtonCurrentButton,
IsSynchronizedWithCurrentItem,
PushButton
AssemblyName, AvailabilityClassName,
ClassName, LongDescription
ToggleButton
TextBox
Image, PromptText, SelectTextOnFocus, ShowImageAsButton, Value, Width
© 2012 Autodesk
Ribbon Controls
Tooltips Using ToolTip property Extended tooltip displayed using LongDescription and ToolTipImage If no tooltip is set, RibbonItem.ItemText is displayed
© 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
© 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; } } }
© 2012 Autodesk
External Command Availability
For External commands from External Tools drop down list Use <VisibilityMode> in AddIn Manifest file Control over flavor, project vs. family editor mode, etc. Use <AvailabilityClassName> 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
© 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
© 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; } }
© 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
© 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
© 2012 Autodesk
AU Sample - Ribbon API
© 2012 Autodesk
Task Dialogs
© 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
© 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
© 2012 Autodesk
Methods and Properties
WasVerificationChecked() TitleAutoPrefix DefaultButton CommonButtons
None, Ok, Yes, No, Cancel, Retry, Close
© 2012 Autodesk
AU Sample - Task Dialogs
<CS> //' (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();</CS>
© 2012 Autodesk
User Selection and Status Bar
© 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()
© 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()
© 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); }
© 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()
© 2012 Autodesk
Selection Filter
ISelection interface to help filter objects during selection AllowElement() AllowReference()
Pick methods with ISelection overload PickElementsByRectangle() PickObject() PickObjects()
© 2012 Autodesk
Selection Filter public void SelectPlanarFaces(Autodesk.Revit.DB.Document document) { UIDocument uidoc = new UIDocument(document); ISelectionFilter selFilter = new PlanarFacesSelectionFilter(document); IList<Reference> 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; } }
© 2012 Autodesk
AU Sample - User Selection and Status Bar
© 2012 Autodesk
SDK Samples
© 2012 Autodesk
Ribbon SDK Sample
Displays Creation of RibbonPanel, PushButton, PulldownButton, Stackable Buttons, RadioButtonGroup, TextBox, SplitButton
© 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.
© 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
© 2012 Autodesk
Learn More
Resources on your system Software Development Kit
Samples Documentation Tools - Autodesk Revit® LookUp and Add-In Manager
© 2012 Autodesk
Learn More
Resources Online ADN Open
Latest SDK DevTVs API Training Material
Blogs ADN AEC DevBlog The Building Coder: By Jeremy Tammik
Revit API Discussion Forum Autodesk Developer Network
© 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!
© 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.