Introduction to Revit Programming

Revit UI API

Developer Technical Services

© 2014 Autodesk
 Agenda Introduction to Revit Programming

UI Topics
 Ribbon
 User Selection
 Task dialog
 Events
 Dynamic model update

© 2014 Autodesk
 Introduction to Revit Programming

Ribbon API
How to add your own Ribbon buttons
 Ribbon API Introduction to Revit Programming

Overview

 The Ribbon API is the only GUI customization API

 Menus and toolbars need to be migrated to ribbon
 Easy to use
 No WPF knowledge needed
 Guidelines provided
 Ribbon design guidelines.pdf
 Autodesk Icon Guidelines.pdf

© 2014 Autodesk
 Ribbon API Overview Introduction to Revit Programming

Custom ribbon panels are by default added to the Add-Ins tab

Custom ribbon panels can also be placed on the Analyze tab
Custom ribbon tabs can be created (since Revit 2012, max. 20)
External commands are placed under Add-Ins > External Tools
External applications can use custom ribbon panel or tab
 Push button

 Pull-down button

 Single or stacked layout with two or three rows

 Split button

 Radio Group

 Combo box
© 2014 Autodesk
 Ribbon API Classes Introduction to Revit Programming

RibbonPanel
 A panel containing ribbon items or buttons
RibbonItem
 A button, push or pull-down, ComboBox, TextBox, RadioButton, etc.
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
…

© 2014 Autodesk
 Ribbon API Since Revit 2011~ Introduction to Revit Programming

Namespace
Autodesk.Revit.UI

Widgets (SplitButton, ComboBox, TextBox, etc)

 Events for ComboBox and TextBox

Properties
 RibbonItem.Visible
 RibbonItem.LongDescription
 RibbonItem.ToolTipImage
 PushButton.AvailabilityClassName

© 2014 Autodesk
 Lab - Ribbon API Introduction to Revit Programming

© 2014 Autodesk
 Introduction to Revit Programming

User Selection
Point and object(s) selection using the API
 User Selection Introduction to Revit Programming

Overview

Ability to select Object(s), Point, Edge and Face

Add new selection to active collection using:
PickObject()

 PickObjects()
 PickElementsByRectangle()
UIDocument uidoc = new UIDocument(document);
 PickPoint()
Selection choices = uidoc.Selection;

// Choose objects from Revit.

IList<Element> hasPickSome =
choices.PickElementsByRectangle("Select by rectangle");

if (hasPickSome.Count > 0)
{
int newSelectionCount = choices.Elements.Size;
string prompt = string.Format("{0} elements added to Selection.",
newSelectionCount - selectionCount);
TaskDialog.Show("Revit", prompt);
}

© 2014 Autodesk
 User Selection Introduction to Revit Programming

Overview

Ability to specify type of object

 Element, PointOnElement, Edge, Face
Ability to add custom status messages
 StatusbarTip
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);
}

Ability to set the active workplane

 View.SketchPlane
© 2014 Autodesk
 User Selection Introduction to Revit Programming

Selection Filter
ISelection Interface to help filter objects during selection

 AllowElement()
 AllowReference()
public void SelectPlanarFaces(Autodesk.Revit.DB.Document document)
{
UIDocument uidoc = new UIDocument(document);
ISelectionFilter selFilter = new PlanarFacesSelectionFilter();
IList<Reference> faces = uidoc.Selection.PickObjects(
ObjectType.Face, selFilter, "Select multiple planar faces");
}

public class PlanarFacesSelectionFilter : ISelectionFilter

{
public bool AllowElement(Element element)
{
return true;
}

public bool AllowReference(Reference refer, XYZ point)

{
if (refer.GeometryObject is PlanarFace) { return true; }
return false;
}
}

© 2014 Autodesk
 Lab - User Selection
Introduction to Revit Programming

Pick Sampler

© 2014 Autodesk
 Lab - User Selection Introduction to Revit Programming

Create House Pick

<CS>
XYZ pt1 = rvtUIDoc.Selection.PickPoint("Pick the first corner of walls");
XYZ pt2 = rvtUIDoc.Selection.PickPoint("Pick the second corner");

// simply create four walls with orthogonal rectangular profile

// from the two points picked.
List<Wall> walls = RevitIntroVB.ModelCreation.CreateWalls(
rvtUIDoc.Document, pt1, pt2);

// pick a wall to add a front door

SelectionFilterWall selFilterWall = new SelectionFilterWall();
Reference @ref = rvtUIDoc.Selection.PickObject(
ObjectType.Element, selFilterWall, "Select a wall to place a front door");
Wall wallFront = @ref.Element as Wall;

// add a door to the selected wall

RevitIntroVB.ModelCreation.AddDoor(rvtUIDoc.Document, wallFront);
</CS>

© 2014 Autodesk
 Introduction to Revit Programming

Task Dialogs
Revit styled message boxes
 Task Dialogs Introduction to Revit Programming

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

*) progress bar is not available

© 2014 Autodesk
 Task Dialog Introduction to Revit Programming

Overview

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 set

 instructions
 detailed text
 icons
 buttons
 command links
 verification text, etc

© 2014 Autodesk
 Lab - Task Dialog Introduction to Revit Programming

Dialog Sampler

<CS>
// (0) create an instance of task dialog to set more options.
TaskDialog myDialog = new TaskDialog("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 Revit UI Lab 3 Task Dialog";
myDialog.MainContent = "Main content: You can add detailed description here.";

if (stepByStep) myDialog.Show();
</CS>

© 2014 Autodesk
 Lab - Task Dialog Introduction to Revit Programming

Create House Dialog

<CS>
TaskDialog houseDialog = new TaskDialog("Revit UI Labs - Create House Dialog");
houseDialog.MainInstruction = "Create a house";
houseDialog.MainContent = "There are two options to create a house.";
houseDialog.AddCommandLink(TaskDialogCommandLinkId.CommandLink1, "Interactive",
"You will pick two corners of rectangular footprint of a house, and choose where you
want to add a front door.");
houseDialog.AddCommandLink(TaskDialogCommandLinkId.CommandLink2, "Automatic",
"This is will automatically place a house with a default settings.");
houseDialog.CommonButtons = TaskDialogCommonButtons.Cancel;
houseDialog.DefaultButton = TaskDialogResult.CommandLink1;

// show the dialog to the user.

TaskDialogResult res = houseDialog.Show();
</CS>

© 2014 Autodesk
 Introduction to Revit Programming

Events and Dynamic Model Update

Application, Document and Element events
 Events Introduction to Revit Programming

Overview

Notifications triggered on specific actions

Compliant to .NET event standard
 Pre and Post events
 Single event (DocumentChanged and FailureProcessing)

Types :
 Application level
 Document level
 Element level

© 2014 Autodesk
 Events Introduction to Revit Programming

Overview

Also Classified as DB and UI events

 DB events available from Application and Document classes
 UI events available from UIApplication class

Edit model during events using

 Document.IsModifiable
 Document.IsReadOnly

Many of the new pre-events are cancellable

 RevitEventArgs.Cancellable
 RevitAPIPreEventArgs.Cancel

© 2014 Autodesk
 Events Introduction to Revit Programming

Event Handler, Registering and Unregistering events

EventHandler
public void UILabs_DocumentChanged(object
{
sender, DocumentChangedEventArgs args)

// Do something here
}

public Result OnStartup(UIControlledApplication application)

Registering events
{
application.ControlledApplication.DocumentChanged += UILabs_DocumentChanged;
return Result.Succeeded;
}

public Result OnShutdown(UIControlledApplication application)

Unregistering events
{
application.ControlledApplication.DocumentChanged -= UILabs_DocumentChanged;

return Result.Succeeded;
}

© 2014 Autodesk
 Lab - Events Introduction to Revit Programming

// register the document changed event

application.ControlledApplication.DocumentChanged += UILabs_DocumentChanged;

// you can get the list of ids of element added/changed/modified.

Document rvtdDoc = args.GetDocument();

ICollection<ElementId> idsAdded = args.GetAddedElementIds();

ICollection<ElementId> idsDeleted = args.GetDeletedElementIds();
ICollection<ElementId> idsModified = args.GetModifiedElementIds();

// put it in a string to show to the user.

string msg = "Added: ";
foreach (ElementId id in idsAdded)
{
msg += id.IntegerValue.ToString() + " ";
}

© 2014 Autodesk
 Dynamic Model Update Overview
Introduction to Revit Programming

“Ability for a Revit API application to modify the Revit model as a

reaction to changes happening in the model”.

Helps track element addition, modification and deletion

© 2014 Autodesk
 Dynamic Model Update Introduction to Revit Programming

Updaters

Updaters :
Ability to implement a method that is informed of the scope of
changes

Implements the IUpdater interface.

 GetUpdaterId ()
 GetUpdaterName()
 GetAdditionalInformation ()
 GetChangePriority()
 Execute()

© 2014 Autodesk
 Dynamic Model Update Introduction to Revit Programming

Registration and Triggers

Register the Updater

OnStartUp for application level scope

 ExternalCommand
WindowUpdater updater =for
newcommand level scope
WindowUpdater(application.ActiveAddInId );
// Register the updater in the singleton UpdateRegistry class
UpdaterRegistry.RegisterUpdater( updater );

Add Trigger
 Change of Scope - list of ElementIds or list of elements via ElementFilter.
 Change
// Set of Type - addition, deletion and modification
the filter
ElementClassFilter filter = new ElementClassFilter( typeof( Wall ) );
// Add trigger
UpdaterRegistry.AddTrigger(updater.GetUpdaterId(),filter,
Element.GetChangeTypeGeometry());

© 2014 Autodesk
 Lab - Dynamic Model Update Introduction to Revit Programming

// construct our updater.

WindowDoorUpdater winDoorUpdater =
new WindowDoorUpdater(application.ActiveAddInId);

// ActiveAddInId is from addin menifest. register it

UpdaterRegistry.RegisterUpdater(winDoorUpdater);

// tell which elements we are interested in notified.

// we want to know when wall changes it's length.

ElementClassFilter wallFilter = new ElementClassFilter(typeof(Wall));

UpdaterRegistry.AddTrigger(
winDoorUpdater.GetUpdaterId(), wallFilter, Element.GetChangeTypeGeometry());

© 2014 Autodesk
 Introduction to Revit Programming

Conclusion
Where do we go next …
 We have covered… Introduction to Revit Programming

UI Topics
 Ribbon
 User Selection
 Task dialog
 Events
 Dynamic model update

© 2014 Autodesk
 Learning More Introduction to Revit Programming

Online Help, Developer's Guide and SDK Samples

Developer Resources for Revit API
 http://www.autodesk.com/developrevit

Discussion Groups
 http://discussion.autodesk.com > Revit Architecture > Revit API

API Training Classes

 http://www.autodesk.com/apitraining
The Building Coder, Jeremy Tammik's Revit API Blog
 http://thebuildingcoder.typepad.com
ADN AEC Developer Blog
 http://adndevblog.typepad.com/aec/
Developer Wiki
 http://www.autodesk.com/revit-help/?guid=GUID-F0A122E0-E556-4D0D-9D0F-7E72A9315A42

Autodesk Developer Network

 http://www.autodesk.com/joinadn
DevHelp Online for ADN members
 http://adn.autodesk.com

© 2014 Autodesk
 Introduction to Revit Programming

Thank you!

© 2014 Autodesk
 Introduction to Revit Programming

Autodesk is a registered trademark 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.

© 2014 Autodesk, Inc. All rights reserved.