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
2014 Autodesk
RibbonItem.Visible
RibbonItem.LongDescription
RibbonItem.ToolTipImage
PushButton.AvailabilityClassName
Lab - Ribbon API
2014 Autodesk
Introduction to Revit Programming
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
public void PickPoint(UIDocument uidoc)
Ability
to
define
snap
types
for
selection
{
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 :
2014 Autodesk
Application level
Document level
Element level
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
public void UILabs_DocumentChanged(object
EventHandler
{
sender, DocumentChangedEventArgs args)
// Do something here
}
public Result OnStartup(UIControlledApplication application)
{
application.ControlledApplication.DocumentChanged += UILabs_DocumentChanged;
return Result.Succeeded;
}
Registering events
public Result OnShutdown(UIControlledApplication application)
{
application.ControlledApplication.DocumentChanged -= UILabs_DocumentChanged;
Unregistering events
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
new
WindowUpdater(application.ActiveAddInId
);
command
level scope
// 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
of Type - addition, deletion and modification
// Set
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.