MapMarker

public class MapMarker
extension MapMarker: NativeBase
extension MapMarker: Hashable

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(...). To stop displaying it, remove it from the scene using MapScene.removeMapMarker(...).

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.addDelegate(...). Query the bounding box of the camera viewport using MapCamera.boundingBox (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.

  • Creates an instance of a marker at given coordinates, represented by specified image.

    The altitude component of the coordinates is ignored.

    Declaration

    Swift

    public init(at coordinates: GeoCoordinates, image: MapImage)

    Parameters

    coordinates

    The marker’s geographical coordinates.
    image

    The image to draw on the map.

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

    Declaration

    Swift

    public init(at coordinates: GeoCoordinates, image: MapImage, text: String)

    Parameters

    coordinates

    The marker’s geographical coordinates.
    image

    The image to draw on the map.
    text

    The text to draw on the map.

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

    Declaration

    Swift

    public init(at coordinates: GeoCoordinates, image: MapImage, anchor: Anchor2D)

    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.

  • The point on the map where the map marker is drawn. The altitude component of the coordinates is ignored.

    Declaration

    Swift

    public var coordinates: GeoCoordinates { get set }

  • The Metadata instance attached to this marker, see Metadata. This will be nil if nothing has been attached before.

    Declaration

    Swift

    public var metadata: Metadata? { get set }

  • Determines whether or not the marker can overlap 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.

    Defaults to true.

    Declaration

    Swift

    public var isOverlapAllowed: Bool { get set }

  • Determines if the marker can be displayed with icon and without text. Controls whenever MapMarker can be shown as icon only when MapMarker.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.

    Defaults to false.

    Declaration

    Swift

    public var isTextOptional: Bool { get set }

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

    Declaration

    Swift

    public var drawOrder: Int32 { get set }

  • Image representing the marker on the screen.

    Declaration

    Swift

    public var image: MapImage { get set }

  • The anchor point for 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.

    Declaration

    Swift

    public var anchor: Anchor2D { get set }

  • Opacity, the factor applied to the alpha channel of the marker image. Provided value is clamped in range [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 map and are considered for picking.

    Declaration

    Swift

    public var opacity: Double { get set }

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

    Declaration

    Swift

    public var fadeDuration: TimeInterval { get set }

  • The text to be drawn on the map along with the image of the MapMarker.

    Declaration

    Swift

    public var text: String { get set }

  • The TextStyle applied to the text of the MapMarker.

    Declaration

    Swift

    public var textStyle: MapMarker.TextStyle { get set }

  • The list of visibility ranges. The map marker is visible only inside these map measure ranges. A range is half open - [minimumZoomLevel, maximumZoomLevel), the given maximum value is not contained in the range.

    When empty (the default), the map marker is visible without map measure restrictions. Only MapMeasureRange(s) of MapMeasure.Kind.zoomLevel type are supported. MapMeasureRange(s) of other unsupported types will be ignored.

    Declaration

    Swift

    public var visibilityRanges: [MapMeasureRange] { get set }

  • Styling options for the text of a MapMarker.

    See more

    Declaration

    Swift

    public class TextStyle
    extension MapMarker.TextStyle: NativeBase
    extension MapMarker.TextStyle: Hashable

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

    Declaration

    Swift

    public func startAnimation(_ animation: MapMarkerAnimation, animationDelegate: AnimationDelegate?)

    Parameters

    animation

    The animation to start, may be used for multiple different map markers.
    animationDelegate

    The delegate to receive notifications about animation start, completion or cancellation.

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

    Declaration

    Swift

    public func cancelAnimation(_ animation: MapMarkerAnimation)

    Parameters

    animation

    The animation to cancel.