Revit api developer guide Revit api developer guide Revit api developer guide Revit api developer guide Revit api developer guide Revit api developer guide Revit api developer guide Revit api developer guide Revit api developer guide Revit api developer guide Revit api developer guide Revit api developer guide
Revit 2012 API Developer’s Guide Copyright 2011 Autodesk, Inc All Rights Reserved This publication, or parts thereof, may not be reproduced in any form, by any method, for any purpose AUTODESK, INC., MAKES NO WARRANTY, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE REGARDING THESE MATERIALS, AND MAKES SUCH MATERIALS AVAILABLE SOLELY ON AN "AS-IS" BASIS IN NO EVENT SHALL AUTODESK, INC., BE LIABLE TO ANYONE FOR SPECIAL, COLLATERAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES IN CONNECTION WITH OR ARISING OUT OF ACQUISITION OR USE OF THESE MATERIALS THE SOLE AND EXCLUSIVE LIABILITY TO AUTODESK, INC., REGARDLESS OF THE FORM OF ACTION, SHALL NOT EXCEED THE PURCHASE PRICE, IF ANY, OF THE MATERIALS DESCRIBED HEREIN Autodesk, Inc., reserves the right to revise and improve its products as it sees fit This publication describes the state of the product at the time of publication, and may not reflect the product at all times in the future Autodesk Trademarks The following are registered trademarks or trademarks of Autodesk, Inc., in the USA and other countries: 3DEC (design/logo), 3December, 3December.com, 3ds Max, ActiveShapes, Actrix, ADI, Alias, Alias (swirl design/logo), AliasStudio, Alias|Wavefront (design/logo), ATC, AUGI, AutoCAD, AutoCAD Learning Assistance, AutoCAD LT, AutoCAD Simulator, AutoCAD SQL Extension, AutoCAD SQL Interface,Autodesk, Autodesk Envision, Autodesk Insight, Autodesk Intent, Autodesk Inventor, Autodesk Map, Autodesk MapGuide, Autodesk Streamline, AutoLISP, AutoSnap, AutoSketch, AutoTrack, Backdraft, Built with ObjectARX(logo), Burn, Buzzsaw, CAiCE, Can You Imagine, Character Studio, Cinestream, Civil 3D, Cleaner, Cleaner Central, ClearScale, Colour Warper, Combustion, Communication Specification, Constructware, Content Explorer, Create>what's>Next> (design/logo), Dancing Baby (image), DesignCenter, Design Doctor, Designer's Toolkit, DesignKids, DesignProf, DesignServer, DesignStudio, Design|Studio (design/logo), Design Your World, Design Your World (design/logo), DWF, DWG, DWG (logo), DWG TrueConvert, DWG TrueView, DXF, EditDV, Education by Design, Extending the Design Team, FBX, Filmbox, FMDesktop, GDX Driver, Gmax, Heads-up Design, Heidi, HOOPS, HumanIK, i-drop, iMOUT, Incinerator, IntroDV, Kaydara, Kaydara (design/logo), LocationLogic, Lustre, Maya, Mechanical Desktop, MotionBuilder, ObjectARX, ObjectDBX, Open Reality, PolarSnap, PortfolioWall, Powered with Autodesk Technology, Productstream, ProjectPoint, Reactor, RealDWG, Real-time Roto, Render Queue, Revit, Showcase, SketchBook, StudioTools, Topobase, Toxik, Visual, Visual Bridge, Visual Construction, Visual Drainage, Visual Hydro, Visual Landscape, Visual Roads, Visual Survey, Visual Syllabus, Visual Toolbox, Visual Tugboat, Visual LISP, Voice Reality, Volo, and Wiretap The following are registered trademarks or trademarks of Autodesk Canada Co in the USA and/or Canada and other countries: Backburner, Discreet, Fire, Flame, Flint, Frost, Inferno, Multi-Master Editing, River, Smoke, Sparks, Stone, Wire Third Party Trademarks All other brand names, product names or trademarks belong to their respective holders Third Party Software Program Credits ACIS Copyright 1989-2001 Spatial Corp Portions Copyright 2002 Autodesk, Inc Copyright 1997 Microsoft Corporation All rights reserved Flash is a registered trademark of Macromedia, Inc in the United States and/or other countries International CorrectSpell™ Spelling Correction System 1995 by Lernout & Hauspie Speech Products, N.V All rights reserved InstallShield™ 3.0 Copyright 1997 InstallShield Software Corporation All rights reserved PANTONE2 Colors displayed in the software application or in the user documentation may not match PANTONE-identified standards Consult current PANTONE Color Publications for accurate color PANTONE2 and other Pantone, Inc trademarks are the property of Pantone, Inc Pantone, Inc., 2002 Pantone, Inc is the copyright owner of color data and/or software which are licensed to Autodesk, Inc., to distribute for use only in combination with certain Autodesk software products PANTONE Color Data and/or Software shall not be copied onto another disk or into memory unless as part of the execution of this Autodesk software product Portions Copyright 1991-1996 Arthur D Applegate All rights reserved Portions of this software are based on the work of the Independent JPEG Group RAL DESIGN RAL, Sankt Augustin, 2002 RAL CLASSIC RAL, Sankt Augustin, 2002 Representation of the RAL Colors is done with the approval of RAL Deutsches Institut für Gütesicherung und Kennzeichnung e.V (RAL German Institute for Quality Assurance and Certification, re Assoc.), D-53757 Sankt Augustin Typefaces from the Bitstream2 typeface library copyright 1992 Typefaces from Payne Loving Trust 1996 All rights reserved AutoCAD 2008 is produced under a license of data derived from DIC Color Guide2 from Dainippon Ink and Chemicals, Inc Copyright Dainippon Ink and Chemicals, Inc All rights reserved DIC Color Guide computer color simulations used in this product may not exactly match DIC Color Guide, DIC color Guide Part identified solid color standards Use current DIC Color Guide Manuals for exact color reference DIC and DIC Color Guide are registered trademarks of Dainippon Ink and Chemicals, Inc Printed manual and help produced with Idiom WorldServer™ WindowBlinds: DirectSkin™ OCX Stardock® AnswerWorks 4.0 ; 1997-2003 WexTech Systems, Inc Portions of this software Vantage-Knexys All rights reserved The Director General of the Geographic Survey Institute has issued the approval for the coordinates exchange numbered TKY2JGD for Japan Geodetic Datum 2000, also known as technical information No H1-N0.2 of the Geographic Survey Institute, to be installed and used within this software product (Approval No.: 646 issued by GSI, April 8, 2002) Portions of this computer program are copyright 1995-1999 LizardTech, Inc All rights reserved MrSID is protected by U.S Patent No 5,710,835 Foreign Patents Pending Portions of this computer program are Copyright ; 2000 Earth Resource Mapping, Inc OSTN97 Crown Copyright 1997 All rights reserved OSTN02 Crown copyright 2002 All rights reserved OSGM02 Crown copyright 2002, Ordnance Survey Ireland, 2002 FME Objects Engine 2005 SAFE Software All rights reserved GOVERNMENT USE Use, duplication, or disclosure by the U.S Government is subject to restrictions as set forth in FAR 12.212 (Commercial Computer Software-Restricted Rights) and DFAR 227.7202 (Rights in Technical Data and Computer Software), as applicable Table of Contents Contents Welcome to the Revit Platform API 19 1.1 Introduction to the Revit Platform API 19 1.2 What Can You Do with the Revit Platform API? 19 1.3 Requirements 19 1.4 Install and Learn the Revit-Based Product 20 1.5 Installation 20 1.6 Supported Programming Languages 20 1.7 User Manual 21 1.7.1 Introduction to the Revit Platform API 21 1.7.2 Basic Topics 21 1.7.3 Element Topics 21 1.7.4 Advanced Topics 22 1.7.5 Product Specific 22 1.7.6 Other 22 1.8 1.8.1 1.9 Documentation Conventions 22 Indexed Properties 22 What‘s new in this release 23 Getting Started 24 2.1 Walkthroughs 24 2.2 Walkthrough: Hello World 24 2.2.1 Create a New Project 24 2.2.2 Add References 25 2.2.3 Add Code 25 2.2.4 Build the Program 26 2.2.5 Create a addin manifest file 26 2.2.6 Debug the Add-in 27 2.2.7 Troubleshooting 29 2.3 Walkthrough: Add Hello World Ribbon Panel 31 2.3.1 Create a New Project 31 2.3.2 Change the Class Name 32 2.3.3 Add Code 32 2.3.4 Build the Application 33 2.3.5 Create the addin manifest file 33 2.3.6 Debugging 34 2.4 Walkthrough: Retrieve Selected Elements 34 2.5 Walkthrough: Retrieve Filtered Elements 35 Add-In Integration 37 3.1 Overview 37 3.2 External Commands 38 3.2.1 Loading and Running External Commands 38 3.2.2 IExternalCommand 39 3.3 3.3.1 3.4 IExternalApplication 43 Add-in Registration 45 3.4.1 Manifest Files 45 3.4.2 NET Add-in Utility for manifest files 48 3.5 Localization 50 3.6 Attributes 50 3.6.1 TransactionAttribute 50 3.6.2 JournalingAttribute 51 3.7 Revit Exceptions 52 3.8 Ribbon Panels and Controls 52 3.8.1 Create a New Ribbon Panel and Controls 52 3.8.2 Ribbon Panel 53 3.8.3 Ribbon Controls 54 3.9 External Application 43 Revit-style Task Dialogs 61 Application and Document 63 4.1 Application Functions 63 4.1.1 Application 63 4.1.2 UIApplication 64 4.2 Document Functions 65 4.2.1 Document 65 4.2.2 UIDocument 66 4.3 Document and File Management 67 4.3.1 Document Retrieval 67 4.3.2 Document File Information 67 4.3.3 Open a Document 67 4.3.4 Create a Document 67 4.3.5 Save and Close a Document 68 4.3.6 Load Family 68 4.4 Settings 68 4.5 Units 70 Elements Essentials 71 5.1 5.1.1 Model Elements 71 5.1.2 View Elements 71 5.1.3 Group Elements 71 5.1.4 Annotation and Datum Elements 71 5.1.5 Sketch Elements 72 5.1.6 Information Elements 72 5.2 Category 72 5.2.2 Family 75 5.2.3 ElementType 76 5.2.4 Instance 76 Element Retrieval 77 5.3.1 Getting an Element by ID 77 5.3.2 Filtering the Elements Collection 77 5.3.3 Selection 77 5.3.4 Accessing Specific Elements from Document 77 5.4 Other Classifications 72 5.2.1 5.3 Element Classification 71 General Properties 78 5.4.1 ElementId 78 5.4.2 UniqueId 79 5.4.3 Location 79 5.4.4 Level 80 5.4.5 Parameter 81 Filtering 82 6.1 Create a FilteredElementCollector 82 6.2 Applying Filters 82 6.2.1 Quick filters 83 6.2.2 Slow Filters 86 6.2.3 Logical filters 88 6.3 Getting filtered elements or element ids 89 6.4 LINQ Queries 92 Selection 94 7.1 Changing the Selection 94 7.2 User Selection 95 7.3 Filtered User Selection 96 Parameters 98 8.1 Walkthrough: Get Selected Element Parameters 98 8.2 Definition 100 8.2.1 ParameterType 101 8.2.2 ParameterGroup 102 8.3 BuiltInParameter 102 8.4 StorageType 102 8.5 AsValueString() and SetValueString() 104 8.6 Parameter Relationships 104 8.7 Adding Parameters to Elements 105 Collections 106 9.1 Interface 106 9.1.1 IEnumerable 106 9.1.2 IEnumerator 106 9.2 10 Collections and Iterators 107 Editing Elements 110 10.1 Moving Elements 110 10.2 Rotating elements 112 10.3 Mirror 114 10.4 Group 115 10.5 Array 116 10.6 Delete 117 11 Walls, Floors, Roofs and Openings 120 11.1 Walls 120 11.2 Floors and Foundations 122 11.2.1 11.3 11.3.1 Modifying Slabs 125 Roofs 125 Gutter and Fascia 127 11.4 Curtains 127 11.5 Other Elements 128 11.5.1 Stair and Ramp 128 11.5.2 Ceiling 128 11.6 11.6.1 11.7 CompoundStructure 128 Material 128 Opening 130 11.7.1 General Properties 130 11.7.2 Create Opening 132 12 Family Instances 134 12.1 Identifying Elements 134 12.2 Family 135 12.2.1 Loading Families 135 12.2.2 Categories 135 12.3 FamilyInstances 136 12.3.1 Location-Related Properties 136 12.3.2 Host and Component 138 12.3.3 Subcomponent and Supercomponent 139 12.3.4 Other Properties 140 12.3.5 Creating FamilyInstance Objects 140 12.4 Code Samples 145 12.4.1 Create Tables 146 12.4.2 Create a Beam 147 12.4.3 Create Doors 148 12.4.4 Create FamilyInstances Using Reference Directions 149 13 Family Creation 151 13.1 Family Documents 151 13.1.1 Family 151 13.1.2 Categories 151 13.1.3 Parameters 151 13.1.4 Creating a Family Document 151 13.1.5 Nested Family Symbols 152 13.2 Family Item Factory 152 13.2.1 Creating Forms 153 13.2.2 Creating Annotations 155 13.3 Family Element Visibility 158 13.4 Family Manager 159 13.4.1 Getting Types in a Family 159 13.4.2 Editing FamilyTypes 160 14 Conceptual Design 162 14.1 Point and curve objects 162 14.2 Forms 165 14.2.1 Creating Forms 165 14.2.2 Form modification 169 14.3 Rationalizing a Surface 171 14.3.1 Dividing a surface 171 14.3.2 Patterning a surface 172 15 Datum and Information Elements 177 15.1 15.1.1 Levels 177 Elevation 177 15.1.2 15.2 Creating a Level 179 Grids 179 15.2.1 Curve 179 15.2.2 Creating a Grid 180 15.3 Phase 181 15.4 Design Options 183 16 Annotation Elements 184 16.1 Dimensions and Constraints 184 16.1.1 Dimensions 185 16.1.2 Constraint Elements 186 16.1.3 Spot Dimensions 188 16.1.4 Comparison 188 16.1.5 Create and Delete 189 16.2 Detail Curve 189 16.3 Tags 190 16.4 Text 192 16.5 Annotation Symbol 193 16.5.1 Create and Delete 193 16.5.2 Add and Remove Leader 193 17 Sketching 194 17.1 The 2D Sketch Class 194 17.2 3D Sketch 197 17.2.1 Extrusion 197 17.2.2 Revolution 198 17.2.3 Blend 200 17.2.4 Sweep 202 17.3 ModelCurve 204 17.3.1 Creating a ModelCurve 204 17.3.2 Properties 205 18 Views 207 18.1 Overview 207 18.1.1 View Process 207 18.1.2 View Types 208 18.1.3 Element Visibility in a View 212 18.1.4 Creating and Deleting Views 213 18.2 The View3D Class 214 18.2.1 Perspective View 214 18.2.2 Orthographic View 216 18.2.3 3D Views SectionBox 218 18.3 ViewPlan 220 18.4 ViewDrafting 220 18.5 ViewSection 221 18.6 ViewSheet 223 18.6.1 19 Printer Setup 224 Material 226 19.1 General Material Information 226 19.1.1 Classification 226 19.1.2 Properties 229 19.2 Material Management 232 19.2.1 Creating Materials 232 19.2.2 Deleting Materials 233 19.3 Element Material 234 19.3.1 Material in a Parameter 235 19.3.2 Material and Category 236 19.3.3 CompoundStructureLayer Material 238 19.3.4 Retrieve Element Materials 238 19.3.5 Walkthrough: Get Window Materials 240 20 Geometry 242 20.1 Example: Retrieve Geometry Data from a Wall 242 20.1.1 Create Geometry Options 242 20.1.2 Retrieve Faces and Edges 242 20.2 Geometry Node Class 243 20.2.1 Geometry.Instance 244 20.2.2 Geometry.Mesh 246 20.2.3 Solid 247 20.3 Geometry Helper Class 247 20.3.1 Transform 248 20.3.2 Reference 251 20.3.3 Options 251 20.3.4 BoundingBoxXYZ 253 20.3.5 BoundingBoxUV 257 20.4 Collection Classes 257 20.5 Example: Retrieve Geometry Data from a Beam 258 21 Place and Locations 260 21.1 Place 260 21.2 City 260 21.3 ProjectLocation 260 21.4 Project Position 261 21.4.1 22 Creating and Deleting Project Locations 264 Storing Data in the Revit model 266 22.1 Shared Parameters 266 22.2 Definition File 266 22.2.1 22.3 Definition File Format 266 Definition File Access 268 22.3.1 Create a Shared Parameter File 269 22.3.2 Access an Existing Shared Parameter File 269 22.3.3 Change the Parameter Definition Owner Group 270 22.4 Binding 271 22.4.1 Type Binding 271 22.4.2 Instance Binding 273 22.5 Extensible Storage 274 22.5.1 Schemas and SchemaBuilder 275 22.5.2 Fields and FieldBuilder 275 22.5.3 Entities 276 23 Transactions 278 23.1 Transaction Classes 278 23.1.1 Transaction 279 23.1.2 SubTransaction 280 23.1.3 TransactionGroup 280 23.2 Transactions in Events 282 23.2.1 Modifying the document during an event 282 23.2.2 DocumentChanged Event 282 23.3 Failure Handling Options 282 23.3.1 ClearAfterRollback 282 23.3.2 DelayedMiniWarnings 282 23.3.3 ForcedModalHandling 283 23.3.4 SetFailuresPreprocessor 283 23.3.5 SetTransactionFinalizer 283 23.4 24 Getting Element Geometry and AnalyticalModel 283 Events 285 24.1 Database Events 285 24.2 User Inteface Events 287 24.3 Registering Events 287 24.4 Canceling Events 288