© 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.