Class MapMarker
- Last UpdatedDec 18, 2024
- 9 minute read
Class MapMarker
- java.lang.Object
-
- com.here.NativeBase
-
- com.here.sdk.mapview.MapMarker
-
public final class MapMarker extends NativeBase
MapMarker
is used to draw images on the map, for example to mark a specific location. By default, the marker is centered on the given geographic coordinates. Markers keep their size regardless of the current zoom level of the map view.The image to be displayed is represented by
MapImage
object. For performance reasons, it is highly recommended to reuse a single instance of the image when creating multiple identical markers.To display the map marker, it needs to be added to the scene using
MapScene.addMapMarker(com.here.sdk.mapview.MapMarker)
. To stop displaying it, remove it from the scene usingMapScene.removeMapMarker(com.here.sdk.mapview.MapMarker)
.The display of a map marker is only guaranteed in case its origin is within the viewport. At the moment, this is a known limitation that mostly affects map markers which are visually large and cover a sizeable part of the viewport.
Note: Due to technical limitations using the MapMarkers API to add a very large number of markers (several thousands, especially 10000+) is not recommended. Adding this many markers will have a negative impact on the performance leading to stuttering of the app and lower frame rates. To work around this limitation the following approach can be used: Register to map camera updates using
MapCamera.addListener(com.here.sdk.mapview.MapCameraListener)
. Query the bounding box of the camera viewport usingMapCamera.getBoundingBox()
(it may be extended) and then use the methodGeoBox.contains(GeoCoordinates)
in combination withMapCamera.State.distanceToTargetInMeters
to determine which MapMarkers are actually visible to the user in the current camera viewport and thus need to be added to the map.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
MapMarker.TextStyle
Styling options for the text of aMapMarker
.
-
Constructor Summary
Constructors Constructor Description MapMarker(GeoCoordinates coordinates, MapImage image)
Creates an instance of a marker at given coordinates, represented by specified image.MapMarker(GeoCoordinates coordinates, MapImage image, Anchor2D anchor)
Creates an instance of a marker at given coordinates, represented by specified image, with anchor point specifying how the image is positioned relative to the marker's coordinates.MapMarker(GeoCoordinates coordinates, MapImage image, java.lang.String text)
Creates aMapMarker
instance at given coordinates with specified image and text and a default text style.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
cancelAnimation(MapMarkerAnimation animation)
Cancels single ongoing animation.Anchor2D
getAnchor()
Gets current anchor point for the marker image.GeoCoordinates
getCoordinates()
Gets the point on the map where the marker is drawn.int
getDrawOrder()
Gets draw order of this marker relative to other markers.Duration
getFadeDuration()
Gets the current duration of a fade-in effect on marker addition to a scene or a fade-out effect on marker removal from a scene.MapImage
getImage()
Gets currently used map image.Metadata
getMetadata()
Gets the Metadata instance attached to this marker.double
getOpacity()
Gets the current opacity of the marker image.java.lang.String
getText()
Gets the text drawn on the map by theMapMarker
.MapMarker.TextStyle
getTextStyle()
Gets a copy of theTextStyle
currently in use by theMapMarker
.java.util.List<MapMeasureRange>
getVisibilityRanges()
Gets the list of visibility ranges.boolean
isOverlapAllowed()
Returnstrue
if the marker allows overlap with other markers,false
otherwise.void
setAnchor(Anchor2D value)
Sets anchor point of the marker image which specifies the position offset relative to the marker's coordinates.void
setCoordinates(GeoCoordinates value)
Sets the point on the map where the marker is drawn.void
setDrawOrder(int value)
Sets draw order of this marker relative to other markers.void
setFadeDuration(Duration value)
Sets duration of a fade-in effect on marker addition to a scene or a fade-out effect on marker removal from a scene.void
setImage(MapImage value)
Sets map image used to represent the marker on screen.void
setMetadata(Metadata value)
Sets the Metadata instance attached to this marker.void
setOpacity(double value)
Sets the opacity of the marker image.void
setOverlapAllowed(boolean value)
Sets whether the marker is allowed to overlap with other markers.void
setText(java.lang.String value)
Sets the text to be drawn on the map by theMapMarker
.void
setTextStyle(MapMarker.TextStyle value)
Sets theTextStyle
to be used by theMapMarker
.void
setVisibilityRanges(java.util.List<MapMeasureRange> value)
Sets visibility ranges for this map marker.void
startAnimation(MapMarkerAnimation animation, AnimationListener animationListener)
Starts animation of this map marker according to providedMapMarkerAnimation
.
-
-
-
Constructor Detail
-
MapMarker
public MapMarker(@NonNull GeoCoordinates coordinates, @NonNull MapImage image)
Creates an instance of a marker at given coordinates, represented by specified image.
The altitude component of the coordinates is ignored.
- Parameters:
coordinates
-The marker's geographical coordinates.
image
-The image to draw on the map.
-
MapMarker
public MapMarker(@NonNull GeoCoordinates coordinates, @NonNull MapImage image, @NonNull java.lang.String text)
Creates a
MapMarker
instance at given coordinates with specified image and text and a default text style.The altitude component of the coordinates is ignored.
- Parameters:
coordinates
-The marker's geographical coordinates.
image
-The image to draw on the map.
text
-The text to draw on the map.
-
MapMarker
public MapMarker(@NonNull GeoCoordinates coordinates, @NonNull MapImage image, @NonNull Anchor2D anchor)
Creates an instance of a marker at given coordinates, represented by specified image, with anchor point specifying how the image is positioned relative to the marker's coordinates.
The anchor is a way of specifying position offset relative to image's dimensions on the screen. For example, (0, 0) places the top-left corner of the image at the marker's coordinates. (1, 1) would place the bottom-right corner of the image at the marker's coordinates. (0.5, 0.5) which is the default value would center the image at the marker's coordinates. Values outside the 0..1 range are also allowed, for example (0.5, 2) would display the image centered horizontally with its bottom edge above the marker's coordinates at the distance in pixels that is equal to the height of the image.
- Parameters:
coordinates
-The marker's geographical coordinates.
image
-The image to draw on the map.
anchor
-The anchor point for the marker image which specifies the position offset relative to the marker's coordinates.
-
-
Method Detail
-
startAnimation
public void startAnimation(@NonNull MapMarkerAnimation animation, @Nullable AnimationListener animationListener)
Starts animation of this map marker according to provided
MapMarkerAnimation
.The
MapMarkerAnimation
may be shared between multiple instances ofMapMarker
.Starting animation on one map marker does not influence any ongoing animations on other map markers. Any ongoing animation of this marker instance will get cancelled.
- Parameters:
animation
-The animation to start, may be used for multiple different map markers.
animationListener
-The listener to receive notifications about animation start, completion or cancellation.
-
cancelAnimation
public void cancelAnimation(@NonNull MapMarkerAnimation animation)
Cancels single ongoing animation.
Does nothing if animation was not started for this map marker.
Does not cancel other animations if the same
MapMarkerAnimation
object was applied to multipleMapMarker
s.- Parameters:
animation
-The animation to cancel.
-
getCoordinates
@NonNull public GeoCoordinates getCoordinates()
Gets the point on the map where the marker is drawn.
- Returns:
The point on the map where the map marker is drawn.
-
setCoordinates
public void setCoordinates(@NonNull GeoCoordinates value)
Sets the point on the map where the marker is drawn. The altitude component of the coordinates is ignored.
The altitude component of the coordinates is ignored.
- Parameters:
value
-The point on the map where the map marker is drawn.
-
getMetadata
@Nullable public Metadata getMetadata()
Gets the Metadata instance attached to this marker. This will be
null
if nothing has been attached before.- Returns:
The Metadata instance attached to this marker, see
Metadata
. This will benull
if nothing has been attached before.
-
setMetadata
public void setMetadata(@Nullable Metadata value)
Sets the Metadata instance attached to this marker.
- Parameters:
value
-The Metadata instance attached to this marker, see
Metadata
. This will benull
if nothing has been attached before.
-
isOverlapAllowed
public boolean isOverlapAllowed()
Returns
true
if the marker allows overlap with other markers,false
otherwise. Defaults totrue
.- Returns:
Determines whether or not the marker can overlap other markers.
-
setOverlapAllowed
public void setOverlapAllowed(boolean value)
Sets whether the marker is allowed to overlap with other markers.
If
false
, it will disappear the moment it overlaps another marker that has a higher visibility priority. A marker that allows overlap will always be drawn. Among markers that don't allow overlap, the one with the highest draw order has priority. Marker that is hidden due to overlapping with other markers is not pickable.- Parameters:
value
-Determines whether or not the marker can overlap other markers.
-
getDrawOrder
public int getDrawOrder()
Gets draw order of this marker relative to other markers. The default value is 0.
- Returns:
The draw order of this marker relative to other markers.
-
setDrawOrder
public void setDrawOrder(int value)
Sets draw order of this marker relative to other markers.
Markers with higher draw order value are drawn on top of markers with lower draw order. In case multiple markers have the same draw order value then the order in which they were added to the scene matters. Last added marker is drawn on top.
Allowed range is [0, 1023]. Values outside this range will be clamped. The default value is 0.
- Parameters:
value
-The draw order of this marker relative to other markers.
-
getImage
@NonNull public MapImage getImage()
Gets currently used map image.
- Returns:
Image representing the marker on the screen.
-
setImage
public void setImage(@NonNull MapImage value)
Sets map image used to represent the marker on screen.
- Parameters:
value
-Image representing the marker on the screen.
-
getAnchor
@NonNull public Anchor2D getAnchor()
Gets current anchor point for the marker image.
- Returns:
The anchor point for the marker image which specifies the position offset relative to the marker's coordinates.
-
setAnchor
public void setAnchor(@NonNull Anchor2D value)
Sets anchor point of the marker image which specifies the position offset relative to the marker's coordinates.
For example, (0, 0) places the top-left corner of the image at the marker's coordinates. (1, 1) would place the bottom-right corner of the image at the marker's coordinates. (0.5, 0.5) which is the default value would center the image at the marker's coordinates. Values outside the 0..1 range are also allowed, for example (0.5, 2) would display the image centered horizontally with its bottom edge above the marker's coordinates at the distance in pixels that is equal to the height of the image.
- Parameters:
value
-The anchor point for the marker image which specifies the position offset relative to the marker's coordinates.
-
getOpacity
public double getOpacity()
Gets the current opacity of the marker image. Value is in the range of [0.0, 1.0]. Default value is 1.0.
- Returns:
Opacity, the factor applied to the alpha channel of the marker image.
-
setOpacity
public void setOpacity(double value)
Sets the opacity of the marker image.
Provided value is clamped to the range of [0.0, 1.0]. Default value is 1.0, which means marker is displayed with the default opacity of the image.
Markers with opacity value set to 0.0 are still on the map and are considered for picking.
- Parameters:
value
-Opacity, the factor applied to the alpha channel of the marker image.
-
getFadeDuration
@NonNull public Duration getFadeDuration()
Gets the current duration of a fade-in effect on marker addition to a scene or a fade-out effect on marker removal from a scene.
- Returns:
Duration of a fade-in effect on marker addition to a scene or a fade-out effect on marker removal from a scene.
-
setFadeDuration
public void setFadeDuration(@NonNull Duration value)
Sets duration of a fade-in effect on marker addition to a scene or a fade-out effect on marker removal from a scene.
Provided value is clamped in range [0.0, 10.0] seconds. Default value is 0 seconds which means the effect is disabled and marker is added/removed immediately without any animation. Fade-in effect is also applied when marker leaves and then re-enters screen area.
Change to this property is made asynchronously and is not guaranteed to take effect on the next rendered frame. In particular, changing fade duration and removing the marker immediately after may result in the new value being ignored for this removal.
- Parameters:
value
-Duration of a fade-in effect on marker addition to a scene or a fade-out effect on marker removal from a scene.
-
getText
@NonNull public java.lang.String getText()
Gets the text drawn on the map by the
MapMarker
.- Returns:
The text to be drawn on the map along with the image of the
MapMarker
.
-
setText
public void setText(@NonNull java.lang.String value)
Sets the text to be drawn on the map by the
MapMarker
.- Parameters:
value
-The text to be drawn on the map along with the image of the
MapMarker
.
-
getTextStyle
@NonNull public MapMarker.TextStyle getTextStyle()
Gets a copy of the
TextStyle
currently in use by theMapMarker
.- Returns:
The
TextStyle
applied to the text of theMapMarker
.
-
setTextStyle
public void setTextStyle(@NonNull MapMarker.TextStyle value)
Sets the
TextStyle
to be used by theMapMarker
.- Parameters:
value
-The
TextStyle
applied to the text of theMapMarker
.
-
getVisibilityRanges
@NonNull public java.util.List<MapMeasureRange> getVisibilityRanges()
Gets the list of visibility ranges. The map marker is visible only inside these map measure ranges. When empty (the default), the map marker is visible without map measure restrictions.
- Returns:
The list of visibility ranges. The map marker is visible only inside these map measure ranges.
-
setVisibilityRanges
public void setVisibilityRanges(@NonNull java.util.List<MapMeasureRange> value)
Sets visibility ranges for this map marker.
A range is half open - [minimumZoomLevel, maximumZoomLevel), the given maximum value is not contained in the range. The map marker is visible only inside these map measure ranges.
When empty (the default), the map marker is visible without map measure restrictions. Only
MapMeasureRange
(s) ofMapMeasure.Kind.ZOOM_LEVEL
type are supported.MapMeasureRange
(s) of other unsupported types will be ignored.- Parameters:
value
-The list of visibility ranges. The map marker is visible only inside these map measure ranges.
-
-