- All Implemented Interfaces:
JsonSerializable
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
getWhereClause()
SQL constraint - what text should be displayed, based on the individual feature's attributes and the chosen
getExpression()
formula - how the text should appear, using the label definition's
TextSymbol
- where the text should appear, with respect to its feature, using the
getPlacement()
- how to move or avoid other labels or features that would overlap each label.
- Since:
- 100.1.0
-
Property Summary
TypePropertyDescriptionThe strategy for how to use the geometry of the feature when calculating the label position.The strategy for whethergetPlacement()
above or below a line geometry will be interpreted as above or below on the `screen`, or with respect to the `direction` of line's geometry (that is, the digitization order in which the vertices are listed). -
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionstatic LabelDefinition
Creates a LabelDefinition instance from a JSON string.The strategy for how to use the geometry of the feature when calculating the label position.getAngle()
Gets the angular positions and layout directions for labels on or around point feature symbols.Gets the strategy for moving labels to avoid overlapping feature, annotation, dimension or graphic symbols or higher priority labels.Gets the expression script used to calculate the label text.Gets the strategy for whether other labels are allowed to overlap the boundary of polygon features/graphics being labeled by this LabelDefinition.Gets the strategy for whether other labels are allowed to overlap the interior of polygon features/graphics being labeled by this LabelDefinition.Gets the value of thegeometryStrategy
property.Gets the strategy for whether other labels are allowed to overlap labels created by this LabelDefinition.Gets the strategy for whether line features with the same label, and matching end vertices, should be joined before sharing a label.Gets the value of thelineOrientation
property.double
Gets the maximum scale at which labels will be visible.double
Gets the minimum scale at which labels will be visible.Gets the strategy for how many labels should be placed on each polyline or polygon (multi-ring) feature.getName()
Gets the text name for the class of labels.double
Gets the distance (in points, i.e.Gets the strategy for whether a label will be visible at scales where the feature is too small for the label to fit.Gets the preferred position of the text label, with respect to its feature geometry.double
Gets the priority of this class of labels.double
Gets a value that controls the duplicate thinning radius (in points, i.e.Gets the strategy for whether labels are removed if other features have the same text label.double
Gets the distance apart (in points, i.e.Gets the strategy for whether a label should have multiple copies created and placed along or across the same feature.Gets the strategy for how multi-row (stacked) text should be aligned.Gets the strategy for whether a row of text should be broken before or after it exceeds the ideal length.double
Gets a value that limits the number of characters in a row of stacked text.Gets a mutable list of stack separators used for automatic line breaking of label text.Gets the strategy for whether the text should be stacked or wrapped, rather than placed as long trailing labels across the map.Gets the layout of the text, which can be either horizontal, straight, perpendicular, or follow the line feature.Gets the orientation of the text, which can be either angle direction or screen-oriented.Gets the text symbol which describes the overall appearance of label text (for example font and size).Gets unknown data from the source JSON.Gets unsupported data from the source JSON.Gets a SQL where clause expression that limits the set of features for which labels will be generated and placed.boolean
Indicates whether the data source should translate domain identifiers into meanings using aCodedValueDomain
.The strategy for whethergetPlacement()
above or below a line geometry will be interpreted as above or below on the `screen`, or with respect to the `direction` of line's geometry (that is, the digitization order in which the vertices are listed).void
setAngle
(LabelAngle angle) Sets the angular positions and layout directions for labels on or around point feature symbols.void
setDeconflictionStrategy
(LabelDeconflictionStrategy deconflictionStrategy) Sets the strategy for moving labels to avoid overlapping feature, annotation, dimension or graphic symbols or higher priority labels.void
setExpression
(LabelExpression expression) Sets the expression script used to calculate the label text.void
setFeatureBoundaryOverlapStrategy
(LabelOverlapStrategy featureBoundaryOverlapStrategy) Sets the strategy for whether other labels are allowed to overlap the boundary of polygon features/graphics being labeled by this LabelDefinition.void
setFeatureInteriorOverlapStrategy
(LabelOverlapStrategy featureInteriorOverlapStrategy) Sets the strategy for whether other labels are allowed to overlap the interior of polygon features/graphics being labeled by this LabelDefinition.void
setGeometryStrategy
(LabelGeometryStrategy geometryStrategy) Sets the value of thegeometryStrategy
property.void
setLabelOverlapStrategy
(LabelOverlapStrategy labelOverlapStrategy) Sets the strategy for whether other labels are allowed to overlap labels created by this LabelDefinition.void
setLineConnection
(LabelLineConnection lineConnection) Sets the strategy for whether line features with the same label, and matching end vertices, should be joined before sharing a label.void
setLineOrientation
(LabelLineOrientation lineOrientation) Sets the value of thelineOrientation
property.void
setMaxScale
(double maxScale) Sets the maximum scale at which labels will be visible.void
setMinScale
(double minScale) Sets the minimum scale at which labels will be visible.void
setMultipartStrategy
(LabelMultipartStrategy multipartStrategy) Sets the strategy for how many labels should be placed on each polyline or polygon (multi-ring) feature.void
Sets the text name for the class of labels.void
setOffsetDistance
(double offsetDistance) Sets the distance (in points, i.e.void
setOverrunStrategy
(LabelOverrunStrategy overrunStrategy) Sets the strategy for whether a label will be visible at scales where the feature is too small for the label to fit.void
setPlacement
(LabelingPlacement placement) Sets the preferred position of the text label, with respect to its feature geometry.void
setPriority
(double priority) Sets the priority of this class of labels.void
setRemoveDuplicatesDistance
(double removeDuplicatesDistance) Sets a value that controls the duplicate thinning radius (in points, i.e.void
setRemoveDuplicatesStrategy
(LabelRemoveDuplicatesStrategy removeDuplicatesStrategy) Sets the strategy for whether labels are removed if other features have the same text label.void
setRepeatDistance
(double repeatDistance) Sets the distance apart (in points, i.e.void
setRepeatStrategy
(LabelRepeatStrategy repeatStrategy) Sets the strategy for whether a label should have multiple copies created and placed along or across the same feature.void
setStackAlignment
(LabelStackAlignment stackAlignment) Sets the strategy for how multi-row (stacked) text should be aligned.void
setStackBreakPosition
(LabelStackBreakPosition stackBreakPosition) Sets the strategy for whether a row of text should be broken before or after it exceeds the ideal length.void
setStackRowLength
(double stackRowLength) Sets a value that limits the number of characters in a row of stacked text.void
setStackStrategy
(LabelStackStrategy stackStrategy) Sets the strategy for whether the text should be stacked or wrapped, rather than placed as long trailing labels across the map.void
setTextLayout
(LabelTextLayout textLayout) Gets the layout of the text, which can be either horizontal, straight, perpendicular, or follow the line feature.void
setTextOrientation
(LabelTextOrientation textOrientation) Sets the orientation of the text, which can be either angle direction or screen-oriented.void
setTextSymbol
(TextSymbol textSymbol) Sets the text symbol which describes the overall appearance of label text (for example font and size).void
setUseCodedValues
(boolean useCodedValues) Sets whether the data source should translate domain identifiers into meanings using aCodedValueDomain
.void
setWhereClause
(String whereClause) Sets a SQL where clause expression that limits the set of features for which labels will be generated and placed.toJson()
Serializes this object to a JSON string.
-
Property Details
-
geometryStrategy
The strategy for how to use the geometry of the feature when calculating the label position.Only applicable to labels for lines or polygons.
Attempting to set the value to null will throw a NullPointerException exception.
- Since:
- 200.3.0
- See Also:
-
lineOrientation
The strategy for whethergetPlacement()
above or below a line geometry will be interpreted as above or below on the `screen`, or with respect to the `direction` of line's geometry (that is, the digitization order in which the vertices are listed).- If the
getLineOrientation()
is set toLabelLineOrientation.SCREEN
thenLabelDefinition.getPlacement()
above means the label will be offset perpendicularly from its line segment towards the top of the screen. - If the
LabelDefinition.getLineOrientation()
is set toLabelLineOrientation.DIRECTION
thenLabelDefinition.getPlacement()
above means the label will be offset perpendicularly left from its line segment. - If the
LabelDefinition.getLineOrientation()
is set toLabelLineOrientation.UNCONSTRAINED
then the label will be offset perpendicularly to whichever side of the line geometry has space (defaulting to above in the `screen` sense).
LabelDefinition.getPlacement()
below would have the corresponding interpretations. The default isLabelLineOrientation.SCREEN
.Must not be set to null.
- Since:
- 200.1.0
- See Also:
- If the
-
-
Constructor Details
-
LabelDefinition
Creates aLabelDefinition
with a clone of the specifiedLabelExpression
andTextSymbol
.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
orWebmapLabelExpression
.- Parameters:
labelExpression
- the expression script used to calculate the label texttextSymbol
- the text symbol which describes the overall appearance of label text (for example font and size). May be null, but in that case no labels will be created.- Throws:
IllegalArgumentException
- if labelExpression is null- Since:
- 100.11.0
-
-
Method Details
-
fromJson
Creates a LabelDefinition instance from a JSON string.- Parameters:
json
- a valid string in JSON format- Returns:
- a LabelDefinition instance
- Throws:
IllegalArgumentException
- if json is null or emptyArcGISRuntimeException
- if json is in invalid format- Since:
- 100.1.0
-
getAngle
Gets 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. This may be different for each feature (driven by one or more feature attributes) or constant for all features (specified by a fixed number).
These properties will only be used if the
LabelAngle.getAngleExpression()
has an Arcade expression set into itsArcadeExpression.getExpression()
property.The
getPlacement()
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,getTextLayout()
andgetTextOrientation()
are used to specify the layout of the text at that position.Warning: If the expression attempts to use attributes which don't exist then no label will be produced. This is distinct from the attribute existing but having a null or empty value, which will be interpreted as a zero angle.
- Returns:
- a LabelAngle specifying angular positions and layout directions, or null if none
- Since:
- 100.11.0
- See Also:
-
setAngle
Sets 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. This may be different for each feature (driven by one or more feature attributes) or constant for all features (specified by a fixed number).
These properties will only be used if the
LabelAngle.getAngleExpression()
has an Arcade expression set into itsArcadeExpression.getExpression()
property.The
getPlacement()
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,getTextLayout()
andgetTextOrientation()
are used to specify the layout of the text at that position.Warning: If the expression attempts to use attributes which don't exist then no label will be produced. This is distinct from the attribute existing but having a null or empty value, which will be interpreted as a zero angle.
- Parameters:
angle
- a LabelAngle specifying angular positions and layout directions; may be null- Since:
- 100.11.0
- See Also:
-
getDeconflictionStrategy
Gets the strategy for moving labels to avoid overlapping feature, annotation, dimension or graphic symbols or higher priority labels. In 3DLabelDeconflictionStrategy.STATIC
is selected by default.The default is
LabelDeconflictionStrategy.AUTOMATIC
(which will be interpreted asLabelDeconflictionStrategy.STATIC
, i.e. use preferred location unless it would overlap an obstacle).- Returns:
- the strategy for moving labels to avoid overlapping feature, annotation, dimension or graphic symbols or higher priority labels
- Since:
- 100.11.0
- See Also:
-
setDeconflictionStrategy
Sets the strategy for moving labels to avoid overlapping feature, annotation, dimension or graphic symbols or higher priority labels. In 3DLabelDeconflictionStrategy.STATIC
is selected by default.- Parameters:
deconflictionStrategy
- the strategy for moving labels to avoid overlapping feature, annotation, dimension or graphic symbols or higher priority labels- Throws:
IllegalArgumentException
- if deconflictionStrategy is null- Since:
- 100.11.0
- See Also:
-
getExpression
Gets 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
orWebmapLabelExpression
.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 tosetExpression(LabelExpression)
.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 Text formatting tags.
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.
Warning: If the expression attempts to use attributes which don't exist then no label will be produced. This is distinct from the attribute existing but having a null or empty value, which can form part of the produced text label.
- Returns:
- the expression script used to calculate the label text
- Since:
- 100.11.0
-
setExpression
Sets 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
orWebmapLabelExpression
.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 tosetExpression(LabelExpression)
.Warning: If the expression attempts to use attributes which don't exist then no label will be produced. This is distinct from the attribute existing but having a null or empty value, which can form part of the produced text label.
- Parameters:
expression
- the expression script used to calculate the label text- Throws:
IllegalArgumentException
- if expression is null- Since:
- 100.11.0
-
getFeatureBoundaryOverlapStrategy
Gets the strategy for whether other labels are allowed to overlap the boundary of polygon features/graphics being labeled by this LabelDefinition.The default is
LabelOverlapStrategy.AUTOMATIC
which will give the same behavior asLabelOverlapStrategy.ALLOW
.In 3D scenes, labels will be allowed to overlap the boundaries of polygon features.
- Returns:
- the feature/graphic boundary overlap strategy
- Since:
- 100.11.0
-
setFeatureBoundaryOverlapStrategy
Sets the strategy for whether other labels are allowed to overlap the boundary of polygon features/graphics being labeled by this LabelDefinition.In 3D scenes, labels will be allowed to overlap the boundaries of polygon features.
- Parameters:
featureBoundaryOverlapStrategy
- the feature/graphic boundary overlap strategy- Throws:
IllegalArgumentException
- if featureBoundaryOverlapStrategy is null- Since:
- 100.11.0
-
getFeatureInteriorOverlapStrategy
Gets the strategy for whether other labels are allowed to overlap the interior of polygon features/graphics being labeled by this LabelDefinition.The default is
LabelOverlapStrategy.AUTOMATIC
which will give the same behavior asLabelOverlapStrategy.ALLOW
.In 3D scenes, labels will be allowed to overlap the interiors of polygon features.
- Returns:
- the feature/graphic interior overlap strategy
- Since:
- 100.11.0
-
setFeatureInteriorOverlapStrategy
Sets the strategy for whether other labels are allowed to overlap the interior of polygon features/graphics being labeled by this LabelDefinition.In 3D scenes, labels will be allowed to overlap the interiors of polygon features.
- Parameters:
featureInteriorOverlapStrategy
- the feature/graphic interior overlap strategy- Throws:
IllegalArgumentException
- if featureInteriorOverlapStrategy is null- Since:
- 100.11.0
-
getLabelOverlapStrategy
Gets the strategy for whether other labels are allowed to overlap labels created by this LabelDefinition.The default is
LabelOverlapStrategy.AUTOMATIC
which will give the same behavior asLabelOverlapStrategy.EXCLUDE
.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.
- Returns:
- the label overlap strategy
- Since:
- 100.11.0
-
setLabelOverlapStrategy
Sets the strategy for whether other labels are allowed to overlap labels created by this LabelDefinition.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.
- Parameters:
labelOverlapStrategy
- the label overlap strategy- Throws:
IllegalArgumentException
- if labelOverlapStrategy is null- Since:
- 100.11.0
-
getLineConnection
Gets the strategy for whether line features with the same label, and matching end vertices, should be joined before sharing a label.The default is
LabelLineConnection.AUTOMATIC
, which will be interpreted asLabelLineConnection.MINIMIZE_LABELS
.3D line features will be treated as independent features with their own label.
- Returns:
- the line connection strategy
- Since:
- 100.11.0
-
setLineConnection
Sets 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.
- Parameters:
lineConnection
- the line connection strategy- Throws:
IllegalArgumentException
- if lineConnection is null- Since:
- 100.11.0
-
geometryStrategyProperty
The strategy for how to use the geometry of the feature when calculating the label position.Only applicable to labels for lines or polygons.
Attempting to set the value to null will throw a NullPointerException exception.
- Returns:
- the
geometryStrategy
property - Since:
- 200.3.0
- See Also:
-
getGeometryStrategy
Gets the value of thegeometryStrategy
property.- Property description:
- The strategy for how to use the geometry of the feature when calculating the label position.
Only applicable to labels for lines or polygons.
Attempting to set the value to null will throw a NullPointerException exception.
- Returns:
- the value of the
geometryStrategy
property - Since:
- 200.3.0
- See Also:
-
setGeometryStrategy
Sets the value of thegeometryStrategy
property.- Property description:
- The strategy for how to use the geometry of the feature when calculating the label position.
Only applicable to labels for lines or polygons.
Attempting to set the value to null will throw a NullPointerException exception.
- Parameters:
geometryStrategy
- the value for thegeometryStrategy
property- Since:
- 200.3.0
- See Also:
-
lineOrientationProperty
The strategy for whethergetPlacement()
above or below a line geometry will be interpreted as above or below on the `screen`, or with respect to the `direction` of line's geometry (that is, the digitization order in which the vertices are listed).- If the
getLineOrientation()
is set toLabelLineOrientation.SCREEN
thenLabelDefinition.getPlacement()
above means the label will be offset perpendicularly from its line segment towards the top of the screen. - If the
LabelDefinition.getLineOrientation()
is set toLabelLineOrientation.DIRECTION
thenLabelDefinition.getPlacement()
above means the label will be offset perpendicularly left from its line segment. - If the
LabelDefinition.getLineOrientation()
is set toLabelLineOrientation.UNCONSTRAINED
then the label will be offset perpendicularly to whichever side of the line geometry has space (defaulting to above in the `screen` sense).
LabelDefinition.getPlacement()
below would have the corresponding interpretations. The default isLabelLineOrientation.SCREEN
.Must not be set to null.
- Returns:
- the
lineOrientation
property - Since:
- 200.1.0
- See Also:
- If the
-
getLineOrientation
Gets the value of thelineOrientation
property.- Property description:
- The strategy for whether
getPlacement()
above or below a line geometry will be interpreted as above or below on the `screen`, or with respect to the `direction` of line's geometry (that is, the digitization order in which the vertices are listed).- If the
getLineOrientation()
is set toLabelLineOrientation.SCREEN
thenLabelDefinition.getPlacement()
above means the label will be offset perpendicularly from its line segment towards the top of the screen. - If the
LabelDefinition.getLineOrientation()
is set toLabelLineOrientation.DIRECTION
thenLabelDefinition.getPlacement()
above means the label will be offset perpendicularly left from its line segment. - If the
LabelDefinition.getLineOrientation()
is set toLabelLineOrientation.UNCONSTRAINED
then the label will be offset perpendicularly to whichever side of the line geometry has space (defaulting to above in the `screen` sense).
LabelDefinition.getPlacement()
below would have the corresponding interpretations. The default isLabelLineOrientation.SCREEN
.Must not be set to null.
- If the
- Returns:
- the value of the
lineOrientation
property - Since:
- 200.1.0
- See Also:
-
setLineOrientation
Sets the value of thelineOrientation
property.- Property description:
- The strategy for whether
getPlacement()
above or below a line geometry will be interpreted as above or below on the `screen`, or with respect to the `direction` of line's geometry (that is, the digitization order in which the vertices are listed).- If the
getLineOrientation()
is set toLabelLineOrientation.SCREEN
thenLabelDefinition.getPlacement()
above means the label will be offset perpendicularly from its line segment towards the top of the screen. - If the
LabelDefinition.getLineOrientation()
is set toLabelLineOrientation.DIRECTION
thenLabelDefinition.getPlacement()
above means the label will be offset perpendicularly left from its line segment. - If the
LabelDefinition.getLineOrientation()
is set toLabelLineOrientation.UNCONSTRAINED
then the label will be offset perpendicularly to whichever side of the line geometry has space (defaulting to above in the `screen` sense).
LabelDefinition.getPlacement()
below would have the corresponding interpretations. The default isLabelLineOrientation.SCREEN
.Must not be set to null.
- If the
- Parameters:
lineOrientation
- the value for thelineOrientation
property- Since:
- 200.1.0
- See Also:
-
getMaxScale
public double getMaxScale()Gets 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
.getMaxScale()
is 10000, then the labels will be visible (because 1/12000 <= 1/10000). A.getMaxScale()
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.
- Returns:
- the maximum scale at which labels will be visible
- Since:
- 100.11.0
- See Also:
-
setMaxScale
public void setMaxScale(double maxScale) Sets 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
getMaxScale()
is 10000, then the labels will be visible (because 1/12000 <= 1/10000). A.getMaxScale()
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.
- Parameters:
maxScale
- the maximum scale at which labels will be visible- Throws:
IllegalArgumentException
- if maxScale is negative- Since:
- 100.11.0
- See Also:
-
getMinScale
public double getMinScale()Gets 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
.getMinScale()
is 20000, then the labels will be visible (because 1/12000 >= 1/20000). A.getMinScale()
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.
- Returns:
- the minimum scale at which labels will be visible
- Since:
- 100.11.0
- See Also:
-
setMinScale
public void setMinScale(double minScale) Sets 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
getMinScale()
is 20000, then the labels will be visible (because 1/12000 >= 1/20000). A.getMinScale()
of 0, which is the default, indicates no lower limit on the viewing scale.- Parameters:
minScale
- the minimum scale at which labels will be visible- Throws:
IllegalArgumentException
- if minScale is negative- Since:
- 100.11.0
- See Also:
-
getMultipartStrategy
Gets the strategy for how many labels should be placed on each polyline or polygon (multi-ring) feature.The default is
LabelMultipartStrategy.AUTOMATIC
.- Returns:
- the strategy for labeling multipart features
- Since:
- 100.11.0
-
setMultipartStrategy
Sets the strategy for how many labels should be placed on each polyline or polygon (multi-ring) feature.- Parameters:
multipartStrategy
- the strategy for labeling multipart features- Throws:
IllegalArgumentException
- if multipartStrategy is null- Since:
- 100.11.0
-
getName
Gets the 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.
- Returns:
- text name for the class of labels
- Since:
- 100.11.0
-
setName
Sets the 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.
- Parameters:
name
- text name for the class of labels- Throws:
IllegalArgumentException
- if name is null- Since:
- 100.11.0
-
getOffsetDistance
public double getOffsetDistance()Gets the distance (in points, i.e. 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.
- Returns:
- the distance (in points, i.e. 1/72 inches) that text should be moved away from its features
- Since:
- 100.11.0
-
setOffsetDistance
public void setOffsetDistance(double offsetDistance) Sets the distance (in points, i.e. 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.
- Parameters:
offsetDistance
- the distance (in points, i.e. 1/72 inches) that text should be moved away from its features- Since:
- 100.11.0
-
getOverrunStrategy
Gets 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
LabelOverrunStrategy.AUTOMATIC
which will give different behavior depending on the type of feature that the label might overrun.- Returns:
- the label overrun strategy
- Since:
- 100.11.0
-
setOverrunStrategy
Sets 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.- Parameters:
overrunStrategy
- the label overrun strategy- Throws:
IllegalArgumentException
- if overrunStrategy is null- Since:
- 100.11.0
-
getPlacement
Gets the preferred position of the text label, with respect to its feature geometry.The default is
LabelingPlacement.AUTOMATIC
. The effect of this is the same as one of the following, depending on the type of feature geometry:LabelingPlacement.POINT_ABOVE_RIGHT
for point featuresLabelingPlacement.POLYGON_ALWAYS_HORIZONTAL
for polygon featuresLabelingPlacement.LINE_ABOVE_ALONG
for line features.
- Returns:
- the preferred position of the text label, with respect to its feature geometry
- Since:
- 100.11.0
-
setPlacement
Sets the preferred position of the text label, with respect to its feature geometry.- Parameters:
placement
- the preferred position of the text label, with respect to its feature geometry- Throws:
IllegalArgumentException
- if placement is null- Since:
- 100.11.0
-
getPriority
public double getPriority()Gets the priority of this class of labels. This defines which labels are placed first, and can also supplant existing lower-priority labels (for example 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.
- Returns:
- the priority of this class of labels
- Since:
- 100.11.0
-
setPriority
public void setPriority(double priority) Sets the priority of this class of labels. This defines which labels are placed first, and can also supplant existing lower-priority labels (for example 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.
- Parameters:
priority
- the priority of this class of labels- Since:
- 100.11.0
-
getRemoveDuplicatesDistance
public double getRemoveDuplicatesDistance()Gets a value that controls the duplicate thinning radius (in points, i.e. 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
getRemoveDuplicatesStrategy()
is enabled.The default value is 0. This indicates that duplicates should be removed from the entire extent.
- Returns:
- a value that controls the duplicate thinning radius (in points, i.e. 1/72 inches)
- Since:
- 100.11.0
-
setRemoveDuplicatesDistance
public void setRemoveDuplicatesDistance(double removeDuplicatesDistance) Sets a value that controls the duplicate thinning radius (in points, i.e. 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
getRemoveDuplicatesStrategy()
is enabled.- Parameters:
removeDuplicatesDistance
- a value that controls the duplicate thinning radius (in points, i.e. 1/72 inches)- Since:
- 100.11.0
-
getRemoveDuplicatesStrategy
Gets 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
LabelRemoveDuplicatesStrategy.AUTOMATIC
, which will be interpreted asLabelRemoveDuplicatesStrategy.NONE
indicating that all labels should be shown if possible.The distance within which to look for duplicates is controlled by
getRemoveDuplicatesDistance()
.- Returns:
- the remove duplicates strategy
- Since:
- 100.11.0
-
setRemoveDuplicatesStrategy
Sets the strategy for whether labels are removed if other features have the same text label. This can reduce clutter and free up space.The distance within which to look for duplicates is controlled by
getRemoveDuplicatesDistance()
.- Parameters:
removeDuplicatesStrategy
- the remove duplicates strategy- Throws:
IllegalArgumentException
- if removeDuplicatesStrategy is null- Since:
- 100.11.0
-
getRepeatDistance
public double getRepeatDistance()Gets the distance apart (in points, i.e. 1/72 inches) that the repetitions should be. In 3D scenes, only one label will be placed per line feature.This value is only used if
getRepeatStrategy()
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.
Warning: The distance is considered a guide for the approximate label separation and should not be used for precise distance markings.
A distance of 0 disables label repetition.
- Returns:
- the distance apart (in points, i.e. 1/72 inches) that the repetitions should be
- Since:
- 100.11.0
-
setRepeatDistance
public void setRepeatDistance(double repeatDistance) Sets the distance apart (in points, i.e. 1/72 inches) that the repetitions should be. In 3D scenes, only one label will be placed per line feature.This value is only used if
getRepeatStrategy()
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.Warning: The distance is considered a guide for the approximate label separation and should not be used for precise distance markings.
A distance of 0 disables label repetition.
- Parameters:
repeatDistance
- the distance apart (in points, i.e. 1/72 inches) that the repetitions should be- Since:
- 100.11.0
-
getRepeatStrategy
Gets 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
LabelRepeatStrategy.AUTOMATIC
.The frequency of repetition is controlled by the
getRepeatDistance()
property.Warning: This property is currently only supported for line features, but will be extended to polygons in the future.
- Returns:
- the label repeat strategy
- Since:
- 100.11.0
-
setRepeatStrategy
Sets 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 frequency of repetition is controlled by the
getRepeatDistance()
property.Warning: This property is currently only supported for line features, but will be extended to polygons in the future.
- Parameters:
repeatStrategy
- the label repeat strategy- Throws:
IllegalArgumentException
- if repeatStrategy is null- Since:
- 100.11.0
-
getStackAlignment
Gets 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 thesetStackAlignment(LabelStackAlignment)
method, the user can choose to use theTextSymbol.getHorizontalAlignment()
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
LabelStackAlignment.AUTOMATIC
(which will have the same effect on labels asLabelStackAlignment.TEXT_SYMBOL
).Warning: This property has no effect if
getStackStrategy()
==LabelStackStrategy.NONE
.- Returns:
- the alignment strategy for multi-row (stacked) text
- Since:
- 100.11.0
-
setStackAlignment
Sets 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 thesetStackAlignment(LabelStackAlignment)
method, the user can choose to use theTextSymbol.getHorizontalAlignment()
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.Warning: This property has no effect if
getStackStrategy()
==LabelStackStrategy.NONE
.- Parameters:
stackAlignment
- the alignment strategy for multi-row (stacked) text- Throws:
IllegalArgumentException
- if stackAlignment is null- Since:
- 100.11.0
-
getStackBreakPosition
Gets 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
LabelStackBreakPosition.BEFORE
option means rows will generally be shorter than thegetStackRowLength()
(although will overrun for individual words larger than this count).The default value is
LabelStackBreakPosition.AUTOMATIC
(which will have the same effect on labels asLabelStackBreakPosition.AFTER
).Warning: This property has no effect if
getStackStrategy()
==LabelStackStrategy.NONE
.- Returns:
- the break position strategy for multi-row (stacked) text
- Since:
- 100.11.0
-
setStackBreakPosition
Sets 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
LabelStackBreakPosition.BEFORE
option means rows will generally be shorter than thegetStackRowLength()
(although will overrun for individual words larger than this count).Warning: This property has no effect if
getStackStrategy()
==LabelStackStrategy.NONE
.- Parameters:
stackBreakPosition
- the break position strategy for multi-row (stacked) text- Throws:
IllegalArgumentException
- if stackBreakPosition is null- Since:
- 100.11.0
-
getStackRowLength
public double getStackRowLength()Gets 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
getStackBreakPosition()
, the break may be inserted before the breaking word, or after.The default value is -1. This means that a default length of 13 characters is currently used.
Warning: This property has no effect if
getStackStrategy()
==LabelStackStrategy.NONE
.- Returns:
- a value that limits the number of characters in a row of stacked text
- Since:
- 100.11.0
-
setStackRowLength
public void setStackRowLength(double stackRowLength) Sets 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
getStackBreakPosition()
, the break may be inserted before the breaking word, or after.Warning: This property has no effect if
getStackStrategy()
==LabelStackStrategy.NONE
.- Parameters:
stackRowLength
- a value that limits the number of characters in a row of stacked text- Since:
- 100.11.0
-
getStackSeparators
Gets a mutable list of stack separators 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 aString
to describe it. So eachLabelStackSeparator.getSeparator()
is a String intended to describe one code point. For example:- to use a comma as a separator, the
LabelStackSeparator.getSeparator()
string would be just "," - to use a Hebrew punctuation Paseq as a separator, the
LabelStackSeparator.getSeparator()
would need to encode the code point with the UTF16 value "\u05c0".
If it is found, then the
LabelStackSeparator
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 (\n) in the label will always be considered a forced separator.
Warning: This property has no effect if
getStackStrategy()
==LabelStackStrategy.NONE
.- Returns:
- a mutable list of stack separators
- Since:
- 100.11.0
- to use a comma as a separator, the
-
getStackStrategy
Gets 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.
Warning: This property has no effect if
getStackStrategy()
==LabelStackStrategy.NONE
.- Returns:
- the stack strategy
- Since:
- 100.11.0
-
setStackStrategy
Sets 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.
- Parameters:
stackStrategy
- the stack strategy- Throws:
IllegalArgumentException
- if stackStrategy is null- Since:
- 100.11.0
-
getTextLayout
Gets 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
LabelTextLayout.AUTOMATIC
, which will be interpreted as:LabelTextLayout.HORIZONTAL
for labels attached to point featuresLabelTextLayout.FOLLOW_FEATURE
for labels attached to line featuresLabelTextLayout.HORIZONTAL
for labels attached to polygon features.
- Returns:
- the layout of the text
- Since:
- 100.11.0
-
setTextLayout
Gets 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.
- Parameters:
textLayout
- the layout of the text- Throws:
IllegalArgumentException
- if textLayout is null- Since:
- 100.11.0
-
getTextOrientation
Gets the orientation of the text, which can be either angle direction or screen-oriented. Not supported in 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
LabelTextOrientation.AUTOMATIC
, which is interpreted asLabelTextOrientation.SCREEN
.- Returns:
- the orientation of the text
- Since:
- 100.11.0
-
setTextOrientation
Sets the orientation of the text, which can be either angle direction or screen-oriented. Not supported in 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).
- Parameters:
textOrientation
- the orientation of the text- Throws:
IllegalArgumentException
- if textOrientation is null- Since:
- 100.11.0
-
getTextSymbol
Gets the text symbol which describes the overall appearance of label text (for example font and size).If no
setTextSymbol(TextSymbol)
has been set, then no labels can be created. If a loadedTextSymbol
is a Text Symbol as defined by the CIM standard, then this property provides a simplified version of it.- Returns:
- the text symbol, or null if none has been set
- Since:
- 100.11.0
-
setTextSymbol
Sets the text symbol which describes the overall appearance of label text (for example font and size).If no
setTextSymbol(TextSymbol)
has been set, then no labels can be created. If a loadedTextSymbol
is a Text Symbol as defined by the CIM standard, then this property provides a simplified version of it.- Parameters:
textSymbol
- the text symbol to use- Since:
- 100.11.0
-
isUseCodedValues
public boolean isUseCodedValues()Indicates whether the data source should translate domain identifiers into meanings using aCodedValueDomain
.For any translation to occur, the data source must have one or more CodedValueDomains set up for the attribute fields.
The default value is true, meaning that 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.
- Returns:
- true to translate, false otherwise
- Since:
- 100.11.0
-
setUseCodedValues
public void setUseCodedValues(boolean useCodedValues) Sets whether the data source should translate domain identifiers into meanings using aCodedValueDomain
.For any translation to occur, the data source must have one or more CodedValueDomains set up for the attribute fields.
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.
- Parameters:
useCodedValues
- true to translate, false otherwise- Since:
- 100.11.0
-
getWhereClause
Gets 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, for example:
""
(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.- Returns:
- a SQL where clause expression that limits the set of features for which labels will be generated and placed
- Since:
- 100.11.0
-
setWhereClause
Sets 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, for example:
""
(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).
- Parameters:
whereClause
- a SQL where clause expression that limits the set of features for which labels will be generated and placed- Throws:
IllegalArgumentException
- if whereClause is null- Since:
- 100.11.0
-
toJson
Description copied from interface:JsonSerializable
Serializes this object to a JSON string. Note that unknown JSON is omitted from the serialized string.- Specified by:
toJson
in interfaceJsonSerializable
- Returns:
- a JSON string
-
getUnknownJson
Description copied from interface:JsonSerializable
Gets unknown data from the source JSON.Unknown JSON is a Map of values not defined in the ArcGIS specification used to create this object but found in the source JSON. If the object is written back to JSON, any unknown JSON data is not persisted. The ArcGIS specification may be for a web map, web scene, REST API, and so on.
- Specified by:
getUnknownJson
in interfaceJsonSerializable
- Returns:
- an unmodifiable Map containing unknown data from the source JSON
-
getUnsupportedJson
Description copied from interface:JsonSerializable
Gets unsupported data from the source JSON.Unsupported JSON is a Map of values defined in the ArcGIS specification used to create this object but not currently used in this API. If the object is written back to JSON, any unsupported JSON data is persisted. The ArcGIS specification may be from a web map, web scene, REST API, and so on.
- Specified by:
getUnsupportedJson
in interfaceJsonSerializable
- Returns:
- an unmodifiable Map containing unsupported data from the source JSON
-