Description
An object that defines the text, appearance, and position of labels for features within a given scale range.
An AGSLabelDefinition describes a class of labels. A collection of label definitions can be attached to a feature data source (example AGSFeatureLayer). Each AGSLabelDefinition specifies:
- Which features are covered by the definition, by applying the
AGSLabelDefinition::whereClauseSQL constraint - What text should be displayed, based on the individual feature's attributes and the chosen
AGSLabelDefinition::expressionformula - How the text should appear, using the label definition's
AGSTextSymbolobject - Where the text should appear, with respect to its feature, using the
AGSLabelDefinition::labelPlacementproperty - How to move or avoid other labels and features/graphics that would overlap each label
In addtion, an instance of AGSLabelDefinition can be constructed from JSON as follows:
- Since
- 100.1
- See also
AGSFeatureLayer::labelsEnabled,AGSGraphicsOverlay::labelsEnabled,AGSArcGISMapImageSublayer::labelsEnabledto enable labels-
AGSFeatureLayer::labelDefinitions,AGSGraphicsOverlay::labelDefinitions,AGSArcGISMapImageSublayer::labelDefinitionsto specify label definitions
Instance Methods | |
| (instancetype) | - init |
| (instancetype) | - initWithLabelExpression:textSymbol: |
| (nullable id) | - toJSON: |
Class Methods | |
| (nullable id< AGSJSONSerializable >) | + fromJSON:error: |
| (instancetype) | + labelDefinition |
| (instancetype) | + labelDefinitionWithLabelExpression:textSymbol: |
Method Documentation
◆ fromJSON:error:
|
staticrequiredinherited |
Initializes and returns an object from its JSON representation.
- Parameters
-
JSONObject NSDictionaryorNSArraycontaining the JSON.error encountered during the operation, if any.
- Since
- 100
◆ init
| - (instancetype) init |
Creates a label definition. The default AGSLabelDefinition will have an empty AGSLabelDefinition::expression and no AGSTextSymbol, and will not produce any text labels until those properties are set.
- Since
- 100.1
- Deprecated:
- 100.11. It is safer to construct an
AGSLabelDefinitionobject using anAGSLabelExpressionandAGSTextSymbol. This reduces the chance ofAGSLabelDefinitionbeing used with noAGSLabelDefinition::expressionorAGSLabelDefinition::textSymbol, which would result in no labels being created.
Provided by category AGSLabelDefinition(AGSDeprecated).
◆ initWithLabelExpression:textSymbol:
| - (instancetype) initWithLabelExpression: | (AGSLabelExpression *) | labelExpression | |
| textSymbol: | (nullable AGSTextSymbol *) | textSymbol | |
Creates an AGSLabelDefinition object with the specified AGSLabelExpression and AGSTextSymbol objects.
- Parameters
-
labelExpression The expression script used to calculate the label text. textSymbol The text symbol which describes the overall appearance of label text (e.g. font and size).
- Since
- 100.11
◆ labelDefinition
| + (instancetype) labelDefinition |
Creates a label definition. The default AGSLabelDefinition will have an empty AGSLabelDefinition::expression and no AGSTextSymbol, and will not produce any text labels until those properties are set.
- Since
- 100.1
- Deprecated:
- 100.11. It is safer to construct an
AGSLabelDefinitionobject using anAGSLabelExpressionandAGSTextSymbol. This reduces the chance ofAGSLabelDefinitionbeing used with noAGSLabelDefinition::expressionorAGSLabelDefinition::textSymbol, which would result in no labels being created.
Provided by category AGSLabelDefinition(AGSDeprecated).
◆ labelDefinitionWithLabelExpression:textSymbol:
| + (instancetype) labelDefinitionWithLabelExpression: | (AGSLabelExpression *) | labelExpression | |
| textSymbol: | (nullable AGSTextSymbol *) | textSymbol | |
Creates an AGSLabelDefinition object with the specified AGSLabelExpression and AGSTextSymbol objects.
- Parameters
-
labelExpression The expression script used to calculate the label text. textSymbol The text symbol which describes the overall appearance of label text (e.g. font and size).
- Since
- 100.11
◆ toJSON:
|
requiredinherited |
Returns JSON representation for this object.
- Parameters
-
error encountered during the operation, if any.
- Returns
NSDictionaryorNSArraycontaining the JSON.
- Since
- 100
Reimplemented in AGSPortalItem.
Property Documentation
◆ angle
|
readwritenonatomicstrong |
The angular positions and layout directions for labels on or around point feature symbols. Not supported by 3D scenes.
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 AGSLabelDefinition::placement property 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. Once the position has been determined, the AGSLabelDefinition::textLayout and AGSLabelDefinition::textOrientation properties are used to specify the layout of the text at that position.
- Since
- 100.11
◆ deconflictionStrategy
|
readwritenonatomicassign |
The strategy for moving labels to avoid overlapping feature, annotation, dimension or graphic symbols or higher priority labels. In 3D, AGSLabelDeconflictionStrategyStatic is selected by default.
The default is AGSLabelDeconflictionStrategyAutomatic (which will be interpreted as AGSLabelDeconflictionStrategyStatic i.e. use preferred location unless it would overlap an obstacle).
- Since
- 100.11
◆ expression
|
readwritenonatomicstrong |
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: AGSArcadeLabelExpression, AGSSimpleLabelExpression or AGSWebmapLabelExpression. 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 AGSLabelExpression subclass and assigning it to AGSLabelDefinition::expression. The default value is an empty AGSArcadeLabelExpression, 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 ArcGISPro 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.
- Since
- 100.11
◆ featureBoundaryOverlapStrategy
|
readwritenonatomicassign |
The strategy for whether other labels are allowed to overlap the boundary of polygon features/graphics being labeled by this AGSLabelDefinition. In 3D scenes, labels will be allowed to overlap the boundaries of polygon features.
The default is AGSLabelOverlapStrategyAutomatic, which will give the same behavior as AGSLabelOverlapStrategyAllow.
- Since
- 100.11
◆ featureInteriorOverlapStrategy
|
readwritenonatomicassign |
The strategy for whether other labels are allowed to overlap interior of polygon features/graphics being labeled by this AGSLabelDefinition. In 3D scenes, labels will be allowed to overlap the interiors of polygon features.
The default is AGSLabelOverlapStrategyAutomatic, which will give the same behavior as AGSLabelOverlapStrategyAllow.
- Since
- 100.11
◆ labelOverlapStrategy
|
readwritenonatomicassign |
The strategy for whether other labels are allowed to overlap labels created by this AGSLabelDefinition. 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.
The default is AGSLabelOverlapStrategyAutomatic, which will give the same behavior as AGSLabelOverlapStrategyExclude.
- Since
- 100.11
◆ lineConnection
|
readwritenonatomicassign |
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 AGSLabelLineConnectionAutomatic, which will be interpreted as AGSLabelLineConnectionMinimizeLabels.
- Since
- 100.11
◆ maxScale
|
readwritenonatomicassign |
The maximum scale at which labels will be visible. In 3D scenes,the scale range is between individual label and view plane instead of map and view plane.
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 AGSLabelDefinition::maxScale is 1:10000, then the labels will be visible (because 1/12000 <= 1/10000). An AGSLabelDefinition::maxScale of 0, which is the default, indicates no upper limit on the viewing scale.
- Since
- 100.11
◆ minScale
|
readwritenonatomicassign |
The minimum scale at which labels will be visible. In 3D scenes, the scale range is between individual label and view plane instead of map and view plane.
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 AGSLabelDefinition::minScale is 1:20000, then the labels will be visible (because 1/12000 >= 1/20000). An AGSLabelDefinition::minScale of 0, which is the default, indicates no lower limit on the viewing scale.
- Since
- 100.11
◆ multipartStrategy
|
readwritenonatomicassign |
The strategy for how many labels should be placed on each polyline or polygon (multi-ring) feature.
The default is AGSLabelMultipartStrategyAutomatic.
- Since
- 100.11
◆ name
|
readwritenonatomiccopy |
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.
- Since
- 100.11
◆ offsetDistance
|
readwritenonatomicassign |
The distance (in points) 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.
- Since
- 100.11
◆ overrunStrategy
|
readwritenonatomicassign |
The strategy for whether a label will be visible at scales where the feature is too small for the label to fit. Not supported by 3D scenes.
The default is AGSLabelOverrunStrategyAutomatic, which will give different behavior depending on the type of feature that the label might overrun.
- Since
- 100.11
◆ placement
|
readwritenonatomicassign |
The preferred position of the text label, with respect to its feature geometry.
The default is AGSLabelingPlacementAutomatic. The effect of this is the same as one of the following, depending on the type of feature geometry:
AGSLabelingPlacementPointAboveRightfor point featuresAGSLabelingPlacementPolygonAlwaysHorizontalfor polygon featuresAGSLabelingPlacementLineAboveAlongfor line features- Since
- 100.11
◆ priority
|
readwritenonatomicassign |
Defines which labels are placed first, and can also supplant existing lower-priority labels (e.g. during panning).
Lower values indicate more important labels i.e.:
- 0 is the most important
- 5 is high priority
- 15 is medium priority
- higher values indicate lower 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.
- Since
- 100.11
◆ removeDuplicatesDistance
|
readwritenonatomicassign |
A value that controls the duplicate thinning radius (in points).
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 AGSLabelDefinition::removeDuplicatesStrategy is enabled. The default value is 0. This indicates that duplicates should be removed from the entire extent.
- Since
- 100.11
◆ removeDuplicatesStrategy
|
readwritenonatomicassign |
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 AGSLabelRemoveDuplicatesStrategyAutomatic, which will be interpreted as AGSLabelRemoveDuplicatesStrategyNone indicating that all labels should be shown if possible.
The distance within which to look for duplicates is controlled by AGSLabelDefinition::removeDuplicatesDistance.
- Since
- 100.11
◆ repeatDistance
|
readwritenonatomicassign |
The distance apart (in points) that the repetitions should be. In 3D scenes, only one label will be placed per line feature.
This value is only used if AGSLabelDefinition::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. A distance of 0 points disables label repetition.
- Warning
- The distance is considered a guide for the approximate label separation and should not be used for precise distance markings.
- Since
- 100.11
◆ repeatStrategy
|
readwritenonatomicassign |
The strategy for whether a label should have multiple copies created and placed along or across the same feature. In 3D scenes, only label will be placed per line feature.
The default is AGSLabelRepeatStrategyAutomatic.
The frequency of repetition is controlled by the AGSLabelDefinition::repeatDistance property.
- Warning
- This property is currently only supported for line features, but will be extended to polygons in the future.
- Since
- 100.11
◆ stackAlignment
|
readwritenonatomicassign |
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 AGSTextSymbol assigned to the AGSLabelDefinition. By using the AGSLabelDefinition::stackAlignment property, the user can choose to use the AGSTextSymbol::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 AGSLabelStackAlignmentAutomatic, which will have the same effect on labels as AGSLabelStackAlignmentTextSymbol.
- Warning
- This property has no effect if
AGSLabelDefinition::stackStrategyisAGSLabelStackStrategyNone.
- Since
- 100.11
◆ stackBreakPosition
|
readwritenonatomicassign |
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 AGSLabelStackBreakPositionBefore option means rows will generally be shorter than the AGSLabelDefinition::stackRowLength (although will overrun for individual words larger than this count).
The default is AGSLabelStackBreakPositionAutomatic, which will have the same effect on labels as AGSLabelStackBreakPositionAfter.
- Warning
- This property has no effect if
AGSLabelDefinition::stackStrategyisAGSLabelStackStrategyNone.
- Since
- 100.11
◆ stackRowLength
|
readwritenonatomicassign |
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 AGSLabelDefinition::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).
- Warning
- This property has no effect if
AGSLabelDefinition::stackStrategyisAGSLabelStackStrategyNone.
- Since
- 100.11
◆ stackSeparators
|
readwritenonatomiccopy |
The stack separators that should be used for automatic line breaking of label text.
Each AGSLabelStackSeparator 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 an NSString to describe it. So each AGSLabelStackSeparator::separator is an NSString intended to describe one code point.
For example:
- To use a comma as a separator, the
AGSLabelStackSeparator::separatorstring would be just "," - To use a Hebrew punctuation Paseq as a separator, the
AGSLabelStackSeparator::separatorwould need to encode the code point with utf16 value "\u05c0" if your SDK uses utf16 strings (e.g. Java, c#) or with the utf8 string "\x30\x35\x63\x30" if your SDK uses utf8 strings - To use higher range unicode code points such as Aegean Word Separator Dot which has utf32 hex value 10101, the
AGSLabelStackSeparator::separatorwould need to encode the code point with utf16 value "\ud800\udd01" if your SDK uses utf16 strings (e.g. Java, c#) or with the utf8 string "\xf0\x90\x84\x81" if your SDK uses utf8 strings
If it is found, then the AGSLabelStackSeparator also specifies whether:
- The text should always be broken here
- Whether the separator code point should remain visible
- Whether 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 (
) in the label will always be considered a forced separator.
- Warning
- This property has no effect if
AGSLabelDefinition::stackStrategyisAGSLabelStackStrategyNone.
- Since
- 100.11
◆ stackStrategy
|
readwritenonatomicassign |
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, or not, or should be calculated automatically based on feature type. The default is AGSLabelStackStrategyAutomatic, meaning that stacking will be enabled for point and polygon features and disabled for line features.
- Since
- 100.11
◆ textLayout
|
readwritenonatomicassign |
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 (i.e. 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 AGSLabelTextLayoutAutomatic, which will be interpreted as:
AGSLabelTextLayoutHorizontalfor labels attached to point featuresAGSLabelTextLayoutFollowFeaturefor labels attached to line featuresAGSLabelTextLayoutHorizontalfor labels attached to polygon features- Since
- 100.11
◆ textOrientation
|
readwritenonatomicassign |
The orientation of the text, which can be either angle direction or screen-oriented. Not supported by 3D scenes.
Optional specification of whether text should follow the placement angle direction even if it means being rendered upside-down, or whether 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 AGSLabelTextOrientationAutomatic, which is interpreted as AGSLabelTextOrientationScreen.
- Since
- 100.11
◆ textSymbol
|
readwritenonatomicstrong |
The text symbol which describes the overall appearance of label text (e.g. font and size).
If no AGSLabelDefinition::textSymbol has been set, then no labels can be created.
- Since
- 100.11
◆ unknownJSON
|
readrequirednonatomiccopyinherited |
A dictionary of values that was in the source JSON but was unparsed by API.
- Returns
NSDictionarycontaining the unknown JSON.
- Since
- 100
◆ unsupportedJSON
|
readnonatomiccopyinherited |
A dictionary of values that are supported by the REST API, but not exposed through the SDK API.
- Returns
NSDictionarycontaining the unsupported JSON.
- Since
- 100
◆ useCodedValues
|
readwritenonatomicassign |
Specifies whether the data source should translate domain identifiers into meanings using an AGSCodedValueDomain.
For any translation to occur, the data source must have one or more AGSCodedValueDomain objects set up for the attribute fields. The default value is YES i.e. translation will be done.
- Warning
- This property only affects Simple label expressions. Arcade expressions can use functions to specify when code translations should be carried out. Coded value translation for Webmap expressions is not currently supported.
- Since
- 100.11
◆ whereClause
|
readwritenonatomiccopy |
A SQL where clause expression that limits the set of features for which labels will be generated and placed.
This is a 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 the empty string, which will allow all features in the data source and extent to be labeled.
- Since
- 100.11
