I am in vacation in Italy, and trying not to work.
There is one project that I had in mind for quite a while, though, and will start addressing now anyway during this break: I plan to publish the contents of the Revit API documentation 'What's New' sections from the previous few releases of the Revit API help file RevitAPI.chm here, so that they become included in future Internet searches.
The reason for this is that I have found them to be a very valuable source of information. I regularly look for answers in these document sections myself first of all when I encounter a question in an API area that I am not familiar with.
So let's start chronologically, with the Revit 2010 API news.
Well, on second thoughts, the Revit 2008 and 2009 API releases also included some 'What's New' information in the form of an 'API Changes' folder containing XML files listing the additions and removals, which I will simply provide for download right here:
For Revit the 2010 API, I actually extracted the following from the document 'Revit Platform API Changes and Additions.doc' provided in the Revit 2010 SDK, which lists the same information as the help file.
I plan to follow up with the corresponding information for the Revit 2011, 2012 and 2013 APIs by and by.
Major Enhancements and Modifications Affecting the Revit 2010 API
New Revit user interface
Autodesk Revit 2010 offers a new user-interface system based on Ribbons. The API has been modified to support customization of the Ribbon user-interface in a similar manner to what was supported in previous releases for toolbars and menus.
External commands registered directly to Revit via the Revit.ini file are now located on the “Add-ins” tab under the “External commands” pulldown. No code changes are required to move the buttons to this location. The Add-ins tab will be automatically displayed if any external command is registered with Revit.
External applications can register and lay out panels on the Add-ins tab of the Ribbon. Custom panels may be given an application-specified name, and may contain:
- Pushbuttons – a single button with label and icon that invokes a command when pressed.
- Pulldown buttons – a button with label and icon that opens a menu with different choices when pressed.
- Separators – a vertical line separating panel components.
Pushbuttons and Pulldown buttons may be created as large size, or stacked in sets of 2 or 3.
The API for creating Ribbon Panels is completely different from the Toolbar and Menubar API. External applications which added content to the toolbars and menus will need to be modified to create Ribbon panel(s) instead.
Family Creation API
The Family Creation API provides programmatic access for creation and modification of the contents of Revit Family documents. Geometric data, Family Types, and other information that can be specified through the Revit Family Editor can now be specified via the API. As a result of this project, API external commands are now displayed while editing a family document in the Family Editor. API access to in-place family editing is still restricted. The project introduces the class Autodesk.Revit.FamilyManager, which allows access to family types and parameters. Using this class you can add and remove types, add and remove family and shared parameters, set the value for parameters in different family types, and define formulas to drive parameter values.
The Category and Categories classes have been enhanced and a new GraphicsStyle class has been created to provide control of the appearance of Revit families.
The new class FamilyItemFactory provides the ability to create elements in families. Access this class through the Document.FamilyCreate property. It includes the following methods:
- NewBlend
- NewDimension
- NewDuctConnector (in Revit MEP only)
- NewElectricalConnector (in Revit MEP only)
- NewExtrusion
- NewFamilyInstance
- NewModelText
- NewPipeConnector (in Revit MEP only)
- NewRevolution
- NewSketchPlane
- NewSweep
- NewSweptBlend
- NewSymbolicCurve
- NewTextNote
The new class ItemFactoryBase provides the ability to create elements both in project and family documents and includes the NewAlignment method.
New document methods – Document.LoadFamily and Document.EditFamily – are introduced to bring families from the Family Editor to the Project environment and vice versa. These methods can be used to examine the contents of the family in terms of its elements, parameters and types; as a result, the properties of Family which access the contents have been removed (Family.SolidForms, Family.VoidForms, Family.Components, Family.LoadedSymbols, Family.Others).
New Events
The Revit API offers totally revamped events that allow an application to subscribe to events taking place in the Revit user interface or in API workflows. In all of the new events, events now occur before and after various triggering actions (known as "pre" and "post" events). Many of the new pre-events are cancellable, offering the API application the ability to prevent the event from taking place based on criteria it cares about. (It is the responsibility of the event subscriber to inform the user of the reason for the cancellation).
Events that existed before release 2010 have been marked Obsolete. You should use the new events added in this release to cover situations like:
- Document creation
- Document opening
- Document saving
- Document saving as (new filename)
- Document closing
- Dialog box showing
The dialog box showing event has been restructured to support notification by Revit when task dialogs are shown.
The new events added in Revit 2010 are:
- File export
- File import
- View printing
- Document printing
- View activating
- Document synchronize with central
API for new Massing functionality
Revit 2010 introduces new conceptual design functionality for creation of complex geometry. Intuitive and flexible form-making is supported by the addition of new objects: points and spline curves that pass through these points. The resulting surfaces can be divided, patterned, and panelized to create buildable forms with persistent parametric relationships.
The following classes provide the API user with access to this functionality:
- CurveByPoints
- CurveByPointsArray
- DividedSurface
- DividedSurfaceData
- Form
- ReferencePoint
- ReferencePointArray
- TilePatterns
- TilePattern
Other methods and properties added to support this functionality are:
- ModelCurve.ChangeToReferenceLine()
- FamilyCreate.NewLevel(double)
- Family.IsCurtainPanelFamily
- Family.CurtainPanelHorizontalSpacing
- Family.CurtainPanelVerticalSpacing
- Family.CurtainPanelTilePattern
- SketchPlane.PlaneReference
- Level.PlaneReference
The following classes cannot be used in 2010 Mass families. Instead, equivalent geometry can be created with the Form class.
- Blend
- Extrusion
- Revolution
- Sweep
- SweptBlend
MEP API for ducts and pipes
This project provides read/write access to HVAC and Piping data in a Revit model including:
- Traversing ducts, pipes, fittings, and connectors in a system
- Adding, removing, and changing ducts, pipes, and other equipment
- Getting and setting system properties
- Determining if the system is well-connected
The following classes have new methods and properties related to duct and pipes:
- Autodesk.Revit.MEP.Connector
- Autodesk.Revit.Elements.MechanicalSystem
- Autodesk.Revit.Elements.PipingSystem
Elements related to duct and pipe systems can be created using new methods on Autodesk.Revit.Creation.Document:
- NewCrossFitting
- NewDuct
- NewElbowFitting
- NewFlexDuct
- NewFlexPipe
- NewMechanicalSystem
- NewPipe
- NewPipingSystem
- NewTakeoffFitting
- NewTeeFitting
- NewTransitionFitting
- NewUnionFitting
All MEP-related classes have been moved into the MEP namespace from namespaces such as Elements and Symbols.
Upgrade to .NET Framework version 3.5
Revit now uses Microsoft .NET Framework version 3.5. Applications compiled using .NET 2.0 should continue to work unless they are affected by other changes in the Revit 2010 API.
Small enhancements & API interface changes
Parameters
The new property Autodesk.Revit.Parameters.InternalDefinition.BuiltInParameter provides access to the enumerated type for the parameter, if it is a built-in parameter. The property makes it easier to locate a built-in parameter value based on the name of the parameter shown in the Revit UI.
Rooms and Spaces
The new method Autodesk.Revit.Elements.Room.IsPointInRoom determines if a 3D point is in the volume of a room.
The new method Autodesk.Revit.Elements.Space.IsPointInSpace determines if a 3D point is in the volume of a space.
The new methods Autodesk.Revit.Document. GetRoomAtPoint() and GetSpaceAtPoint() find the Room or Space that encloses a given 3D point within the project.
The new property Autodesk.Revit.Elements.FamilyInstance.Space allows an API application to determine what in which Space an air terminal or other family instance exists in Revit MEP.
Grids
The new method Autodesk.Revit.Elements.Grid.ExtendToAllLevels() method allows grids to intersect all levels of a project.
The method Autodesk.Revit.Creation.Document.NewGrid will throw an exception if given an unbounded line.
Batch creation methods (NewWalls, NewGrids, etc.)
If one of the elements which is supposed to be created can't be created the entire the operation will be properly rolled back.
Rebar
NewRebar:StartHookOrientation and EndHookOrientation arguments were changed to an enum. Rebar.SetLayoutRuleWithoutExaminingHost value type was changed to an enum.
Structural framing
Beams created with an offset from their level now have their analytical model aligned with the physical geometry of the beam.
Curved beams can be created in the vertical plane.
Categories
Internal categories that are not directly exposed through the Revit UI can be accessed via the API. This makes it possible to add shared parameters to Materials using Revit API.
The new Category.AllowsBoundParameters property indicates if a category can have shared or project parameter. When category.AllowsBoundParameters is false, it may not be bound to shared parameters using the BindingMap.
Category. AllowsVisibilityControl(view) indicates if the visibility of a category can be controlled in a given view.
Sketch
Autodesk.Revit.Elements.Sketch.CurveLoop now returns CurveArrayArray instead of CurveArray. If the sketch contains multiple loops, the output will be segregated into separate CurveArrays within the output.
Revit session properties
The new Autodesk.Revit.Application.Language property identifies the language used in the current session of Revit.
The new Autodesk.Revit.Application.Product property identifies the Revit vertical application (Building, Structure, MEP) via an enumerated type.
External Commands and Applications
Revit now offers improved diagnostics when Revit is unable to run an external application or command listed in the Revit.ini file. A popup message will explain the problem. If the problem is related to an exception caught from the application, the popup will include the exception stack trace.
Revit no longer silently renumbers the Revit.ini file entries when they fail to load or start. An option in the popup message will allow a user to permanently disable a failed API application.
HostedSweep
In the Autodesk.Revit.Elements.HostedSweep class the new abstract method AddSegment() allows applications to write generic code that operates upon all hosted sweep types (gutter, fascia, or slab edge).
VolumeCalculationOptions
The Autodesk.Revit.VolumeCalculationOptions.VolumeComputationEnbale field was removed. Use the property VolumeComputationEnable instead.
Curtain Systems
Autodesk.Revit.Elements.CurtainGridLine new property ExistingSegmentCurves allows access to the existing segments in the grid line (excluding those which have been removed).
Autodesk.Revit.Elements.Mullion now provides access to its location via the LocationCurve property.
Output Arguments from API methods
Output arguments are now marked with the [Out] attribute. Methods changed include:
- Application.GetAllTopMenus
- ControlledApplication.GetAllTopMenus
- Document.Import - both overloads
- Face.Intersect
- Curve.Intersect
- Curve.IsInside
- Face.IsInside
- Document.LoadFamily
- Document.LoadFamilySymbol
Where previously these output arguments were declared as “reference”. In C#, where these arguments were passed using the “ref” keyword, this should now be “out”.
Visual Studio Tools for Applications (VSTA) 2.0
Revit's macro functionality is now based on VSTA 2.0. More information about VSTA and version 2.0 are available on Microsoft's MSDN Developer Center.
Find references in the direction of a ray
This new method returns a reference array of all references found when moving through the Revit model from a specified point at a specified direction.
Syntax:
public ReferenceArray FindReferencesByDirection(XYZ origin, XYZ direction, View3D view)
Reference parsing
The Autodesk.Revit.Geometry.Reference class now offers properties to extract the element, geometry object, transform, point, and parameters of the referenced item.
Element Hiding
To allow hiding and un-hiding of elements via the API, the methods View.Hide(ElementSet) and View.Unhide(ElementSet) have been added. The properties Element.IsHidden(View) and Element.CanBeHidden(View) return a boolean value that indicates if an element is current hidden and if it can be hidden.
Parameter.Set return value when value is unchanged
Previously, Revit returned False if the input value for Parameter.Set was the same as the current value. Revit now returns True in this case.
NoConditionType removed for Spaces
The NoConditionType enum has been removed as an option for Spaces. All spaces must have a ConditionType value and the default is HeatedAndCooled. A user wishing to specify an unconditioned space may use the value ConditionType::Unconditioned.
Detail Curves use sketch plane of their view
NewDetailCurve and NewDetailCurveArray no longer require specification of a sketch plane. The sketch plane of the view is used.
SketchPlane property added to View class
The property View.SketchPlane has been created to return a view's sketch plane.
Export family data to XML for Autodesk Seek integration
The method ExtractPartAtomFromFamilyFile will open a family file and create an XML file with data used by Autodesk Seek for content search.
Exceptions when parameters are disabled
Set and Get for the following parameters may now result in exceptions when the parameter is disabled for the specified object: View.Scale, RoofBase.FasciaDepth, FootPrintRoof.SlopeAngle
New options for export to DWF
The new option DWF2DExportOptions.ExportFormat allows specification of the paper format for the DWF.
The new option DWF2DExportOptions.PortraitLayout allows specification of the layout for the DWF.
The new option DWF2DExportOptions.ImageFormat allows specification of the format for the exported image in the DWF.
The new option DWF2DExportOptions.ImageQuality allows specification of the format for the exported image in the DWF.
The new option DWF2DExportOptions.StopOnError and DWF3DExportOptions.StopOnError controls whether or not the export process stops when an error is generated during export of one view, or whether Revit attempts to continue the export for other pending views.
New option for export to FBX
The new option FBXExportOptions.StopOnError controls whether or not the export process stops when an error is generated during export of one view, or whether Revit attempts to continue the export for other pending views.
New method for export to DGN
The new method Document.Export(String, String, ViewSet, DGNExportOptions) exports a Revit project exports a model into DGN format.
New method for export to Civil3D
The new method Document.Export(String, String, View3D, ViewPlan, BuildingSiteExportOptions) exports a Revit project exports a model in the format of Civil Engineering design applications.
New method for import from gbXML
The new method Document.Import(String, GBXMLImportOptions) imports a Green-Building XML file into Revit.
New method for import from Inventor
The new method Document.Import(String, InventorImportOptions) imports an Inventor file into Revit. The Inventor file must be a .adsk file exported from Inventor for the purposes of transfer to Revit.
Document.Application property
The new property Document.Application returns the Application object which contains this document.
New element collector properties
Two new methods for collecting elements have been added.
- int Elements[Filter, ElementArray] – Collects all elements which satisfy specified filter within the document.
- int Elements[Type, ElementArray] – Collects all elements which satisfy specified type within the document.
These methods are similar to previously existing methods accepting a System.Collection.Generics.ICollection A new element sub-type ImportInstance represents external geometry content such as DWG that has been imported to Revit. This element type is also output from the Import() methods, however, those methods have not been updated to specific output this new type. You can downcast the output to this sub-type.
The ImportInstance element types offer the ability to access and modify the Visibility and Pinned parameters.
This property has changed type since Revit release 2009. The property now returns an ElementArray, instead of List The API provides access to the material quantities for a material in a given element. These values are the same values calculated by Revit to show in material takeoff schedules. In some cases the value may be approximate. Access these values through:
This property has been removed. Obtain the transformed geometry of the instance using Instance.GetInstanceGeometry(), Instance.GetSymbolGeometry(Transform) and Instance.GetInstanceGeometry(Transform)
The method Autodesk.Revit.Creation.Document.PlaceGroup() has been modified to correctly interpret the coordinates of the input point in the coordinates of the document. Previously it interpreted the points in the coordinates of the group, which were not accessible.
This property has been removed and replaced with gbXMLParamElem.ExportComplexity with a wider variety of options.
The new methods
allow you to create and populate topography surface elements in projects.
The workflows used to change print settings via the PrintManager class have changed. Previously, changes to settings happened immediately and would be visible in the Revit Print dialogs and applicable to all API printing activities. In the 2010 API, you must commit the changes you have made to the PrintManager, PrintSettings and PrintParameters classes by one of these methods:
The properties PrintSetup.PaperSizes and PrintSetup.PaperSources have moved to the PrintManager class.
A new option has been added to PrintParameters: ReplaceHalftoneWithThinLines.
A new option Autodesk.Revit.Geometry.Options.IncludeNonVisibleObjects has been added. Use this option to instruct Revit to include GeometryObjects whose Visibility type is something other than ‘Visible’ when extracting geometry from Revit. Objects which appear in this category include MEP Duct lining and insulation and joined geometry currently selected and highlighted in the Revit User Interface. When this option is not set (the default) only visible geometry is extracted, the same as in Revit 2009.
The geometry extraction API uses new algorithms to extract the faces and edges from a solid. The handles to these faces and edges are no longer maintained centrally (which means they are not suitable to be used as an index for collections like a Dictionary or Map). The new algorithm also changes the order in which the faces are returned, thus they may not be returned in the same order as in Revit 2009.
Several enums have been added to the Revit API to assist developers with interpretation of the values of certain BuiltInParameter types:
End of document So that was the news in the Revit 2010 API back in 2009. Stay tuned for the next installments leading up to the current day.ImportInstance elements
LocationCurve.ElementsAtJoin
Element material quantities
Instance.Transformed and Geometry of Instances
PlaceGroup()
gbXMLParamElem.ShadingSurfaces
Creating topography surfaces
Changes to Printing
Geometry extraction
Additional enums