Module com.esri.arcgisruntime
Package com.esri.arcgisruntime.arcgisservices

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.
Label definitions can be set and updated with the following methods:
Since:
100.1.0

  • Property Details

  • Constructor Details

    • LabelDefinition

      public LabelDefinition(LabelExpression labelExpression, TextSymbol textSymbol)
      Creates a LabelDefinition with a clone of the specified LabelExpression and TextSymbol.

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

      Parameters:
      labelExpression - the expression script used to calculate the label text
      textSymbol - 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

      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 empty
      ArcGISRuntimeException - 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 its ArcadeExpression.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() and getTextOrientation() 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

      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 its ArcadeExpression.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() and getTextOrientation() 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

      public LabelDeconflictionStrategy getDeconflictionStrategy()
      Gets the strategy for moving labels to avoid overlapping feature, annotation, dimension or graphic symbols or higher priority labels. In 3D LabelDeconflictionStrategy.STATIC is selected by default.

      The default is LabelDeconflictionStrategy.AUTOMATIC (which will be interpreted as LabelDeconflictionStrategy.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

      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 3D LabelDeconflictionStrategy.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

      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 or WebmapLabelExpression.

      A label expression using one scripting language can be replaced by an expression using a different scripting language just by creating an object of the new LabelExpression subclass and assigning it to setExpression(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

      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 or WebmapLabelExpression.

      A label expression using one scripting language can be replaced by an expression using a different scripting language just by creating an object of the new LabelExpression subclass and assigning it to setExpression(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

      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 as LabelOverlapStrategy.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 as LabelOverlapStrategy.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 as LabelOverlapStrategy.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 as LabelLineConnection.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

    • geometryStrategyProperty

      public ObjectProperty<LabelGeometryStrategy> 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

      public LabelGeometryStrategy getGeometryStrategy()
      Gets the value of the geometryStrategy 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

      public void setGeometryStrategy(LabelGeometryStrategy geometryStrategy)
      Sets the value of the geometryStrategy 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 the geometryStrategy property
      Since:
      200.3.0
      See Also:

    • lineOrientationProperty

      public ObjectProperty<LabelLineOrientation> lineOrientationProperty()
      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 to LabelLineOrientation.SCREEN then LabelDefinition.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 to LabelLineOrientation.DIRECTION then LabelDefinition.getPlacement() above means the label will be offset perpendicularly left from its line segment.
      • If the LabelDefinition.getLineOrientation() is set to LabelLineOrientation.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 is LabelLineOrientation.SCREEN.

      Must not be set to null.

      Returns:
      the lineOrientation property
      Since:
      200.1.0
      See Also:

    • getLineOrientation

      public LabelLineOrientation getLineOrientation()
      Gets the value of the lineOrientation 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 to LabelLineOrientation.SCREEN then LabelDefinition.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 to LabelLineOrientation.DIRECTION then LabelDefinition.getPlacement() above means the label will be offset perpendicularly left from its line segment.
      • If the LabelDefinition.getLineOrientation() is set to LabelLineOrientation.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 is LabelLineOrientation.SCREEN.

      Must not be set to null.

      Returns:
      the value of the lineOrientation property
      Since:
      200.1.0
      See Also:

    • setLineOrientation

      public void setLineOrientation(LabelLineOrientation lineOrientation)
      Sets the value of the lineOrientation 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 to LabelLineOrientation.SCREEN then LabelDefinition.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 to LabelLineOrientation.DIRECTION then LabelDefinition.getPlacement() above means the label will be offset perpendicularly left from its line segment.
      • If the LabelDefinition.getLineOrientation() is set to LabelLineOrientation.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 is LabelLineOrientation.SCREEN.

      Must not be set to null.

      Parameters:
      lineOrientation - the value for the lineOrientation 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

      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:

      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 as LabelRemoveDuplicatesStrategy.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 the setStackAlignment(LabelStackAlignment) method, the user can choose to use the TextSymbol.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 as LabelStackAlignment.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 the setStackAlignment(LabelStackAlignment) method, the user can choose to use the TextSymbol.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 the getStackRowLength() (although will overrun for individual words larger than this count).

      The default value is LabelStackBreakPosition.AUTOMATIC (which will have the same effect on labels as LabelStackBreakPosition.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 the getStackRowLength() (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

      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 a String to describe it. So each LabelStackSeparator.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

    • 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:

      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 as LabelTextOrientation.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 loaded TextSymbol 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 loaded TextSymbol 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 a CodedValueDomain.

      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 a CodedValueDomain.

      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 interface JsonSerializable
      Returns:
      a JSON string

    • getUnknownJson

      public Map<String,Object> 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 interface JsonSerializable
      Returns:
      an unmodifiable Map containing unknown data from the source JSON

    • getUnsupportedJson

      public Map<String,Object> 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 interface JsonSerializable
      Returns:
      an unmodifiable Map containing unsupported data from the source JSON