iOS Developer Library

Developer

MapKit Framework Reference MKMapViewDelegate Protocol Reference

Options
Deployment Target:

On This Page
Language:

MKMapViewDelegate

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.

Inheritance


Not Applicable

Import Statement


Swift

import MapKit

Objective-C

@import MapKit;

Availability


Available in iOS 3.0 and later.
  • Tells the delegate that the region displayed by the map view is about to change.

    Declaration

    Swift

    optional func mapView(_ mapView: MKMapView!, regionWillChangeAnimated animated: Bool)

    Objective-C

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

    Parameters

    mapView

    The map view whose visible region is about to change.

    animated

    If YEStrue, the change to the new region will be animated. If NOfalse, 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.

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    optional func mapView(_ mapView: MKMapView!, regionDidChangeAnimated animated: Bool)

    Objective-C

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

    Parameters

    mapView

    The map view whose visible region changed.

    animated

    If YEStrue, 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.

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    optional func mapViewWillStartLoadingMap(_ mapView: MKMapView!)

    Objective-C

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

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    optional func mapViewDidFinishLoadingMap(_ mapView: MKMapView!)

    Objective-C

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

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    optional func mapViewDidFailLoadingMap(_ mapView: MKMapView!, withError error: NSError!)

    Objective-C

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

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    optional func mapViewWillStartRenderingMap(_ mapView: MKMapView!)

    Objective-C

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

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    optional func mapViewDidFinishRenderingMap(_ mapView: MKMapView!, fullyRendered fullyRendered: Bool)

    Objective-C

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

    Parameters

    mapView

    The map view that was rendering its tiles.

    fullyRendered

    This parameter is set to YEStrue if the map view was able to render all tiles completely or NOfalse 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 NOfalse.

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    optional func mapViewWillStartLocatingUser(_ mapView: MKMapView!)

    Objective-C

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

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    optional func mapViewDidStopLocatingUser(_ mapView: MKMapView!)

    Objective-C

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

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    optional func mapView(_ mapView: MKMapView!, didUpdateUserLocation userLocation: MKUserLocation!)

    Objective-C

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

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    optional func mapView(_ mapView: MKMapView!, didFailToLocateUserWithError error: NSError!)

    Objective-C

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

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 4.0 and later.

  • Tells the delegate that the user tracking mode changed.

    Declaration

    Swift

    optional func mapView(_ mapView: MKMapView!, didChangeUserTrackingMode mode: MKUserTrackingMode, animated animated: Bool)

    Objective-C

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

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 5.0 and later.

  • Returns the view associated with the specified annotation object.

    Declaration

    Swift

    optional func mapView(_ mapView: MKMapView!, viewForAnnotation annotation: MKAnnotation!) -> MKAnnotationView!

    Objective-C

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

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    optional func mapView(_ mapView: MKMapView!, didAddAnnotationViews views: [AnyObject]!)

    Objective-C

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

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    optional func mapView(_ mapView: MKMapView!, annotationView view: MKAnnotationView!, calloutAccessoryControlTapped control: UIControl!)

    Objective-C

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

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    optional func mapView(_ mapView: MKMapView!, didSelectAnnotationView view: MKAnnotationView!)

    Objective-C

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

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    optional func mapView(_ mapView: MKMapView!, didDeselectAnnotationView view: MKAnnotationView!)

    Objective-C

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

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    optional func mapView(_ mapView: MKMapView!, rendererForOverlay overlay: MKOverlay!) -> MKOverlayRenderer!

    Objective-C

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

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    optional func mapView(_ mapView: MKMapView!, didAddOverlayRenderers renderers: [AnyObject]!)

    Objective-C

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

    Import Statement

    Objective-C

    @import MapKit;

    Swift

    import MapKit

    Availability

    Available in iOS 7.0 and later.

  • Asks the delegate for the overlay view to use when displaying the specified overlay object.

    Deprecation Statement

    Implement the mapView:rendererForOverlay: method instead.

    Declaration

    Objective-C

    - (MKOverlayView *)mapView:(MKMapView *)mapView viewForOverlay:(id<MKOverlay>)overlay

    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

    Prior to iOS 7, you would implement this method to provide the views for your overlay objects.

    Import Statement

    Objective-C

    @import MapKit;

    Availability

    Available in iOS 4.0 and later.

    Deprecated in iOS 7.0.

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

    Deprecation Statement

    Implement the mapView:didAddOverlayRenderers: method instead.

    Declaration

    Objective-C

    - (void)mapView:(MKMapView *)mapView didAddOverlayViews:(NSArray *)overlayViews

    Parameters

    mapView

    The map view that added the overlay views.

    overlayViews

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

    Discussion

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

    Import Statement

    Objective-C

    @import MapKit;

    Availability

    Available in iOS 4.0 and later.

    Deprecated in iOS 7.0.