Package com.esri.arcgisruntime.arcgisservices

Class LabelDefinition

    • Constructor Detail

      • LabelDefinition

        public LabelDefinition​(LabelExpression labelExpression,
                       TextSymbol textSymbol)
        Creates a LabelDefinition with 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:
        java.lang.IllegalArgumentException - if labelExpression is null
        Since:
        100.11.0

    • Method Detail

      • fromJson

        public static LabelDefinition fromJson​(java.lang.String json)
        Creates a LabelDefinition instance from a JSON string.
        Parameters:
        json - a valid string in JSON format
        Returns:
        a LabelDefinition instance
        Throws:
        java.lang.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.

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

        Parameters:
        angle - a LabelAngle specifying angular positions and layout directions; may be null
        Since:
        100.11.0
        See Also:
        getAngle()

      • 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:
        java.lang.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 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 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 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).

        Parameters:
        expression - the expression script used to calculate the label text
        Throws:
        java.lang.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:
        java.lang.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:
        java.lang.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:
        java.lang.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:
        java.lang.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:
        java.lang.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:
        java.lang.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:
        java.lang.IllegalArgumentException - if multipartStrategy is null
        Since:
        100.11.0

      • getName

        public java.lang.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​(java.lang.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:
        java.lang.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:
        java.lang.IllegalArgumentException - if overrunStrategy is null
        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:
        java.lang.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

      • 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:
        java.lang.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:
        java.lang.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:
        java.lang.IllegalArgumentException - if stackAlignment is null
        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:
        java.lang.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 java.util.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:
        java.lang.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:
        java.lang.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:
        java.lang.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 java.lang.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​(java.lang.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:
        java.lang.IllegalArgumentException - if whereClause is null
        Since:
        100.11.0

      • toJson

        public java.lang.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 java.util.Map<java.lang.String,​java.lang.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 interface JsonSerializable
        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

      • getUnsupportedJson

        public java.util.Map<java.lang.String,​java.lang.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 interface JsonSerializable
        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