ArcGIS Runtime SDK for iOS
100.15
|
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:
AGSLabelDefinition::whereClause
SQL constraint AGSLabelDefinition::expression
formula AGSTextSymbol
object AGSLabelDefinition::labelPlacement
property In addtion, an instance of AGSLabelDefinition
can be constructed from JSON as follows:
AGSFeatureLayer::labelsEnabled
, AGSGraphicsOverlay::labelsEnabled
, AGSArcGISMapImageSublayer::labelsEnabled
to enable labels AGSFeatureLayer::labelDefinitions
, AGSGraphicsOverlay::labelDefinitions
, AGSArcGISMapImageSublayer::labelDefinitions
to 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: |
|
staticrequiredinherited |
Initializes and returns an object from its JSON representation.
JSONObject | NSDictionary or NSArray containing the JSON. |
error | encountered during the operation, if any. |
- (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.
AGSLabelDefinition
object using an AGSLabelExpression
and AGSTextSymbol
. This reduces the chance of AGSLabelDefinition
being used with no AGSLabelDefinition::expression
or AGSLabelDefinition::textSymbol
, which would result in no labels being created. Provided by category AGSLabelDefinition(AGSDeprecated).
- (instancetype) initWithLabelExpression: | (AGSLabelExpression *) | labelExpression | |
textSymbol: | (nullable AGSTextSymbol *) | textSymbol | |
Creates an AGSLabelDefinition
object with the specified AGSLabelExpression
and AGSTextSymbol
objects.
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). |
+ (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.
AGSLabelDefinition
object using an AGSLabelExpression
and AGSTextSymbol
. This reduces the chance of AGSLabelDefinition
being used with no AGSLabelDefinition::expression
or AGSLabelDefinition::textSymbol
, which would result in no labels being created. Provided by category AGSLabelDefinition(AGSDeprecated).
+ (instancetype) labelDefinitionWithLabelExpression: | (AGSLabelExpression *) | labelExpression | |
textSymbol: | (nullable AGSTextSymbol *) | textSymbol | |
Creates an AGSLabelDefinition
object with the specified AGSLabelExpression
and AGSTextSymbol
objects.
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). |
|
requiredinherited |
Returns JSON representation for this object.
error | encountered during the operation, if any. |
NSDictionary
or NSArray
containing the JSON. Reimplemented in AGSPortalItem.
|
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.
|
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).
|
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:
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.
|
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
.
|
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
.
|
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
.
|
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
.
|
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.
|
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.
|
readwritenonatomicassign |
The strategy for how many labels should be placed on each polyline or polygon (multi-ring) feature.
The default is AGSLabelMultipartStrategyAutomatic
.
|
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.
|
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.
|
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.
|
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:
AGSLabelingPlacementPointAboveRight
for point features AGSLabelingPlacementPolygonAlwaysHorizontal
for polygon features AGSLabelingPlacementLineAboveAlong
for line features
|
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.:
If set to -1 or not set at all, then default values are used, depending on the geometry types of the 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.
|
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.
|
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
.
|
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.
|
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.
|
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
.
AGSLabelDefinition::stackStrategy
is AGSLabelStackStrategyNone
.
|
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
.
AGSLabelDefinition::stackStrategy
is AGSLabelStackStrategyNone
.
|
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).
AGSLabelDefinition::stackStrategy
is AGSLabelStackStrategyNone
.
|
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:
AGSLabelStackSeparator::separator
string would be just "," AGSLabelStackSeparator::separator
would 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 AGSLabelStackSeparator::separator
would 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 stringsIf it is found, then the AGSLabelStackSeparator
also specifies whether:
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.
AGSLabelDefinition::stackStrategy
is AGSLabelStackStrategyNone
.
|
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.
|
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:
The default is AGSLabelTextLayoutAutomatic
, which will be interpreted as:
AGSLabelTextLayoutHorizontal
for labels attached to point features AGSLabelTextLayoutFollowFeature
for labels attached to line features AGSLabelTextLayoutHorizontal
for labels attached to polygon features
|
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
.
|
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.
|
readrequirednonatomiccopyinherited |
A dictionary of values that was in the source JSON but was unparsed by API.
NSDictionary
containing the unknown JSON.
|
readnonatomiccopyinherited |
A dictionary of values that are supported by the REST API, but not exposed through the SDK API.
NSDictionary
containing the unsupported JSON.
|
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.
|
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.
The default value is the empty string, which will allow all features in the data source and extent to be labeled.