Most non-geometrical element data in Revit is stored in element parameters, so this is obviously an important topic, and one that we have not explored much yet. We did touch on it when discussing adding a shared parameter to a DWG file, and now we will recapitulate some basics and discuss the built-in parameter checker, which is a useful tool for exploring element parameters.
First some brief basic facts of life on parameters. They are discussed in more detail by the DevTV recording available for online viewing or download and the Revit API introduction labs, especially the sample commands in Labs4.cs.
Every Revit element has parameters attached to it, and the 'official' collection of parameters can be accessed through the Element Parameters property. If you are looking for a specific parameter, you can also use one of the direct access methods to retrieve a parameter from an element:
- Parameter( BuiltInParameter ): given a built-in parameter enumeration id.
- Parameter( Definition ): given a parameter definition.
- Parameter( Guid ): given a GUID for a shared parameter.
- Parameter( String ): given a localised parameter name.
A parameter has a value and a definition associated with it. The definition manages data such as the user visible parameter name and the interpretation of the parameter data. Shared parameters also have a GUID associated with them. All four methods above can be used to retrieve an individual parameter. Using the localised parameter name should be avoided, though, since it will cause the application to be language dependent. The build-in parameter enumeration is a hard-coded list of several hundred different parameters and provides a language independent method to identify most parameters.
Sometimes an element will have other parameters attached to it as well, which are not listed in the 'official' collection returned by the Parameters property. To explore all parameters attached to an element, one can make use of the built-in parameter checker.
This useful tool is included with the labs. It iterates over all the built-in parameter enumeration values and attempts to read a parameter for each one. Each one successfully retrieved is listed with all of its data, including the enumeration value, the localised name, the value, the string representation, and its read-write status. If the value is an element id, the id is evaluated and the type and name of referenced element is listed.
This tool can be used in conjunction with another tool also provided by the labs, the element lister implemented in Lab2_1_Elements, to discover information about elements that are not easy to access otherwise. As an example, let us analyse the data associated with Revit filters in the database, starting with the following question:
How can I access the filters stored in a Revit document?
We can explore this issue in the following manner: First, create an empty Revit model. In that, list all the elements in the document into a text file RevitElementsBeforeFilter.txt. Then, create a filter and list the elements again in RevitElementsAfterFilter.txt. Now we can determine the properties of the filter element that was added:
C:\tmp\ > diff RevitElementsBeforeFilter.txt RevitElementsAfterFilter.txt 2159a2160 > Id=127147; Class=Symbol; Category=?; Name=Filter 1
As you can see, one single element was added to the database, the filter element. Its System.Type is Symbol. It does not have a category associated with it, so we cannot use that to identify it. Its element name is "Filter 1". Next, we can explore its parameters and see whether they might be used to help identify filter elements. Entering the element id in the Revit menu entry Tools > Element Ids > Select by ID, select the filter into the current Revit selection set and list its parameters using the built-in parameter checker:
Symbol 'Filter 1' 127147 Instance Built-in Parameters ELEM_CATEGORY_PARAM_MT Category ElementId read-only -1 ELEM_CATEGORY_PARAM Category ElementId read-only -1 DESIGN_OPTION_ID Design Option ElementId read-only -1 PHASE_DEMOLISHED Phase Demolished ElementId read-write -1 PHASE_CREATED Phase Created ElementId read-write -1 ELEMENT_LOCKED_PARAM Locked Integer read-write 0 ELEM_DELETABLE_IN_FAMILY Deletable Integer read-write 1 UNIFORMAT_DESCRIPTION Assembly Description String read-only UNIFORMAT_CODE Assembly Code String read-write ID_PARAM Id ElementId read-only Symbol 'Filter 1' 127147 EDITED_BY Edited by String read-only ELEM_PARTITION_PARAM Workset Integer read-write 0 ELEM_FAMILY_AND_TYPE_PARAM Family and Type ElementId read-only -1 ELEM_FAMILY_PARAM Family ElementId read-only -1 ELEM_TYPE_PARAM Type ElementId read-only -1 SYMBOL_FAMILY_AND_TYPE_NAMES_PARAM Family and Type String read-only Filters: Filter 1 SYMBOL_FAMILY_NAME_PARAM Family Name String read-only Filters SYMBOL_FAMILY_NAME_PARAM Family Name String read-only Filters SYMBOL_NAME_PARAM Type Name String read-only Filter 1 SYMBOL_NAME_PARAM Type Name String read-only Filter 1 SYMBOL_ID_PARAM Type Id ElementId read-only -1
Please excuse the overly long lines ... you can see them in full by copying them to a text file. This shows all the information accessible through the API for the filter element. This information may be enough to identify the filters in the document. For instance, it might be possible to use combinations of these built-in parameters to construct a Revit API filter to extract all database elements of interest.
Addendum: For an improved version of the built-in parameter checker for Revit 2012, please refer to the BipChecker.