LabelDefinition QML Type

An object that defines the text, appearance, and position of labels for features within a given scale range. More...

Import Statement: import Esri.ArcGISRuntime 100.15
Since: Esri.ArcGISRuntime 100.1
Inherits:

Object

Properties

Signals

Detailed Description

A LabelDefinition describes a class of labels. A collection of label definitions can be attached to a feature data source (example FeatureLayer). Each LabelDefinition specifies:

  • which features are covered by the definition, by applying the whereClause SQL constraint
  • what text should be displayed, based on the individual feature's attributes and the chosen expression formula
  • how the text should appear, using the label definition's TextSymbol
  • where the text should appear, with respect to its feature, using the placement
  • how to move or avoid other labels or features that would overlap each label.

See also JsonSerializable.

Property Documentation

angle : LabelAngle

The angular positions and layout directions for labels on or around point feature symbols.

This optional object specifies how to position a label following the direction of an angle. The angular position may be different for each feature (driven by one or more feature attributes) or constant for all features (specified by a fixed number).

The placement will still be used to indicate whether offset or centered positioning is required, but the exact position will be overridden by the angle calculated for the feature. After the position has been determined, textLayout and textOrientation are used to specify the layout of the text at that position.

This property was introduced in Esri.ArcGISRuntime 100.11.


deconflictionStrategy : Enums.LabelDeconflictionStrategy

The strategy for moving labels to avoid overlapping feature, annotation, dimension, or graphic symbols or higher-priority labels.

The default is Enums.LabelDeconflictionStrategyAutomatic (which will be interpreted as Enums.LabelDeconflictionStrategyStatic, meaning, use preferred location unless it overlaps an obstacle). In 3D Enums.LabelDeconflictionStrategyStatic is selected by default.

This property was introduced in Esri.ArcGISRuntime 100.11.


expression : LabelExpression

The expression script used to calculate the label text.

The expression may be a combination of literal text and attribute values from the feature being labeled. The syntax of the expression is determined by which label expression object is used: ArcadeLabelExpression, SimpleLabelExpression or WebmapLabelExpression.

A label expression using one scripting language can be replaced by an expression using a different scripting language just by creating an object of the new LabelExpression subclass and assigning it to expression.

The default value is an empty ArcadeLabelExpression, which will evaluate to an empty text label.

The expression needs to create a text string which will be used as the label text. The text string can be any legal UTF16 characters.

The text string can also include HTML-style formatting tags e.g.

"Hello <BOL>World</BOL>"

where the angle-bracketed tags will not appear in the label, but may change the presentation of the text. In the example, the "World" will appear in bold.

The available tags are:

  • <BOL></BOL> for bold text
  • <UND></UND> for underlined text
  • <ITA></ITA> for italic text
  • <CLR red='256'></CLR> for colored text
  • <FNT name='Arial' size='18'></FNT> for text using a different size or font (if available on client).

Tags can be upper or lower case, but not a mixture. Tags can be nested e.g. "<ITA>Hello <BOL>World</BOL></ITA>".

Full documentation of the tag parameters is available at https://pro.arcgis.com/en/pro-app/latest/help/mapping/text/text-formatting-tags.htm.

Note that not all ArcGIS Pro tags are currently supported in Runtime. The "<CLR>" tag is currently only supported for text in 2D views. Any unsupported tags will be ignored and not written as part of the label text.

This property was introduced in Esri.ArcGISRuntime 100.11.


featureBoundaryOverlapStrategy : Enums.LabelOverlapStrategy

The strategy for whether other labels are allowed to overlap the boundary of polygon features/graphics being labeled by this LabelDefinition.

The default is Enums.LabelOverlapStrategyAutomatic, which will give the same behavior as Enums.LabelOverlapStrategyAllow.

In 3D scenes, labels will be allowed to overlap the boundaries of polygon features.

This property was introduced in Esri.ArcGISRuntime 100.11.


featureInteriorOverlapStrategy : Enums.LabelOverlapStrategy

The strategy for whether other labels are allowed to overlap the polygon features/graphics being labeled by this LabelDefinition.

The default is Enums.LabelOverlapStrategyAutomatic, which will give the same behavior as Enums.LabelOverlapStrategyAllow.

In 3D scenes, labels will be allowed to overlap the boundaries of polygon features.

This property was introduced in Esri.ArcGISRuntime 100.11.


json : jsobject

JSON that can be used to instantiate the LabelDefinition.


labelOverlapStrategy : Enums.LabelOverlapStrategy

The strategy for whether other labels are allowed to overlap labels created by this LabelDefinition.

The default is Enums.LabelOverlapStrategyAutomatic, which will give the same behavior as Enums.LabelOverlapStrategyExclude.

In 3D, labels will not be allowed to overlap other labels. Overlapping labels will not be displayed until the user zooms in further so that the labels don't overlap

This property was introduced in Esri.ArcGISRuntime 100.11.


lineConnection : Enums.LabelLineConnection

The strategy for whether line features with the same label, and matching end vertices, should be joined before sharing a label.

3D line features will be treated as independent features with their own label.

The default is Enums.LabelLineConnectionAutomatic, which will be interpreted as Enums.LabelLineConnectionMinimizeLabels.

This property was introduced in Esri.ArcGISRuntime 100.11.


maxScale : double

The maximum scale at which labels will be visible.

Labels will only be visible when the viewing scale is smaller than (or equal to) the maxScale.

For example, if the viewing scale is 1:12000 and the maxScale is 1:10000, then the labels will be visible (because 1/12000 <= 1/10000). A maxScale of 0, which is the default, indicates no upper limit on the viewing scale.

In 3D scenes,the scale range is between individual label and view plane instead of map and view plane.

This property was introduced in Esri.ArcGISRuntime 100.11.


minScale : double

The minimum scale at which labels will be visible.

Labels will only be visible when the viewing scale is larger than (or equal to) the minScale.

For example, if the viewing scale is 1:12000 and the minScale is 1:20000, then the labels will be visible (because 1/12000 >= 1/20000). A minScale of 0, which is the default, indicates no lower limit on the viewing scale.

In 3D scenes, the scale range is between individual label and view plane instead of map and view plane.

This property was introduced in Esri.ArcGISRuntime 100.11.


multipartStrategy : Enums.LabelMultipartStrategy

The strategy for how many labels should be placed on each polyline or polygon (multi-ring) feature.

The default is Enums.LabelMultipartStrategyAutomatic.

This property was introduced in Esri.ArcGISRuntime 100.11.


name : string

Text name for the class of labels.

This name is assigned by the map author to clarify the purpose of this label definition. It is used for display or debugging purposes. If no name is explicitly assigned, then an empty text string is stored.

This property was introduced in Esri.ArcGISRuntime 100.11.


offsetDistance : double

The distance in points (1/72 inches) that text should be moved away from its features.

The distance is measured from the point symbol radius or line feature symbology edge. The distance is measured on the screen (i.e. not in the map) in points, comparable to the text font size.

This can be a negative value, to pull the label closer to the feature if, for example, the average size for a point symbol is overly conservative for the actual graphic shown.

If no value is set, then 1 point is assumed.

This property was introduced in Esri.ArcGISRuntime 100.11.


overrunStrategy : Enums.LabelOverrunStrategy

The strategy for whether a label will be visible at scales where the feature is too small for the label to fit.

The default is Enums.LabelOverrunStrategyAutomatic, which will give different behavior depending on the type of feature that the label might overrun.

This property was introduced in Esri.ArcGISRuntime 100.11.


placement : Enums.LabelingPlacement

The preferred position of the text label, with respect to its feature geometry.

The default is Enums.LabelingPlacementAutomatic. The effect of this is the same as one of the following, depending on the type of feature geometry:

This property was introduced in Esri.ArcGISRuntime 100.11.


priority : double

Defines which labels are placed first, and can also supplant existing lower-priority labels (e.g., during panning).

Lower values indicate more important labels; higher values indicate lower priority, i.e.:

  • 0 is the most important
  • 5 is high priority
  • 15 is medium priority

If set to -1 or not set at all, then default values are used, depending on the geometry types of the features:

  • 12 for point features
  • 15 for line features
  • 18 for polygon features

This value does not have to be an integer because it is just a continuum of values for comparison. Users can use this to specify that a class of labels should have priority between two other classes with close priorities.

For example, PreferredRoutes might be given priority 13 to appear ahead of general line feature labels, but after general point feature labels. And HistoricSites might be given priority 12.5 to appear ahead of PreferredRoute labels, but still after general point feature labels.

This property was introduced in Esri.ArcGISRuntime 100.11.


removeDuplicatesDistance : double

A value that controls the duplicate thinning radius in points (1/72 inches).

The distance is measured on the screen (i.e. not in the map) in points, comparable to the text font size. This value is only used if removeDuplicatesStrategy is enabled. The default value is 0. This indicates that duplicates should be removed from the entire extent.

This property was introduced in Esri.ArcGISRuntime 100.11.


removeDuplicatesStrategy : Enums.LabelRemoveDuplicatesStrategy

The strategy for whether labels are removed if other features have the same text label. This can reduce clutter and free up space.

The default is Enums.LabelRemoveDuplicatesStrategyAutomatic, which will be interpreted as Enums.LabelRemoveDuplicatesStrategyNone indicating that all labels should be shown if possible.

The distance within which to look for duplicates is controlled by removeDuplicatesDistance.

This property was introduced in Esri.ArcGISRuntime 100.11.


repeatDistance : double

The distance apart in points (1/72 inches) that the repetitions should be.

This value is only used if repeatStrategy is enabled. The distance is measured on the screen along the line feature. As the user zooms in closer, two repetitions move further apart on the screen, until there is room for a new repetition between them. The default is 216 points i.e. line labels should be repeated approximately every 3 inches along long features.

In 3D scenes, only one label will be placed per line feature.

A distance of 0 disables label repetition.

This property was introduced in Esri.ArcGISRuntime 100.11.


repeatStrategy : Enums.LabelRepeatStrategy

The strategy for whether a label should have multiple copies created and placed along or across the same feature.

The default is Enums.LabelRepeatStrategyAutomatic.

The frequency of repetition is controlled by the repeatDistance property.

In 3D scenes, only one label will be placed per line feature. This property is currently only supported for line features, but will be extended to polygons in the future.

This property was introduced in Esri.ArcGISRuntime 100.11.


stackAlignment : Enums.LabelStackAlignment

The strategy for how multi-row (stacked) text should be aligned.

Multi-row text labels can be horizontally aligned on the left, right or at its center. This preference can be specified by the TextSymbol assigned to the LabelDefinition. By using the stackAlignment property, the user can choose to use the TextSymbol::horizontalAlignment property for all labels, or can choose to have the most aesthetic alignment calculated case-by-case for each label depending on its placement position around its feature. This is particularly useful for labels of dense point features, where labels may move above, below, left or right of their point symbol, in order to fit on the display.

The default value is Enums.LabelStackAlignmentAutomatic (which will have the same effect on labels as Enums.LabelStackAlignmentTextSymbol).

This property has no effect if stackStrategy equals Enums.LabelStackStrategyNone.

This property was introduced in Esri.ArcGISRuntime 100.11.


stackBreakPosition : Enums.LabelStackBreakPosition

The strategy for whether a row of text should be broken before or after it exceeds the ideal length.

If stacking is turned on, label placement can insert a line break before or after the word that overruns the maximum number of characters per row. Using the Enums.LabelStackBreakPositionBefore option means rows will generally be shorter than the stackRowLength (although will overrun for individual words larger than this count).

The default is Enums.LabelStackBreakPositionAutomatic (which will have the same effect on labels as Enums.LabelStackBreakPositionAfter).

This property has no effect if stackStrategy equals Enums.LabelStackStrategyNone.

This property was introduced in Esri.ArcGISRuntime 100.11.


stackRowLength : double

A value that limits the number of characters in a row of stacked text.

This length guides the decision on when to break long text strings into separate rows. The line break will be inserted between words, not in the middle of a word, so rows may be longer or shorter than the ideal. Depending on stackBreakPosition, the break may be inserted before the breaking word, or after.

The default value is -1, which means to use a default length determined by ArcGIS Runtime (currently 13 characters but may vary with feature-geometry in the future).

This property has no effect if stackStrategy equalsEnums.LabelStackStrategyNone.

This property was introduced in Esri.ArcGISRuntime 100.11.


stackSeparators : LabelStackSeparatorListModel

The stack separators that should be used for automatic line breaking of label text.

Each LabelStackSeparator specifies a code point to be looked for in the text. A code point is often thought of as a single character in the text, but may need several chars in a QString to describe it. So each LabelStackSeparator::separator is a QString intended to describe one code point.

For example:

  • To use a comma as a separator, the LabelStackSeparator::separator string would be just ",".
  • To use a Hebrew punctuation Paseq as a separator, the LabelStackSeparator::separator would need to encode the code point with utf16 value "\u05c0".
  • To use higher range unicode code points such as Aegean Word Separator Dot( which has utf32 hex value 10101), the LabelStackSeparator::separator would need to encode the code point with utf16 value "\ud800\udd01".

If it is found, then the LabelStackSeparator also specifies whether:

  • the text should always be broken here
  • the separator code point should remain visible
  • the separator code point should appear at the end of one row, or the beginning of the next.

Three default separators are provided: a comma, a space, and a hyphen. Custom separators can be added, and default separators can be removed if not required.

Note that a carriage-return (\n) in the label will always be considered a forced separator.

This property has no effect if stackStrategy equalsEnums.LabelStackStrategyNone.

This property was introduced in Esri.ArcGISRuntime 100.11.


stackStrategy : Enums.LabelStackStrategy

The strategy for whether the text should be stacked or wrapped, rather than placed as long trailing labels across the map.

This property controls whether stacking is allowed, not allowed, or should be calculated automatically based on feature type. The default is Enums.LabelStackStrategyAutomatic, meaning that stacking will be enabled for point and polygon features and disabled for line features.

This property was introduced in Esri.ArcGISRuntime 100.11.


textLayout : Enums.LabelTextLayout

The layout of the text, which can be either horizontal, straight, perpendicular, or follow the line feature.

Optional specification of whether, once the text is positioned, it should be written:

  • horizontally
  • straight (parallel) to the tangent to the line feature
  • straight in line with the point feature positioning angle
  • perpendicular to the tangent or positioning angle
  • following the geometry of the line feature.

The default is Enums.LabelTextLayoutAutomatic, which will be interpreted as:

  • {Enums.LabelTextLayout} {Enums.LabelTextLayoutHorizontal} for labels attached to point features
  • {Enums.LabelTextLayout} {Enums.LabelTextLayoutFollowFeature} for labels attached to line features
  • {Enums.LabelTextLayout} {Enums.LabelTextLayoutHorizontal} for labels attached to polygon features.

This property was introduced in Esri.ArcGISRuntime 100.11.


textOrientation : Enums.LabelTextOrientation

The orientation of the text, which can be either angle direction or screen-oriented.

This is an optional specification of whether text should follow the placement angle direction even if it means being rendered upside-down, or text should be flipped through 180 degrees to keep it screen-oriented. This setting will take effect whenever the feature geometry determines that the text is angled upside-down, or if the map is rotated within the screen to make the text upside-down (with respect to the screen). The default is Enums.LabelTextOrientationAutomatic, which is interpreted as Enums.LabelTextOrientationScreen.

Not supported by 3D scenes.

This property was introduced in Esri.ArcGISRuntime 100.11.


textSymbol : TextSymbol

The text symbol that describes the overall appearance of label text (e.g., font and size).

If no textSymbol has been set, then no labels can be created.

This property was introduced in Esri.ArcGISRuntime 100.11.


unknownJson : jsobject

Returns the unknown JSON from the source JSON.

See also JsonSerializable.


unsupportedJson : jsobject

Returns the unsupported data from the source JSON.

See also JsonSerializable.


useCodedValues : bool

Specifies whether the data source should translate domain identifiers into meanings using a CodedValueDomain.

For any translation to occur, the data source must have one or more CodedValueDomain s set up for the attribute fields. The default value is true i.e., translation is done.

This property was introduced in Esri.ArcGISRuntime 100.11.


whereClause : string

An SQL WHERE clause expression that limits the set of features for which labels will be generated and placed.

This is an SQL WHERE clause that can refer to the attributes of the feature e.g.,

  • "" (no limitations)
  • "NAME LIKE 'A%'" (Only label features with NAME attribute values starting with 'A')
  • "(LENGTH > CAPACITY) and (TYPE = 1)" (Only label features whose attributes satisfy the SQL condition).

The default value is "" - which will allow all features in the data source and extent to be labeled.

This property was introduced in Esri.ArcGISRuntime 100.11.


Signal Documentation

angleChanged()

Emitted when the angle property changes.

Note: The corresponding handler is onAngleChanged.

This signal was introduced in Esri.ArcGISRuntime 100.11.


deconflictionStrategyChanged()

Emitted when the deconflictionStrategy property changes.

Note: The corresponding handler is onDeconflictionStrategyChanged.

This signal was introduced in Esri.ArcGISRuntime 100.11.


expressionChanged()

Emitted when the expression property changes.

Note: The corresponding handler is onExpressionChanged.

This signal was introduced in Esri.ArcGISRuntime 100.11.


featureBoundaryOverlapStrategyChanged()

Emitted when the featureBoundaryOverlapStrategy property changes.

Note: The corresponding handler is onFeatureBoundaryOverlapStrategyChanged.

This signal was introduced in Esri.ArcGISRuntime 100.11.


featureInteriorOverlapStrategyChanged()

Emitted when the featureInteriorOverlapStrategy property changes.

Note: The corresponding handler is onFeatureInteriorOverlapStrategyChanged.

This signal was introduced in Esri.ArcGISRuntime 100.11.


labelOverlapStrategyChanged()

Emitted when the labelOverlapStrategy property changes.

Note: The corresponding handler is onLabelOverlapStrategyChanged.

This signal was introduced in Esri.ArcGISRuntime 100.11.


lineConnectionChanged()

Emitted when the lineConnection property changes.

Note: The corresponding handler is onLineConnectionChanged.

This signal was introduced in Esri.ArcGISRuntime 100.11.


maxScaleChanged()

Emitted when the maxScale property changes.

Note: The corresponding handler is onMaxScaleChanged.

This signal was introduced in Esri.ArcGISRuntime 100.11.


minScaleChanged()

Emitted when the minScale property changes.

Note: The corresponding handler is onMinScaleChanged.

This signal was introduced in Esri.ArcGISRuntime 100.11.


multipartStrategyChanged()

Emitted when the multipartStrategy property changes.

Note: The corresponding handler is onMultipartStrategyChanged.

This signal was introduced in Esri.ArcGISRuntime 100.11.


nameChanged()

Emitted when the name property changes.

Note: The corresponding handler is onNameChanged.

This signal was introduced in Esri.ArcGISRuntime 100.11.


offsetDistanceChanged()

Emitted when the offsetDistance property changes.

Note: The corresponding handler is onOffsetDistanceChanged.

This signal was introduced in Esri.ArcGISRuntime 100.11.


overrunStrategyChanged()

Emitted when the overrunStrategy property changes.

Note: The corresponding handler is onOverrunStrategyChanged.

This signal was introduced in Esri.ArcGISRuntime 100.11.


placementChanged()

Emitted when the placement property changes.

Note: The corresponding handler is onPlacementChanged.

This signal was introduced in Esri.ArcGISRuntime 100.11.


priorityChanged()

Emitted when the priority property changes.

Note: The corresponding handler is onPriorityChanged.

This signal was introduced in Esri.ArcGISRuntime 100.11.


removeDuplicatesDistanceChanged()

Emitted when the removeDuplicatesDistance property changes.

Note: The corresponding handler is onRemoveDuplicatesDistanceChanged.

This signal was introduced in Esri.ArcGISRuntime 100.11.


removeDuplicatesStrategyChanged()

Emitted when the removeDuplicatesStrategy property changes.

Note: The corresponding handler is onRemoveDuplicatesStrategyChanged.

This signal was introduced in Esri.ArcGISRuntime 100.11.


repeatDistanceChanged()

Emitted when the repeatDistance property changes.

Note: The corresponding handler is onRepeatDistanceChanged.

This signal was introduced in Esri.ArcGISRuntime 100.11.


repeatStrategyChanged()

Emitted when the repeatStrategy property changes.

Note: The corresponding handler is onRepeatStrategyChanged.

This signal was introduced in Esri.ArcGISRuntime 100.11.


stackAlignmentChanged()

Emitted when the stackAlignment property changes.

Note: The corresponding handler is onStackAlignmentChanged.

This signal was introduced in Esri.ArcGISRuntime 100.11.


stackBreakPositionChanged()

Emitted when the stackBreakPosition property changes.

Note: The corresponding handler is onStackBreakPositionChanged.

This signal was introduced in Esri.ArcGISRuntime 100.11.


stackRowLengthChanged()

Emitted when the stackRowLength property changes.

Note: The corresponding handler is onStackRowLengthChanged.

This signal was introduced in Esri.ArcGISRuntime 100.11.


stackStrategyChanged()

Emitted when the stackStrategy property changes.

Note: The corresponding handler is onStackStrategyChanged.

This signal was introduced in Esri.ArcGISRuntime 100.11.


textLayoutChanged()

Emitted when the textLayout property changes.

Note: The corresponding handler is onTextLayoutChanged.

This signal was introduced in Esri.ArcGISRuntime 100.11.


textOrientationChanged()

Emitted when the textOrientation property changes.

Note: The corresponding handler is onTextOrientationChanged.

This signal was introduced in Esri.ArcGISRuntime 100.11.


textSymbolChanged()

Emitted when the textSymbol property changes.

Note: The corresponding handler is onTextSymbolChanged.

This signal was introduced in Esri.ArcGISRuntime 100.11.


useCodedValuesChanged()

Emitted when the useCodedValues property changes.

Note: The corresponding handler is onUseCodedValuesChanged.

This signal was introduced in Esri.ArcGISRuntime 100.12.


whereClauseChanged()

Emitted when the whereClause property changes.

Note: The corresponding handler is onWhereClauseChanged.

This signal was introduced in Esri.ArcGISRuntime 100.11.


Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.