MKMapView Class

MKMapView Class Reference

Contents

MKMapView Class Reference 5Overview 5

Annotating the Map 6Adding Overlays to the Map 7

Tasks 8Accessing Map Properties 8Accessing the Delegate 8Manipulating the Visible Portion of the Map 8Configuring the Map’s Appearance 9Displaying the User’s Location 9Annotating the Map 10Managing Annotation Selections 10Accessing Overlays 10Adding and Inserting Overlays 11Removing Overlays 12Converting Map Coordinates 12Adjusting Map Regions and Rectangles 12

Properties 12annotations 12annotationVisibleRect 13camera 13centerCoordinate 14delegate 14mapType 15overlays 15pitchEnabled 16region 16rotateEnabled 17scrollEnabled 18selectedAnnotations 18showsBuildings 18showsPointsOfInterest 19showsUserLocation 19userLocation 20

2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved.

2

userLocationVisible 20userTrackingMode 21visibleMapRect 21zoomEnabled 22

Instance Methods 22addAnnotation: 22addAnnotations: 23addOverlay: 23addOverlay:level: 24addOverlays: 25addOverlays:level: 26annotationsInMapRect: 26convertCoordinate:toPointToView: 27convertPoint:toCoordinateFromView: 28convertRect:toRegionFromView: 28convertRegion:toRectToView: 29dequeueReusableAnnotationViewWithIdentifier: 30deselectAnnotation:animated: 30exchangeOverlay:withOverlay: 31exchangeOverlayAtIndex:withOverlayAtIndex: 31insertOverlay:aboveOverlay: 32insertOverlay:atIndex: 33insertOverlay:atIndex:level: 33insertOverlay:belowOverlay: 34mapRectThatFits: 35mapRectThatFits:edgePadding: 35overlaysInLevel: 36regionThatFits: 37removeAnnotation: 37removeAnnotations: 38removeOverlay: 39removeOverlays: 39rendererForOverlay: 40selectAnnotation:animated: 40setCamera:animated: 41setCenterCoordinate:animated: 41setRegion:animated: 42setUserTrackingMode:animated: 43setVisibleMapRect:animated: 44


3

Contents

setVisibleMapRect:edgePadding:animated: 44showAnnotations:animated: 45viewForAnnotation: 46

Constants 46MKMapType 46MKUserTrackingMode 47MKOverlayLevel 47

Deprecated MKMapView Methods 49Deprecated in iOS 7.0 49

viewForOverlay: 49

Document Revision History 50


4

Contents

Inherits from UIView : UIResponder : NSObject

Conforms to NSCoding

NSCoding (UIView)

UIAppearance (UIView)

UIAppearanceContainer (UIView)

UIDynamicItem (UIView)

NSObject (NSObject)

Framework /System/Library/Frameworks/MapKit.framework

Availability Available in iOS 3.0 and later.

Companion guide Location and Maps Programming Guide

Declared in MKMapView.h

MKTypes.h

Related sample code Breadcrumb

KMLViewer

MapCallouts

PhotosByLocation

Regions

OverviewAn MKMapView object provides an embeddable map interface, similar to the one provided by the Mapsapplication. You use this class as-is to display map information and to manipulate the map contents from yourapplication. You can center the map on a given coordinate, specify the size of the area you want to display,and annotate the map with custom information.


5

MKMapView Class Reference

Important: In iOS 5.1 and earlier, the Map Kit framework uses the Google Mobile Maps (GMM) service toprovide map data. Use of specific classes of this framework (and their associated interfaces) is subject tothe Google Mobile Maps terms of service. You can find these terms of service athttp://code.google.com/apis/maps/iphone/terms.html.

When you initialize a map view, you should specify the initial region for that map to display. You do this bysetting the region (page 16) property of the map. A region is defined by a center point and a horizontal andvertical distance, referred to as the span. The span defines how much of the map at the given point should bevisible and is also how you set the zoom level. Specifying a large span results in the user seeing a widegeographical area and corresponds to a low zoom level. Specifying a small span results in the user seeing amore narrow geographical area and corresponds to a higher zoom level.

In addition to setting the span programmatically, the MKMapView class supports many standard interactionsfor changing the position and zoom level of the map. In particular, map views support flick and pinch gesturesfor scrolling around the map and zooming in and out. Support for these gestures is enabled by default butcan also be disabled using the scrollEnabled (page 18) and zoomEnabled (page 22) properties.

You can also use projected map coordinates instead of regions to specify some values. When you project thecurved surface of the globe onto a flat surface, you get a two-dimensional version of a map where longitudelines appear to be parallel. To specify locations and distances, you use the MKMapPoint, MKMapSize, andMKMapRect data types.

Although you should not subclass the MKMapView class itself, you can get information about the map view’sbehavior by providing a delegate object. The map view calls the methods of your custom delegate to let itknow about changes in the map status and to coordinate the display of custom annotations, which are describedin more detail in “Annotating the Map” (page 6). The delegate object can be any object in your applicationas long as it conforms to the MKMapViewDelegate protocol. For more information about implementing thedelegate object, see MKMapViewDelegate Protocol Reference .

Annotating the MapThe MKMapView class supports the ability to annotate the map with custom information. Because a map mayhave potentially large numbers of annotations, map views differentiate between the annotation objects usedto manage the annotation data and the view objects for presenting that data on the map.

An annotation object is any object that conforms to the MKAnnotation protocol. Annotation objects aretypically implemented using existing classes in your application’s data model. This allows you to manipulatethe annotation data directly but still make it available to the map view. Each annotation object containsinformation about the annotation’s location on the map along with descriptive information that can be displayedin a callout.

MKMapView Class ReferenceOverview


6

http://code.google.com/apis/maps/iphone/terms.html

The presentation of annotation objects on the screen is handled by an annotation view, which is an instanceof the MKAnnotationView class. An annotation view is responsible for presenting the annotation data in away that makes sense. For example, the Maps application uses a pin icon to denote specific points of intereston a map. (The Map Kit framework offers the MKPinAnnotationView class for similar annotations in yourown applications.) You could also create annotation views that cover larger portions of the map.

Because annotation views are needed only when they are onscreen, the MKMapView class provides a mechanismfor queueing annotation views that are not in use. Annotation views with a reuse identifier can be detachedand queued internally by the map view when they move offscreen. This feature improves memory use bykeeping only a small number of annotation views in memory at once and by recycling the views you do have.It also improves scrolling performance by alleviating the need to create new views while the map is scrolling.

When configuring your map interface, you should add all of your annotation objects right away. The map viewuses the coordinate data in each annotation object to determine when the corresponding annotation viewneeds to appear onscreen. When an annotation moves onscreen, the map view asks its delegate to create acorresponding annotation view. If your application has different types of annotations, it can define differentannotation view classes to represent each type.

Adding Overlays to the MapYou can use overlays to layer content over a wide portion of the map. An overlay object is any object thatconforms to the MKOverlay protocol. An overlay object is a data object that contains the points needed tospecify the shape and size of the overlay and its location on the map. Overlays can represent shapes such ascircles, rectangles, multi-segment lines, and simple or complex polygons. You can also define your own customoverlays to represent other shapes.

In iOS 7 and later, the presentation of an overlay is handled by an overlay renderer object, which is an instanceof the MKOverlayRenderer class. The job of the renderer is to draw the overlay’s content onto the screenwhen asked to do so by the map view. For example, if you have a simple overlay that represents a bus route,you could use a polyline renderer to draw the line segments that trace the route of the bus. You could alsodefine a custom renderer that draws both the bus route and icons at the location of each bus stop. Whenspecifying overlays, you can add them to specific levels of the map, which allows them to be rendered aboveor below other types of map content. Prior to iOS 7, overlays are drawn on onscreen using overlay views, whichare instances of the MKOverlayView class.

When configuring your map interface, you can add overlay objects at any time. The map view uses the datain each overlay object to determine when the corresponding overlay view needs to appear onscreen. Whenan overlay moves onscreen, the map view asks its delegate to create a corresponding overlay renderer.

MKMapView Class ReferenceOverview


7

Tasks

Accessing Map Properties

mapType (page 15) propertyThe type of data displayed by the map view.

zoomEnabled (page 22) propertyA Boolean value that determines whether the user may use pinch gestures to zoom in and out of themap.

scrollEnabled (page 18) propertyA Boolean value that determines whether the user may scroll around the map.

pitchEnabled (page 16) propertyA Boolean value indicating whether the map camera’s pitch information is used.

rotateEnabled (page 17) propertyA Boolean value indicating whether the map camera’s heading information is used.

Accessing the Delegate

delegate (page 14) propertyThe receiver’s delegate.

Manipulating the Visible Portion of the Map

region (page 16) propertyThe area currently displayed by the map view.

– setRegion:animated: (page 42)Changes the currently visible region and optionally animates the change.

centerCoordinate (page 14) propertyThe map coordinate at the center of the map view.

– setCenterCoordinate:animated: (page 41)Changes the center coordinate of the map and optionally animates the change.

– showAnnotations:animated: (page 45)Sets the visible region so that the map displays the specified annotations.

MKMapView Class ReferenceTasks


8

visibleMapRect (page 21) propertyThe area currently displayed by the map view.

– setVisibleMapRect:animated: (page 44)Changes the currently visible portion of the map and optionally animates the change.

– setVisibleMapRect:edgePadding:animated: (page 44)Changes the currently visible portion of the map, allowing you to specify additional space around theedges.

Configuring the Map’s Appearance

camera (page 13) propertyThe camera used for determining the appearance of the map.

– setCamera:animated: (page 41)Changes the camera used for determining the map’s viewing parameters and optionally animates thechange.

showsPointsOfInterest (page 19) propertyA Boolean indicating whether the map displays point-of-interest information.

showsBuildings (page 18) propertyA Boolean indicating whether the map displays extruded building information.

Displaying the User’s Location

showsUserLocation (page 19) propertyA Boolean value indicating whether the map should try to display the user’s location.

userLocationVisible (page 20) propertyA Boolean value indicating whether the device’s current location is visible in the map view. (read-only)

userLocation (page 20) propertyThe annotation object representing the user’s current location. (read-only)

userTrackingMode (page 21) propertyThe mode used to track the user location.

– setUserTrackingMode:animated: (page 43)Sets the mode used to track the user location with optional animation.



9

Annotating the Map

annotations (page 12) propertyThe complete list of annotations associated with the receiver. (read-only)

– addAnnotation: (page 22)Adds the specified annotation to the map view.

– addAnnotations: (page 23)Adds an array of annotation objects to the map view.

– removeAnnotation: (page 37)Removes the specified annotation object from the map view.

– removeAnnotations: (page 38)Removes an array of annotation objects from the map view.

– viewForAnnotation: (page 46)Returns the annotation view associated with the specified annotation object, if any.

– annotationsInMapRect: (page 26)Returns the annotation objects located in the specified map rectangle.

annotationVisibleRect (page 13) propertyThe visible rectangle where annotation views are currently being displayed. (read-only)

– dequeueReusableAnnotationViewWithIdentifier: (page 30)Returns a reusable annotation view located by its identifier.

Managing Annotation Selections

selectedAnnotations (page 18) propertyThe annotations that are currently selected.

– selectAnnotation:animated: (page 40)Selects the specified annotation and displays a callout view for it.

– deselectAnnotation:animated: (page 30)Deselects the specified annotation and hides its callout view.

Accessing Overlays

overlays (page 15) propertyThe overlay objects currently associated with the map view. (read-only)



10

– overlaysInLevel: (page 36)The overlay objects in the specified level of the map.

– rendererForOverlay: (page 40)Returns the renderer object used to draw the contents of the specified overlay object.

– viewForOverlay: (page 49) Deprecated in iOS 7.0Returns the view associated with the overlay object if any. (Deprecated. Use therendererForOverlay: (page 40) method instead.)

Adding and Inserting Overlays

– addOverlay:level: (page 24)Adds the overlay object to the map at the specified level.

– addOverlays:level: (page 26)Adds an array of overlay objects to the map at the specified level.

– addOverlay: (page 23)Adds a single overlay object to the map.

– addOverlays: (page 25)Adds an array of overlay objects to the map.

– insertOverlay:atIndex:level: (page 33)Inserts an overlay object into the level at the specified index.

– insertOverlay:atIndex: (page 33)Inserts an overlay object into the list associated with the map.

– insertOverlay:aboveOverlay: (page 32)Inserts one overlay object on top of another.

– insertOverlay:belowOverlay: (page 34)Inserts one overlay object below another.

– exchangeOverlay:withOverlay: (page 31)Exchanges the positions of the two overlay objects.

– exchangeOverlayAtIndex:withOverlayAtIndex: (page 31)Exchanges the position of two overlay objects.



11

Removing Overlays

– removeOverlay: (page 39)Removes a single overlay object from the map.

– removeOverlays: (page 39)Removes one or more overlay objects from the map.

Converting Map Coordinates

– convertCoordinate:toPointToView: (page 27)Converts a map coordinate to a point in the specified view.

– convertPoint:toCoordinateFromView: (page 28)Converts a point in the specified view’s coordinate system to a map coordinate.

– convertRegion:toRectToView: (page 29)Converts a map region to a rectangle in the specified view.

– convertRect:toRegionFromView: (page 28)Converts a rectangle in the specified view’s coordinate system to a map region.

Adjusting Map Regions and Rectangles

– regionThatFits: (page 37)Adjusts the aspect ratio of the specified region to ensure that it fits in the map view’s frame.

– mapRectThatFits: (page 35)Adjusts the aspect ratio of the specified map rectangle to ensure that it fits in the map view’s frame.

– mapRectThatFits:edgePadding: (page 35)Adjusts the aspect ratio of the specified map rectangle, incorporating the specified inset values.

Properties

annotations

The complete list of annotations associated with the receiver. (read-only)

MKMapView Class ReferenceProperties


12

@property(nonatomic, readonly) NSArray *annotations

DiscussionThe objects in this array must adopt the MKAnnotation protocol. If no annotations are associated with themap view, the value of this property is nil.

AvailabilityAvailable in iOS 3.0 and later.

See Also– addAnnotation: (page 22)– addAnnotations: (page 23)– removeAnnotation: (page 37)– removeAnnotations: (page 38)

Declared inMKMapView.h

annotationVisibleRect

The visible rectangle where annotation views are currently being displayed. (read-only)

@property(nonatomic, readonly) CGRect annotationVisibleRect



camera

The camera used for determining the appearance of the map.

@property(nonatomic, copy) MKMapCamera *camera

DiscussionA camera object defines a point above the map’s surface from which to view the map. Applying a camera toa map has the effect of giving the map a 3D-like appearance. You can use a camera to rotate the map so thatit is oriented to match the user’s heading or to apply a pitch angle to tilt the plane of the map.

Assigning a new camera to this property updates the map immediately and without animating the change. Ifyou want to animate changes in camera position, use the setCamera:animated: (page 41) method instead.



13

You must not set this property to nil. To restore the map to a flat appearance, apply a camera with a pitchangle of 0, which yields a camera looking straight down onto the map surface.


See Also– setCamera:animated: (page 41)


centerCoordinate

The map coordinate at the center of the map view.

@property(nonatomic) CLLocationCoordinate2D centerCoordinate

DiscussionChanging the value in this property centers the map on the new coordinate without changing the currentzoom level. It also updates the values in the region property to reflect the new center coordinate and thenew span values needed to maintain the current zoom level.

Changing the value of this property updates the map view immediately. If you want to animate the change,use the setCenterCoordinate:animated: method instead.


See Also– setCenterCoordinate:animated: (page 41) @property region (page 16)

Related Sample CodeRegions


delegate

The receiver’s delegate.



14

@property(nonatomic, assign) id<MKMapViewDelegate> delegate

DiscussionA map view sends messages to its delegate regarding the loading of map data and changes in the portion ofthe map being displayed. The delegate also manages the annotation views used to highlight points of intereston the map.

The delegate should implement the methods of the MKMapViewDelegate protocol.



mapType

The type of data displayed by the map view.

@property(nonatomic) MKMapType mapType

DiscussionChanging the value in this property may cause the receiver to begin loading new map content. For example,changing from MKMapTypeStandard to MKMapTypeSatellite might cause it to begin loading the satelliteimagery needed for the map. If new data is needed, however, it is loaded asynchronously and appropriatemessages are sent to the receiver’s delegate indicating the status of the operation.


Related Sample CodeGeocoderDemo


overlays

The overlay objects currently associated with the map view. (read-only)



15

@property(nonatomic, readonly) NSArray *overlays

DiscussionThis property contains the union of all overlays at the different levels of the map. The objects in this array mustadopt the MKOverlay protocol. If no overlays are associated with the map view, the value of this property isan empty array.

The order of the objects in this array does not necessary reflect their visual order on the map.



pitchEnabled

A Boolean value indicating whether the map camera’s pitch information is used.

@property(nonatomic, getter=isPitchEnabled) BOOL pitchEnabled

DiscussionWhen this property is set to YES and a valid camera is associated with the map, the camera’s pitch angle isused to tilt the plane of the map. When this property is set to NO, the camera’s pitch angle is ignored and themap is always displayed as if the user is looking straight down onto it.



region

The area currently displayed by the map view.

@property(nonatomic) MKCoordinateRegion region

DiscussionThe region encompasses both the latitude and longitude point on which the map is centered and the span ofcoordinates to display. The span values provide an implicit zoom value for the map. The larger the displayedarea, the lower the amount of zoom. Similarly, the smaller the displayed area, the greater the amount of zoom.



16

Changing only the center coordinate of the region can still cause the span to change implicitly. The span mightchange because the distances represented by a span change at different latitudes and longitudes and the mapview may need to adjust the span to account for the new location. If you want to change the center coordinatewithout changing the zoom level, use the centerCoordinate instead.

Changing the value of this property updates the map view immediately. When setting this property, the mapmay adjust the new region value so that it fits the visible area of the map precisely. This is normal and is doneto ensure that the value in this property always reflects the visible portion of the map. However, it does meanthat if you get the value of this property right after setting it, the returned value may not match the value youset. (You can use the regionThatFits: (page 37) method to determine the region that will actually be set bythe map.)

If you want to animate the change in region, use the setRegion:animated: method instead.


See Also– setRegion:animated: (page 42) @property centerCoordinate (page 14)


rotateEnabled

A Boolean value indicating whether the map camera’s heading information is used.

@property(nonatomic, getter=isRotateEnabled) BOOL rotateEnabled

DiscussionWhen this property is set to YES and a valid camera is associated with the map, the camera’s heading angleis used to rotate the plane of the map around its center point. When this property is set to NO, the camera’sheading angle is ignored and the map is always oriented so that true north is situated at the top of the mapview.





17

scrollEnabled

A Boolean value that determines whether the user may scroll around the map.

@property(nonatomic, getter=isScrollEnabled) BOOL scrollEnabled

DiscussionThis property controls only user interactions with the map. If you set the value of this property to NO, you maystill change the map location programmatically by changing the value in the region property.

The default value of this property is YES.



selectedAnnotations

The annotations that are currently selected.

@property(nonatomic, copy) NSArray *selectedAnnotations

DiscussionAssigning a new array to this property selects only the first annotation in the array.



showsBuildings

A Boolean indicating whether the map displays extruded building information.



18

@property (nonatomic) BOOL showsBuildings;

DiscussionWhen this property is set to YES and the camera has a pitch angle greater than zero, the map extrudes buildingsso that they extend above the map plane, creating a 3D effect. The mapType (page 15) property must be setto MKMapTypeStandard (page 46) for extruded buildings to be displayed. The default value of this property isYES.



showsPointsOfInterest

A Boolean indicating whether the map displays point-of-interest information.

@property (nonatomic) BOOL showsPointsOfInterest;

DiscussionWhen this property is set to YES, the map displays icons and labels for restaurants, schools, and other relevantpoints of interest. The default value of this property is YES.



showsUserLocation

A Boolean value indicating whether the map should try to display the user’s location.

@property(nonatomic) BOOL showsUserLocation

DiscussionThis property does not indicate whether the user’s position is actually visible on the map, only whether themap view should try to display it. Setting this property to YES causes the map view to use the Core Locationframework to find the current location and try to display it on the map. As long as this property is YES, themap view continues to track the user’s location and update it periodically. The default value of this propertyis NO.



19

Showing the user’s location does not guarantee that the location is visible on the map. The user might havescrolled the map to a different point, causing the current location to be offscreen. To determine whether theuser’s current location is currently displayed on the map, use the userLocationVisible property.


See Also @property userLocationVisible (page 20)


userLocation

The annotation object representing the user’s current location. (read-only)

@property(nonatomic, readonly) MKUserLocation *userLocation


See Also @property showsUserLocation (page 19)


userLocationVisible

A Boolean value indicating whether the device’s current location is visible in the map view. (read-only)

@property(nonatomic, readonly, getter=isUserLocationVisible) BOOL userLocationVisible

DiscussionThis property tells you whether the icon used to represent the user’s current location is visible in the map view.When determining whether the current location is visible, this property factors in the horizontal accuracy ofthe location data. Specifically, if the rectangle represented by the user’s current location plus or minus minusthe horizontal accuracy of that location intersects the map’s visible rectangle, this property contains the valueYES. If that location rectangle does not intersect the map’s visible rectangle, this property contains the valueNO.



20

If the user’s location cannot be determined, this property contains the value NO.



userTrackingMode

The mode used to track the user location.

@property(nonatomic) MKUserTrackingMode userTrackingMode

DiscussionPossible values are described in “MKUserTrackingMode” (page 47).

Setting the tracking mode to MKUserTrackingModeFollow (page 47) orMKUserTrackingModeFollowWithHeading (page 47) causes the map view to center the map on that locationand begin tracking the user’s location. If the map is zoomed out, the map view automatically zooms in on theuser’s location, effectively changing the current visible region.


See Also– setUserTrackingMode:animated: (page 43)


visibleMapRect

The area currently displayed by the map view.

@property(nonatomic) MKMapRect visibleMapRect

DiscussionThis property represents the same basic information as the region (page 16) property but specified as a maprectangle instead of a region.

Changing the value of this property updates the map view immediately. If you want to animate the change,use the setVisibleMapRect:animated: method instead.



21


Related Sample CodeKMLViewerPhotosByLocation


zoomEnabled

A Boolean value that determines whether the user may use pinch gestures to zoom in and out of the map.

@property(nonatomic, getter=isZoomEnabled) BOOL zoomEnabled

DiscussionThis property controls only user interactions with the map. If you set the value of this property to NO, you maystill change the zoom level programmatically by changing the value in the region property.

The default value of this property is YES.



Instance Methods

addAnnotation:

Adds the specified annotation to the map view.

- (void)addAnnotation:(id < MKAnnotation >)annotation

Parametersannotation

The annotation object to add to the receiver. This object must conform to the MKAnnotation protocol.The map view retains the specified object.

MKMapView Class ReferenceInstance Methods


22


See Also– addAnnotations: (page 23)– removeAnnotation: (page 37)

Related Sample CodeGeocoderDemoRegions


addAnnotations:

Adds an array of annotation objects to the map view.

- (void)addAnnotations:(NSArray *)annotations

Parametersannotations

An array of annotation objects. Each object in the array must conform to the MKAnnotation protocol.The map view retains the individual annotation objects.


See Also– addAnnotation: (page 22)– removeAnnotations: (page 38)


addOverlay:

Adds a single overlay object to the map.

- (void)addOverlay:(id < MKOverlay >)overlay



23

Parametersoverlay

The overlay object to add. This object must conform to the MKOverlay protocol.

DiscussionThe specified object is added to the group of overlay objects in the MKOverlayLevelAboveLabels (page 48)level. Adding an overlay causes the map view to begin monitoring the area represented by that overlay. Assoon as the bounding rectangle of an overlay intersects the visible portion of the map, the map view adds acorresponding overlay view to the map. The overlay view is provided by the mapView:viewForOverlay:method of the map view’s delegate object.

To remove an overlay from a map, use the removeOverlay: (page 39) method.


See Also– addOverlays: (page 25)– removeOverlay: (page 39)– removeOverlays: (page 39)



addOverlay:level:

Adds the overlay object to the map at the specified level.

- (void)addOverlay:(id < MKOverlay >)overlay level:(MKOverlayLevel)level

Parametersoverlay

The overlay object to add. This object must conform to the MKOverlay protocol.

levelThe map level at which to place the overlay. For a list of possible values for this parameter, see“MKOverlayLevel” (page 47).



24

DiscussionPositioning an overlay at a specific level places that overlay’s visual representation in front of or behind othermap content such as map labels and point-of-interest icons.

This method adds the specified overlay to the end of the list of overlay objects at the given level. Adding anoverlay also causes the map view to begin monitoring the area they represent. As soon as the boundingrectangle of the overlay intersects the visible portion of the map, the map view calls your delegate’smapView:rendererForOverlay: method to get the renderer object to use when drawing the overlay.

To remove an overlay from a map, use the removeOverlay: (page 39) method.



addOverlays:

Adds an array of overlay objects to the map.

- (void)addOverlays:(NSArray *)overlays

Parametersoverlays

An array of objects, each of which must conform to the MKOverlay protocol.

DiscussionThe specified objects are added to the group of overlay objects in the MKOverlayLevelAboveLabels (page48) level. Adding an overlay causes the map view to begin monitoring the area represented by that overlay.As soon as the bounding rectangle of the overlay intersects the visible portion of the map, the map view triesto draw the overlay. As soon as the bounding rectangle of an overlay intersects the visible portion of the map,the map view adds a corresponding overlay view to the map. The overlay view is provided by themapView:viewForOverlay: method of the map view’s delegate object.

To remove multiple overlays from a map, use the removeOverlays: (page 39) method.


See Also– addOverlay: (page 23)– removeOverlay: (page 39)



25

– removeOverlays: (page 39)


addOverlays:level:

Adds an array of overlay objects to the map at the specified level.

- (void)addOverlays:(NSArray *)overlays level:(MKOverlayLevel)level

Parametersoverlays

The array of overlay objects to add. Each object in the array must conform to the MKOverlay protocol.

levelThe map level at which to place the overlays. For a list of possible values for this parameter, see“MKOverlayLevel” (page 47).

DiscussionPositioning an overlay at a specific level places that overlay’s visual representation in front of or behind othermap content such as map labels and point-of-interest icons.

This method adds the specified overlays to the end of the list of overlay objects at the given level. Adding theoverlays also causes the map view to begin monitoring the area they represent. As soon as the boundingrectangle of an overlay intersects the visible portion of the map, the map view calls your delegate’smapView:rendererForOverlay: method to get the renderer object to use when drawing that overlay.

To remove multiple overlays from a map, use the removeOverlays: (page 39) method.



annotationsInMapRect:

Returns the annotation objects located in the specified map rectangle.

- (NSSet *)annotationsInMapRect:(MKMapRect)mapRect



26

ParametersmapRect

The portion of the map that you want to search for annotations.

Return ValueThe set of annotation objects located in mapRect.

DiscussionThis method offers a fast way to retrieve the annotation objects in a particular portion of the map. This methodis much faster than doing a linear search of the objects in the annotations (page 12) property yourself.

Special ConsiderationsPrior to iOS 7 this method incorrectly did not return instances of MKUserLocation.



convertCoordinate:toPointToView:

Converts a map coordinate to a point in the specified view.

- (CGPoint)convertCoordinate:(CLLocationCoordinate2D)coordinate toPointToView:(UIView*)view

Parameterscoordinate

The map coordinate for which you want to find the corresponding point.

viewThe view in whose coordinate system you want to locate the specified map coordinate. If this parameteris nil, the returned point is specified in the window’s coordinate system. If view is not nil, it mustbelong to the same window as the map view.

Return ValueThe point (in the appropriate view or window coordinate system) corresponding to the specified latitude andlongitude value.




27

See Also– convertPoint:toCoordinateFromView: (page 28)


convertPoint:toCoordinateFromView:

Converts a point in the specified view’s coordinate system to a map coordinate.

- (CLLocationCoordinate2D)convertPoint:(CGPoint)point toCoordinateFromView:(UIView*)view

Parameterspoint

The point you want to convert.

viewThe view that serves as the reference coordinate system for the point parameter.

Return ValueThe map coordinate at the specified point.


See Also– convertCoordinate:toPointToView: (page 27)


convertRect:toRegionFromView:

Converts a rectangle in the specified view’s coordinate system to a map region.

- (MKCoordinateRegion)convertRect:(CGRect)rect toRegionFromView:(UIView *)view

Parametersrect

The rectangle you want to convert.



28

viewThe view that serves as the reference coordinate system for the rect parameter.

Return ValueThe map region corresponding to the specified view rectangle.


See Also– convertRegion:toRectToView: (page 29)


convertRegion:toRectToView:

Converts a map region to a rectangle in the specified view.

- (CGRect)convertRegion:(MKCoordinateRegion)region toRectToView:(UIView *)view

Parametersregion

The map region for which you want to find the corresponding view rectangle.

viewThe view in whose coordinate system you want to locate the specified map region. If this parameter isnil, the returned rectangle is specified in the window’s coordinate system. If view is not nil, it mustbelong to the same window as the map view.

Return ValueThe rectangle corresponding to the specified map region.


See Also– convertRect:toRegionFromView: (page 28)




29

dequeueReusableAnnotationViewWithIdentifier:

Returns a reusable annotation view located by its identifier.

- (MKAnnotationView *)dequeueReusableAnnotationViewWithIdentifier:(NSString*)identifier

Parametersidentifier

A string identifying the annotation view to be reused. This string is the same one you specify wheninitializing the annotation view using the initWithAnnotation:reuseIdentifier: method.

Return ValueAn annotation view with the specified identifier, or nil if no such object exists in the reuse queue.

DiscussionFor performance reasons, you should generally reuse MKAnnotationView objects in your map views. Asannotation views move offscreen, the map view moves them to an internally managed reuse queue. As newannotations move onscreen, and your code is prompted to provide a corresponding annotation view, youshould always attempt to dequeue an existing view before creating a new one. Dequeueing saves time andmemory during performance-critical operations such as scrolling.



deselectAnnotation:animated:

Deselects the specified annotation and hides its callout view.

- (void)deselectAnnotation:(id < MKAnnotation >)annotation animated:(BOOL)animated


The annotation object to deselect.

animatedIf YES, the callout view is animated offscreen.




30


exchangeOverlay:withOverlay:

Exchanges the positions of the two overlay objects.

- (void)exchangeOverlay:(id < MKOverlay >)overlay1 withOverlay:(id < MKOverlay>)overlay2

Parametersoverlay1

The first overlay object.

overlay2The second overlay object.

DiscussionIf the overlays are in the same map level, they exchange positions within that level’s array of overlay objects.If they are in different map levels, the two objects also swap levels. Swapping the position of the overlaysaffects their visibility in the map view.


See Also– exchangeOverlayAtIndex:withOverlayAtIndex: (page 31)


exchangeOverlayAtIndex:withOverlayAtIndex:

Exchanges the position of two overlay objects.

- (void)exchangeOverlayAtIndex:(NSUInteger)index1withOverlayAtIndex:(NSUInteger)index2

Parametersindex1

The index of an overlay in the MKOverlayLevelAboveLabels (page 48) map level.

index2The index of another overlay in the MKOverlayLevelAboveLabels map level.



31

DiscussionIf you need to exchange overlays in other map levels, use the exchangeOverlay:withOverlay: method.


See Also– exchangeOverlay:withOverlay: (page 31)


insertOverlay:aboveOverlay:

Inserts one overlay object on top of another.

- (void)insertOverlay:(id < MKOverlay >)overlay aboveOverlay:(id < MKOverlay >)sibling

Parametersoverlay

The overlay object to insert.

siblingAn existing object in the overlays array. This object must exist in the array and must not be nil.

DiscussionThis method inserts the overlay into the MKOverlayLevelAboveLabels (page 48) level and positions it relativeto the specified sibling. When displayed, this leads to the overlay’s contents being displayed above that of itssibling. If sibling is not in the same map level, this method appends the overlay to the end of the list of overlaysat the indicated level.


See Also– insertOverlay:atIndex: (page 33)– insertOverlay:belowOverlay: (page 34)




32

insertOverlay:atIndex:

Inserts an overlay object into the list associated with the map.

- (void)insertOverlay:(id < MKOverlay >)overlay atIndex:(NSUInteger)index

Parametersoverlay


indexThe index at which to insert the overlay object. If this value is greater than the number of objects in theoverlays (page 15) property, this method appends the object to the end of the array.

DiscussionThis method inserts the overlay into the MKOverlayLevelAboveLabels (page 48) level.


See Also– insertOverlay:aboveOverlay: (page 32)– insertOverlay:belowOverlay: (page 34)


insertOverlay:atIndex:level:

Inserts an overlay object into the level at the specified index.

- (void)insertOverlay:(id < MKOverlay >)overlay atIndex:(NSUInteger)indexlevel:(MKOverlayLevel)level

Parametersoverlay


indexThe index at which to insert the overlay object. If this value is greater than the number of objects in theoverlays (page 15) property, this method appends the object to the end of the array.

levelThe map level at which to place the overlay. For a list of possible values for this parameter, see“MKOverlayLevel” (page 47).



33

DiscussionInserting an overlay at a specific level places that overlay’s visual representation in front of or behind othermap content such as map labels and point-of-interest icons.



insertOverlay:belowOverlay:

Inserts one overlay object below another.

- (void)insertOverlay:(id < MKOverlay >)overlay belowOverlay:(id < MKOverlay >)sibling

Parametersoverlay


siblingAn existing object in the overlays (page 15) array. This object must exist in the array and must not benil.

DiscussionThis method inserts the overlay into the MKOverlayLevelAboveLabels (page 48) level and positions it relativeto the specified sibling. When displayed, this leads to the overlay’s contents being displayed beneath that ofits sibling. If sibling is not in the same map level, this method appends the overlay to the end of the list ofoverlays at the indicated level.


See Also– insertOverlay:atIndex: (page 33)– insertOverlay:aboveOverlay: (page 32)




34

mapRectThatFits:

Adjusts the aspect ratio of the specified map rectangle to ensure that it fits in the map view’s frame.

- (MKMapRect)mapRectThatFits:(MKMapRect)mapRect

ParametersmapRect

The initial map rectangle whose width and height you want to adjust.

Return ValueA map rectangle that is still centered on the same point of the map but whose width and height are adjustedto fit in the map view’s frame.

DiscussionYou can use this method to normalize map rectangle values before displaying the corresponding area. Thismethod returns a new map rectangle that both contains the specified rectangle and fits neatly inside the mapview’s frame.


See Also– mapRectThatFits:edgePadding: (page 35)


mapRectThatFits:edgePadding:

Adjusts the aspect ratio of the specified map rectangle, incorporating the specified inset values.

- (MKMapRect)mapRectThatFits:(MKMapRect)mapRect edgePadding:(UIEdgeInsets)insets

ParametersmapRect

The initial map rectangle whose width and height you want to adjust.

insetsThe distance (measured in screen points) by which to inset the returned rectangle from the actualboundaries of the map view’s frame.



35

Return ValueA map rectangle that is still centered on the same point of the map but whose width and height are adjustedto fit in the map view’s frame minus the inset values.


See Also– mapRectThatFits: (page 35)


overlaysInLevel:

The overlay objects in the specified level of the map.

- (NSArray *)overlaysInLevel:(MKOverlayLevel)level

Parameterslevel

The map level whose overlays you want. For a list of possible values for this parameter, see“MKOverlayLevel” (page 47).

Return ValueAn array of objects conforming to the MKOverlay protocol that display in the specified map level. If there areno overlays at the specified level, this method returns an empty array.

DiscussionYou can use this method to get all of the overlays assigned to a specific map level, which might be a subsetof the complete set of overlay objects. For overlapping overlay objects, the order of objects in the arrayrepresents their visual order when displayed on the map, with objects in the beginning of the array locatedbehind those at later indexes.


See Also– addOverlay:level: (page 24)– addOverlays:level: (page 26)




36

regionThatFits:

Adjusts the aspect ratio of the specified region to ensure that it fits in the map view’s frame.

- (MKCoordinateRegion)regionThatFits:(MKCoordinateRegion)region

Parametersregion

The initial region whose span you want to adjust.

Return ValueA region that is still centered on the same point of the map but whose span values are adjusted to fit in themap view’s frame.

DiscussionYou can use this method to normalize the region values before displaying them in the map. This methodreturns a new region that both contains the specified region and fits neatly inside the map view’s frame.



removeAnnotation:

Removes the specified annotation object from the map view.

- (void)removeAnnotation:(id < MKAnnotation >)annotation


The annotation object to remove. This object must conform to the MKAnnotation protocol.

DiscussionIf the annotation is currently associated with an annotation view, and that view has a reuse identifier, thismethod removes the annotation view and queues it internally for later reuse. You can retrieve queued annotationviews (and associate them with new annotations) using thedequeueReusableAnnotationViewWithIdentifier: (page 30) method.

Removing an annotation object disassociates it from the map view entirely, preventing it from being displayedon the map. Thus, you would typically call this method only when you want to hide or delete a given annotation.



37


See Also– removeAnnotations: (page 38)– addAnnotation: (page 22)


removeAnnotations:

Removes an array of annotation objects from the map view.

- (void)removeAnnotations:(NSArray *)annotations


The array of annotations to remove. Objects in the array must conform to the MKAnnotation protocol.

DiscussionIf any annotation object in the array has an associated annotation view, and if that view has a reuse identifier,this method removes the annotation view and queues it internally for later reuse. You can retrieve queuedannotation views (and associate them with new annotations) using thedequeueReusableAnnotationViewWithIdentifier: (page 30) method.

Removing annotation objects disassociates them from the map view entirely, preventing them from beingdisplayed on the map. Thus, you would typically call this method only when you want to hide or delete thespecified annotations.


See Also– removeAnnotation: (page 37)– addAnnotations: (page 23)




38

removeOverlay:

Removes a single overlay object from the map.

- (void)removeOverlay:(id < MKOverlay >)overlay

Parametersoverlay

The overlay object to remove.

DiscussionThis method removes the overlay regardless of the level that it is in. Removing an overlay also removes itscorresponding renderer, if one is in use. If the specified overlay is not currently associated with the map view,this method does nothing.


See Also– addOverlay: (page 23)– addOverlays: (page 25)– removeOverlays: (page 39)



removeOverlays:

Removes one or more overlay objects from the map.

- (void)removeOverlays:(NSArray *)overlays

Parametersoverlays

An array of objects, each of which conforms to the MKOverlay protocol.

DiscussionThis method removes the specified overlays regardless of which level each one is in. Removing an overlay alsoremoves its corresponding renderer, if one is in use. If a given overlay object is not associated with the mapview, it is ignored.



39


See Also– addOverlay: (page 23)– addOverlays: (page 25)– removeOverlay: (page 39)


rendererForOverlay:

Returns the renderer object used to draw the contents of the specified overlay object.

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

Parametersoverlay

The overlay object whose renderer you want.

Return ValueThe renderer object in use for the specified overlay or nil if the overlay is not onscreen.

DiscussionThis method returns the renderer object that your map delegate provided in itsmapView:rendererForOverlay: method.



selectAnnotation:animated:

Selects the specified annotation and displays a callout view for it.

- (void)selectAnnotation:(id < MKAnnotation >)annotation animated:(BOOL)animated



40


The annotation object to select.

animatedIf YES, the callout view is animated into position.

DiscussionIf the specified annotation is not onscreen, and therefore does not have an associated annotation view, thismethod has no effect.



setCamera:animated:

Changes the camera used for determining the map’s viewing parameters and optionally animates the change.

- (void)setCamera:(MKMapCamera *)camera animated:(BOOL)animated

Parameterscamera

The camera object containing the viewing angle information. This parameter must not be nil.

animatedSpecify YES if you want the change in viewing angle to be animated or NO if you want the map to reflectthe changes without animations.


See Also @property camera (page 13)


setCenterCoordinate:animated:

Changes the center coordinate of the map and optionally animates the change.



41

- (void)setCenterCoordinate:(CLLocationCoordinate2D)coordinate animated:(BOOL)animated

Parameterscoordinate

The new center coordinate for the map.

animatedSpecify YES if you want the map view to scroll to the new location or NO if you want the map to displaythe new location immediately.

DiscussionChanging the center coordinate centers the map on the new coordinate without changing the current zoomlevel. It also updates the value in the region property to reflect the new center coordinate and the new spanvalues needed to maintain the current zoom level.


See Also @property centerCoordinate (page 14) @property region (page 16)


setRegion:animated:

Changes the currently visible region and optionally animates the change.

- (void)setRegion:(MKCoordinateRegion)region animated:(BOOL)animated

Parametersregion

The new region to display in the map view.

animatedSpecify YES if you want the map view to animate the transition to the new region or NO if you want themap to center on the specified region immediately.



42

DiscussionChanging just the center coordinate of the region can still cause the span values to change implicitly. The spanvalues might change because that the distances represented by a span change at different latitudes andlongitudes and the map view may need to adjust the span to account for the new location. If you want tochange the center coordinate without changing the zoom level, use the setCenterCoordinate:animated:instead.

When setting a new region, the map may adjust the value in the region parameter so that it fits the visiblearea of the map precisely. This adjustment is normal and is done to ensure that the value in the region (page16) property always reflects the visible portion of the map. However, it does mean that if you get the value ofthat property right after calling this method, the returned value may not match the value you set. (You canuse the regionThatFits: (page 37) method to determine the region that will actually be set by the map.)


See Also @property region (page 16)– setCenterCoordinate:animated: (page 41)


setUserTrackingMode:animated:

Sets the mode used to track the user location with optional animation.

- (void)setUserTrackingMode:(MKUserTrackingMode)mode animated:(BOOL)animated

Parametersmode

The mode used to track the user location. Possible values are described in “MKUserTrackingMode” (page47).

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

DiscussionSetting the tracking mode to MKUserTrackingModeFollow (page 47) orMKUserTrackingModeFollowWithHeading (page 47) causes the map view to center the map on that locationand begin tracking the user’s location. If the map is zoomed out, the map view automatically zooms in on theuser’s location, effectively changing the current visible region.



43


See Also @property userTrackingMode (page 21)mapView:didChangeUserTrackingMode:animated:mapView:didUpdateUserLocation:heading


setVisibleMapRect:animated:

Changes the currently visible portion of the map and optionally animates the change.

- (void)setVisibleMapRect:(MKMapRect)mapRect animated:(BOOL)animate

ParametersmapRect

The map rectangle to make visible in the map view.

animateSpecify YES if you want the map view to animate the transition to the new map rectangle or NO if youwant the map to center on the specified rectangle immediately.


See Also– setVisibleMapRect:edgePadding:animated: (page 44)


setVisibleMapRect:edgePadding:animated:

Changes the currently visible portion of the map, allowing you to specify additional space around the edges.

- (void)setVisibleMapRect:(MKMapRect)mapRect edgePadding:(UIEdgeInsets)insetsanimated:(BOOL)animate



44

ParametersmapRect

The map rectangle to make visible in the map view.

insetsThe amount of additional space (measured in screen points) to make visible around the specified rectangle.

animateSpecify YES if you want the map view to animate the transition to the new map rectangle or NO if youwant the map to center on the specified rectangle immediately.


See Also– setVisibleMapRect:animated: (page 44)


showAnnotations:animated:

Sets the visible region so that the map displays the specified annotations.

- (void)showAnnotations:(NSArray *)annotations animated:(BOOL)animated


The annotations that you want to be visible in the map.

animatedYES if you want the map region change to be animated, or NO if you want the map to display the newregion immediately without animations.

DiscussionCalling this method updates the value in the region property and potentially other properties to reflect thenew map region.





45

viewForAnnotation:

Returns the annotation view associated with the specified annotation object, if any.

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


The annotation object whose view you want.

Return ValueThe annotation view or nil if the view has not yet been created. This method may also return nil if theannotation is not in the visible map region and therefore does not have an associated annotation view.



Constants

MKMapType

The type of map to display.

typedef enum : NSUInteger{MKMapTypeStandard,MKMapTypeSatellite,MKMapTypeHybrid

} MKMapType;

ConstantsMKMapTypeStandard

Displays a street map that shows the position of all roads and some road names.

Available in iOS 3.0 and later.

Declared in MKTypes.h.

MKMapView Class ReferenceConstants


46

MKMapTypeSatelliteDisplays satellite imagery of the area.



MKMapTypeHybridDisplays a satellite image of the area with road and road name information layered on top.



MKUserTrackingMode

The mode used to track the user location on the map.

typedef enum : NSInteger {MKUserTrackingModeNone = 0,MKUserTrackingModeFollow,MKUserTrackingModeFollowWithHeading,

} MKUserTrackingMode;

ConstantsMKUserTrackingModeNone

The map does not follow the user location.


Declared in MKMapView.h.

MKUserTrackingModeFollowThe map follows the user location.



MKUserTrackingModeFollowWithHeadingThe map follows the user location and rotates when the heading changes.



MKOverlayLevel

Constants indicating the position of overlays relative to other content.

typedef enum : NSInteger {



47

MKOverlayLevelAboveRoads = 0,MKOverlayLevelAboveLabels

} MKOverlayLevel;

ConstantsMKOverlayLevelAboveRoads

Place the overlay above roadways but below map labels, shields, or point-of-interest icons.



MKOverlayLevelAboveLabelsPlace the overlay above map labels, shields, or point-of-interest icons but below annotations and 3Dprojections of buildings.





48

A method identified as deprecated has been superseded and may become unsupported in the future.

Deprecated in iOS 7.0

viewForOverlay:

Returns the view associated with the overlay object if any. (Deprecated in iOS 7.0. Use therendererForOverlay: (page 40) method instead.)

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

Parametersoverlay

The overlay object whose view you want.

Return ValueThe view associated with the overlay object or nil if the overlay is not onscreen.


Deprecated in iOS 7.0.



49

Deprecated MKMapView Methods

This table describes the changes to MKMapView Class Reference .

NotesDate

Added new methods for managing overlays.2013-09-18

Updated description of annotationsInMapRect: (page 26).

Updated for iOS 5.0.2011-10-12

Documented the annotationsInMapRect: method, which is new in iOS 4.2.2010-11-15

Added symbols introduced in iOS 4.0.2010-05-11

Updated the description of the annotations property.2009-07-27

New document that describes the class for managing an embeddablemap interface.

2009-05-12


50

Document Revision History

Apple Inc.Copyright © 2013 Apple Inc.All rights reserved.

No part of this publication may be reproduced,stored in a retrieval system, or transmitted, in anyform or by any means, mechanical, electronic,photocopying, recording, or otherwise, withoutprior written permission of Apple Inc., with thefollowing exceptions: Any person is herebyauthorized to store documentation on a singlecomputer for personal use only and to printcopies of documentation for personal useprovided that the documentation containsApple’s copyright notice.

No licenses, express or implied, are granted withrespect to any of the technology described in thisdocument. Apple retains all intellectual propertyrights associated with the technology describedin this document. This document is intended toassist application developers to developapplications only for Apple-labeled computers.

Apple Inc.1 Infinite LoopCupertino, CA 95014408-996-1010

Apple, the Apple logo, Cocoa, and Cocoa Touchare trademarks of Apple Inc., registered in theU.S. and other countries.

iOS is a trademark or registered trademark ofCisco in the U.S. and other countries and is usedunder license.

Even though Apple has reviewed this document,APPLE MAKES NO WARRANTY OR REPRESENTATION,EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THISDOCUMENT, ITS QUALITY, ACCURACY,MERCHANTABILITY, OR FITNESS FOR A PARTICULARPURPOSE. AS A RESULT, THIS DOCUMENT IS PROVIDED“AS IS,” AND YOU, THE READER, ARE ASSUMING THEENTIRE RISK AS TO ITS QUALITY AND ACCURACY.

IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT,INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIALDAMAGES RESULTING FROM ANY DEFECT ORINACCURACY IN THIS DOCUMENT, even if advised ofthe possibility of such damages.

THE WARRANTY AND REMEDIES SET FORTH ABOVEARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORALOR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer,agent, or employee is authorized to make anymodification, extension, or addition to this warranty.

Some states do not allow the exclusion or limitationof implied warranties or liability for incidental orconsequential damages, so the above limitation orexclusion may not apply to you. This warranty givesyou specific legal rights, and you may also have otherrights which vary from state to state.

MKMapView Class

Documents

Transcript of MKMapView Class