Class

MKAnnotationView

The visual representation of one of your annotation objects.

Overview

Annotation views are loosely coupled to a corresponding annotation object, which is an object that conforms to the MKAnnotation protocol. When an annotation’s coordinate point is in the map's visible region, the map view asks its delegate to provide a corresponding annotation view. Annotation views may be recycled later and put into a reuse queue that is maintained by the map view.The most efficient way to provide the content for an annotation view is to set its image property. The annotation view sizes itself automatically to the image you specify and draws that image for its contents. Because it is a view, however, you could also override the draw(_:) method and draw your view’s content manually. If you choose to override draw(_:) directly and you do not specify a custom image in the image property, be aware that the width and height of the annotation view’s frame are set to 0 by default. Before your custom content can be drawn, you must set the width and height to nonzero values by modifying the view’s frame property. In general, if your content consists entirely of static images, it is more efficient to set the image property and change it as needed than to draw the images yourself.

Annotation views remain anchored to the map at the point specified by their associated annotation object. Although they scroll with the map contents, annotation views reside in a separate display layer and are not scaled when the size of the visible map region changes.

Annotation views support the concept of a selection state, which determines whether the view is unselected, selected, or selected and displaying a standard callout view. The user toggles between the selection states through interactions with the annotation view. In the unselected state, the annotation view is displayed but not highlighted. In the selected state, the annotation is highlighted but the callout is not displayed. And finally, the annotation can be displayed both with a highlight and a callout. The callout view displays additional information such as a title string and controls for viewing more information. The title information is provided by the annotation object but your annotation view is responsible for providing any custom controls. For more information, see the subclassing notes.

Reusing Annotation Views

Annotation views are designed to be reused as the user (or your application) changes the visible map region. The reuse of annotation views provides significant performance improvements during scrolling by avoiding the creation of new view objects during this time critical operation. For this reason, annotation views should not be tightly coupled to the contents of their associated annotation. Instead, it should be possible to use the properties of an annotation view (or setter methods) to configure the view for a new annotation object.

Whenever you initialize a new annotation view, you should always specify a reuse identifier for that view. As annotation views are no longer needed, the map view may put them into a reuse queue. As new annotations are added to the map view, the delegate object can then dequeue and reconfigure an existing view (rather than create a new one) using the dequeueReusableAnnotationView(withIdentifier:) method of MKMapView.

Subclassing Notes

You can use the MKAnnotationView class as is or subclass it to provide custom behavior as needed. The image property of the class lets you set the appearance of the annotation view without subclassing directly. You might also create custom subclasses as a convenience and use them to put the annotation view in a known state. For example, the MKPinAnnotationView subclass initializes the contents of the annotation view to a pin image.

There are no special requirements for subclassing MKAnnotationView. However, the following list includes some reasons you might want to subclass and some of the methods you would override to implement the desired behavior:

  • To put the annotation view into a consistent state, provide a custom initialization method. Your custom initialization method would then call init(annotation:reuseIdentifier:) to initialize the superclass.

  • To provide custom callout views, override the leftCalloutAccessoryView method and use it to return the views.

If you support draggable annotation views in iOS 4.0 and later, your subclass is responsible for changing the value in the dragState property to appropriate values at key transition points in the drag operation. For more information, see the description of that property.

Topics

Initializing and Preparing the View

init(annotation: MKAnnotation?, reuseIdentifier: String?)

Initializes and returns a new annotation view.

func prepareForReuse()

Called when the view is removed from the reuse queue.

Setting the Priority for Display

var displayPriority: MKFeatureDisplayPriority

The display priority of this annotation view.

Beta
struct MKFeatureDisplayPriority

Constants indicating the display priority for annotations.

Beta

Getting and Setting Attributes

var isEnabled: Bool

A Boolean value indicating whether the annotation is enabled.

var image: UIImage?

The image to be displayed by the annotation view.

var isHighlighted: Bool

A Boolean value indicating whether the annotation view is highlighted.

var annotation: MKAnnotation?

The annotation object currently associated with the view.

var centerOffset: CGPoint

The offset (in points) at which to display the view.

var calloutOffset: CGPoint

The offset (in points) at which to place the callout bubble.

var reuseIdentifier: String?

The string that identifies that this annotation view is reusable.

Managing the Selection State

func setSelected(Bool, animated: Bool)

Sets the selection state of the annotation view.

var isSelected: Bool

A Boolean value indicating whether the annotation view is currently selected.

Managing Callout Views

var canShowCallout: Bool

A Boolean value indicating whether the annotation view is able to display extra information in a callout bubble.

var leftCalloutAccessoryView: UIView?

The view to display on the left side of the standard callout bubble.

var rightCalloutAccessoryView: UIView?

The view to display on the right side of the standard callout bubble.

var detailCalloutAccessoryView: UIView?

The detail accessory view to be used in the standard callout.

var leftCalloutOffset: CGPoint

The offset in points from the middle-left of the annotation view.

var rightCalloutOffset: CGPoint

The offset in points from the middle-right of the annotation view.

Supporting Drag Operations

var isDraggable: Bool

A Boolean indicating whether the annotation view is draggable.

func setDragState(MKAnnotationViewDragState, animated: Bool)

Sets the current drag state for the annotation view.

var dragState: MKAnnotationViewDragState

The current drag state of the annotation view.

Managing Collisions Between Annotation Views

var collisionMode: MKAnnotationViewCollisionMode

The collision mode to use when interpreting the collision frame rectangle.

Beta
enum MKAnnotationViewCollisionMode

Constants indicating how to interpret the collision frame rectangle of an annotation view.

Beta

Clustering Annotation Views

var clusteringIdentifier: String?

An identifier that determines whether the annotation view participates in clustering.

Beta
var cluster: MKAnnotationView?

The clustering annotation view currently standing in for this annotation view.

Beta

Notifications

static let MKAnnotationCalloutInfoDidChange: NSNotification.Name

Notifies observers that the title or subtitle information of an annotation object changed.

See Also

Annotations and Overlays

class MKPlacemark

A user-friendly description of a location on the map.

protocol MKAnnotation

An interface for associating your content with a specific map location.

protocol MKOverlay

An interface for associating content with a specific map region.

class MKOverlayRenderer

The shared infrastructure used to draw overlays on the map surface.

MapKit Annotations

Use these annotation objects as-is in your maps.

MapKit Overlays

Use these overlays as-is in your maps.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software