Class LabelDefinition
- java.lang.Object
-
- com.esri.arcgisruntime.arcgisservices.LabelDefinition
-
- All Implemented Interfaces:
JsonSerializable
public final class LabelDefinition extends Object implements JsonSerializable
An object that defines the text, appearance, and position of labels for features within a given scale range.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
-
-
Constructor Summary
Constructors Constructor Description LabelDefinition(LabelExpression labelExpression, TextSymbol textSymbol)
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description static LabelDefinition
fromJson(String json)
Creates a LabelDefinition instance from a JSON string.LabelAngle
getAngle()
Gets the angular positions and layout directions for labels on or around point feature symbols.LabelDeconflictionStrategy
getDeconflictionStrategy()
Gets the strategy for moving labels to avoid overlapping feature, annotation, dimension or graphic symbols or higher priority labels.LabelExpression
getExpression()
Gets the expression script used to calculate the label text.LabelOverlapStrategy
getFeatureBoundaryOverlapStrategy()
Gets the strategy for whether other labels are allowed to overlap the boundary of polygon features/graphics being labeled by this LabelDefinition.LabelOverlapStrategy
getFeatureInteriorOverlapStrategy()
Gets the strategy for whether other labels are allowed to overlap the interior of polygon features/graphics being labeled by this LabelDefinition.LabelOverlapStrategy
getLabelOverlapStrategy()
Gets the strategy for whether other labels are allowed to overlap labels created by this LabelDefinition.LabelLineConnection
getLineConnection()
Gets the strategy for whether line features with the same label, and matching end vertices, should be joined before sharing a label.double
getMaxScale()
Gets the maximum scale at which labels will be visible.double
getMinScale()
Gets the minimum scale at which labels will be visible.LabelMultipartStrategy
getMultipartStrategy()
Gets the strategy for how many labels should be placed on each polyline or polygon (multi-ring) feature.String
getName()
Gets the text name for the class of labels.double
getOffsetDistance()
Gets the distance (in points, i.e.LabelOverrunStrategy
getOverrunStrategy()
Gets the strategy for whether a label will be visible at scales where the feature is too small for the label to fit.LabelingPlacement
getPlacement()
Gets the preferred position of the text label, with respect to its feature geometry.double
getPriority()
Gets the priority of this class of labels.double
getRemoveDuplicatesDistance()
Gets a value that controls the duplicate thinning radius (in points, i.e.LabelRemoveDuplicatesStrategy
getRemoveDuplicatesStrategy()
Gets the strategy for whether labels are removed if other features have the same text label.double
getRepeatDistance()
Gets the distance apart (in points, i.e.LabelRepeatStrategy
getRepeatStrategy()
Gets the strategy for whether a label should have multiple copies created and placed along or across the same feature.LabelStackAlignment
getStackAlignment()
Gets the strategy for how multi-row (stacked) text should be aligned.LabelStackBreakPosition
getStackBreakPosition()
Gets the strategy for whether a row of text should be broken before or after it exceeds the ideal length.double
getStackRowLength()
Gets a value that limits the number of characters in a row of stacked text.List<LabelStackSeparator>
getStackSeparators()
Gets a mutable list of stack separators used for automatic line breaking of label text.LabelStackStrategy
getStackStrategy()
Gets the strategy for whether the text should be stacked or wrapped, rather than placed as long trailing labels across the map.LabelTextLayout
getTextLayout()
Gets the layout of the text, which can be either horizontal, straight, perpendicular, or follow the line feature.LabelTextOrientation
getTextOrientation()
Gets the orientation of the text, which can be either angle direction or screen-oriented.TextSymbol
getTextSymbol()
Gets the text symbol which describes the overall appearance of label text (for example font and size).Map<String,Object>
getUnknownJson()
If this object was created from JSON, this method gets unknown data from the source JSON.Map<String,Object>
getUnsupportedJson()
If this object was created from JSON, this method gets unsupported data from the source JSON.String
getWhereClause()
Gets a SQL where clause expression that limits the set of features for which labels will be generated and placed.boolean
isUseCodedValues()
Indicates whether the data source should translate domain identifiers into meanings using aCodedValueDomain
.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
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
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
setName(String name)
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.String
toJson()
Serializes this object to a JSON string.
-
-
-
Constructor Detail
-
LabelDefinition
public LabelDefinition(LabelExpression labelExpression, TextSymbol textSymbol)
Creates aLabelDefinition
with 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 Detail
-
fromJson
public static LabelDefinition fromJson(String json)
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
public LabelAngle 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.- Returns:
- a LabelAngle specifying angular positions and layout directions, or null if none
- Since:
- 100.11.0
- See Also:
setAngle(LabelAngle)
-
setAngle
public void setAngle(LabelAngle angle)
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.- Parameters:
angle
- a LabelAngle specifying angular positions and layout directions; may be null- Since:
- 100.11.0
- See Also:
getAngle()
-
getDeconflictionStrategy
public LabelDeconflictionStrategy 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(LabelDeconflictionStrategy)
-
setDeconflictionStrategy
public void setDeconflictionStrategy(LabelDeconflictionStrategy deconflictionStrategy)
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:
getDeconflictionStrategy()
-
getExpression
public LabelExpression 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 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.
- Returns:
- the expression script used to calculate the label text
- Since:
- 100.11.0
-
setExpression
public void setExpression(LabelExpression expression)
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)
.- Parameters:
expression
- the expression script used to calculate the label text- Throws:
IllegalArgumentException
- if expression is null- Since:
- 100.11.0
-
getFeatureBoundaryOverlapStrategy
public LabelOverlapStrategy 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
public 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.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
public LabelOverlapStrategy 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
public 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.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
public LabelOverlapStrategy 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
public void setLabelOverlapStrategy(LabelOverlapStrategy labelOverlapStrategy)
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
public LabelLineConnection 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
public 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.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
-
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(double)
-
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:
getMaxScale()
-
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(double)
-
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:
getMinScale()
-
getMultipartStrategy
public LabelMultipartStrategy 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
public void setMultipartStrategy(LabelMultipartStrategy multipartStrategy)
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
public String 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
public void setName(String name)
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
public LabelOverrunStrategy 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
public 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. Not supported by 3D scenes.- Parameters:
overrunStrategy
- the label overrun strategy- Throws:
IllegalArgumentException
- if overrunStrategy is null- Since:
- 100.11.0
-
getPlacement
public LabelingPlacement 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
public void setPlacement(LabelingPlacement placement)
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
public LabelRemoveDuplicatesStrategy 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
public void setRemoveDuplicatesStrategy(LabelRemoveDuplicatesStrategy removeDuplicatesStrategy)
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
public LabelRepeatStrategy 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
public void setRepeatStrategy(LabelRepeatStrategy repeatStrategy)
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
public LabelStackAlignment 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
public void setStackAlignment(LabelStackAlignment stackAlignment)
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
public LabelStackBreakPosition 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
public void setStackBreakPosition(LabelStackBreakPosition stackBreakPosition)
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 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
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
public List<LabelStackSeparator> 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
public LabelStackStrategy 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
public 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.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
public LabelTextLayout 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
public void setTextLayout(LabelTextLayout textLayout)
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
public LabelTextOrientation 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
public void setTextOrientation(LabelTextOrientation textOrientation)
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
public TextSymbol 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
public void setTextSymbol(TextSymbol textSymbol)
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
public String 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
public void setWhereClause(String whereClause)
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
public String 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
public Map<String,Object> getUnknownJson()
Description copied from interface:JsonSerializable
If this object was created from JSON, this method gets unknown data from the source JSON. Unknown JSON is a Map of values that were in the source JSON but are not known by the Runtime and therefore not exposed in the API.- Specified by:
getUnknownJson
in interfaceJsonSerializable
- Returns:
- an unmodifiable Map containing unknown JSON data. The keys are Strings containing names. The types of
the values depend on the types of tokens within the JSON as follows:
- a
Map<String, Object>
represents an object in the JSON - a
List<Object>
represents an array in the JSON - a
String
represents a string in the JSON - a
Double
represents a number in the JSON - a
Boolean
represents true or false in the JSON null
represents null in the JSON
- a
-
getUnsupportedJson
public Map<String,Object> getUnsupportedJson()
Description copied from interface:JsonSerializable
If this object was created from JSON, this method gets unsupported data from the source JSON. Unsupported JSON is a Map of values that are supported by webmaps and known to the version of the webmap specification the API supports (see system requirements), but are not explicitly exposed through the Runtime API.- Specified by:
getUnsupportedJson
in interfaceJsonSerializable
- Returns:
- an unmodifiable Map containing unsupported JSON data. The keys are Strings containing names. The types of
the values depend on the types of tokens within the JSON as follows:
- a
Map<String, Object>
represents an object in the JSON - a
List<Object>
represents an array in the JSON - a
String
represents a string in the JSON - a
Double
represents a number in the JSON - a
Boolean
represents true or false in the JSON null
represents null in the JSON
- a
-
-