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 |
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. One place you can do this is in the dealloc method where you dispose of the map view.
Tasks
Responding to Map Position Changes
Loading the Map Data
Tracking the User Location
-
– mapViewWillStartLocatingUser: -
– mapViewDidStopLocatingUser: -
– mapView:didUpdateUserLocation: -
– mapView:didFailToLocateUserWithError: -
– mapView:didChangeUserTrackingMode:animated:required method
Managing Annotation Views
-
– mapView:viewForAnnotation: -
– mapView:didAddAnnotationViews: -
– mapView:annotationView:calloutAccessoryControlTapped:
Dragging an Annotation View
Selecting Annotation Views
Managing Overlay Views
Instance Methods
mapView:annotationView:calloutAccessoryControlTapped:
Tells the delegate that the user tapped one of the annotation view’s accessory buttons.
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.hmapView:annotationView:didChangeDragState:fromOldState:
Tells the delegate that the drag state of one of its annotation views changed.
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.hmapView:didAddAnnotationViews:
Tells the delegate that one or more annotation views were added to the map.
Parameters
- mapView
The map view that added the annotation views.
- views
An array of
MKAnnotationViewobjects 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.hmapView:didAddOverlayViews:
Tells the delegate that one or more overlay views were added to the map.
Parameters
- mapView
The map view that added the overlay views.
- overlayViews
An array of
MKOverlayViewobjects 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 4.0 and later.
Declared In
MKMapView.hmapView:didChangeUserTrackingMode:animated:
Tells the delegate that the user tracking mode changed. (required)
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.hmapView:didDeselectAnnotationView:
Tells the delegate that one of its annotation views was deselected.
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.hmapView:didFailToLocateUserWithError:
Tells the delegate that an attempt to locate the user’s position failed.
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.hmapView:didSelectAnnotationView:
Tells the delegate that one of its annotation views was selected.
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.hmapView:didUpdateUserLocation:
Tells the delegate that the location of the user was updated.
Parameters
- mapView
The map view that is tracking the user’s location.
- userLocation
The location object representing the user’s latest location.
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.hmapView:regionDidChangeAnimated:
Tells the delegate that the region displayed by the map view just changed.
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.hmapView:regionWillChangeAnimated:
Tells the delegate that the region displayed by the map view is about to change.
Parameters
- mapView
The map view whose visible region is about to change.
- animated
If
YES, the change to the new region will be animated. IfNO, 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.hmapView:viewForAnnotation:
Returns the view associated with the specified annotation object.
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
MKUserLocationobject 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.hmapView:viewForOverlay:
Asks the delegate for the overlay view to use when displaying the specified overlay object.
Parameters
- mapView
The map view that requested the overlay view.
- overlay
The object representing the overlay that is about to be displayed.
Return Value
The view to use when presenting the specified overlay on the map. If you return nil, no view is displayed for the specified overlay object.
Discussion
If you support the presentation of overlays, you must implement this method and provide the views for your overlay objects.
Availability
- Available in iOS 4.0 and later.
Declared In
MKMapView.hmapViewDidFailLoadingMap:withError:
Tells the delegate that the specified view was unable to load the map data.
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.hmapViewDidFinishLoadingMap:
Tells the delegate that the specified map view successfully loaded the needed map data.
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.hmapViewDidStopLocatingUser:
Tells the delegate that the map view stopped tracking the user’s location.
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.hmapViewWillStartLoadingMap:
Tells the delegate that the specified map view is about to retrieve some map data.
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.hmapViewWillStartLocatingUser:
Tells the delegate that the map view will start tracking the user’s position.
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© 2011 Apple Inc. All Rights Reserved. (Last updated: 2011-10-12)