MKMapViewDelegate Protocol Reference

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

Overview

The MKMapViewDelegate protocol defines a set of optional methods that you can use to receive map-related update messages. Because many map operations require the MKMapView class to load data asynchronously, the map view calls these methods to notify your application when specific operations complete. The map view also uses these methods to request annotation and overlay views and to manage interactions with those views.

Before releasing an MKMapView object for which you have set a delegate, remember to set that object’s delegate property to nil.

Tasks

Responding to Map Position Changes

Loading the Map Data

Tracking the User Location

Managing Annotation Views

Dragging an Annotation View

Selecting Annotation Views

Managing the Display of Overlays

Instance Methods

mapView:annotationView:calloutAccessoryControlTapped:

Tells the delegate that the user tapped one of the annotation view’s accessory buttons.

- (void)mapView:(MKMapView *)mapView annotationView:(MKAnnotationView *)view calloutAccessoryControlTapped:(UIControl *)control
Parameters
mapView

The map view containing the specified annotation view.

view

The annotation view whose button was tapped.

control

The control that was tapped.

Discussion

Accessory views contain custom content and are positioned on either side of the annotation title text. If a view you specify is a descendant of the UIControl class, the map view calls this method as a convenience whenever the user taps your view. You can use this method to respond to taps and perform any actions associated with that control. For example, if your control displayed additional information about the annotation, you could use this method to present a modal panel with that information.

If your custom accessory views are not descendants of the UIControl class, the map view does not call this method.

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

mapView:annotationView:didChangeDragState:fromOldState:

Tells the delegate that the drag state of one of its annotation views changed.

- (void)mapView:(MKMapView *)mapView annotationView:(MKAnnotationView *)annotationView didChangeDragState:(MKAnnotationViewDragState)newState fromOldState:(MKAnnotationViewDragState)oldState
Parameters
mapView

The map view containing the annotation view.

annotationView

The annotation view whose drag state changed.

newState

The new drag state of the annotation view.

oldState

The previous drag state of the annotation view.

Discussion

The drag state typically changes in response to user interactions with the annotation view. However, the annotation view itself is responsible for changing that state as well.

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

mapView:didAddAnnotationViews:

Tells the delegate that one or more annotation views were added to the map.

- (void)mapView:(MKMapView *)mapView didAddAnnotationViews:(NSArray *)views
Parameters
mapView

The map view that added the annotation views.

views

An array of MKAnnotationView objects representing the views that were added.

Discussion

By the time this method is called, the specified views are already added to the map.

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

mapView:didAddOverlayRenderers:

Tells the delegate that one or more renderer objects were added to the map.

- (void)mapView:(MKMapView *)mapView didAddOverlayRenderers:(NSArray *)renderers
Parameters
mapView

The map view that added the renderer objects.

renderers

The renderer objects that were added.

Discussion

The map view adds renderer objects when it needs them to draw their contents, which might be prior to those contents appearing onscreen. It calls this method to let you know that the renderer is active and in use. By the time this method is called, the specified renderers have already been added to the map.

Availability
  • Available in iOS 7.0 and later.
Declared In
MKMapView.h

mapView:didChangeUserTrackingMode:animated:

Tells the delegate that the user tracking mode changed.

- (void)mapView:(MKMapView *)mapView didChangeUserTrackingMode:(MKUserTrackingMode)mode animated:(BOOL)animated
Parameters
mapView

The map view whose user tracking mode changed.

mode

The mode used to track the user’s location.

animated

If YES, the change from the current mode to the new mode is animated; otherwise, it is not. This parameter affects only tracking mode changes. Changes to the user location or heading are always animated.

Availability
  • Available in iOS 5.0 and later.
Declared In
MKMapView.h

mapView:didDeselectAnnotationView:

Tells the delegate that one of its annotation views was deselected.

- (void)mapView:(MKMapView *)mapView didDeselectAnnotationView:(MKAnnotationView *)view
Parameters
mapView

The map view containing the annotation view.

view

The annotation view that was deselected.

Discussion

You can use this method to track changes in the selection state of annotation views.

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

mapView:didFailToLocateUserWithError:

Tells the delegate that an attempt to locate the user’s position failed.

- (void)mapView:(MKMapView *)mapView didFailToLocateUserWithError:(NSError *)error
Parameters
mapView

The map view that is tracking the user’s location.

error

An error object containing the reason why location tracking failed.

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

mapView:didSelectAnnotationView:

Tells the delegate that one of its annotation views was selected.

- (void)mapView:(MKMapView *)mapView didSelectAnnotationView:(MKAnnotationView *)view
Parameters
mapView

The map view containing the annotation view.

view

The annotation view that was selected.

Discussion

You can use this method to track changes in the selection state of annotation views.

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

mapView:didUpdateUserLocation:

Tells the delegate that the location of the user was updated.

- (void)mapView:(MKMapView *)mapView didUpdateUserLocation:(MKUserLocation *)userLocation
Parameters
mapView

The map view that is tracking the user’s location.

userLocation

The location object representing the user’s latest location. This property may be nil.

Discussion

While the showsUserLocation property is set to YES, this method is called whenever a new location update is received by the map view. This method is also called if the map view’s user tracking mode is set to MKUserTrackingModeFollowWithHeading and the heading changes.

This method is not called if the application is currently running in the background. If you want to receive location updates while running in the background, you must use the Core Location framework.

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

mapView:regionDidChangeAnimated:

Tells the delegate that the region displayed by the map view just changed.

- (void)mapView:(MKMapView *)mapView regionDidChangeAnimated:(BOOL)animated
Parameters
mapView

The map view whose visible region changed.

animated

If YES, the change to the new region was animated.

Discussion

This method is called whenever the currently displayed map region changes. During scrolling, this method may be called many times to report updates to the map position. Therefore, your implementation of this method should be as lightweight as possible to avoid affecting scrolling performance.

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

mapView:regionWillChangeAnimated:

Tells the delegate that the region displayed by the map view is about to change.

- (void)mapView:(MKMapView *)mapView regionWillChangeAnimated:(BOOL)animated
Parameters
mapView

The map view whose visible region is about to change.

animated

If YES, the change to the new region will be animated. If NO, the change will be made immediately.

Discussion

This method is called whenever the currently displayed map region changes. During scrolling, this method may be called many times to report updates to the map position. Therefore, your implementation of this method should be as lightweight as possible to avoid affecting scrolling performance.

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

mapView:rendererForOverlay:

Asks the delegate for a renderer object to use when drawing the specified overlay.

- (MKOverlayRenderer *)mapView:(MKMapView *)mapView rendererForOverlay:(id < MKOverlay >)overlay
Parameters
mapView

The map view that requested the renderer object.

overlay

The overlay object that is about to be displayed.

Return Value

The renderer to use when presenting the specified overlay on the map. If you return nil, no content is drawn for the specified overlay object.

Discussion

You must implement this method and use it to provide an appropriate renderer object for your overlays. The renderer object is responsible for drawing the contents of your overlay when asked to do so by the map view. Map Kit supports many different types of standard renderer objects and you may also define your own custom renderers.

Availability
  • Available in iOS 7.0 and later.
Declared In
MKMapView.h

mapView:viewForAnnotation:

Returns the view associated with the specified annotation object.

- (MKAnnotationView *)mapView:(MKMapView *)mapView viewForAnnotation:(id < MKAnnotation >)annotation
Parameters
mapView

The map view that requested the annotation view.

annotation

The object representing the annotation that is about to be displayed. In addition to your custom annotations, this object could be an MKUserLocation object representing the user’s current location.

Return Value

The annotation view to display for the specified annotation or nil if you want to display a standard annotation view.

Discussion

Rather than create a new view each time this method is called, you should use the dequeueReusableAnnotationViewWithIdentifier: method of the MKMapView class to see if an existing annotation view of the desired type already exists. If one does exist, you should update the view to reflect the attributes of the specified annotation and return it. If a view of the appropriate type does not exist, you should create one, configure it with the needed annotation data, and return it.

If the object in the annotation parameter is an instance of the MKUserLocation class, you can provide a custom view to denote the user’s location. To display the user’s location using the default system view, return nil.

If you do not implement this method, or if you return nil from your implementation for annotations other than the user location annotation, the map view uses a standard pin annotation view.

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

mapViewDidFailLoadingMap:withError:

Tells the delegate that the specified view was unable to load the map data.

- (void)mapViewDidFailLoadingMap:(MKMapView *)mapView withError:(NSError *)error
Parameters
mapView

The map view that started the load operation.

error

The reason that the map data could not be loaded.

Discussion

This method might be called in situations where the device does not have access to the network or is unable to load the map data for some reason. It may also be called if a request for additional map tiles comes in while a previous request for tiles is still pending. You can use this message to notify the user that the map data is unavailable.

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

mapViewDidFinishLoadingMap:

Tells the delegate that the specified map view successfully loaded the needed map data.

- (void)mapViewDidFinishLoadingMap:(MKMapView *)mapView
Parameters
mapView

The map view that started the load operation.

Discussion

This method is called when the map tiles associated with the current request have been loaded. Map tiles are requested when a new visible area is scrolled into view and tiles are not already available. Map tiles may also be requested for portions of the map that are not currently visible. For example, the map view may load tiles immediately surrounding the currently visible area as needed to handle small pans by the user.

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

mapViewDidFinishRenderingMap:fullyRendered:

Tells the delegate that the map view has finished rendering all visible tiles.

- (void)mapViewDidFinishRenderingMap:(MKMapView *)mapView fullyRendered:(BOOL)fullyRendered
Parameters
mapView

The map view that was rendering its tiles.

fullyRendered

This parameter is set to YES if the map view was able to render all tiles completely or NO if errors prevented all tiles from being rendered.

Discussion

This method lets you know when the map view finishes rendering all of the currently visible tiles to the best of its ability. This method is called regardless of whether all tiles were rendered successfully. If there were errors loading one or more tiles that prevented map view from rendering them, the fullyRendered parameter is set to NO.

Availability
  • Available in iOS 7.0 and later.
Declared In
MKMapView.h

mapViewDidStopLocatingUser:

Tells the delegate that the map view stopped tracking the user’s location.

- (void)mapViewDidStopLocatingUser:(MKMapView *)mapView
Parameters
mapView

The map view that stopped tracking the user’s location.

Discussion

This method is called when the value of the showsUserLocation property changes to NO.

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

mapViewWillStartLoadingMap:

Tells the delegate that the specified map view is about to retrieve some map data.

- (void)mapViewWillStartLoadingMap:(MKMapView *)mapView
Parameters
mapView

The map view that began loading the data.

Discussion

This method is called whenever a new group of map tiles need to be downloaded from the server. This typically occurs whenever you expose portions of the map by panning or zooming the content. You can use this method to mark the time that it takes for the map view to load the data.

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

mapViewWillStartLocatingUser:

Tells the delegate that the map view will start tracking the user’s position.

- (void)mapViewWillStartLocatingUser:(MKMapView *)mapView
Parameters
mapView

The map view that is tracking the user’s location.

Discussion

This method is called when the value of the showsUserLocation property changes to YES.

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

mapViewWillStartRenderingMap:

Tells the delegate that the map view is about to start rendering some of its tiles.

- (void)mapViewWillStartRenderingMap:(MKMapView *)mapView
Parameters
mapView

The map view that is about to start rendering.

Discussion

The map view calls this method when one or more tiles are revealed and require rendering.

Availability
  • Available in iOS 7.0 and later.
Declared In
MKMapView.h