MKAnnotationView Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/MapKit.framework
Availability
Available in iOS 3.0 and later.
Companion guide
Declared in
MKAnnotationView.h
Related sample code

Overview

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:

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.

Tasks

Initializing and Preparing the View

Getting and Setting Attributes

Managing the Selection State

Managing Callout Views

Supporting Drag Operations

Properties

annotation

The annotation object currently associated with the view.

@property (nonatomic, retain) 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

Availability
  • Available in iOS 3.0 and later.
Related Sample Code
Declared In
MKAnnotationView.h

calloutOffset

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

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

Availability
  • Available in iOS 3.0 and later.
Declared In
MKAnnotationView.h

canShowCallout

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

@property (nonatomic) BOOL canShowCallout
Discussion

If the value of this property is YES, 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 NO. The callout also displays any custom callout views stored in the leftCalloutAccessoryView and rightCalloutAccessoryView properties.

If the value of this property is NO, 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.

Availability
  • Available in iOS 3.0 and later.
Declared In
MKAnnotationView.h

centerOffset

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

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

Availability
  • Available in iOS 3.0 and later.
Related Sample Code
Declared In
MKAnnotationView.h

draggable

A Boolean indicating whether the annotation view is draggable.

@property (nonatomic, getter=isDraggable) BOOL draggable
Discussion

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

Setting this property to YES, 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.

Availability
  • Available in iOS 4.0 and later.
Declared In
MKAnnotationView.h

dragState

The current drag state of the annotation view.

@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 NO.

Availability
  • Available in iOS 4.0 and later.
Declared In
MKAnnotationView.h

enabled

A Boolean value indicating whether the annotation is enabled.

@property (nonatomic, getter=isEnabled) BOOL enabled
Discussion

The default value of this property is YES. If the value of this property is NO, 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.

Availability
  • Available in iOS 3.0 and later.
Declared In
MKAnnotationView.h

highlighted

A Boolean value indicating whether the annotation view is highlighted.

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

Availability
  • Available in iOS 3.0 and later.
Declared In
MKAnnotationView.h

image

The image to be displayed by the annotation view.

@property (nonatomic, retain) 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.

Availability
  • Available in iOS 3.0 and later.
Related Sample Code
Declared In
MKAnnotationView.h

leftCalloutAccessoryView

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

@property (retain, 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.

Availability
  • Available in iOS 3.0 and later.
Declared In
MKAnnotationView.h

reuseIdentifier

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

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

Availability
  • Available in iOS 3.0 and later.
Related Sample Code
Declared In
MKAnnotationView.h

rightCalloutAccessoryView

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

@property (retain, 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.

Availability
  • Available in iOS 3.0 and later.
Related Sample Code
Declared In
MKAnnotationView.h

selected

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

@property (nonatomic, getter=isSelected) BOOL selected
Discussion

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

Availability
  • Available in iOS 3.0 and later.
Declared In
MKAnnotationView.h

Instance Methods

initWithAnnotation:reuseIdentifier:

Initializes and returns a new annotation view.

- (id)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.

Availability
  • Available in iOS 3.0 and later.
Declared In
MKAnnotationView.h

prepareForReuse

Called when the view is removed from the reuse queue.

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

Availability
  • Available in iOS 3.0 and later.
Related Sample Code
Declared In
MKAnnotationView.h

setDragState:animated:

Sets the current drag state for the annotation view.

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

The new drag state for the annotation view.

animated

If YES, 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 NO.

Availability
  • Available in iOS 4.2 and later.
Declared In
MKAnnotationView.h

setSelected:animated:

Sets the selection state of the annotation view.

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

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

animated

Set to YES 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.

Availability
  • Available in iOS 3.0 and later.
See Also
Declared In
MKAnnotationView.h

Constants

MKAnnotationViewDragState

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

typedef enum MKAnnotationViewDragState {
   MKAnnotationViewDragStateNone = 0,
   MKAnnotationViewDragStateStarting,
   MKAnnotationViewDragStateDragging,
   MKAnnotationViewDragStateCanceling,
   MKAnnotationViewDragStateEnding
} MKAnnotationViewDragState;
Constants
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.

Declared in MKAnnotationView.h.

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.

Declared in MKAnnotationView.h.

MKAnnotationViewDragStateDragging

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

Available in iOS 4.0 and later.

Declared in MKAnnotationView.h.

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.

Declared in MKAnnotationView.h.

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.

Declared in MKAnnotationView.h.

Notifications

MKAnnotationCalloutInfoDidChangeNotification

Notifies observers that the title or subtitle information of an annotation object changed. (Deprecated. 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.

Availability
Declared In
MKAnnotationView.h