Labeling Dimensions with Global Parameters

A key feature of global parameters is their ability to "label" dimensions.

When a dimension is labeled by a global parameter, then its value is either controlled by the parameter (non-reporting), or drives the value of the parameter (reporting). It is important to note that a reporting parameter can label at most one dimension object - meaning, a parameter can be driven by one dimension only. If the dimension has several segments and is labeled by a non-reporting parameter, the value of each segment will be driven by this parameter. Multi-segmented dimensions cannot be labeled by reporting parameters.

If the dimension is already labeled by another global parameter, labeling it again will automatically detach it from that parameter.

Presently, only single Linear and Angular dimensions can be labeled, but there are other restrictions in effect too. Use the CanLabelDimension() method to find out whether a particular dimension element may be labeled or not. Also, since the value of the parameter and the dimension labeled by it depend on each other, the data type of the global parameter must be either Length or Angle, since those are the only units a dimension can represent.

The following example creates a global parameter and uses it to label the set of given dimension elements.

Code Region: Labeling dimensions

public int DriveSelectedDimensions(Document document, string name, double value, ISet<ElementId> dimset)
{
    if (!GlobalParametersManager.AreGlobalParametersAllowed(document))
        throw new System.InvalidOperationException("Global parameters are not permitted in the given document");

    if (!GlobalParametersManager.IsUniqueName(document, name))
        throw new System.ArgumentException("Global parameter with such name already exists in the document", "name");

    if (value <= 0.0)
        throw new System.ArgumentException("Value of a global parameter that drives dimension must be a positive number", "value");

    int nLabeledDims = 0;   // number of labeled dimensions (for testing)

    // creation of any element must be in a transaction
    using (Transaction trans = new Transaction(document, "Create Global Parameter"))
    {
        trans.Start();

        // create a GP with the given name and type Length
        // Note: Length (or Angle) is required type of global parameters that are to label a dimension
        GlobalParameter newgp = GlobalParameter.Create(document, name, ParameterType.Length);
        if (newgp != null)
        {
            newgp.SetValue(new DoubleParameterValue(value));

            // use the parameter to label the given dimensions
            foreach (ElementId elemid in dimset)
            {
                // not just any dimension is allowed to be labeled
                // check first to avoid exceptions
                if (newgp.CanLabelDimension(elemid))
                {
                    newgp.LabelDimension(elemid);
                    nLabeledDims += 1;
                }
            }

            trans.Commit();
        }
    }

    // for illustration purposes only, we'll test the results of our modifications 

    // 1.) Check the new parameter can be found

    ElementId gpid = GlobalParametersManager.FindByName(document,name);
    if (gpid == ElementId.InvalidElementId)
    {
        TaskDialog.Show("Error", "Failed to find a newly created global parameter");
    }

    GlobalParameter gp = document.GetElement(gpid) as GlobalParameter;

    // 2. Check the number of labeled dimension is as expected

    ISet<ElementId> labeledSet = gp.GetLabeledDimensions();
    if (labeledSet.Count != nLabeledDims)
    {
        TaskDialog.Show("Error", "Have not found all the dimension that were labeled.");
    }

    return labeledSet.Count;
}

The SetDrivingDimension() method combines two actions: a) Making the parameter reporting if it is not yet, and b) Labeling the given dimension with it. Therefore, the global parameter must be eligible for reporting, and must not be used to label more than one dimensions yet. See the Reporting vs. Non-Reporting Parameters page for more information on reporting parameters

In case this parameter is already driven by another dimension, the other dimension will be unlabeled first before the given one is labeled. This is because a reporting parameter can only label one dimension at a time (i.e. it can be driven by one dimension only.)

The next example creates a global parameter to be driven by the value of a dimension.

Code Region: Assign driving dimension

public bool AssignDrivingDimension(Document document, ElementId gpid, ElementId dimid)
{
    // we expect to find the global parameter in the document
    GlobalParameter gp = document.GetElement(gpid) as GlobalParameter;
    if (gp == null)
        return false;

    // we expect to find the given dimension in the document
    Dimension dim = document.GetElement(dimid) as Dimension;
    if (dim == null)
        return false;

    // not every global parameter can label
    // and not every dimension can be labeled
    if (!gp.CanLabelDimension(dimid))
        return false;

    // we need a transaction to modify the model
    using (Transaction trans = new Transaction(document,"Assign a driving dimension"))
    {
        trans.Start();

        // we cannot assign a driving dimension to a global
        // parameter that is already used to label other dimensions
        ISet<ElementId> dimset = gp.GetLabeledDimensions();
        foreach (ElementId elemid in dimset)
        {
            gp.UnlabelDimension(elemid);
        }
                
        // with the GP free of all previously labels (if there were any)
        gp.SetDrivingDimension(dimid);

        // we should be able to commit, but we test the result anyway
        if (trans.Commit() != TransactionStatus.Committed)
            return false;
    }

    return true;
}