Package com.here.sdk.mapview

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 using MapScene.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 using MapCamera.getBoundingBox() (it may be extended) and then use the method GeoBox.contains(GeoCoordinates) in combination with MapCamera.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.

  • Constructor Details

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

    • 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 of MapMarker.

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

      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.

      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.

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

    • isOverlapAllowed

      public boolean isOverlapAllowed()

      Returns true if the marker allows overlap with other markers, false otherwise. Defaults to true.

      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.

    • isTextOptional

      public boolean isTextOptional()

      Returns true if the marker allows text to be hidden, false otherwise. Defaults to false.

      Returns:

      Determines if the marker can be displayed with icon and without text.

    • setTextOptional

      public void setTextOptional(boolean value)

      Sets whether the marker is allowed to appear without text.

      Controls whenever MapMarker can be shown as icon only when isOverlapAllowed() is false, has no effect otherwise. If false then the MapMarker will not appear when icon or text are blocked by other labels. If true, icon will appear even if the text part is blocked by other labels.

      Parameters:
      value -

      Determines if the marker can be displayed with icon and without text.

    • 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 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 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 the MapMarker.

      Returns:

      The TextStyle applied to the text of the MapMarker.

    • setTextStyle

      public void setTextStyle(@NonNull MapMarker.TextStyle value)

      Sets the TextStyle to be used by the MapMarker.

      Parameters:
      value -

      The TextStyle applied to the text of the MapMarker.

    • getVisibilityRanges

      @NonNull public 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 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) of MapMeasure.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.