Assembly: RevitAPI (in RevitAPI.dll) Version: 220.127.116.11 (17.0.484.0)
Since: 2016 Subscription Update
Global parameters can be used to drive values of dimensions or other elements' parameters. Also, a global parameter can be driven by a selected dimension, the value of which then determines the value of the global parameter. Such parameters can further be used to drive values of other elements' parameters.See also the GlobalParametersManager class for methods that operate upon global parameters of a document, such as getting all defined global parameters and testing whether a global parameter of certain name already exists or not.
Reporting vs. Non-Reporting parameters
There are several ways global parameters can be categorized, but probably the most significant categorization stems from the IsReporting property which divides global parameters into two groups - Reporting and Non-Reporting. The significance of reporting parameters lays in the fact that their values are driven by the dimension that has been labeled by a reporting parameter. It means that the value of a reporting parameter reflects the value of a dimension (length or angle) and gets updated anytime the dimension changes. Non-Reporting parameters behave in the opposite manner - they drive value of dimensions that have been labeled by them, which results in controlling the model's geometry through global parameters' values.
Reporting parameters are limited in several ways. They can be only of Length or Angle type, a requirement due to the fact that a dimension must be able to drive the value. For the same reason reporting parameters may not have formulas.
Non-Reporting parameters, on the other way, can be of almost any type ( Length , Integer , Area , etc.) with the exception of ElementId type. Also, Non-Reporting parameters may have assigned formulas in which other global parameters may be used as arguments. This way one global parameter's value can be derived from other parameter (or parameters), and the other parameter can be either reporting or non-reporting.
Creating Global Parameters
Global parameters get created via the static method Create(Document, String, ParameterType) . It is important to note that each new parameter must have a name that is unique within the document. Parameters are created as non-reporting initially, but programmers are free to modify the IsReporting property once a global parameter is created and is of an eligible type. The programmer can call the HasValidTypeForReporting when in doubt whether parameters of a certain data type can be made reporting. Note, that a parameter may not be made reporting after more than one dimension has been labeled by it. It is because reporting parameter can label (and be driven) by one dimension only.
An alternative way of making a parameter reporting is via the SetDrivingDimension(ElementId) method which labels one dimension by a global parameter and also makes the parameter reporting if it is not reporting yet.
Other important properties of global parameters are IsDrivenByDimension and IsDrivenByFormula , which are mutually exclusive - a parameter that has a formula assigned cannot be driven by a dimension (nor can be reporting) and vice versa.
Global Parameters with formulas
Like with family parameters, formulas may be assigned to non-reporting global parameters using the SetFormula(String) method (paired with GetFormula to query the current formula.) Formulas may include all standard arithmetic operations and logical operations (as functions and , or , not .) Input to logical operations must be Boolean values (parameters of YesNo type). Consequently, arithmetic operations can be applied to numeric values only. While there are no operations supported for string (text) arguments, strings can be used as results of a logical If operation. Depending on their type (and units), parameters of different value types can be combined. However, unit-less values such as Integer and Number (double) may only be combined with each other. Since formulas can get quite complicated, the method IsValidFormula(String) is available for the programmer to ensure a formula is valid in order to avoid potential exception due to applying an invalid formula.
Probably the most notable feature of global parameters is their ability to "Label" dimensions, a process that establishes dependency of a dimension on a global parameter (or vice versa, depending on the reporting status.) One parameter can label any number of dimensions as long as the parameter is non-reporting. If the parameter labels a multi-segment dimension, values of all segments of this dimension will be equal to the parameter's value. As mentioned above, reporting parameter can label one dimension only, and this dimension can have only one segment. Methods and properties related to labeling include: LabelDimension(ElementId) , UnlabelDimension(ElementId) , and GetLabeledDimensions . Also in this set is the CanLabelDimension(ElementId) method which indicates whether or not a particular dimension can be labeled. Presently, only single linear dimensions and angles are permitted.
Elements affected by a Global Parameter
Global parameters can be associated with other global parameters as well as regular family instance parameters (which may report global parameters as their values via the assignment formula.) There are two methods available to find relations among parameters: GetAffectedGlobalParameters and GetAffectedElements . The former returns all other global parameters that refer to a particular global parameter in their respective formulas. The other method returns a set of all elements of which some parameters are controlled by the global parameter. These two methods together with the GetLabeledDimensions can help the programmer in figuring out how model elements relate to each other via global parameters.
Methods for maintaining associations between element properties and global parameters can be found in the Parameter class.
Getting and setting the value of a Global Parameter
All global parameters, formula-driven, dimension-driven, or independent, have values. A value can be obtained by calling the GetValue method. The object returned by that method is an instance of one of the classes derived from ParameterValue class. The concrete instance is determined by the type of the global parameter (specified upon creation.) Parameters that are neither formula-driven nor dimension-driven (reporting) can have a value assigned. The method to use is SetValue(ParameterValue) and it accepts the same type of ParameterValue that is returned by SetValue. However, the type can also be deduced easily: Text parameters accept only StringParameterValue . Integer and YesNo parameters accept only IntegerParameterValue . All other parameters accept only DoubleParameterValue .