ViewAnnotationManager

public final class ViewAnnotationManager

Manager API to control View Annotations.

View annotations are UIView instances that are drawn on top of the MapView and bound to some Geometry (only Point is supported for now). In case some view annotations intersect on the screen Z-index is based on addition order.

View annotations are invariant to map camera transformations however such properties as size, visibility etc could be controlled by the user using update operation.

View annotations are not explicitly bound to any sources however associatedFeatureId could be used to bind given view annotation with some Feature by Feature.identifier meaning visibility of view annotation will be driven by visibility of given feature.

validatesViews
If the superview or the UIView.isHidden property of a custom view annotation is changed manually by the users the SDK prints a warning and reverts the changes, as the view is still considered for layout calculation. The default value is true, and setting this value to false will disable the validation.
Declaration
Swift

public var validatesViews: Bool
annotations
The complete list of annotations associated with the receiver.
Declaration
Swift

public var annotations: [UIView : ViewAnnotationOptions] { get }

Public APIs


                    
                    
                    add(_:options:)

Add a UIView instance which will be displayed as an annotation. View dimensions will be taken as width / height from the bounds of the view unless they are not specified explicitly with width and height.

Annotation options must include Geometry where we want to bind our view annotation.

Width and height could be specified explicitly but better idea will be not specifying them as they will be calculated automatically based on view layout.

Important

The annotation view to be added should have UIView.transform property set to .identity. Providing a transformed view can result in annotation views being misplaced, overlapped and other layout artifacts.

Note

Use update(_:options:) for changing the visibilty of the view, instead of UIView.isHidden so that it is removed from the layout calculation.

Throws

Throws:

viewIsAlreadyAdded if the supplied view is already added as an annotation
geometryFieldMissing if options did not include geometry
associatedFeatureIdIsAlreadyInUse if the supplied associatedFeatureId is already used by another annotation view
MapError: errors during insertion

Declaration

Swift

public func add(_ view: UIView, options: ViewAnnotationOptions) throws

Parameters

`view`	`UIView` to be added to the map
`options`	`ViewAnnotationOptions` to control the layout and visibility of the annotation


                    
                    
                    add(_:id:options:)

Annotation options must include Geometry where we want to bind our view annotation.

Width and height could be specified explicitly but better idea will be not specifying them as they will be calculated automatically based on view layout.

Important

Note

Use update(_:options:) for changing the visibilty of the view, instead of UIView.isHidden so that it is removed from the layout calculation.

Throws

Throws:

viewIsAlreadyAdded if the supplied view is already added as an annotation, or there is an existing annotation view with the same id.
geometryFieldMissing if options did not include geometry
associatedFeatureIdIsAlreadyInUse if the supplied associatedFeatureId is already used by another annotation view
MapError: errors during insertion

Declaration

Swift

public func add(_ view: UIView, id: String?, options: ViewAnnotationOptions) throws

Parameters

`view`	`UIView` to be added to the map
`id`	The unique string for the `view`.
`options`	`ViewAnnotationOptions` to control the layout and visibility of the annotation


                    
                    
                    remove(_:)

Remove given UIView from the map if it was present.

Declaration

Swift

public func remove(_ view: UIView)

Parameters


                                  view

UIView to be removed

removeAll()
Removes all annotations views from the map.
Declaration
Swift

public func removeAll()


                    
                    
                    update(_:options:)

Update given UIView with ViewAnnotationOptions. Important thing to keep in mind that only properties present in options will be updated, all other will remain the same as specified before.

Important

The annotation view to be updated should have UIView.frame property set to identify. Providing a transformed view can result in annotation views being misplaced, overlapped and other layout artifacts.

Throws

annotationNotFound: the supplied view was not found
associatedFeatureIdIsAlreadyInUse if the supplied associatedFeatureId is already used by another annotation view
MapError: errors during the update of the view (eg. incorrect parameters)

Declaration

Swift

public func update(_ view: UIView, options: ViewAnnotationOptions) throws

Parameters

`view`	`UIView` to be updated
`options`	view annotation options with optional fields used for the update


                    
                    
                    view(forId:)

Find view annotation by the given id.

Declaration

Swift

public func view(forId id: String) -> UIView?

Parameters

`id`	The identifier of the view set in `add(_:id:options:)`.

Return Value

UIView if view was found, otherwise nil.


                    
                    
                    view(forFeatureId:)

Find UIView by feature id if it was specified as part of associatedFeatureId.

Declaration

Swift

public func view(forFeatureId identifier: String) -> UIView?

Parameters


                                  identifier

the identifier of the feature which will be used for finding the associated UIView

Return Value

UIView if view was found and nil otherwise.


                    
                    
                    options(forFeatureId:)

Find ViewAnnotationOptions of view annotation by feature id if it was specified as part of associatedFeatureId.

Declaration

Swift

public func options(forFeatureId identifier: String) -> ViewAnnotationOptions?

Parameters


                                  identifier

the identifier of the feature which will be used for finding the associated ViewAnnotationOptions

Return Value

ViewAnnotationOptions if view was found and nil otherwise.


                    
                    
                    options(for:)

Get current ViewAnnotationOptions for given UIView.

Declaration

Swift

public func options(for view: UIView) -> ViewAnnotationOptions?

Parameters


                                  view

an UIView for which the associated ViewAnnotationOptions is looked up

Return Value

ViewAnnotationOptions if view was found and nil otherwise.


                    
                    
                    addViewAnnotationUpdateObserver(_:)

Add an observer for annotation views updates

Observers are held strongly.

Declaration

Swift

public func addViewAnnotationUpdateObserver(_ observer: ViewAnnotationUpdateObserver)

Parameters


                                  observer

The object to notify when updates occur.


                    
                    
                    removeViewAnnotationUpdateObserver(_:)

Remove an observer for annotation views updates.

Declaration

Swift

public func removeViewAnnotationUpdateObserver(_ observer: ViewAnnotationUpdateObserver)

Parameters


                                  observer

The object to stop sending notifications to.

Framing


                    
                    
                    camera(forAnnotations:padding:bearing:pitch:)

Calculates CameraOptions to fit the list of view annotations.

Important

This API isn’t supported by Globe projection.

Declaration

Swift

public func camera(
    forAnnotations identifiers: [String],
    padding: UIEdgeInsets = .zero,
    bearing: CGFloat? = nil,
    pitch: CGFloat? = nil
) -> CameraOptions?

Parameters

`ids`	The list of annotations ids to be framed.
`padding`	See `padding`.
`bearing`	See `bearing`.
`pitch`	See `pitch`.