Class FeatureCanvas.LabelDrawCommand
- All Implemented Interfaces:
AutoCloseable
- Enclosing class:
FeatureCanvas
It is mandatory to specify at least the following:
- The
anchor geometry
to which the label is attached - The label content
- Label content
- A single line of text: see
text(std#string)
- Multiple lines text: see
text(std.vector<std#string>,HorizontalAlignment alignment)
- A text block: see
text(TextBlock)
- An icon: see
icon
It is mandatory to call at least one of these methods. If not, an exception will be thrown when submitting
this label draw command. If these methods are called multiple times, only the last one is used.
- Label positions
- the
pointPositions
method: to anchor a label to aPoint
geometry - the
onPath
method: to place a label along a line - the
inPath
method: to place a label inside an area
If these methods are called multiple times, only the last one is used. If none of these methods is called, a default label positions is chosen using the LabelDrawCommand#anchor
geometry.
- Label decluttering
- Multiple label locations are tried to avoid overlapping labels
- Labels for which no good location can be found (i.e. that would always overlap with an other label) are dropped.
See the related guide for a more extensive overview of the labeling API.
-
Method Summary
Modifier and TypeMethodDescriptionSets the anchor of the label.anchorDraped
(boolean draped) Specify whether the anchor is draped or not.void
close()
protected void
finalize()
Sets the icon to use for the label.inPath()
Configure theLabelDrawCommand
to paint the label inside the anchor.labelGroup
(LabelGroup labelGroup) Set theLabelGroup
for label decluttering.onPath
(OnPathLabelStyle onPathLabelStyle) Configure theLabelDrawCommand
to position a single label along a line.onPath
(PathLabelPosition verticalPosition, double additionalVerticalOffset) Configure theLabelDrawCommand
to position a single label along a line.This method enables pins for labels and defines their styling.pointPositions
(List<@NotNull RelativePosition> positions) Specifies the possible positions to place aPoint
label.Sets the priority that is used to determine the order in which labels are placed.queryable
(boolean queryable) Indicates whether or not the label should be considered when aMap#queryFeatures
is requested.void
submit()
Submits this draw command.Sets the text block to use for the label.Sets the text to use for the label.Sets the text to use for the label.text
(List<@NotNull String> text, HorizontalAlignment alignment) Sets the text to use for the label.Sets the styling for the text.
-
Method Details
-
finalize
protected void finalize() -
close
public void close()- Specified by:
close
in interfaceAutoCloseable
-
text
Sets the text to use for the label.This property is optional, though it is mandatory that at least one method is used to specify the label content. See the
class documentation
for more info.- Parameters:
text
- the text to use for the label.- Returns:
- this
-
text
Sets the text block to use for the label.A text block is composed of multiple texts with different styling each. See
TextBlock
andTextBlock.Builder
.This property is optional, though it is mandatory that at least one method is used to specify the label content. See the
class documentation
for more info.- Parameters:
text
- the text block to use for the label.- Returns:
- this
-
text
@NotNull public FeatureCanvas.LabelDrawCommand text(@NotNull List<@NotNull String> text, @NotNull HorizontalAlignment alignment) Sets the text to use for the label.Each string in this vector is rendered as a separate line.
This property is optional, though it is mandatory that at least one method is used to specify the label content. See the
class documentation
for more info.- Parameters:
text
- the text to use for the label.alignment
- side where text is aligned. By default text is aligned on the left.- Returns:
- this
-
text
Sets the text to use for the label.Each string in this vector is rendered as a separate line.
This property is optional, though it is mandatory that at least one method is used to specify the label content. See the
class documentation
for more info.- Parameters:
text
- the text to use for the label.- Returns:
- this
-
textStyle
Sets the styling for the text.This property is optional. See the text style
builder
for the default values.- Parameters:
textStyle
- the styling for the text.- Returns:
- this
-
pinStyle
This method enables pins for labels and defines their styling.By default, there's no pin for labels.
Pins are only supported when a label is attached
to a point
. No pin will be painted whenonPath
orinPath
label positioning is used.- Parameters:
pinStyle
- the styling for the pin. SeePinStyle#newBuilder
. This property is optional. By default, there's no pin for labels.- Returns:
- this
-
icon
@NotNull public FeatureCanvas.LabelDrawCommand icon(@NotNull IIcon icon) throws NullPointerException Sets the icon to use for the label.This property is optional, though it is mandatory that at least one method is used to specify the label content. See the
class documentation
for more info.- Parameters:
icon
- the icon to use for the label, cannot benull
- Returns:
- this
- Throws:
NullPointerException
- when the icon isnull
.
-
anchor
@NotNull public FeatureCanvas.LabelDrawCommand anchor(@NotNull Geometry anchor) throws NullPointerException Sets the anchor of the label.This property is mandatory.
- Parameters:
anchor
- the anchor of the label, cannot benull
.- Returns:
- this
- Throws:
NullPointerException
- if the anchor isnull
.
-
anchorDraped
Specify whether the anchor is draped or not.If this method is not invoked, the draping status will be the same as when rendering the anchor: if all Z components equal to 0, draping is enabled and the label will be on the ground. Otherwise, the label will be placed at anchor elevation.
- Parameters:
draped
- whether the anchor is draped or not.- Returns:
- this
-
priority
Sets the priority that is used to determine the order in which labels are placed.- Using a high priority will make it more likely for a label to be placed.
- Using a low priority will make it more likely for the label to be omitted during label placement, because other labels with a higher priority may already occupy its space.
Label priorities work across layers. This means that it is possible to give a high priority to a label, regardless of where the layer is located in the
Map
'sLayerList
.This property is optional. The default is
Priority#normal()
.- Parameters:
priority
- the priority for this label- Returns:
- this
-
pointPositions
@NotNull public FeatureCanvas.LabelDrawCommand pointPositions(@NotNull List<@NotNull RelativePosition> positions) throws IllegalArgumentException Specifies the possible positions to place aPoint
label.If the
anchor
is not a point geometry, an exception is thrown in thesubmit
method.Calling this method is optional. See
LabelDrawCommand
for more information.- Parameters:
positions
- the possible positions for a point label. If empty, an exception is thrown.- Returns:
- this
LabelDrawCommand
- Throws:
IllegalArgumentException
- if the list of positions is empty.
-
inPath
Configure theLabelDrawCommand
to paint the label inside the anchor.The anchor is used as follows:
- The anchor must be a closed ring or a surface, or contain one. If it's not the case, an exception is thrown in the
submit
method. - If the anchor is a multi geometry, only the biggest one is considered.
- If the anchor is an extruded one, the base geometry is considered.
- If the anchor is a
Patch
, the base geometry is considered. - For other geometries, the label is positioned in such a way that it's inside the anchor geometry.
Calling this method is optional. See
LabelDrawCommand
for more information.- Returns:
- this
LabelDrawCommand
- The anchor must be a closed ring or a surface, or contain one. If it's not the case, an exception is thrown in the
-
queryable
Indicates whether or not the label should be considered when aMap#queryFeatures
is requested.The default is true.
- Parameters:
queryable
- true if the label should be considered.- Returns:
- this
TextDrawCommand
.
-
onPath
@NotNull public FeatureCanvas.LabelDrawCommand onPath(@NotNull PathLabelPosition verticalPosition, double additionalVerticalOffset) Configure theLabelDrawCommand
to position a single label along a line.The label will also be placed within the view extent if possible.
When this method is called, the
anchor
must be aCurve
or consist of one in case of:Also
Bounds
geometries are supported.If an anchor is specified that is not supported by this labeling method, an exception will be thrown when the label command is submitted.
Calling this method is optional. See
LabelDrawCommand
for more information.- Parameters:
verticalPosition
- specifies where the label is placed wrt to a position on the line.additionalVerticalOffset
- an additional perpendicular offset from the position on the line at which a label will be placed. This offset is expressed in pixels. If the value is positive, the label position is moved away from the line. If the value is negative, the label positions is moved towards the line. There is no maximum limit to the negative values, but keep in mind that large negative values will push the label to the opposite side of the line. The default offset is 0.- Returns:
- this
LabelDrawCommand
-
onPath
Configure theLabelDrawCommand
to position a single label along a line.Depending on how the given
OnPathLabelStyle
is configured, it can be located- somewhere along the line, but also within the view extent
- at a specific location along the line, for example exactly in the middle
When this method is called, the
anchor
must be aCurve
.If an anchor is specified that is not supported by this labeling method, an exception will be thrown when the label command is submitted.
Calling this method is optional. See
LabelDrawCommand
for more information.- Parameters:
onPathLabelStyle
- specifies all parameters needed to place the label at a specific location along the line, cannot benull
.- Returns:
- this
LabelDrawCommand
-
labelGroup
Set theLabelGroup
for label decluttering.A label declutter group is a collection of labels that are positioned independently from other label declutter groups. I.e. labels from one group will never affect labels from other groups. This also means that labels from different groups are allowed to overlap.
- Parameters:
labelGroup
- declutter group for this label. SeeLabelGroup
for more information.- Returns:
- this
LabelDrawCommand
-
submit
Submits this draw command.Nothing will be painted if the draw command is not submitted.
- Throws:
IllegalStateException
- if anchor is not aPoint
and thepointPositions
method is used.
-