LabelDimension Method


Labels a dimension with this global 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 LabelDimension(
	ElementId dimensionId
)
Visual Basic
Public Sub LabelDimension ( _
	dimensionId As ElementId _
)
Visual C++
public:
void LabelDimension(
	ElementId^ dimensionId
)

Parameters

dimensionId
Type: Autodesk.Revit.DB ElementId
Id of a dimension element.

Remarks

When a dimension is labeled by a global parameters, 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-reprting 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, not just any kind of dimensions may be labeled by a global parameter. Typically only single Linear and Angular dimensions can be labeled, but there are other restrictions in effect too. Also, for the value of the parameter and dimension labeled by it depend on each other, the data type of the global parameters must be either Length or Angle , since those are the only units a dimension can represent. Refer to the [!:CanLabelDimension(Autodesk::Revit::DB::ElementId)] method to find out whether a particular dimension element may be labeled or not.

Examples

Copy C#
/// <summary>
/// Creates a global parameter and uses it to label the set of given dimension elements 
/// </summary>
/// <param name="document">Revit project document that contains the dimension.</param>
/// <param name="gpname">A name of the global parameter to create.</param>
/// <param name="value">Initial value of the global parameter</param>
/// <param name="dimset">A collection of dimension elements to drive by a global parameter</param>
/// <returns>Number of actually labeled dimension</returns>
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;
}
Copy VB.NET
' <summary>
' Creates a global parameter and uses it to label the set of given dimension elements 
' </summary>
' <param name="document">Revit project document that contains the dimension.</param>
' <param name="gpname">A name of the global parameter to create.</param>
' <param name="value">Initial value of the global parameter</param>
' <param name="dimset">A collection of dimension elements to drive by a global parameter</param>
' <returns>Number of actually labeled dimension</returns>
Public Function DriveSelectedDimensions(document As Document, name As String, value As Double, dimset As ISet(Of ElementId)) As Integer
    If Not GlobalParametersManager.AreGlobalParametersAllowed(document) Then
        Throw New System.InvalidOperationException("Global parameters are not permitted in the given document")
    End If

    If Not GlobalParametersManager.IsUniqueName(document, name) Then
        Throw New System.ArgumentException("Global parameter with such name already exists in the document", "name")
    End If

    If value <= 0.0 Then
        Throw New System.ArgumentException("Value of a global parameter that drives dimension must be a positive number", "value")
    End If

    Dim nLabeledDims As Integer = 0
    ' number of labeled dimensions (for testing)
    ' creation of any element must be in a transaction
    Using trans As 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
        Dim newgp As GlobalParameter = GlobalParameter.Create(document, name, ParameterType.Length)
        If newgp IsNot Nothing Then
            newgp.SetValue(New DoubleParameterValue(value))

            ' use the parameter to label the given dimensions
            For Each elemid As ElementId In dimset
                ' not just any dimension is allowed to be labeled
                ' check first to avoid exceptions
                If newgp.CanLabelDimension(elemid) Then
                    newgp.LabelDimension(elemid)
                    nLabeledDims += 1
                End If
            Next

            trans.Commit()
        End If
    End Using

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


    ' 1.) Check the new parameter can be found


    Dim gpid As ElementId = GlobalParametersManager.FindByName(document, name)
    If gpid = ElementId.InvalidElementId Then
        TaskDialog.Show("Error", "Failed to find a newly created global parameter")
    End If

    Dim gp As GlobalParameter = TryCast(document.GetElement(gpid), GlobalParameter)

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


    Dim labeledSet As ISet(Of ElementId) = gp.GetLabeledDimensions()
    If labeledSet.Count <> nLabeledDims Then
        TaskDialog.Show("Error", "Have not found all the dimension that were labeled.")
    End If

    Return labeledSet.Count
End Function

Exceptions

Exception Condition
Autodesk.Revit.Exceptions 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.
Autodesk.Revit.Exceptions ArgumentNullException A non-optional argument was NULL

See Also