Formulas and Global Parameters

Formulas may be assigned to non-reporting parameters.

As with family parameters, formulas may be assigned to global parameters using the GlobalParameter.SetFormula() method. Since a global parameter must be non-reporting to set a formula, a reporting parameter must be changed to non-reporting prior to 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 whose type is ether Integer or Number.

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, and since some formulas cannot be assigned to certain parameters, the method IsValidFormula() can be used to test whether a formula is valid for a global parameter. If SetFormula() is called with an invalid formula for the global parameter, an Exception will be thrown.

GetFormula() will return the current formula in the form of a string.

The following code sample creates four global parameters and then sets a formula to one so that it has a value of either of two other parameters depending on the boolean value of the fourth one.

Code Region: Setting a formula

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");
    }

}