Revit 2014 Platform API Developers Guidelines [email protected] Index Developers • Introduction  Welcome to the Revit Platform API  What Can you do with the Revit Platform API  Requirements  Installation  Supported Programming Languages  User Manual  Documentation Conventions  Whats new in this release Getting Started o  Walkthroughs  Walkthrough: Hello World  Walkthrough: Add Hello World Ribbon Panel  Walkthrough: Retrieve Selected Elements  Walkthrough: Retrieve Filtered Elements Add-In Integration o  Overview  External Commands  External Application  Add-In Registration  Localization  Attributes  Revit Exceptions  Ribbon Panels and Controls  Revit Style Task Dialogs  DB Level External Applications Application and Document o  Application Functions • Discipline Controls • How to use Application properties to enforce a correct version for your add-in  Document Functions  Document and File Management  Settings  Units Element Essentials o  Element Classification  Other Classifications  Element Retrieval  General Properties • Basic Interaction with Revit Elements Filtering o  Create a FilteredElementCollector  Applying Filters  Getting filtered elements or element ids  LINQ Queries  Bounding Box filters  Element Intersection Filters Selection o  Changing the Selection  User Selection  Filtered User Selection Parameters o  Walkthrough: Get Selected Elements Parameters  Definition  Builtin Parameters  Storage Types  asValueString() and SetValueString()  Parameter Relationships  Adding Parameters to Elements Collections o  Interface  Collections and Iterators Editing Elements o  Moving Elements  Copying Elements  Rotating Elements  Aligning Elements  Mirroring Elements  Grouping Elements  Creating Arrays of Elements  Deleting Elements  Pinned Elements Views o  About views  View Types • Overview • View3D • ViewPlan • ViewDrafting • ViewSelection • ViewSheet • ViewSchedule Creating a schedule o Working with ViewSchedule o TableView and TableData o  View Filters  View Cropping  Displaced Views  UIView • Revit Geometric Elements Walls, Floors, Ceilings, Roofs and Openings o  Walls  Floors, Ceilings and Foundations  Roofs  Curtains  Other Elements  Compound Structure  Opening  Thermal Properties Family Instances o  Identifying Elements  Family  Family Instances  Code Samples  FamilySymbol Family Documents o  About family documents  Creating elements in families • Create a Form Element • Create an Annotation  Visibility of family elements  Managing family types and parameters Conceptual Design o  Point and curve objects  Forms  Rationalizing a Surface  Adaptive Components Datum and Information Elements o  Levels  Grids  Phase  Design Options Annotation Elements o  Dimensions and Constraints  Detail Curve  Tags  Text  Annotation Symbol Geometry o  Example: Retrieve Geometry Data from a Wall  Geometry Object Class • Curves Curve Analysis o Curve Collections o Curve Creation o Curve Parameterization o Curve Types o Mathematical representations of curve types o • GeometryInstances • Meshes • Points • PolyLines • Solids, Faces and Edges Edge and face parameterization o Faces o Face analysis o Face splitting o Face types o Mathematical representation of face types o Solid analysis o Solid and face creation o  Geometry Helper Class  Collection Classes  Example: Retrieve Geometry Data from a Beam  Extrusion Analysis of a Solid  Finding geometry by ray projection  Geometry Utility Classes  Room and Space Geometry Sketching o  The 2D Sketch Class  3D Sketch Class  Model Curve Material o  General Material Information  Material Management  Element Material  Material quantities  Painting the Face of an Element Stairs and Railings o  Creating and Editing Stairs  Railings  Stairs Annotations  Stair Components • Discipline-Specific Functionality Revit Architecture o  Rooms Revit Structure o  Structural Model Elements  Analytical Model  Loads  Analysis Links  Analytical Links Revit MEP o  MEP Element Creation • Create Pipes and Ducts • Placeholders • Systems  Connectors  Family Creation  Mechanical Settings  Electrical Settings  Routing Preferences • Advanced Topics Storing Data in the Revit model o  Shared Parameters  Definition File  Definition File Access  Binding  Extensible Storage Transactions o  Transaction Classes  Transactions in Events  Failure Handling Options  Getting Element Geometry and AnalyticalModel  Temporary Transations Events o  Database Events • DocumentChanged event  User Interface Events  Registering Events  Canceling Events External Events o Dockable Dialog Panes o Dynamic Model Update o  Implementing IUpdater  The Execute method  Registering Updaters  Exposure to End-User Commands o Failure Posting and Handling o  Posting Failures  Handling Failures Performance Advisor o Point Clouds o  Point Cloud Client  Point Cloud Engine Analysis o  Energy Data  Analysis Visualization • Manager for analysis results • Creating analysis results data • Anlaysis Results Display • Updating Analysis Results  Conceptual Energy Analysis  Detailed Energy Analysis Model Place and Locations o  Place  City  Project Location  Project Position Worksharing o  Elements in Worksets  Element Ownership  Opening a Workshared Document  Visibility and Display  Worksets  Workshared File Management Construction Modeling o  Assemblies and Views  Parts Linked Files o  Revit Links  Managing External Files Export o  Export Tables  IFC Export  Custom Export • Appendices Glossary o  Array  BIM  Class  Events  Iterator  Method  Namespace  Overloading  Properties  Revit Families  Revit Parameters  Revit Types  Sets  Element ED  Element UID FAQ o  General Questions  Revit Structure Questions Hello World for VB.Net o  Create a New Project  Add Reference and Namespace  Change the Class Name  Add Code  Creat a *.addin manifest file  Build the Program  Debug the Program Material Properties Internal Units o Concrete Section Definitions o  Concrete-Rectangular Beam  Precast-Rectangular Beam  Precast-L Shaped Beam  Precast-Single Tee  Precast-Inverted Tee  Precast-Double Tee API User Interface Guidelines o  Introduction  Consistency  Speaking the Users Language  Good Layout  Good Defaults  Progressive Disclosure  Localization of the User Interface  Dialog Guidelines  Ribbon Guidelines  Common Definitions  Terminology Definitions Note: The Contents of this document were copied from the http://wikihelp.autodesk.com/Revit/enu/2014/Help/3665-Developers website on 16 & 17/11/2013 and are up to date as of that point. The Copyright and ownership of the information contained within remain as per the original copyright notices on the website. This document has been put together for the purposes of offline reading and educational purposes and should only be used for this purpose. By reading further you are agreeing to respect all copyright and ownership laws. Thank you Most links copied will direct back to the orginal source location on the internet rather than internally within the document so differences may occur depending on information updates Developers This API Developer's Guide describes how to use the application programming interface (API) for Autodesk Revit 2014. Topics in this section • Introduction • Basic Interaction with Revit Elements • Revit Geometric Elements • Discipline-Specific Functionality • Advanced Topics • Appendices Introduction Welcome to the Revit Platform API All Revit-based products are Parametric Building Information Modeling (BIM) tools. These tools are similar to Computer-Aided Design (CAD) programs but are used to build 3D models as well as 2D drawings. In Revit, you place real-world elements like columns and walls into the model. Once the model is built, you can create model views such as sections and callouts. Views are generated from the 3D physical model; consequently, changes made in one view automatically propagate through all views. This virtually eliminates the need to update multiple drawings and details when you make changes to the model. Introduction to the Revit Platform API The Revit .NET API allows you to program with any .NET compliant language including Visual Basic.NET, C#, and C++/CLI. Revit Architecture 2013, Revit Structure 2013, and Revit MEP 2013 all contain the Revit Platform API so that you can integrate your applications into Revit. The three APIs are very similar and are jointly referred to as the Revit Platform API. Before using the API, learn to use Revit and its features so that you can better understand the relevant areas related to your programming. Learning Revit can help you: • Maintain consistency with the Revit UI and commands. • Design your add-in application seamlessly. • Master API classes and class members efficiently and effectively. If you are not familiar with Revit or BIM, learn more in the Revit product center at www.autodesk.com/revit. What Can You Do with the Revit Platform API? You can use the Revit Platform API to: • Gain access to model graphical data. • Gain access to model parameter data. • Create, edit, and delete model elements like floors, walls, columns, and more. • Create add-ins to automate repetitive tasks. • Integrate applications into Revit-based vertical products. Examples include linking an external relational database to Revit or sending model data to an analysis application. • Perform analysis of all sorts using BIM. • Automatically create project documentation. Requirements To go through the user manual, you need the following: 1. A working understanding of Revit Architecture 2013, Revit Structure 2013, or Revit MEP 2013. 2. Familiarity with a Common Language Specification compliant language like C# or VB.NET. 3. Microsoft Visual Studio 2010, or Microsoft Visual Studio 2010 Express Edition. Alternatively, you can use the built-in SharpDevelop development environment in Revit. 4. Microsoft .NET Framework 4.0. 5. The Revit Software Developer's Kit (SDK) which you can download from the Autodesk Developer Network (ADN) or the Revit installation CD/DVD (<DVD_Drive>:\Utilities\Common\Software Development Kit). Installation The Revit Platform API is installed with Revit Architecture, Revit Structure, and Revit MEP. Any .NET based application will reference the RevitAPI.dll and the RevitAPIUI.dll located in the Revit Program directory. The RevitAPI.dll contains methods used to access Revit's application, documents, elements and parameters at the database level. The RevitAPIUI.dll contains the interfaces related to manipulation and customization of the Revit user interface. Supported Programming Languages The Revit Platform API is fully accessible by any language compatible with the Microsoft .NET Framework 4.0, such as Visual Basic .NET or Visual C#. User Manual This document is part of the Revit SDK. It provides an introduction to implementing Revit add-in applications using the Revit Platform API. Before creating a Revit Platform API add-in application read through the manual and try the sample code. If you already have some experience with the Revit Platform API, you may just want to review the Notes and Troubleshooting sections. Introduction to the Revit Platform API The first two chapters present an introduction to the Revit Platform API and provide an overview of the User Manual. Welcome to the Revit Platform API - Presents an introduction to the Revit Platform API and necessary prerequisite knowledge before you create your first add-in. Getting Started - Step-by-step instructions for creating your first Hello World add-in application using Visual Studio 2010 and four other walkthroughs covering primary add-in functions. Basic Topics These chapters cover the Revit Platform API basic mechanisms and functionality. Add-in Integration - Discusses how an add-in is integrated into the Revit UI and invoked by user commands or specific Revit events such as program startup. Application and Document - Application and Document classes respectively represent the Revit application and project file in the Revit Platform API. This chapter explains basic concepts and links to pertinent chapters and sections. Elements Essentials - The bulk of the data in a Revit project is in a collection of Elements. This chapter discusses the essential Element mechanism, classification, and features. Filtering - Filtering is used to get a set of elements from the document. Selection - Working with the set of selected elements in a document Parameters - Most Element information is stored as Parameters. This chapter discusses Parameter functionality. Collection - Utility collection types such as Array, Map, Set collections, and related Iterators. Element Topics Elements are introduced based on element classification. Make sure that you read the Elements Essentials and Parameter chapters before reading about the individual elements. Editing Elements - Learn how to move, rotate, delete, mirror, group, and array elements. Wall, Floors, Roofs and Openings - Discusses Elements, their corresponding ElementTypes representing built-in place construction, and different types of Openings in the API. Family Instances - Learn about the relationship between family and family instance, family and family instance features, and how to load or create them. Family Creation - Learn about creation and modification of Revit Family documents. Conceptual Design - Discusses how to create complex geometry and forms in a Revit Conceptual Mass document. Datum and Information Elements - Learn how to set up grids, add levels, use design options, and more. Annotation Elements - Discusses document annotation including adding dimensions, detail curves, tags, and annotation symbols. Sketching - Sketch functions include 2D and 3D sketch classes such as SketchPlane, ModelCurve, GenericForm, and more. Views - Learn about the different ways to view models and components and how to manipulate the view in the API. Material - Material data is an Element that identifies the physical materials used in the project as well as texture, color, and more. Advanced Topics Geometry - Discusses graphics-related types in the API used to describe the graphical representation of the model including the three classes that describe and store the geometry information. Place and Locations - Defines the project location including city, country, latitude, and longitude. Shared Parameters - Shared parameters are external text files containing parameter specifications. This chapter introduces how to access to shared parameters through the Revit Platform API. Transaction - Introduces the two uses for Transaction and the limits that you must consider when using Transaction. Events - Discusses how to take advantage of Revit Events. Dynamic Model Update - Learn how to use updaters to modify the model in reaction to changes in the document. Failure Posting and Handling - Learn how to post failures and interact with Revit's failure handling mechanism. Analysis Visualization - How to display analysis results in a Revit project. Product Specific Revit products include Revit Architecture, Revit Structure, and Revit MEP. Some APIs only work in specific products. Revit Architecture - Discusses the APIs specific to Revit Architecture. Revit Structure - Discusses the APIs specific to Revit Structure. Revit MEP - Discusses the APIs specific to Revit MEP. Other Appendix - Additional information such as Frequently Asked Questions, Using Visual Basic.Net for programming, and more. Documentation Conventions This document contains class names in namespace format, such as Autodesk.Revit.DB.Element. In C++/CLI Autodesk.Revit.Element is Autodesk::Revit::DB::Element. Since only C# is used for sample code in this manual, the default namespace is Autodesk.Revit.DB. If you want to see code in Visual Basic, you will find several VB.NET applications in the SDK Samples directory. Indexed Properties Some Revit Platform API class properties are "indexed", or described as overloaded in the API help file (RevitAPI.chm). For example, the Element.Geometry property. In the text of this document, these are referred to as properties, although you access them as if they were methods in C# code by pre-pending the property name with "get_" or "set_". For example, to use the Element.Geometry(Options) property, you use Element.get_Geometry(Options). What's new in this release Please see the "What's New" section in Revit 2012 API.chm for information about changes and new features.