GlobalParameterSetDrivingDimension Method

Set a dimension to drive the value of this parameter.

Namespace: Autodesk.Revit.DB
Assembly: RevitAPI (in RevitAPI.dll) Version: 25.0.0.0 (25.0.0.0)

Syntax

public void SetDrivingDimension(
	ElementId dimensionId
)

Public Sub SetDrivingDimension ( 
	dimensionId As ElementId
)

public:
void SetDrivingDimension(
	ElementId^ dimensionId
)

member SetDrivingDimension : 
        dimensionId : ElementId -> unit

Parameters

dimensionId ElementId: Id of a dimension element.

Exceptions

Exception	Condition
ArgumentException	Given element Id is not of a valid dimension element. -or- Dimension with the Id of dimensionId cannot be labeled by this global parameter. Possible causes include the dimension cannot be labeled at all, or it is a dimension of other than Linear or Angular type, or the Dimension object does not have the appropriate labeling parameter, or the dimension has more than one segment and the parameter is reporting.
ArgumentNullException	A non-optional argument was null
InvalidOperationException	This is a formula-driven parameter. As such it does not allow the current operation. -or- This non-reporting global parameter has already labeled other dimension segments (more then 1). It cannot, therefore, be made reporting and dimension-driven before un-labeling all the dependent dimensions first.

Remarks

This method is a combined action of two steps: a) Making the parameter reporting if it is not yet, and b) Labeling the given dimension with it. Because of that, the parameter must be eligible for reporting - i.e must be of certain types, and must not be used to label more than one dimensions yet.

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

Example

C++

Copy

/// <summary>
/// Make a global parameter to be driven by the value of a dimension.
/// </summary>
/// <param name="document">Revit project document containing the global parameter and dimension elements.</param>
/// <param name="gpid">ElementId of a global parameter.</param>
/// <param name="dimid">ElementId of a dimension element.</param>
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;
}

' <summary>
' Make a global parameter to be driven by the value of a dimension.
' </summary>
' <param name="document">Revit project document containing the global parameter and dimension elements.</param>
' <param name="gpid">ElementId of a global parameter.</param>
' <param name="dimid">ElementId of a dimension element.</param>
Public Function AssignDrivingDimension(document As Document, gpid As ElementId, dimid As ElementId) As Boolean
    ' we expect to find the global parameter in the document
    Dim gp As GlobalParameter = TryCast(document.GetElement(gpid), GlobalParameter)
    If gp Is Nothing Then
        Return False
    End If

    ' we expect to find the given dimension in the document
    Dim [dim] As Dimension = TryCast(document.GetElement(dimid), Dimension)
    If [dim] Is Nothing Then
        Return False
    End If

    ' not every global parameter can label
    ' and not every dimension can be labeled
    If Not gp.CanLabelDimension(dimid) Then
        Return False
    End If

    ' we need a transaction to modify the model
    Using trans As 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
        Dim dimset As ISet(Of ElementId) = gp.GetLabeledDimensions()
        For Each elemid As ElementId In dimset
            gp.UnlabelDimension(elemid)
        Next

        ' 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 Then
            Return False
        End If
    End Using

    Return True
End Function

Reference

GlobalParameter Class

Autodesk.Revit.DB Namespace