iOS Developer Library

Developer

MapKit Framework Reference MKAnnotationView Class Reference

Options
Deployment Target:

On This Page
Language:

MKAnnotationView

Inherits From


Import Statement


Swift

import MapKit

Objective-C

@import MapKit;

Availability


Available in iOS 3.0 and later

The MKAnnotationView class is responsible for presenting annotations visually in a map view. Annotation views are loosely coupled to a corresponding annotation object, which is an object that corresponds to the MKAnnotation protocol. When an annotation’s coordinate point is in the 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 drawRect: method and draw your view’s content manually. If you choose to override drawRect: 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 dequeueReusableAnnotationViewWithIdentifier: 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 initWithAnnotation: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.

  • Initializes and returns a new annotation view.

    Declaration

    Swift

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

    Objective-C

    - (instancetype)initWithAnnotation:(id<MKAnnotation>)annotation reuseIdentifier:(NSString *)reuseIdentifier

    Parameters

    annotation

    The annotation object to associate with the new view.

    reuseIdentifier

    If you plan to reuse the annotation view for similar types of annotations, pass a string to identify it. Although you can pass nil if you do not intend to reuse the view, reusing annotation views is generally recommended.

    Return Value

    The initialized annotation view or nil if there was a problem initializing the object.

    Discussion

    The reuse identifier provides a way for you to improve performance by recycling annotation views as they are scrolled on and off of the map. As views are no longer needed, they are moved to a reuse queue by the map view. When a new annotation becomes visible, your application can request a view for that annotation by passing the appropriate reuse identifier string to the dequeueReusableAnnotationViewWithIdentifier: method of MKMapView.

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 3.0 and later

  • Called when the view is removed from the reuse queue.

    Declaration

    Swift

    func prepareForReuse()

    Objective-C

    - (void)prepareForReuse

    Discussion

    The default implementation of this method does nothing. You can override it in your custom annotation views and use it to put the view in a known state before it is returned to your map view delegate.

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 3.0 and later

  • enabled enabled Property

    A Boolean value indicating whether the annotation is enabled.

    Declaration

    Swift

    var enabled: Bool

    Objective-C

    @property(nonatomic, getter=isEnabled) BOOL enabled

    Discussion

    The default value of this property is YEStrue. If the value of this property is NOfalse, the annotation view ignores touch events and cannot be selected. Subclasses may also display the annotation contents differently depending on the value of this property.

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 3.0 and later

  • image image Property

    The image to be displayed by the annotation view.

    Declaration

    Swift

    var image: UIImage!

    Objective-C

    @property(nonatomic, strong) UIImage *image

    Discussion

    Assigning a new image to this property also changes the size of the view’s frame so that it matches the width and height of the new image. The position of the view’s frame does not change.

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 3.0 and later

  • A Boolean value indicating whether the annotation view is highlighted.

    Declaration

    Swift

    var highlighted: Bool

    Objective-C

    @property(nonatomic, getter=isHighlighted) BOOL highlighted

    Discussion

    You should not set the value of this property directly. The map view sets it in response to touch events entering or exiting the annotation view’s bounds.

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 3.0 and later

  • The annotation object currently associated with the view.

    Declaration

    Swift

    var annotation: MKAnnotation!

    Objective-C

    @property(nonatomic, strong) id< MKAnnotation > annotation

    Discussion

    You should not change the value of this property directly. This property contains a non-nil value only while the annotation view is visible on the map. If the view is queued and waiting to be reused, the value is nil

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 3.0 and later

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

    Declaration

    Swift

    var centerOffset: CGPoint

    Objective-C

    @property(nonatomic) CGPoint centerOffset

    Discussion

    By default, the center point of an annotation view is placed at the coordinate point of the associated annotation. You can use this property to reposition the annotation view as needed. This x and y offset values are measured in pixels. Positive offset values move the annotation view down and to the right, while negative values move it up and to the left.

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 3.0 and later

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

    Declaration

    Swift

    var calloutOffset: CGPoint

    Objective-C

    @property(nonatomic) CGPoint calloutOffset

    Discussion

    This property determines the additional distance by which to move the callout bubble. When this property is set to (0, 0), the anchor point of the callout bubble is placed on the top-center point of the annotation view’s frame. Specifying positive offset values moves the callout bubble down and to the right, while specifying negative values moves it up and to the left.

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 3.0 and later

  • The string that identifies that this annotation view is reusable. (read-only)

    Declaration

    Swift

    var reuseIdentifier: String! { get }

    Objective-C

    @property(nonatomic, readonly) NSString *reuseIdentifier

    Discussion

    You specify the reuse identifier when you create the view. You use this type later to retrieve an annotation view that was created previously but which is currently unused because its annotation is not on screen.

    If you define distinctly different types of annotations (with distinctly different annotation views to go with them), you can differentiate between the annotation types by specifying different reuse identifiers for each one.

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 3.0 and later

  • Sets the selection state of the annotation view.

    Declaration

    Swift

    func setSelected(_ selected: Bool, animated animated: Bool)

    Objective-C

    - (void)setSelected:(BOOL)selected animated:(BOOL)animated

    Parameters

    selected

    Contains the value YEStrue if the view should display itself as selected.

    animated

    Set to YEStrue if the change in selection state is animated.

    Discussion

    You should not call this method directly. An MKMapView object calls this method in response to user interactions with the annotation.

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 3.0 and later

    See Also

    selectAnnotation:animated: (MKMapView)

  • selected selected Property

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

    Declaration

    Swift

    var selected: Bool

    Objective-C

    @property(nonatomic, getter=isSelected) BOOL selected

    Discussion

    You should not set the value of this property directly. If the property contains YEStrue, the annotation view is displaying a callout bubble.

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 3.0 and later

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

    Declaration

    Swift

    var canShowCallout: Bool

    Objective-C

    @property(nonatomic) BOOL canShowCallout

    Discussion

    If the value of this property is YEStrue, a standard callout bubble is shown when the user taps a selected annotation view. The callout uses the title and subtitle text from the associated annotation object. If there is no title text, though, the annotation view is treated as if its enabled property is set to NOfalse. The callout also displays any custom callout views stored in the leftCalloutAccessoryView and rightCalloutAccessoryView properties.

    If the value of this property is NOfalse, the value of the title and subtitle strings are ignored and the annotation view remains enabled by default. You can still disable the view explicitly using the enabled property.

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 3.0 and later

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

    Declaration

    Swift

    var leftCalloutAccessoryView: UIView!

    Objective-C

    @property(strong, nonatomic) UIView *leftCalloutAccessoryView

    Discussion

    The default value of this property is nil. The left callout view is typically used to display information about the annotation or to link to custom information provided by your application.

    If the view you specify is also a descendant of the UIControl class, you can use the map view’s delegate to receive notifications when your control is tapped. If it does not descend from UIControl, your view is responsible for handling any touch events within its bounds.

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 3.0 and later

    See Also

    canShowCallout

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

    Declaration

    Swift

    var rightCalloutAccessoryView: UIView!

    Objective-C

    @property(strong, nonatomic) UIView *rightCalloutAccessoryView

    Discussion

    This property is set to nil by default. The right callout view is typically used to link to more detailed information about the annotation. A common view to specify for this property is UIButton object whose type is set to UIButtonTypeDetailDisclosure.

    If the view you specify is also a descendant of the UIControl class, you can use the map view’s delegate to receive notifications when your control is tapped. If it does not descend from UIControl, your view is responsible for handling any touch events within its bounds.

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 3.0 and later

    See Also

    canShowCallout

  • draggable draggable Property

    A Boolean indicating whether the annotation view is draggable.

    Declaration

    Swift

    var draggable: Bool

    Objective-C

    @property(nonatomic, getter=isDraggable) BOOL draggable

    Discussion

    Setting this property to YEStrue makes an annotation draggable by the user. If YEStrue, the associated annotation object must also implement the setCoordinate: method. The default value of this property is NOfalse.

    Setting this property to YEStrue, lets the map view know that the annotation is always draggable. In other words, you cannot conditionalize drag operations by attempting to stop an operation that has already been initiated; doing so can lead to undefined behavior. Once begun, the drag operation should always continue to completion.

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 4.0 and later

  • Sets the current drag state for the annotation view.

    Declaration

    Swift

    func setDragState(_ newDragState: MKAnnotationViewDragState, animated animated: Bool)

    Objective-C

    - (void)setDragState:(MKAnnotationViewDragState)newDragState animated:(BOOL)animated

    Parameters

    newDragState

    The new drag state for the annotation view.

    animated

    If YEStrue, the change to the new drag state should be animated; otherwise, it should be made without animations.

    Discussion

    Applications targeting iOS 4.2 and later can override this method and use it to implement drag support for custom annotation views. As the system detects user actions that would indicate a drag, it calls this method to update the drag state. In response to these changes, your custom implementation of this method should do the following:

    The default implementation of this method sets the value of the dragState property to the value in the newDragState parameter only. Therefore, direct subclasses can simply call the inherited version of this method to change the drag state; otherwise, just change the value in the draggable property directly.

    Changing the state to MKAnnotationViewDragStateDragging or MKAnnotationViewDragStateNone is the way to signal to the map view that you are done with any animations you wanted to perform. For example, when a drag operation begins for a pin annotation, the MKPinAnnotationView class executes an animation to lift the pin off the map. Similarly, when the pin is dropped, the class performs a drop animation. Even if you do not perform any animations, you should call the inherited version of this method to update the dragState property.

    You must not try to abort a new drag operation by changing the state from MKAnnotationViewDragStateStarting to MKAnnotationViewDragStateNone. If you do not want your annotation view to be draggable, set the draggable property to NOfalse.

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 4.2 and later

  • dragState dragState Property

    The current drag state of the annotation view.

    Declaration

    Swift

    var dragState: MKAnnotationViewDragState

    Objective-C

    @property(nonatomic) MKAnnotationViewDragState dragState

    Discussion

    Applications targeting iOS 4.1 and earlier can use this property to support drag operations in custom annotation views. If your application runs in iOS 4.2 or later, you should override the setDragState:animated: method and use it to manage the drag state instead.

    To support drag operations, you must override the implementation of this property and update the drag state at the following times:

    Changing the state to the MKAnnotationViewDragStateDragging or MKAnnotationViewDragStateNone value is the way to signal to the map view that you are done with any animations you wanted to perform. For example, when a drag operation begins for a pin annotation, the MKPinAnnotationView class executes an animation to lift the pin off the map. Similarly, when the pin is dropped, the class performs a drop animation. Even if you do not perform any animations, you should still change the value of this property to reflect the correct state.

    You must not try to abort a new drag operation by changing the state from MKAnnotationViewDragStateStarting to MKAnnotationViewDragStateNone. If you do not want your annotation view to be draggable, set the draggable property to NOfalse.

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 4.0 and later

    See Also

    draggable

  • These constants indicate the current drag state of an annotation view.

    Declaration

    Swift

    enum MKAnnotationViewDragState : UInt { case None case Starting case Dragging case Canceling case Ending }

    Objective-C

    typedef enum MKAnnotationViewDragState { MKAnnotationViewDragStateNone = 0, MKAnnotationViewDragStateStarting, MKAnnotationViewDragStateDragging, MKAnnotationViewDragStateCanceling, MKAnnotationViewDragStateEnding } MKAnnotationViewDragState;

    Constants

    • None

      MKAnnotationViewDragStateNone

      The view is not involved in a drag operation. The annotation view is responsible for returning itself to this state when a drag ends or is canceled.

      Available in iOS 4.0 and later

    • Starting

      MKAnnotationViewDragStateStarting

      An action occurred that indicated the view should begin dragging. The map view automatically moves annotation views to this state in response to appropriate user actions.

      Available in iOS 4.0 and later

    • Dragging

      MKAnnotationViewDragStateDragging

      The view is in the middle of a drag operation and is tracking progress.

      Available in iOS 4.0 and later

    • Canceling

      MKAnnotationViewDragStateCanceling

      An action occurred that indicated the view should cancel the drag operation. You can put an annotation view into this state to abort the operation.

      Available in iOS 4.0 and later

    • Ending

      MKAnnotationViewDragStateEnding

      An action occurred that indicated the view was dropped by the user. The map view automatically moves annotation views to this state in response to appropriate user actions.

      Available in iOS 4.0 and later

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 4.0 and later

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

    Use KVO notifications instead.

    This notification supports legacy applications and is no longer necessary. MapKit tracks changes to the title and subtitle of an annotation using KVO notifications.

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 3.0 and later