public static final class FeatureCanvas.LabelDrawCommand extends Object implements AutoCloseable
It is mandatory to specify at least the following:
anchor geometry
to which the label is attached
text(std#string)
text(std.vector<std#string>,HorizontalAlignment alignment)
text(TextBlock)
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.
pointPositions
method: to anchor a label to a Point
geometry
onPath
method: to place a label along a line
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.
See the related guide for a more extensive overview of the labeling API.
Modifier and Type | Method and Description |
---|---|
FeatureCanvas.LabelDrawCommand |
anchor(Geometry anchor)
Sets the anchor of the label.
|
FeatureCanvas.LabelDrawCommand |
anchorDraped(boolean draped)
Specify whether the anchor is draped or not.
|
void |
close() |
protected void |
finalize() |
FeatureCanvas.LabelDrawCommand |
icon(IIcon icon)
Sets the icon to use for the label.
|
FeatureCanvas.LabelDrawCommand |
inPath()
Configure the
LabelDrawCommand to paint the label inside the anchor. |
FeatureCanvas.LabelDrawCommand |
labelGroup(LabelGroup labelGroup)
Set the
LabelGroup for label decluttering. |
FeatureCanvas.LabelDrawCommand |
onPath(OnPathLabelStyle onPathLabelStyle)
Configure the
LabelDrawCommand to position a single label along a line. |
FeatureCanvas.LabelDrawCommand |
onPath(PathLabelPosition verticalPosition,
double additionalVerticalOffset)
Configure the
LabelDrawCommand to position a single label along a line. |
FeatureCanvas.LabelDrawCommand |
pinStyle(PinStyle pinStyle)
This method enables pins for labels and defines their styling.
|
FeatureCanvas.LabelDrawCommand |
pointPositions(List<RelativePosition> positions)
Specifies the possible positions to place a
Point label. |
FeatureCanvas.LabelDrawCommand |
priority(Priority priority)
Sets the priority that is used to determine the order in which labels are placed.
|
FeatureCanvas.LabelDrawCommand |
queryable(boolean queryable)
Indicates whether or not the label should be considered when a
Map#queryFeatures is requested. |
void |
submit()
Submits this draw command.
|
FeatureCanvas.LabelDrawCommand |
text(List<String> text)
Sets the text to use for the label.
|
FeatureCanvas.LabelDrawCommand |
text(List<String> text,
HorizontalAlignment alignment)
Sets the text to use for the label.
|
FeatureCanvas.LabelDrawCommand |
text(String text)
Sets the text to use for the label.
|
FeatureCanvas.LabelDrawCommand |
text(TextBlock text)
Sets the text block to use for the label.
|
FeatureCanvas.LabelDrawCommand |
textStyle(TextStyle textStyle)
Sets the styling for the text.
|
public void close()
close
in interface AutoCloseable
@NotNull public FeatureCanvas.LabelDrawCommand text(@NotNull String text)
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.
text
- the text to use for the label.@NotNull public FeatureCanvas.LabelDrawCommand text(@NotNull TextBlock text)
A text block is composed of multiple texts with different styling each. See TextBlock
and TextBlock.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.
text
- the text block to use for the label.@NotNull public FeatureCanvas.LabelDrawCommand text(@NotNull List<String> text, @NotNull HorizontalAlignment alignment)
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.
text
- the text to use for the label.alignment
- side where text is aligned. By default text is aligned on the left.@NotNull public FeatureCanvas.LabelDrawCommand text(@NotNull List<String> text)
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.
text
- the text to use for the label.@NotNull public FeatureCanvas.LabelDrawCommand textStyle(@NotNull TextStyle textStyle)
This property is optional. See the text style builder
for the default values.
textStyle
- the styling for the text.@NotNull public FeatureCanvas.LabelDrawCommand pinStyle(@NotNull PinStyle pinStyle)
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 when onPath
or inPath
label positioning is used.
pinStyle
- the styling for the pin. See PinStyle#newBuilder
. This property is optional. By default, there's no pin for labels.@NotNull public FeatureCanvas.LabelDrawCommand icon(@NotNull IIcon icon) throws NullPointerException
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.
icon
- the icon to use for the label, cannot be null
NullPointerException
- when the icon is null
.@NotNull public FeatureCanvas.LabelDrawCommand anchor(@NotNull Geometry anchor) throws NullPointerException
This property is mandatory.
anchor
- the anchor of the label, cannot be null
.NullPointerException
- if the anchor is null
.@NotNull public FeatureCanvas.LabelDrawCommand anchorDraped(boolean draped)
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.
draped
- whether the anchor is draped or not.@NotNull public FeatureCanvas.LabelDrawCommand priority(@NotNull Priority priority)
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
's LayerList
.
This property is optional. The default is Priority#normal()
.
priority
- the priority for this label@NotNull public FeatureCanvas.LabelDrawCommand pointPositions(@NotNull List<RelativePosition> positions) throws IllegalArgumentException
Point
label.
If the anchor
is not a point geometry, an exception is thrown in the submit
method.
Calling this method is optional. See LabelDrawCommand
for more information.
positions
- the possible positions for a point label. If empty, an exception is thrown.LabelDrawCommand
IllegalArgumentException
- if the list of positions is empty.@NotNull public FeatureCanvas.LabelDrawCommand inPath()
LabelDrawCommand
to paint the label inside the anchor.
The anchor is used as follows:
submit
method.
Patch
, the base geometry is considered.
Calling this method is optional. See LabelDrawCommand
for more information.
LabelDrawCommand
@NotNull public FeatureCanvas.LabelDrawCommand queryable(boolean queryable)
Map#queryFeatures
is requested.
The default is true.
queryable
- true if the label should be considered.TextDrawCommand
.@NotNull public FeatureCanvas.LabelDrawCommand onPath(@NotNull PathLabelPosition verticalPosition, double additionalVerticalOffset)
LabelDrawCommand
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 a Curve
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.
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.LabelDrawCommand
@NotNull public FeatureCanvas.LabelDrawCommand onPath(@NotNull OnPathLabelStyle onPathLabelStyle)
LabelDrawCommand
to position a single label along a line.
Depending on how the given OnPathLabelStyle
is configured, it can be located
When this method is called, the anchor
must be a Curve
.
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.
onPathLabelStyle
- specifies all parameters needed to place the label at a specific location along the line, cannot be null
.LabelDrawCommand
@NotNull public FeatureCanvas.LabelDrawCommand labelGroup(@NotNull LabelGroup labelGroup)
LabelGroup
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.
labelGroup
- declutter group for this label. See LabelGroup
for more information.LabelDrawCommand
public void submit() throws IllegalStateException
Nothing will be painted if the draw command is not submitted.
IllegalStateException
- if anchor is not a Point
and the pointPositions
method is used.