Dynamo Python Primer
  • Take Dynamo Further 🚀
  • 1 Hello Python 🐍
    • 1.1 Why Should I Learn to Code?
    • 1.2 Python Introduction
    • 1.3 What is IronPython?
  • 2 Seeing The Bigger Picture 🔭
    • 2.1 Context Matters
    • 2.2 What is an API?
    • 2.3 The .NET Framework
    • 2.4 Object-Oriented Programming
  • 3 Getting Started 🛴
    • 3.1 Dynamo's Python Node
    • 3.2 Boilerplate Setup Code
    • 3.3 Basics: Input and Output
    • 3.4 Common Errors
  • 4 Revit-Specific Topics 🏡
    • 4.1 Introduction to Revit's API
    • 4.2 How to Read Revit's API Documentation
    • 4.3 Doc, UIDoc, App, UIApp
    • 4.4 Unwrapping Revit Elements
    • 4.5 The FilteredElementCollector
    • 4.6 Geometry Conversion Methods
    • 4.7 Working With Parameters
      • Family Parameters
      • Global Parameters
      • Project Information Parameters
      • Group Parameters
      • Built-In Parameters
    • 4.8 Working With Transactions
    • 4.9 Opening & Closing External Files
    • 4.10 Prompting UI Selection
    • 4.11 Working With Units
    • 4.12 Built-In Categories
    • 4.13 Family Acrobatics
    • 4.14 Feedback: TaskDialogs
  • 5 Glossary 📚
  • About This Primer 👋
Powered by GitBook
On this page

Was this helpful?

  1. 4 Revit-Specific Topics 🏡

4.3 Doc, UIDoc, App, UIApp

What's up, Doc? Get to know these important handles you'll use all the time!

Previous4.2 How to Read Revit's API DocumentationNext4.4 Unwrapping Revit Elements

Last updated 5 years ago

Was this helpful?

Boilerplate Code

As seen in the chapter on , Revit boilerplate code often requires setting up handles to the Revit application and document (doc, uidoc, app, uiapp).

But why is this?

Application and Document

This area of the API can seem a little confusing at first. Questions abound: can't Revit just work out which document (i.e. model) I'm in? Why do I have a Document and a UIDocument? Why do I refer to an Application - isn't the application Revit? These are good questions. Luckily, Revit's has a few answers for us:

The top level objects in the Revit Platform API are application and document. These are represented by the classes Application, UIApplication, Document and UIDocument.

  • The application object refers to an individual Revit session, providing access to documents, options, and other application-wide data and settings.

    • Autodesk.Revit.UI.UIApplication - provides access to UI-level interfaces for the application, including the ability to add RibbonPanels to the user interface, and the ability to obtain the active document in the user interface.

    • Autodesk.Revit.ApplicationServices.Application - provides access to all other application level properties.

  • The document object is a single Revit project file representing a building model. Revit can have multiple projects open and multiple views for one project.

    • Autodesk.Revit.UI.UIDocument - provides access to UI-level interfaces for the document, such as the contents of the selection and the ability to prompt the user to make selections and pick points

    • Autodesk.Revit.DB.Document - provides access to all other document level properties

To summarise this:

  • You can have more than one Revit document open at a time (including .rfa files), so you need to specify which document you're targeting.

  • You can also have more than one running instance of the Revit application, so you'll need to specify the application you're targeting.

  • The Document/UIDocument and Application/UIApplication splits are decisions made by the designers of the API. The UI classes generally refer to user-interface elements or those which require interaction (such as prompting the user to select elements in the main Revit window.)

The main thing to know is that the doc, uidoc, app and uiapp handles in our boilerplate code are indispensable for many operations involving editing a Revit document. For instance, want to delete something? You'll need to reference which document you're deleting something from!

boilerplate code
API guidance