Bundle context
Command Availability: Revit commands use standard IExternalCommandAvailability class to let Revit know if they are available in different contexts. For example, if a command needs to work on a set of elements, it can tell Revit to deactivate the button unless the user has selected one or more elements.
In pyRevit, command availability is set through the context key in bundle file. Currently, pyRevit support three types of command availability types.
# Tools are active even when there are no documents available/open in Revit
context: zero-doc
# Tool activates when at least one element is selected
context: selection
# Tool activates when all selected elements are of the given category, or categories
context: <category>
context:
- <category>
- <category>
The selection and zero-doc contexts are pretty easy to follow
Select Element Category Context
If <category> starts with OST_ (e.g. OST_Doors), comparison will be made using BuiltInCategory. The builtin category names are language-agnostic, so your tool would follow the correct context, no matter what Revit language is being used. <category> can also be any of the standard Revit element categories. You can use the pyRevit → Spy → List Elements, to list the standard category names.
Here are a few examples:
# Tool activates when all selected elements are of the given category
context: Doors
context: Walls
context: Floors
context: OST_Doors
context:
- Space Tags
- Spaces
Active Document Context
Bundle can also require a specific type of document to be active. Here are the available options
context: doc-project # bundle is active when the active document is a Project
context: doc-workshared # bundle is active when the active document is a Workshared Project
context: doc-cloud # bundle is active when the active document is a Cloud Project (Revit >=2019.1)
context: doc-family # bundle is active when the active document is a Family
Active View Context
Bundle can also require a specific type of active view to be active. Here are the available options
context: active-drafting-view # bundle is active when the active view is a Drafting view
context: active-detail-view # bundle is active when the active view is a Detail view
context: active-plan-view # bundle is active when the active view is any Plan
context: active-floor-plan # bundle is active when the active view is a Floor Plan
context: active-rcp-plan # bundle is active when the active view is a Reflected Ceiling Plan
context: active-structural-plan # bundle is active when the active view is a Structural Plan
context: active-area-plan # bundle is active when the active view is an Area Plan
context: active-elevation-view # bundle is active when the active view is an Elevation
context: active-section-view # bundle is active when the active view is a Section
context: active-3d-view # bundle is active when the active view is a 3D view
context: active-sheet # bundle is active when the active view is a Sheet
context: active-legend # bundle is active when the active view is a Legend
context: active-schedule # bundle is active when the active view is a Schedule
context: active-panel-schedule # bundle is active when the active view is a Panel Schedule
context: active-column-schedule # bundle is active when the active view is a Graphical Column Schedule
context: active-project-browser # bundle is active when the Project Browser has focus
context: active-system-browser # bundle is active when the System Browser has focus
Finally, the various context types can be combined together for more complex contexts. Here are some examples
Advanced Contexts
You can define more specific context conditions using any, all, and exact conditions. You can also use not_any, not_all, and not_exact to reverse the condition. Here are a series of examples:
Tool with this context only activates when: Active view is a Floor plan, and Walls OR Floors are selected
Tool with this context only activates when: Active view is either Floor plan or RCP, and Walls AND Floors are selected at the same time
Tool with this context only activates when: Active Document is a Project, and ONLY Walls AND Floors are selected
Tool with this context only activates when: Document is a Workshared Project and Walls AND Floors are selected
Tool with this context only activates when: Anything except Walls or Texts are selected
Tool with this context only activates when: Selection is NOT ONLY Walls and Texts