ViewAnnotation

 
public final class ViewAnnotation

Creates a view annotation.

Use view annotations if you need to display interactive UIView bound to a geographical coordinate or map feature.

If you need to display large amounts of data or clustering, please consider using PointAnnotation or Runtime Styling API, for example, SymbolLayer with GeoJSONSource.

To display a view annotation configure a UIView, create ViewAnnotation, and add it to the view annotation manager:

let view = CustomView()
view.icon = UIImage(named: "traffic-icon")
let annotation = ViewAnnotation(
  coordinate: CLLocationCoordinate(latitude: 10, longitude: 10),
  view: view)
mapView.viewAnnotations.add(annotation)

The annotation can be displayed on a layer feature referenced by it’s layerId and featureId:

annotation.annotatedFeature = .layerFeature(layerId: "route-line", featureId: "sf-la")

The view annotation automatically inserts and removes it’s view into the view hierarchy and updates its isHidden property.

Important

Don’t set UIView.isHidden property to hide the annotation. Instead, use visible property.

When view content or layout is updated, use setNeedsUpdateSize() to update the the annotation size. It’s safe to use it multiple times, only one update will be performed.

view.hintText = "Less Traffic"
annotation.setNeedsUpdateSize() // Updates the annotation size.

Note

The ViewAnnotation uses UIView.systemLayoutSizeFitting(_:) to measure the view size. Make sure that your view returns the correct size (e.g. implemented using AutoLayout, or returns correct size from UIView.sizeThatFits(_:) when layout is manual).

To remove annotation when it’s no longer needed, use remove() method.

  • Annotation view.

    Declaration

    Swift

    public let view: UIView

  • Associates the view annotation with the feature geometry.

    The geometry may be any Geometry or a feature rendered on a specified layer.

    Declaration

    Swift

    public var annotatedFeature: AnnotatedFeature { get set }

  • If true, the annotation will be visible even if it collides with other previously drawn annotations.

    The property is false by default.

    Declaration

    Swift

    public var allowOverlap: Bool { get set }

  • Specifies if this view annotation is visible or not.

    The property is true by default.

    Declaration

    Swift

    public var visible: Bool { get set }

  • Specifies if this view annotation is selected meaning it should be placed on top of others.

    The property is false by default.

    Declaration

    Swift

    public var selected: Bool { get set }

  • A list of anchor configurations available.

    The annotation will automatically pick the first best anchor position depending on position relative to other elements on the map.

    If not specified, the annotation will be placed in center.

    The onAnchorChanged is called when the effective position is updated:

    let view = CustomView()
let annotation = ViewAnnotation(
    annotatedFeature: .layerFeature(layerId: "route-line", featureId: "sf-la"),
    view: view)

// Allow top and bottom anchor directions.
annotation.variableAnchors = [
  ViewAnnotationAnchorConfig(anchor: .top),
  ViewAnnotationAnchorConfig(anchor: .bottom)
]

annotation.onAnchorChanged = { config in
    // Update the view's anchor to the newly picked one.
    view.anchor = config.anchor
}

    Declaration

    Swift

    public var variableAnchors: [ViewAnnotationAnchorConfig] { get set }

  • Called when visibility of annotation is changed.

    The annotation becomes hidden when it goes out of MapView’s bounds or visible property is changed.

    The callback takes true when annotation is visible.

    Declaration

    Swift

    public var onVisibilityChanged: ((Bool) -> Void)?

  • Called when anchorConfig is changed.

    See variableAnchors.

    The callback takes the anchorConfig parameter which represents the selected anchor configuration.

    Declaration

    Swift

    public var onAnchorChanged: ((ViewAnnotationAnchorConfig) -> Void)?

  • Called when anchorCoordinate is changed.

    Declaration

    Swift

    public var onAnchorCoordinateChanged: ((CLLocationCoordinate2D) -> Void)?

  • Called when view frame is changed.

    The callback takes the frame parameter.

    Declaration

    Swift

    public var onFrameChanged: ((CGRect) -> Void)?

  • Currently selected anchor configuration.

    Declaration

    Swift

    private(set) public var anchorConfig: ViewAnnotationAnchorConfig? { get set }

  • The actual geographical coordinate used for positioning this annotation.

    Declaration

    Swift

    private(set) public var anchorCoordinate: CLLocationCoordinate2D? { get set }

  • Creates an annotation.

    Declaration

    Swift

    public init(annotatedFeature: AnnotatedFeature, view: UIView)

  • Creates an annotation at specified coordinate.

    Declaration

    Swift

    public convenience init(coordinate: CLLocationCoordinate2D, view: UIView)

  • Creates a view annotation on feature rendered on a layer.

    Declaration

    Swift

    public convenience init(layerId: String, featureId: String? = nil, view: UIView)

    Parameters

    layerId

    Layer identifier which renders the feature.
    featureId

    Feature identifier. If not specified, the annotation will appear on any feature from that layer.
    content

    The view to place on the map.

  • Removes view annotation.

    This method removes the view from its superview.

    Declaration

    Swift

    public func remove()

  • Invalidates the current size of view annotation.

    Call this method when the managed view layout is updated. The annotation will be repositioned according to the new size in the next rendering call.

    Declaration

    Swift

    public func setNeedsUpdateSize()