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

        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 be null 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 be null if nothing has been attached before.

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

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