SetFormula Method


Sets a formula expression for this parameter.

Namespace: Autodesk.Revit.DB
Assembly: RevitAPI (in RevitAPI.dll) Version: 17.0.0.0 (17.0.1090.0)
Since: 2016 Subscription Update

Syntax

C#
public void SetFormula(
	string expression
)
Visual Basic
Public Sub SetFormula ( _
	expression As String _
)
Visual C++
public:
void SetFormula(
	String^ expression
)

Parameters

expression
Type: System String
Valid formula string.

Remarks

An assigned expression will compute the parameter's actual value.

In order to set a formula, the global parameter must be non-reporting. Therefore a reporting parameter must be changed to non-reporting first before assigning a formula.

Value of the evaluated formula must be compatible with the value-type of the parameter. For example, it is permitted to use Integer parameters in a formula assigned to a Double ( Number ) parameter, or vice versa. It is not allowed, however, to use Length or Angle arguments in a formula in a parameter of which type is ether Integer or Number . To test whether a formula is valid for a global parameter, the method IsValidFormula(String) can be used.

An empty string can be used to remove an existing formula. When a formula is removed, the parameter retains its value as it was previously computed using the 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.

Examples

Copy C#
/// <summary>
/// Create global parameters and then set a formula to one so it has a value of
/// either of two other parameters depending on the boolean value of the forth one.
/// </summary>
/// <param name="document">Revit project document in which we create global parameters.</param>
public void SetCombinationParameters(Document document)
{
    GlobalParameter gpB = null;
    GlobalParameter gpT = null;
    GlobalParameter gpF = null;
    GlobalParameter gpX = null;

    int TRUE = 1;
    int FALSE = 0;

    // transaction to create global parameters and set their values
    using (Transaction trans = new Transaction(document, "Creating global parameters"))
    {
        // create 4 new global parameters

        trans.Start();

        gpB = GlobalParameter.Create(document, "GPB", ParameterType.YesNo);
        gpT = GlobalParameter.Create(document, "GPT", ParameterType.Text);
        gpF = GlobalParameter.Create(document, "GPF", ParameterType.Text);
        gpX = GlobalParameter.Create(document, "GPX", ParameterType.Text);

        // assign initial values and a formula to the global parameters

        gpB.SetValue(new IntegerParameterValue(TRUE));
        gpT.SetValue(new StringParameterValue("TypeA"));
        gpF.SetValue(new StringParameterValue("TypeB"));

        // Set the formula to GPX so that its final value is either the value of GPT (TypeA)
        // or GPF (TypeB) depending on whether the value of GPB is True or False.
        // Note: in this particular case we are certain the formula is valid, but if weren't 
        // certain, we could use a validation method as we are now going to illustrate here:
        string expression = "if(GPB,GPT,GPF)"; // XPX <== if (GPB == TRUE) then GPT else GPF
        if (gpX.IsValidFormula(expression))
        {
            gpX.SetFormula(expression);  
        }

        trans.Commit();
    }

    // we can test that the formula works
    // since the boolean value is TRUE, the value of the GPX parameter
    // should be the same as the value of the GPT parameters

    StringParameterValue sTrue = gpT.GetValue() as StringParameterValue;
    StringParameterValue sFalse = gpF.GetValue() as StringParameterValue;
    StringParameterValue sValue = gpX.GetValue() as StringParameterValue;

    if (sValue.Value != sTrue.Value)
    {
        TaskDialog.Show("Error", "Unexpected value of a global parameter");
    }

    // we can also test that evaluation of the formula is affected by changes

    using (Transaction trans = new Transaction(document, "Change value of a YesNo parameter"))
    {
        trans.Start();
        gpB.SetValue(new IntegerParameterValue(FALSE));
        trans.Commit();
    }

    sValue = gpX.GetValue() as StringParameterValue;

    if (sValue.Value != sFalse.Value)
    {
        TaskDialog.Show("Error", "Unexpected value of a global parameter");
    }

}
Copy VB.NET
' <summary>
' Create global parameters and then set a formula to one so it has a value of
' either of two other parameters depending on the boolean value of the forth one.
' </summary>
' <param name="document">Revit project document in which we create global parameters.</param>
Public Sub SetCombinationParameters(document As Document)
    Dim gpB As GlobalParameter = Nothing
    Dim gpT As GlobalParameter = Nothing
    Dim gpF As GlobalParameter = Nothing
    Dim gpX As GlobalParameter = Nothing

    Dim [TRUE] As Integer = 1
    Dim [FALSE] As Integer = 0

    ' transaction to create global parameters and set their values
    Using trans As New Transaction(document, "Creating global parameters")
        ' create 4 new global parameters


        trans.Start()

        gpB = GlobalParameter.Create(document, "GPB", ParameterType.YesNo)
        gpT = GlobalParameter.Create(document, "GPT", ParameterType.Text)
        gpF = GlobalParameter.Create(document, "GPF", ParameterType.Text)
        gpX = GlobalParameter.Create(document, "GPX", ParameterType.Text)

        ' assign initial values and a formula to the global parameters


        gpB.SetValue(New IntegerParameterValue([TRUE]))
        gpT.SetValue(New StringParameterValue("TypeA"))
        gpF.SetValue(New StringParameterValue("TypeB"))

        ' Set the formula to GPX so that its final value is either the value of GPT (TypeA)
        ' or GPF (TypeB) depending on whether the value of GPB is True or False.
        ' Note: in this particular case we are certain the formula is valid, but if weren't 
        ' certain, we could use a validation method as we are now going to illustrate here:
        Dim expression As String = "if(GPB,GPT,GPF)"
        ' XPX <== if (GPB == TRUE) then GPT else GPF
        If gpX.IsValidFormula(expression) Then
            gpX.SetFormula(expression)
        End If

        trans.Commit()
    End Using

    ' we can test that the formula works
    ' since the boolean value is TRUE, the value of the GPX parameter
    ' should be the same as the value of the GPT parameters


    Dim sTrue As StringParameterValue = TryCast(gpT.GetValue(), StringParameterValue)
    Dim sFalse As StringParameterValue = TryCast(gpF.GetValue(), StringParameterValue)
    Dim sValue As StringParameterValue = TryCast(gpX.GetValue(), StringParameterValue)

    If sValue.Value <> sTrue.Value Then
        TaskDialog.Show("Error", "Unexpected value of a global parameter")
    End If

    ' we can also test that evaluation of the formula is affected by changes


    Using trans As New Transaction(document, "Change value of a YesNo parameter")
        trans.Start()
        gpB.SetValue(New IntegerParameterValue([FALSE]))
        trans.Commit()
    End Using

    sValue = TryCast(gpX.GetValue(), StringParameterValue)

    If sValue.Value <> sFalse.Value Then
        TaskDialog.Show("Error", "Unexpected value of a global parameter")
    End If

End Sub

Exceptions

Exception Condition
Autodesk.Revit.Exceptions ArgumentException The given expression argument is not valid as a formula for this parameter.
Autodesk.Revit.Exceptions ArgumentNullException A non-optional argument was NULL
Autodesk.Revit.Exceptions InvalidOperationException This is a non-reporting global parameter. As such it does not allow the current operation.

See Also