MapKit Framework Reference

Map Kit Framework Reference
Contents
Introduction 10
About the Map Kit Framework 11
Classes 12
MKAnnotationView Class Reference 13
Overview 13
Tasks 15
Properties 17
Instance Methods 24
Constants 27
Notifications 28
MKCircle Class Reference 30
Overview 30
Tasks 31
Properties 31
Class Methods 33
MKCircleRenderer Class Reference 35
Overview 35
Tasks 35
Properties 36
Instance Methods 36
MKCircleView Class Reference 37
Overview 37
Tasks 38
Properties 38
Instance Methods 38
MKDirections Class Reference 40
Overview 40
Tasks 40
2013-09-18 | Copyright 2013 Apple Inc. All Rights Reserved.
2
Properties 41
Instance Methods 41
Constants 44
MKDirectionsRequest Class Reference 46
Overview 46
Tasks 47
Properties 48
Class Methods 50
Instance Methods 50
Constants 52
MKDirectionsResponse Class Reference 54
Overview 54
Tasks 54
Properties 55
MKETAResponse Class Reference 57
Overview 57
Tasks 57
Properties 58
MKGeodesicPolyline Class Reference 60
Overview 60
Tasks 60
Class Methods 61
MKLocalSearch Class Reference 63
Overview 63
Tasks 63
Properties 64
Instance Methods 64
Constants 66
MKLocalSearchRequest Class Reference 67
Overview 67
Tasks 67
Properties 68
MKLocalSearchResponse Class Reference 69
3
Contents
Overview 69
Tasks 69
Properties 70
MKMapCamera Class Reference 71
Overview 71
Tasks 71
Properties 72
Class Methods 74
MKMapItem Class Reference 76
Overview 76
Tasks 77
Properties 78
Class Methods 80
Instance Methods 82
Constants 83
MKMapSnapshot Class Reference 86
Overview 86
Tasks 86
Properties 87
Instance Methods 87
MKMapSnapshotOptions Class Reference 88
Overview 88
Tasks 88
Properties 89
MKMapSnapshotter Class Reference 93
Overview 93
Tasks 93
Properties 94
Instance Methods 94
Constants 97
MKMapView Class Reference 98
Overview 98
Tasks 101
Properties 105
4
Contents
Instance Methods 115
Constants 139
MKMultiPoint Class Reference 142
Overview 142
Tasks 142
Properties 143
MKOverlayPathRenderer Class Reference 145
Overview 145
Tasks 145
Properties 147
MKOverlayPathView Class Reference 154
Overview 154
Tasks 155
Properties 156
MKOverlayRenderer Class Reference 165
Overview 165
Tasks 166
Properties 167
MKOverlayView Class Reference 175
Overview 175
Tasks 176
Properties 177
MKPinAnnotationView Class Reference 186
Overview 186
Tasks 187
Properties 187
Constants 188
MKPlacemark Class Reference 190
5
Contents
Overview 190
Tasks 191
Properties 191
MKPointAnnotation Class Reference 193
Overview 193
Tasks 194
Properties 194
MKPolygon Class Reference 195
Overview 195
Tasks 196
Properties 196
Class Methods 197
MKPolygonRenderer Class Reference 200
Overview 200
Tasks 200
Properties 201
MKPolygonView Class Reference 202
Overview 202
Tasks 203
Properties 203
MKPolyline Class Reference 205
Overview 205
Tasks 206
Class Methods 206
MKPolylineRenderer Class Reference 208
Overview 208
Tasks 208
Properties 209
MKPolylineView Class Reference 210
6
Contents
Overview 210
Tasks 211
Properties 211
MKReverseGeocoder Class Reference 213
Overview 213
Tasks 214
Properties 215
MKRoute Class Reference 219
Overview 219
Tasks 219
Properties 220
MKRouteStep Class Reference 224
Overview 224
Tasks 224
Properties 225
MKShape Class Reference 228
Overview 228
Tasks 229
Properties 229
MKTileOverlay Class Reference 231
Overview 231
Tasks 232
Properties 232
Constants 238
MKTileOverlayRenderer Class Reference 239
Overview 239
Tasks 239
MKUserLocation Class Reference 241
Overview 241
7
Contents
Tasks 242
Properties 242
MKUserTrackingBarButtonItem Class Reference 245
Overview 245
Tasks 245
Properties 246
NSValue MapKit Additions Reference 247
Overview 247
Tasks 247
Class Methods 248
Protocols 250
MKAnnotation Protocol Reference 251
Overview 251
Tasks 252
Properties 252
MKMapViewDelegate Protocol Reference 255
Overview 255
Tasks 256
MKOverlay Protocol Reference 271
Overview 271
Tasks 272
Properties 272
MKReverseGeocoderDelegate Protocol Reference 275
Overview 275
Tasks 276
Functions 278
8
Contents
Map Kit Functions Reference 279
Overview 279
Functions by Task 279
Functions 282
Data Types 307
Map Kit Data Types Reference 308
Overview 308
Data Types 308
Constants 313
Map Kit Constants Reference 314
Overview 314
Constants 314
Document Revision History 317
9
Contents
Framework /System/Library/Frameworks/MapKit.framework
Header file directories /System/Library/Frameworks/MapKit.framework/Headers
Companion guide Location and Maps Programming Guide
Declared in MKAnnotation.h
MKAnnotationView.h
MKCircle.h
MKCircleRenderer.h
MKCircleView.h
MKDirections.h
MKDirectionsRequest.h
MKDirectionsResponse.h
MKDirectionsTypes.h
MKGeodesicPolyline.h
MKGeometry.h
MKLocalSearch.h
MKLocalSearchRequest.h
MKLocalSearchResponse.h
MKMapCamera.h
MKMapItem.h
MKMapSnapshot.h
MKMapSnapshotOptions.h
MKMapSnapshotter.h
MKMapView.h
MKMultiPoint.h
MKOverlay.h
MKOverlayPathRenderer.h
MKOverlayPathView.h
MKOverlayRenderer.h
MKOverlayView.h
MKPinAnnotationView.h
10
MKPlacemark.h
MKPointAnnotation.h
MKPolygon.h
MKPolygonRenderer.h
MKPolygonView.h
MKPolyline.h
MKPolylineRenderer.h
MKPolylineView.h
MKReverseGeocoder.h
MKShape.h
MKTileOverlay.h
MKTileOverlayRenderer.h
MKTypes.h
MKUserLocation.h
MKUserTrackingBarButtonItem.h
About the Map Kit Framework
The Map Kit framework provides an interface for embedding maps directly into your own windows and views.
This framework also provides support for annotating the map, adding overlays, and performing
reverse-geocoding lookups to determine placemark information for a given map coordinate.
Important: In iOS 5.1 and earlier, the Map Kit framework uses the Google Mobile Maps (GMM) service to
provide map data. Use of specific classes of this framework (and their associated interfaces) is subject to
the Google Mobile Maps terms of service. You can find these terms of service at
http://code.google.com/apis/maps/iphone/terms.html.
About the Map Kit Framework
11

12
Classes
Inherits from UIView : UIResponder : NSObject
Conforms to NSCoding (UIView)
UIAppearance (UIView)
UIAppearanceContainer (UIView)
UIDynamicItem (UIView)
NSObject (NSObject)
Availability Available in iOS 3.0 and later.
Declared in MKAnnotationView.h
Related sample code
KMLViewer
MapCallouts
MapSearch
PhotosByLocation
Regions
Overview
The MKAnnotationView class is responsible for presenting annotations visually in a map view. Annotation
views are loosely coupled to a corresponding annotation object, which is an object that corresponds to the
MKAnnotation protocol. When an annotations coordinate point is in the visible region, the map view asks
its delegate to provide a corresponding annotation view. Annotation views may be recycled later and put into
a reuse queue that is maintained by the map view.
13
MKAnnotationView Class Reference
The most efficient way to provide the content for an annotation view is to set its image (page 21) property.
The annotation view sizes itself automatically to the image you specify and draws that image for its contents.
Because it is a view, however, you could also override the drawRect: method and draw your views content
manually. If you choose to override drawRect: directly and you do not specify a custom image in the image
property, be aware that the width and height of the annotation views frame are set to 0 by default. Before
your custom content can be drawn, you must set the width and height to nonzero values by modifying the
views frame property. In general, if your content consists entirely of static images, it is more efficient to set
the image property and change it as needed than to draw the images yourself.
Annotation views remain anchored to the map at the point specified by their associated annotation object.
Although they scroll with the map contents, annotation views reside in a separate display layer and are not
scaled when the size of the visible map region changes.
Annotation views support the concept of a selection state, which determines whether the view is unselected,
selected, or selected and displaying a standard callout view. The user toggles between the selection states
through interactions with the annotation view. In the unselected state, the annotation view is displayed but
not highlighted. In the selected state, the annotation is highlighted but the callout is not displayed. And finally,
the annotation can be displayed both with a highlight and a callout. The callout view displays additional
information such as a title string and controls for viewing more information. The title information is provided
by the annotation object but your annotation view is responsible for providing any custom controls. For more
information, see the subclassing notes.
Reusing Annotation Views
Annotation views are designed to be reused as the user (or your application) changes the visible map region.
The reuse of annotation views provides significant performance improvements during scrolling by avoiding
the creation of new view objects during this time critical operation. For this reason, annotation views should
not be tightly coupled to the contents of their associated annotation. Instead, it should be possible to use the
properties of an annotation view (or setter methods) to configure the view for a new annotation object.
Whenever you initialize a new annotation view, you should always specify a reuse identifier for that view. As
annotation views are no longer needed, the map view may put them into a reuse queue. As new annotations
are added to the map view, the delegate object can then dequeue and reconfigure an existing view (rather
than create a new one) using the dequeueReusableAnnotationViewWithIdentifier: (page 122) method of
MKMapView.
Overview
14
Subclassing Notes
You can use the MKAnnotationView class as is or subclass it to provide custom behavior as needed. The
image (page 21) property of the class lets you set the appearance of the annotation view without subclassing
directly. You might also create custom subclasses as a convenience and use them to put the annotation view
in a known state. For example, the MKPinAnnotationView subclass initializes the contents of the annotation
view to a pin image.
There are no special requirements for subclassing MKAnnotationView. However, the following list includes
some reasons you might want to subclass and some of the methods you would override to implement the
desired behavior:

To put the annotation view into a consistent state, provide a custom initialization method. Your custom
initialization method would then call initWithAnnotation:reuseIdentifier: (page 24) to initialize the
superclass.

To provide customcallout views, override the leftCalloutAccessoryView method and use it to return
the views.
If you support draggable annotation views in iOS 4.0 and later, your subclass is responsible for changing the
value in the dragState (page 19) property to appropriate values at key transition points in the drag operation.
For more information, see the description of that property.
Tasks
Initializing and Preparing the View
initWithAnnotation:reuseIdentifier: (page 24)
Initializes and returns a new annotation view.
prepareForReuse (page 25)
Called when the view is removed from the reuse queue.
Getting and Setting Attributes
enabled (page 21) property
A Boolean value indicating whether the annotation is enabled.
image (page 21) property
The image to be displayed by the annotation view.
Tasks
15
highlighted (page 21) property
A Boolean value indicating whether the annotation view is highlighted.
annotation (page 17) property
The annotation object currently associated with the view.
centerOffset (page 18) property
The offset (in pixels) at which to display the view.
calloutOffset (page 17) property
The offset (in pixels) at which to place the callout bubble.
reuseIdentifier (page 22) property
The string that identifies that this annotation view is reusable. (read-only)
Managing the Selection State
setSelected:animated: (page 27)
Sets the selection state of the annotation view.
selected (page 24) property
A Boolean value indicating whether the annotation view is currently selected.
Managing Callout Views
canShowCallout (page 18) property
A Boolean value indicating whether the annotation view is able to display extra information in a callout
bubble.
leftCalloutAccessoryView (page ?) property
The view to display on the left side of the standard callout bubble.
rightCalloutAccessoryView (page ?) property
The view to display on the right side of the standard callout bubble.
Supporting Drag Operations
draggable (page 19) property
A Boolean indicating whether the annotation view is draggable.
Tasks
16
setDragState:animated: (page 26)
Sets the current drag state for the annotation view.
dragState (page 19) property
The current drag state of the annotation view.
Properties
annotation
The annotation object currently associated with the view.
@property (nonatomic, retain) id <MKAnnotation> annotation
Discussion
You should not change the value of this property directly. This property contains a non-nil value only while
the annotation view is visible on the map. If the view is queued and waiting to be reused, the value is nil
Availability
Available in iOS 3.0 and later.
Related Sample Code
MapCallouts
Regions
Declared in
MKAnnotationView.h
calloutOffset
The offset (in pixels) at which to place the callout bubble.
@property (nonatomic) CGPoint calloutOffset
Discussion
This property determines the additional distance by which to move the callout bubble. When this property is
set to (0, 0), the anchor point of the callout bubble is placed on the top-center point of the annotation views
frame. Specifying positive offset values moves the callout bubble down and to the right, while specifying
negative values moves it up and to the left.
Availability
Properties
17
Declared in
MKAnnotationView.h
canShowCallout
A Boolean value indicating whether the annotation view is able to display extra information in a callout bubble.
@property (nonatomic) BOOL canShowCallout
Discussion
If the value of this property is YES, a standard callout bubble is shown when the user taps a selected annotation
view. The callout uses the title and subtitle text from the associated annotation object. If there is no title text,
though, the annotation view is treated as if its enabled property is set to NO. The callout also displays any
custom callout views stored in the leftCalloutAccessoryView and rightCalloutAccessoryView
properties.
If the value of this property is NO, the value of the title and subtitle strings are ignored and the annotation view
remains enabled by default. You can still disable the view explicitly using the enabled property.
Availability
See Also
@property leftCalloutAccessoryView (page 22)
@property rightCalloutAccessoryView (page 23)
Related Sample Code
KMLViewer
MapCallouts
MapSearch
PhotosByLocation
Declared in
MKAnnotationView.h
centerOffset
The offset (in pixels) at which to display the view.
Properties
18
@property (nonatomic) CGPoint centerOffset
Discussion
By default, the center point of an annotation viewis placed at the coordinate point of the associated annotation.
You can use this property to reposition the annotation viewas needed. This x and y offset values are measured
in pixels. Positive offset values move the annotation view down and to the right, while negative values move
it up and to the left.
Availability
Related Sample Code
MapCallouts
Declared in
MKAnnotationView.h
draggable
A Boolean indicating whether the annotation view is draggable.
@property (nonatomic, getter=isDraggable) BOOL draggable
Discussion
Setting this property to YES makes an annotation draggable by the user. If YES, the associated annotation
object must also implement the setCoordinate: (page 254) method. The default value of this property is NO.
Setting this property to YES, lets the map view know that the annotation is always draggable. In other words,
you cannot conditionalize drag operations by attempting to stop an operation that has already been initiated;
doing so can lead to undefined behavior. Once begun, the drag operation should always continue to completion.
Availability
Declared in
MKAnnotationView.h
dragState
The current drag state of the annotation view.
Properties
19
@property (nonatomic) MKAnnotationViewDragState dragState
Discussion
Applications targeting iOS 4.1 and earlier can use this property to support drag operations in customannotation
views. If your application runs in iOS 4.2 or later, you should override the setDragState:animated: (page 26)
method and use it to manage the drag state instead.
To support drag operations, you must override the implementation of this property and update the drag state
at the following times:

When the drag state changes to MKAnnotationViewDragStateStarting (page 28), you should set the
state to MKAnnotationViewDragStateDragging (page 28). If you perform an animation to indicate the
beginning of a drag, you should perform that animation before changing the state. Changing the state
to the new value lets the map know that your animations are done.

When the state changes to either MKAnnotationViewDragStateCanceling (page 28) or
MKAnnotationViewDragStateEnding (page 28), set the state to MKAnnotationViewDragStateNone (page
28). If you performan animation at the end of a drag, you should performthat animation before changing
the state.
Changingthe state tothe MKAnnotationViewDragStateDraggingor MKAnnotationViewDragStateNone
value is the way to signal to the map view that you are done with any animations you wanted to perform. For
example, when a drag operation begins for a pin annotation, the MKPinAnnotationView class executes an
animation to lift the pin off the map. Similarly, when the pin is dropped, the class performs a drop animation.
Even if you do not perform any animations, you should still change the value of this property to reflect the
correct state.
You must not try to abort a new drag operation by changing the state from
MKAnnotationViewDragStateStartingtoMKAnnotationViewDragStateNone. If youdonot want your
annotation view to be draggable, set the draggable (page 19) property to NO.
Availability
See Also
@property draggable (page 19)
Declared in
MKAnnotationView.h
Properties
20
enabled
A Boolean value indicating whether the annotation is enabled.
@property (nonatomic, getter=isEnabled) BOOL enabled
Discussion
The default value of this property is YES. If the value of this property is NO, the annotation view ignores touch
events and cannot be selected. Subclasses may also display the annotation contents differently depending on
the value of this property.
Availability
Declared in
MKAnnotationView.h
highlighted
A Boolean value indicating whether the annotation view is highlighted.
@property (nonatomic, getter=isHighlighted) BOOL highlighted
Discussion
You should not set the value of this property directly. The map viewsets it in response to touch events entering
or exiting the annotation views bounds.
Availability
Declared in
MKAnnotationView.h
image
The image to be displayed by the annotation view.
@property (nonatomic, retain) UIImage *image
Discussion
Assigning a new image to this property also changes the size of the views frame so that it matches the width
and height of the new image. The position of the views frame does not change.
Properties
21
Availability
Related Sample Code
MapCallouts
Declared in
MKAnnotationView.h
leftCalloutAccessoryView
The view to display on the left side of the standard callout bubble.
@property (retain, nonatomic) UIView *leftCalloutAccessoryView
Discussion
The default value of this property is nil. The left callout view is typically used to display information about
the annotation or to link to custom information provided by your application.
If the view you specify is also a descendant of the UIControl class, you can use the map views delegate to
receive notifications when your control is tapped. If it does not descend from UIControl, your view is
responsible for handling any touch events within its bounds.
Availability
See Also
@property canShowCallout (page 18)
Related Sample Code
MapCallouts
PhotosByLocation
Regions
Declared in
MKAnnotationView.h
reuseIdentifier
The string that identifies that this annotation view is reusable. (read-only)
Properties
22
@property (nonatomic, readonly) NSString *reuseIdentifier
Discussion
You specify the reuse identifier when you create the view. You use this type later to retrieve an annotation
view that was created previously but which is currently unused because its annotation is not on screen.
If you define distinctly different types of annotations (with distinctly different annotation views to go with
them), you can differentiate between the annotation types by specifying different reuse identifiers for each
one.
Availability
Related Sample Code
MapCallouts
Declared in
MKAnnotationView.h
rightCalloutAccessoryView
The view to display on the right side of the standard callout bubble.
@property (retain, nonatomic) UIView *rightCalloutAccessoryView
Discussion
This property is set to nil by default. The right callout viewis typically used to link to more detailed information
about the annotation. A common view to specify for this property is UIButton object whose type is set to
UIButtonTypeDetailDisclosure.
If the view you specify is also a descendant of the UIControl class, you can use the map views delegate to
receive notifications when your control is tapped. If it does not descend from UIControl, your view is
responsible for handling any touch events within its bounds.
Availability
See Also
@property canShowCallout (page 18)
Related Sample Code
MapCallouts
PhotosByLocation
Properties
23
Declared in
MKAnnotationView.h
selected
A Boolean value indicating whether the annotation view is currently selected.
@property (nonatomic, getter=isSelected) BOOL selected
Discussion
You should not set the value of this property directly. If the property contains YES, the annotation view is
displaying a callout bubble.
Availability
Declared in
MKAnnotationView.h
Instance Methods
initWithAnnotation:reuseIdentifier:
Initializes and returns a new annotation view.
- (id)initWithAnnotation:(id <MKAnnotation>)annotation reuseIdentifier:(NSString
*)reuseIdentifier
Parameters
annotation
The annotation object to associate with the new view.
reuseIdentifier
If you plan to reuse the annotation view for similar types of annotations, pass a string to identify it.
Although you can pass nil if you do not intend to reuse the view, reusing annotation views is generally
recommended.
Return Value
The initialized annotation view or nil if there was a problem initializing the object.
Instance Methods
24
Discussion
The reuse identifier provides a way for you to improve performance by recycling annotation views as they are
scrolled on and off of the map. As views are no longer needed, they are moved to a reuse queue by the map
view. When a new annotation becomes visible, your application can request a view for that annotation by
passing the appropriate reuse identifier string to the dequeueReusableAnnotationViewWithIdentifier: (page
122) method of MKMapView.
Availability
Related Sample Code
KMLViewer
MapCallouts
MapSearch
PhotosByLocation
Regions
Declared in
MKAnnotationView.h
prepareForReuse
Called when the view is removed from the reuse queue.
- (void)prepareForReuse
Discussion
The default implementation of this method does nothing. You can override it in your customannotation views
and use it to put the view in a known state before it is returned to your map view delegate.
Availability
See Also
dequeueReusableAnnotationViewWithIdentifier: (page 122) (MKMapView)
Related Sample Code
PhotosByLocation
Declared in
MKAnnotationView.h
Instance Methods
25
setDragState:animated:
Sets the current drag state for the annotation view.
- (void)setDragState:(MKAnnotationViewDragState)newDragState animated:(BOOL)animated
Parameters
newDragState
The new drag state for the annotation view.
animated
If YES, the change to the new drag state should be animated; otherwise, it should be made without
animations.
Discussion
Applications targeting iOS 4.2 and later can override this method and use it to implement drag support for
custom annotation views. As the system detects user actions that would indicate a drag, it calls this method
to update the drag state. In response to these changes, your custom implementation of this method should
do the following:

When the drag state changes to MKAnnotationViewDragStateStarting (page 28), set the state to
MKAnnotationViewDragStateDragging (page 28). If you perform an animation to indicate the beginning
of a drag, and the animated parameter is YES, perform that animation before changing the state.

When the state changes to either MKAnnotationViewDragStateCanceling (page 28) or
MKAnnotationViewDragStateEnding (page 28), set the state to MKAnnotationViewDragStateNone (page
28). If you perform an animation at the end of a drag, and the animated parameter is YES, you should
perform that animation before changing the state.
The default implementation of this method sets the value of the dragState (page 19) property to the value
in the newDragState parameter only. Therefore, direct subclasses can simply call the inherited version of this
method to change the drag state; otherwise, just change the value in the draggable property directly.
Changing the state to MKAnnotationViewDragStateDragging or MKAnnotationViewDragStateNone
is the way to signal to the map viewthat you are done with any animations you wanted to perform. For example,
when a drag operation begins for a pin annotation, the MKPinAnnotationView class executes an animation
to lift the pin off the map. Similarly, when the pin is dropped, the class performs a drop animation. Even if you
do not perform any animations, you should call the inherited version of this method to update the
dragState (page 19) property.
You must not try to abort a new drag operation by changing the state from
MKAnnotationViewDragStateStartingtoMKAnnotationViewDragStateNone. If youdonot want your
annotation view to be draggable, set the draggable (page 19) property to NO.
Instance Methods
26
Availability
Declared in
MKAnnotationView.h
setSelected:animated:
Sets the selection state of the annotation view.
- (void)setSelected:(BOOL)selected animated:(BOOL)animated
Parameters
selected
Contains the value YES if the view should display itself as selected.
animated
Set to YES if the change in selection state is animated.
Discussion
You should not call this method directly. An MKMapView object calls this method in response to user interactions
with the annotation.
Availability
See Also
selectAnnotation:animated: (page 133) (MKMapView)
Declared in
MKAnnotationView.h
Constants
MKAnnotationViewDragState
These constants indicate the current drag state of an annotation view.
typedef enum MKAnnotationViewDragState {
MKAnnotationViewDragStateNone = 0,
MKAnnotationViewDragStateStarting,
MKAnnotationViewDragStateDragging,
Constants
27
MKAnnotationViewDragStateCanceling,
MKAnnotationViewDragStateEnding
} MKAnnotationViewDragState;
Constants
MKAnnotationViewDragStateNone
The view is not involved in a drag operation. The annotation view is responsible for returning itself to
this state when a drag ends or is canceled.
Declared in MKAnnotationView.h.
MKAnnotationViewDragStateStarting
An action occurred that indicated the view should begin dragging. The map view automatically moves
annotation views to this state in response to appropriate user actions.
MKAnnotationViewDragStateDragging
The view is in the middle of a drag operation and is tracking progress.
MKAnnotationViewDragStateCanceling
An action occurred that indicated the view should cancel the drag operation. You can put an annotation
view into this state to abort the operation.
MKAnnotationViewDragStateEnding
An action occurred that indicated the view was dropped by the user. The map view automatically moves
annotation views to this state in response to appropriate user actions.
Notifications
MKAnnotationCalloutInfoDidChangeNotification
Notifies observers that the title or subtitle information of an annotation object changed. (#Deprecated. Use KVO
notifications instead.)
Notifications
28
This notification supports legacy applications and is no longer necessary. MapKit tracks changes to the title
and subtitle of an annotation using KVO notifications.
Availability
Declared in
MKAnnotationView.h
Notifications
29
Inherits from MKShape : NSObject
Conforms to MKOverlay
MKAnnotation (MKShape)
NSObject (NSObject)
Declared in MKCircle.h
Related sample code
Regions
Overview
The MKCircle class is a concrete overlay object representing a circular area on a map. This class manages the
data that defines the area and is typically used in conjunction with an MKCircleView object, which handles
the drawing of the circular area on a map.
30
MKCircle Class Reference
Tasks
Creating a Circle Overlay
+ circleWithCenterCoordinate:radius: (page 33)
Creates and returns an MKCircle object using the specified coordinate and radius.
+ circleWithMapRect: (page 33)
Creates and returns an MKCircle object where the circular area is derived from the specified rectangle.
Accessing the Overlays Attributes
coordinate (page 32) property
The center point of the circular area, specified as a latitude and longitude. (read-only)
radius (page 32) property
The radius of the circular area, measured in meters. (read-only)
boundingMapRect (page 31) property
The bounding rectangle of the circular area. (read-only)
Properties
boundingMapRect
The bounding rectangle of the circular area. (read-only)
Tasks
31
@property (nonatomic, readonly) MKMapRect boundingMapRect
Discussion
As latitude values move away from the equator and toward the poles, the physical distance between map
points gets smaller. This means that more map points are needed to represent the same distance. As a result,
the bounding rectangle of a circle overlay gets larger as the center point of that circle moves away from the
equator and toward the poles.
Availability
Declared in
MKCircle.h
coordinate
The center point of the circular area, specified as a latitude and longitude. (read-only)
@property (nonatomic, readonly) CLLocationCoordinate2D coordinate
Availability
Related Sample Code
Regions
Declared in
MKCircle.h
radius
The radius of the circular area, measured in meters. (read-only)
@property (nonatomic, readonly) CLLocationDistance radius
Availability
Declared in
MKCircle.h
Properties
32
Class Methods
circleWithCenterCoordinate:radius:
Creates and returns an MKCircle object using the specified coordinate and radius.
+ (MKCircle *)circleWithCenterCoordinate:(CLLocationCoordinate2D)coord
radius:(CLLocationDistance)radius
Parameters
coord
The center point of the circle, specified as a latitude and longitude value.
radius
The radius of the circle, measured in meters from the center point.
Return Value
A circle overlay object.
Availability
Related Sample Code
Regions
Declared in
MKCircle.h
circleWithMapRect:
Creates and returns an MKCircle object where the circular area is derived from the specified rectangle.
+ (MKCircle *)circleWithMapRect:(MKMapRect)mapRect
Parameters
mapRect
The map rectangle used to determine the circular area. The center point of the rectangle is used as the
center point of the circle. If the rectangle is not a square, the longest side of the rectangle is used to
define the radius of the resulting circle.
Return Value
A circle overlay object.
Class Methods
33
Availability
Declared in
MKCircle.h
Class Methods
34
Inherits from MKOverlayPathRenderer : MKOverlayRenderer : NSObject
Conforms to NSObject (NSObject)
Declared in MKCircleRenderer.h
Overview
The MKCircleRenderer class provides a visual representation for an MKCircle overlay object. This renderer
draws by filling and stroking the circle represented by the overlay object. You can change the color and other
drawing attributes of the circle by modifying the properties inherited from the parent class. You typically use
this class as is and do not subclass it.
You create an instance of this class in your map view delegates mapView:rendererForOverlay: (page 265)
method.
Tasks
Initializing the Renderer Object
initWithCircle: (page 36)
Initializes and returns a new overlay view using the specified circle overlay object.
Accessing the Overlay Object
circle (page 36) property
The circle overlay object that contains the information used to draw the overlay. (read-only)
35
MKCircleRenderer Class Reference
Properties
circle
The circle overlay object that contains the information used to draw the overlay. (read-only)
@property(nonatomic, readonly) MKCircle *circle
Availability
Declared in
MKCircleRenderer.h
Instance Methods
initWithCircle:
Initializes and returns a new overlay view using the specified circle overlay object.
- (id)initWithCircle:(MKCircle *)circle
Parameters
circle
The circle overlay containing the information about the circular area to be drawn. The renderer maintains
a strong reference to the object you provide. This parameter must not be nil.
Return Value
An initialized circle renderer object.
Availability
Declared in
MKCircleRenderer.h
MKCircleRenderer Class Reference
Properties
36
Inherits from MKOverlayPathView : MKOverlayView : UIView : UIResponder : NSObject
NSObject (NSObject)
Declared in MKCircleView.h
Related sample code
Regions
Overview
The MKCircleView class provides the visual representation for an MKCircle annotation object. This view
fills and strokes the circle represented by the annotation. You can change the color and other drawing attributes
of the circle by modifying the properties inherited from the MKOverlayPathView class. This class is typically
used as is and not subclassed.
Use of this class is discouraged in iOS 7 and later. Use the MKCircleRenderer class instead.
37
MKCircleView Class Reference
Tasks
Initializing the Overlay View
initWithCircle: (page 38)
Initializes and returns a new overlay view using the specified circle overlay object. (Deprecated. Use the
MKCircleRenderer class instead.)
Accessing the Overlay
circle (page 38) property
The circle overlay object that contains the information used to drawthe overlay. (read-only) (Deprecated.
Use the MKCircleRenderer class instead.)
Properties
circle
The circle overlay object that contains the information used to draw the overlay. (read-only) (Deprecated in iOS
7.0. Use the MKCircleRenderer class instead.)
@property (nonatomic, readonly) MKCircle *circle
Availability
Deprecated in iOS 7.0.
Declared in
MKCircleView.h
Instance Methods
initWithCircle:
Initializes and returns a new overlay view using the specified circle overlay object. (Deprecated in iOS 7.0. Use the
MKCircleRenderer class instead.)
Tasks
38
- (id)initWithCircle:(MKCircle *)circle
Parameters
circle
The circle overlay containing the information about the circular area to be drawn.
Return Value
A new circle overlay view.
Availability
Declared in
MKCircleView.h
Instance Methods
39
Inherits from NSObject
Declared in MKDirections.h
Overview
An MKDirections object provides you with route-based directions data from Apple servers. You can use
instances of this class to get travel-time information or driving or walking directions based on the data in an
MKDirectionsRequest object that you provide. The directions object passes your request to the Apple
servers and returns the requested information to a block that you provide.
Each directions object handles a single request for directions, although you can cancel and restart that request
as needed. You can create multiple instances of this class and process different route requests at the same
time, but you should make requests only when you plan to present the corresponding route information to
the user. Apps may receive a MKErrorLoadingThrottled (page 316) error if too many requests have been made
from the current device in too short a time period.
Tasks
Initializing a Directions Object
initWithRequest: (page 43)
Initializes and returns a directions object using the specified request.
40
MKDirections Class Reference
Getting the Directions
calculateDirectionsWithCompletionHandler: (page 41)
Begins calculating the requested route information asynchronously.
calculateETAWithCompletionHandler: (page 42)
Begins calculating the requested travel-time information asynchronously.
cancel (page 43)
Cancels a pending request.
calculating (page 41) property
A Boolean value indicating whether a request is currently in process. (read-only)
Properties
calculating
A Boolean value indicating whether a request is currently in process. (read-only)
@property (nonatomic, readonly, getter=isCalculating) BOOL calculating
Availability
Declared in
MKDirections.h
Instance Methods
calculateDirectionsWithCompletionHandler:
Begins calculating the requested route information asynchronously.
-
(void)calculateDirectionsWithCompletionHandler:(MKDirectionsHandler)completionHandler
Parameters
completionHandler
The block to execute when the directions are ready or when an error occurs. This parameter must not
be nil.
Properties
41
Discussion
This method initiates the request for directions and calls your completion handler block with the results. Your
completion handler is executed on your apps main thread. The implementation of your handler should check
for errors and then incorporate the response data as appropriate.
If you call this method while a previous request is in process, this method calls your completion handler with
an error. You can determine if a request is in process by checking the value of the calculating property.
You can also cancel a request as needed.
Availability
See Also
@property calculating (page 41)
cancel (page 43)
Declared in
MKDirections.h
calculateETAWithCompletionHandler:
Begins calculating the requested travel-time information asynchronously.
- (void)calculateETAWithCompletionHandler:(MKETAHandler)completionHandler
Parameters
completionHandler
The block to execute when the travel-time estimate is ready or when an error occurs. This parameter
must not be nil.
Discussion
This method initiates a request for a travel-time estimate and calls your completion handler block with the
results. Travel-time estimates take much less time to generate than directions, so use this method in situations
where you want a time estimate only. Your completion handler is executed on your apps main thread. The
implementation of your handler should check for errors and then incorporate the response data as appropriate.
If you call this method while a previous request is in process, this method calls your completion handler with
an error. You can determine if a request is in process by checking the value of the calculating property.
You can also cancel a request as needed.
Availability
Instance Methods
42
Declared in
MKDirections.h
cancel
Cancels a pending request.
- (void)cancel
Discussion
After canceling a request, you can call the calculateDirectionsWithCompletionHandler: (page 41) method
again (if you want) to restart the request process.
Availability
Declared in
MKDirections.h
initWithRequest:
Initializes and returns a directions object using the specified request.
- (instancetype)initWithRequest:(MKDirectionsRequest *)request
Parameters
request
The request object containing the start and end points of the route. This parameter must not be nil.
Return Value
An initialized directions object.
Discussion
After initializing your directions object, you must call the calculateDirectionsWithCompletionHandler: (page
41) or calculateETAWithCompletionHandler: (page 42) method to perform the request.
Availability
Declared in
MKDirections.h
Instance Methods
43
Constants
MKDirectionsHandler
The block to use for processing the requested route information.
typedef void (^MKDirectionsHandler)(MKDirectionsResponse *response, NSError *error);
Discussion
This block takes two parameters:

The response parameter contains the route information for the request. If an error occurred or no route
could be determined, this parameter is nil.

The error parameter contains information about any errors that occurred. If no errors occurred, this
parameter is nil.
The implementation of your block should check for a value in the error parameter and, if that parameter is
nil, incorporate the route information provided in the response parameter.
Availability
Declared in
MKDirections.h
MKETAHandler
The block to use for processing travel-time information.
typedef void (^MKETAHandler)(MKETAResponse *response, NSError *error);
Discussion

The response parameter contains the travel time response. If an error occurred or no travel time could
be determined, this parameter is nil.

The error parameter contains information about any errors that occurred. If no errors occurred, this
parameter is nil.
Constants
44
The implementation of your block should check for a value in the error parameter and, if that parameter is
nil, incorporate the travel-time information provided in the response parameter.
Availability
Declared in
MKDirections.h
Constants
45
Declared in MKDirectionsRequest.h
Overview
The MKDirectionsRequest class is used by apps that work with turn-based directions. When the Maps app
sends a directions-related URL to your app, you use this class to decode the URL contents and determine the
start and end points of a route. You then use that data to compute the actual route and display the results to
the user. For apps that want to supplement their own routing directions, you can also use instances of this
class to specify route information that you want from Apple.
For apps that provide directions, upon receiving a URL in your app delegates
application:openURL:sourceApplication:annotation: method, use the
isDirectionsRequestURL: (page 50) method of this class to determine if the URL is related to routing
directions. If it is, create an instance of this class using the provided URL and extract the map items associated
with the start and end points. You can then use those points to begin your route planning.
46
MKDirectionsRequest Class Reference
Note: To provide routing directions, apps must include special keys in their Info.plist file and
be able to handle URLs sent to it by the Maps app. These keys indicate a special URL type that your
app must be prepared to handle. For information about howto implement this support, see Location
and Maps Programming Guide .
You can use this class to request directions for modes of transportation that your app does not natively handle.
For example, an app that provides subway directions might request walking directions to and from relevant
subway stations. To request directions, create a new instance of this class and configure it with the new start
and end points you need. Then create a MKDirections object and use the methods of that class to initiate
the request and process the results.
Tasks
Creating a Directions Request Object
+ isDirectionsRequestURL: (page 50)
Returns a Boolean indicating whether the specified URL contains a directions request.
initWithContentsOfURL: (page 51)
Initializes and returns a directions request object using the specified URL.
Accessing the Start and End Points
source (page 52)
Returns the starting point for routing directions.
setSource: (page 52)
Sets the starting point for routing directions.
destination (page 50)
Returns the end point for routing directions
setDestination: (page 51)
Sets the end point for routing directions
Tasks
47
Specifying Transportation Options
transportType (page 49) property
The type of conveyance to which the directions should apply.
requestsAlternateRoutes (page 49) property
A Boolean indicating whether your app wants multiple routes when they are available.
departureDate (page 48) property
The departure date for the trip.
arrivalDate (page 48) property
The arrival date for the trip.
Properties
arrivalDate
The arrival date for the trip.
@property (nonatomic, retain) NSDate *arrivalDate;
Discussion
Specifying an arrival date provides the server with extra information that it can use to optimize the returned
routes. For example, for a trip that takes place during commute hours, the server might consider alternatives
to routes that are typically congested at that time.
The use of this property is optional.
Availability
Declared in
departureDate
The departure date for the trip.
@property (nonatomic, retain) NSDate *departureDate;
Properties
48
Discussion
Specifying a departure date provides the server with extra information that it can use to optimize the returned
routes. For example, for a trip that takes place during commute hours, the server might consider alternatives
to routes that are typically congested at that time.
The use of this property is optional.
Availability
Declared in
requestsAlternateRoutes
A Boolean indicating whether your app wants multiple routes when they are available.
@property (nonatomic) BOOL requestsAlternateRoutes;
Discussion
When this property is set to NO, the server returns a single route between the start and end points. When this
property is YES, the server may return additional routes for the user to follow. The server returns additional
routes only if they are available and represent a reasonable path that the user might take.
The default value of this property is NO.
Availability
Declared in
transportType
The type of conveyance to which the directions should apply.
@property (nonatomic) MKDirectionsTransportType transportType;
Discussion
You can use this property to specify whether you want directions suited to a particular type of transportation.
For example, you can use this to specify that you want walking directions or driving directions.
The default value of this property is MKDirectionsTransportTypeAny (page 53).
Properties
49
Availability
Declared in
Class Methods
isDirectionsRequestURL:
Returns a Boolean indicating whether the specified URL contains a directions request.
+ (BOOL)isDirectionsRequestURL:(NSURL *)url
Parameters
url
The URL provided to your app.
Return Value
YES if the URL contains a directions request that your app should display to the user or NO if it does not.
Availability
Declared in
Instance Methods
destination
Returns the end point for routing directions
- (MKMapItem *)destination
Return Value
The end point for routing directions.
Availability
Class Methods
50
Declared in
initWithContentsOfURL:
Initializes and returns a directions request object using the specified URL.
- (id)initWithContentsOfURL:(NSURL *)url
Parameters
url
The URL provided to your app.
Return Value
An initialized directions request object.
Discussion
You should use the isDirectionsRequestURL: (page 50) method to verify that the specified URL is of the
correct format before calling this method to initialize the object.
Availability
Declared in
setDestination:
Sets the end point for routing directions
- (void)setDestination:(MKMapItem *)destination
Parameters
destination
The map item that represents the end point for routing directions.
Availability
Declared in
Instance Methods
51
setSource:
Sets the starting point for routing directions.
- (void)setSource:(MKMapItem *)source
Parameters
source
The map item that represents the starting point for routing directions.
Availability
Declared in
source
Returns the starting point for routing directions.
- (MKMapItem *)source
Return Value
The starting point for routing directions.
Availability
Declared in
Constants
MKDirectionsTransportType
Constants that specify the type of conveyance to be used.
typedef enum {
MKDirectionsTransportTypeAutomobile = 1 << 0,
MKDirectionsTransportTypeWalking = 1 << 1,
Constants
52
MKDirectionsTransportTypeAny = NSUIntegerMax
} MKDirectionsTransportType;
Constants
MKDirectionsTransportTypeAutomobile
Directions suitable for use while driving.
Declared in MKDirectionsTypes.h.
MKDirectionsTransportTypeWalking
Directions suitable for a pedestrian.
MKDirectionsTransportTypeAny
Directions suitable for any transportation option.
Constants
53
Declared in MKDirectionsResponse.h
Overview
The MKDirectionsResponse class provides a container for route information returned by the Apple servers.
You do not create instances of this class directly. Instead, you initiate a request for directions between two
points by calling the calculateDirectionsWithCompletionHandler: (page 41) method of an MKDirections
object. You receive an instance of this class as the result.
Tasks
Getting the End Points
source (page 55) property
The start point of the route. (read-only)
destination (page 55) property
The end point of the route. (read-only)
Getting the Route Information
routes (page 55) property
An array of route objects representing the directions between the start and end points. (read-only)
54
MKDirectionsResponse Class Reference
Properties
destination
@property (nonatomic, readonly) MKMapItem *destination
Discussion
The item in this property may contain additional details that were not included in the original item used to
create the MKDirectionsRequest object.
Availability
Declared in
routes
An array of route objects representing the directions between the start and end points. (read-only)
@property (nonatomic, readonly) NSArray *routes
Discussion
The array contains one or more MKRoute objects, each of which represents a possible set of directions for the
user to follow. If you did not request alternate routes in the original directions request, this array contains at
most one object.
Each route object contains geometry information that you can use to display that route on your apps map
view. Routes may also contain additional information that is relevant to that particular route, such as the
expected travel time and any trip advisory notices.
Availability
Declared in
source
Properties
55
@property (nonatomic, readonly) MKMapItem *source
Discussion
Availability
Declared in
Properties
56
Overview
The MKETAResponse class provides a container for travel-time information returned by the Apple servers. You
do not create instances of this class directly. Instead, you initiate a request for the travel time between two
points by calling the calculateETAWithCompletionHandler: (page 42) method of an MKDirections object.
You receive an instance of this class as the result.
Tasks
Getting the End Points
source (page 59) property
destination (page 58) property
57
MKETAResponse Class Reference
Getting the Travel Time
expectedTravelTime (page 58) property
The expected travel time in seconds. (read-only)
Properties
destination
@property (nonatomic, readonly) MKMapItem *destination
Discussion
Availability
Declared in
expectedTravelTime
@property (nonatomic, readonly) NSTimeInterval expectedTravelTime
Discussion
This expected travel time reflects the time it takes to traverse the route under ideal conditions. The actual
amount of time may vary based on traffic, weather, and other travel conditions.
Availability
Declared in
Properties
58
source
@property (nonatomic, readonly) MKMapItem *source
Discussion
This item in this property may contain additional details that were not included in the original item used to
Availability
Declared in
Properties
59
Inherits from MKPolyline : MKMultiPoint : MKShape : NSObject
Conforms to MKOverlay (MKPolyline)
NSObject (NSObject)
Declared in MKGeodesicPolyline.h
Overview
The MKGeodesicPolyline class represents a line shape that traces the shortest path along the surface of
the Earth. As with regular polyline overlays, you specify a geodesic polyline using a set of end-to-end points
where the first and last points are not connected to each other. When displayed on a two-dimensional map
view, the line segment between any two points may appear curved.
Tasks
Creating a Geodesic Polyline Overlay
+ polylineWithPoints:count: (page 61)
Creates and returns an geodesic polyline using the specified map points.
+ polylineWithCoordinates:count: (page 61)
Creates and returns an geodesic polyline using the specified coordinates.
60
MKGeodesicPolyline Class Reference
Class Methods
polylineWithCoordinates:count:
Creates and returns an geodesic polyline using the specified coordinates.
+ (instancetype)polylineWithCoordinates:(CLLocationCoordinate2D *)coords
count:(NSUInteger)count
Parameters
coords
A pointer to the array of coordinates that define the path.
count
The number of items in the coords array.
Return Value
A new geodesic polyline object.
Availability
Declared in
polylineWithPoints:count:
Creates and returns an geodesic polyline using the specified map points.
+ (instancetype)polylineWithPoints:(MKMapPoint *)points count:(NSUInteger)count
Parameters
points
A pointer to the array of map points that define the path.
count
The number of items in the points array.
Return Value
A new geodesic polyline object.
Availability
Class Methods
61
Declared in
Class Methods
62
Declared in MKLocalSearch.h
Overview
An MKLocalSearch object initiates a map-based search operation and delivers the results back to your app
asynchronously. Search objects are designed to performone search operation only. To performseveral different
searches, you must create separate instances of this class and start them separately.
You use this class to perform programmatic searches of map-based information. For example, you can use this
class to search for addresses or points-of-interest in much the same way the user might search for those items
in the Maps app.
Tasks
Initializing a Search Request
initWithRequest: (page 65)
Initializes and returns a search object configured with the specified parameters.
63
MKLocalSearch Class Reference
Performing the Search
startWithCompletionHandler: (page 65)
Starts the search and delivers the results to the specified completion handler.
searching (page 64) property
A Boolean indicating whether the search is currently in progress. (read-only)
cancel (page 64)
Cancels an in-progress search operation.
Properties
searching
A Boolean indicating whether the search is currently in progress. (read-only)
@property (nonatomic, readonly, getter=isSearching) BOOL searching;
Discussion
The value of this property is set to YES when a search is initiated and remains in that state until the search
results (or an appropriate error) are delivered, at which time the property is set to NO.
Availability
Declared in
MKLocalSearch.h
Instance Methods
cancel
Cancels an in-progress search operation.
- (void)cancel
Discussion
If no search operation is in progress, this method does nothing.
Properties
64
Availability
Declared in
MKLocalSearch.h
initWithRequest:
Initializes and returns a search object configured with the specified parameters.
- (id)initWithRequest:(MKLocalSearchRequest *)request
Parameters
request
The search request information. This parameter must not be nil.
Return Value
An initialized search object.
Discussion
This method stores a copy of the object in the request parameter. So any changes you make to your request
object after calling this method are ignored.
Availability
Declared in
MKLocalSearch.h
startWithCompletionHandler:
Starts the search and delivers the results to the specified completion handler.
- (void)startWithCompletionHandler:(MKLocalSearchCompletionHandler)completionHandler
Parameters
completionHandler
The completion handler block that processes the results. This parameter must not be nil.
Discussion
You use this method to initiate a map-based search operation. The search runs until the results are delivered,
at which point the specified completion handler is called.
Instance Methods
65
You should call this method only once to start the search operation. Calling this method while the search is
running does not stop the original search operation from finishing. However, for each subsequent call, the
search object executes your completion handler and passes an error object to it.
The provided completion handler is always executed on your apps main thread. The local search object keeps
a reference to the completion handler block until the results (or an error) are delivered, at which point it
relinquishes that reference.
Availability
Declared in
MKLocalSearch.h
Constants
MKLocalSearchCompletionHandler
A completion handler block for a search operation.
typedef void (^MKLocalSearchCompletionHandler)(MKLocalSearchResponse *response, NSError
*error);
Discussion
The response parameter contains the search results. If an error occurred, this parameter is set to nil
and an appropriate error object is provided in the error parameter.
The error parameter is nil if the search was successful. If an error occurred during the operation, this
parameter is set to an appropriate error object.
This block has no return value.
Availability
Declared in
MKLocalSearch.h
Constants
66
Conforms to NSCopying
NSObject (NSObject)
Declared in MKLocalSearchRequest.h
Overview
An MKLocalSearchRequest object is a utility object that you use to specify map-based search parameters.
After creating an instance of this object, you can assign a natural language string containing the address or
point-of-interest to search for. You can also specify a specific map region to narrow the search results. You
then use the configured object to initialize an MKLocalSearch object and perform your search.
Tasks
Configuring the Search Parameters
naturalLanguageQuery (page 68) property
A string containing the desired search item.
region (page 68) property
A map region that provides a hint as to where to search.
67
MKLocalSearchRequest Class Reference
Properties
naturalLanguageQuery
A string containing the desired search item.
@property (nonatomic, copy) NSString *naturalLanguageQuery;
Discussion
You specify this parameter as a string describing the map-based itemyou want to look for. The text is equivalent
to what the user would type in a search field in the Maps app. For example, the text might contain all or part
of an address or it might contain the name of a point of interest.
This property can not be nil.
Availability
Declared in
region
A map region that provides a hint as to where to search.
@property (nonatomic, assign) MKCoordinateRegion region;
Discussion
You can use this parameter to narrow the list of search results to those inside or close to the specified region.
Specifying a region does not guarantee that the results will all be inside the region. It is merely a hint to the
search engine.
Availability
Declared in
MKLocalSearchRequest Class Reference
Properties
68
Declared in MKLocalSearchResponse.h
Overview
An MKLocalSearchResponse object contains the search results from a map-based search that was started
using an MKLocalSearch object.
Tasks
MethodGroup
mapItems (page 70) property
An array of map items representing the search results. (read-only)
boundingRegion (page 70) property
The map region that encloses the returned search results. (read-only)
69
MKLocalSearchResponse Class Reference
Properties
boundingRegion
The map region that encloses the returned search results. (read-only)
@property (nonatomic, readonly) MKCoordinateRegion boundingRegion;
Discussion
The returned region is the smallest bounding box that encloses all of the map items. If there is only one search
result, the size of the region may be (0, 0).
Availability
Declared in
mapItems
An array of map items representing the search results. (read-only)
@property (nonatomic, readonly) NSArray *mapItems;
Discussion
This property contains an array of MKMapItem objects, each of which represents a returned search result. You
can use these objects to retrieve information about the search result, such as the name of the point of interest,
the address, the geographic location, and so on.
Availability
Declared in
MKLocalSearchResponse Class Reference
Properties
70
NSSecureCoding
NSObject (NSObject)
Declared in MKMapView.h
Overview
An MKMapCamera object describes a virtual camera that you use to define the appearance of the map. Acamera
object creates a virtual viewpoint above the map surface and affects how the map renders its tiles and other
content. You use a camera object to specify the location of the camera on the map, the compass heading that
corresponds to the cameras viewing direction, the pitch of the camera relative to the map perpendicular, and
the cameras altitude above the map. These factors let you create a map view that is not just flat but offers a
more 3D-like experience.
After creating an instance of this class, configure it with the desired attributes and assign it to your map view.
When you assign a camera to your map view, the map centers the map using the value in your camera objects
centerCoordinate (page 72) property, updating the maps own region information in the process. The map
also takes the cameras the pitch and altitude into account when calculating the visible region, ensuring that
the region always encompasses the visible content on the map.
Tasks
Getting a Camera Object
+ camera (page 74)
Returns a new camera object for you to configure.
71
MKMapCamera Class Reference
+ cameraLookingAtCenterCoordinate:fromEyeCoordinate:eyeAltitude: (page 74)
Returns a new camera object using the specified viewing angle information.
Configuring the Viewing Angle
centerCoordinate (page 72) property
The map coordinate at the center of the map view.
heading (page 73) property
The heading of the camera (measured in degrees) relative to true north.
pitch (page 73) property
The viewing angle of the camera, measured in degrees.
altitude (page 72) property
The altitude above the ground, measured in meters.
Properties
altitude
The altitude above the ground, measured in meters.
@property (nonatomic) CLLocationDistance altitude;
Discussion
The value you specify for this property must not be less than 0.
Changing this property may also change the maximum pitch that is allowed for the map. If the current pitch
value exceeds the new maximum, the pitch (page 73) property is clamped to the new maximum.
Availability
Declared in
MKMapCamera.h
centerCoordinate
Properties
72
@property (nonatomic) CLLocationCoordinate2D centerCoordinate;
Discussion
This point represents the coordinate on which the map should be centered. When the camera pitch is 0, this
property also corresponds to the geographic position of the camera. Changing the pitch to a nonzero value
moves the camera but does not affect this property.
Availability
Declared in
MKMapCamera.h
heading
The heading of the camera (measured in degrees) relative to true north.
@property (nonatomic) CLLocationDirection heading;
Discussion
The value 0 means that the top edge of the map view corresponds to true north. The value 90 means the top
of the map is pointing due east. The value 180 means the top of the map points due south, and so on.
Availability
Declared in
MKMapCamera.h
pitch
The viewing angle of the camera, measured in degrees.
@property (nonatomic) CGFloat pitch;
Discussion
A value of 0 results in a camera pointed straight down at the map. Angles greater than 0 result in a camera
that is pitched toward the horizon by the specified number of degrees. If the map type is
MKMapTypeSatellite (page 140) or MKMapTypeHybrid (page 140), the pitch value is clamped to 0.
The value in this property may be clamped to a maximum value to maintain map readability. There is no fixed
maximum value, though, because the actual maximum value is dependent on the current altitude of the
camera.
Properties
73
Availability
Declared in
MKMapCamera.h
Class Methods
camera
Returns a new camera object for you to configure.
+ (instancetype)camera
Return Value
A new camera object.
Discussion
You must change the values of the returned camera object before using it.
Availability
Declared in
MKMapCamera.h
cameraLookingAtCenterCoordinate:fromEyeCoordinate:eyeAltitude:
Returns a new camera object using the specified viewing angle information.
+
(instancetype)cameraLookingAtCenterCoordinate:(CLLocationCoordinate2D)centerCoordinate
fromEyeCoordinate:(CLLocationCoordinate2D)eyeCoordinate
eyeAltitude:(CLLocationDistance)eyeAltitude
Parameters
centerCoordinate
The coordinate point on which the map should be centered.
Class Methods
74
eyeCoordinate
The coordinate point at which to place the camera. If the value for this parameter is equal to the value
in the centerCoordinate parameter, the map is displayed as if the camera is looking straight down. If
this point is offset fromthe centerCoordinate value, the map is displayed with an appropriate heading
and pitch angle.
eyeAltitude
The altitude (in meters) above the ground at which to place the camera.
Return Value
A new camera object initialized with the specified information.
Discussion
This method calculates the required pitch and heading angles to accommodate the specified eye position and
altitude.
Availability
Declared in
MKMapCamera.h
Class Methods
75
Declared in MKMapItem.h
Related sample code
MapSearch
Using NSXMLParser to parse XML documents
Overview
The MKMapItem class encapsulates information about a specific point on a map. This information includes the
map location and any other data that might be relevant, such as the name of a business at that location. Apps
use this class to share map-related data with the Maps app.
You use this class in one of two ways. If your app is able to display point-to-point directions, the Maps app can
send a directions request to your app in response to a request by the user to use your app for routing. In that
instance, the directions request contains map items with the start and end points to use when creating the
directions. The other way to use map items is to create them in your app and then ask the Maps app to display
them. For example, if your app allows the user to search for local businesses or points of interest, you can
create map items for each location and ask Maps to display pins at the corresponding locations.
Usually, you use this class to represent fixed locations on the map, but you can also use the
mapItemForCurrentLocation (page 80) method to get a map item that represents the users current location.
For privacy reasons, and because the users location can change, the map item returned by that method does
not contain any coordinate data. When you need the actual location of the user, you must use the Core Location
framework to retrieve it.
76
MKMapItem Class Reference
Usage Special Considerations
To determine whether a class is available at runtime in a given iOS release, you typically check whether that
class is nil. Unfortunately, this test is not cleanly accurate for MKMapItem. Although this class was publicly
available starting with iOS 6.0, it was in development prior to that. Although the class exists in earlier releases,
you should not attempt to use it in those releases.
To determine at runtime whether you can use map items in your application, test whether the class and the
openMapsWithItems:launchOptions: (page 81) class method exist. That method was not added to the class
until iOS 6.0. The code might look like the following:
Class itemClass = [MKMapItem class];
if (itemClass && [itemClass
respondsToSelector:@selector(openMapsWithItems:launchOptions:)]) {
// Use class
}
Tasks
Creating and Initializing Map Items
+ mapItemForCurrentLocation (page 80)
Creates and returns a singleton map item object representing the devices current location.
initWithPlacemark: (page 82)
Initializes and returns a map item object using the specified placemark object.
Accessing the Map Item Attributes
placemark (page 79) property
The placemark object containing the location information.
isCurrentLocation (page 78) property
A Boolean value indicating whether the map item represents the users current location.
name (page 78) property
The descriptive name associated with the map item.
phoneNumber (page 79) property
The phone number associated with a business at the specified location.
Tasks
77
url (page 80) property
The URL associated with the specified location.
Launching the Maps App
+ openMapsWithItems:launchOptions: (page 81)
Open the Maps app and display the specified map items.
openInMapsWithLaunchOptions: (page 82)
Open the Maps app and display this map item.
Properties
isCurrentLocation
A Boolean value indicating whether the map item represents the users current location.
@property (nonatomic, readonly) BOOL isCurrentLocation
Discussion
If the value of this property is YES, the map item represents the users current location. If YES, the value in the
placemark (page 79) property is set to nil.
Availability
Declared in
MKMapItem.h
name
The descriptive name associated with the map item.
@property (nonatomic, copy) NSString *name
Discussion
Use this property to specify the name associated with the location. For example, if there is a business at the
specified location, you would use this property to specify the name of the business.
Properties
78
If this map item represents the users current location, the value in property is set to a localized version of
Current Location.
Availability
Related Sample Code
MapSearch
Declared in
MKMapItem.h
phoneNumber
The phone number associated with a business at the specified location.
@property (nonatomic, copy) NSString *phoneNumber
Discussion
If there is a relevant phone number associated with the location, such as a phone number for a business at
the location, use this property to specify that value.
Availability
Declared in
MKMapItem.h
placemark
The placemark object containing the location information.
@property (nonatomic, readonly, retain) MKPlacemark *placemark
Discussion
If you created the map item using the mapItemForCurrentLocation (page 80) method, the value of this
property is nil and the isCurrentLocation (page 78) property is set to YES.
Availability
Related Sample Code
MapSearch
Properties
79
Declared in
MKMapItem.h
url
The URL associated with the specified location.
@property (nonatomic, retain) NSURL *url
Discussion
If there is a relevant URL associated with the location, such as a URL for a business at the location, use this
property to specify that value.
Availability
Related Sample Code
MapSearch
Declared in
MKMapItem.h
Class Methods
mapItemForCurrentLocation
Creates and returns a singleton map item object representing the devices current location.
+ (MKMapItem *)mapItemForCurrentLocation
Return Value
An MKMapItem object representing the current location.
Availability
Declared in
MKMapItem.h
Class Methods
80
openMapsWithItems:launchOptions:
Open the Maps app and display the specified map items.
+ (BOOL)openMapsWithItems:(NSArray *)mapItems launchOptions:(NSDictionary
*)launchOptions
Parameters
mapItems
An array containing one or more MKMapItem objects representing the items you want to display on the
map. This parameter may be nil.
launchOptions
Additional information that the Maps app can use to configure the map display. For example, you can
use the launch options to specify the visible map region and the map type. For a list of keys you can put
into this dictionary, see Launch Options Dictionary Keys (page 83).
You may specify nil for this parameter.
Return Value
YES if the map items were successfully opened by the Maps app, or NO if there was an error.
Discussion
You use this method to pass one or more map items to the Maps app. For example, you might use this method
to ask the Maps app to display location-based search results generated by your app. Maps displays pins at
each location you specify and uses the contents of each map item object to display additional information.
If you specify the MKLaunchOptionsDirectionsModeKey (page 83) option in the launchOptions dictionary,
the mapItems array must have no more than two items in it. If the array contains one item, the Maps app
generates directions from the users current location to the location specified by the map item. If the array
contains two items, the Maps app generates directions from the location of the first item to the location of the
second item in the array.
If you do not include the MKLaunchOptionsMapCenterKey (page 84) and MKLaunchOptionsMapSpanKey (page
84) keys in your launchOptions dictionary, Maps constructs a region that encompasses the provided items.
It uses this region to set the visible portion of the map.
Availability
Declared in
MKMapItem.h
Class Methods
81
Instance Methods
initWithPlacemark:
Initializes and returns a map item object using the specified placemark object.
- (id)initWithPlacemark:(MKPlacemark *)placemark
Parameters
placemark
The placemark object corresponding to the desired map location. This parameter must not be nil.
Return Value
An initialized map item object.
Discussion
Use this method to create a map itemfor an existing placemark. Do not use it to create a map itemrepresenting
the users current location. To do that, use the mapItemForCurrentLocation (page 80) method instead.
Availability
Declared in
MKMapItem.h
openInMapsWithLaunchOptions:
Open the Maps app and display this map item.
- (BOOL)openInMapsWithLaunchOptions:(NSDictionary *)launchOptions
Parameters
launchOptions
Additional information that the Maps app can use to configure the map display. For example, you can
use the launch options to specify the visible map region and the map type. For a list of keys you can put
into this dictionary, see Launch Options Dictionary Keys (page 83).
This parameter may be nil.
Return Value
YES if this map item was successfully opened by the Maps app, or NO if there was an error.
Instance Methods
82
Discussion
You use this method to pass the current map item to the Maps app. If your map item contains descriptive
information about the location (such as a name or URL), the Maps app displays that information at the specified
coordinate.
If you specify the MKLaunchOptionsDirectionsModeKey (page 83) option in the launchOptions dictionary,
the Maps app interprets that as an attempt to map from the users current location to the location specified
by this map item.
If you do not include the MKLaunchOptionsMapCenterKey (page 84) and MKLaunchOptionsMapSpanKey (page
84) keys in your launchOptions dictionary, Maps constructs a region around the current item. It uses that
region to set the visible portion of the map.
Availability
Related Sample Code
Declared in
MKMapItem.h
Constants
Launch Options Dictionary Keys
Launch options to specify when opening map items in the Maps app.
NSString * const MKLaunchOptionsDirectionsModeKey;
NSString * const MKLaunchOptionsMapTypeKey;
NSString * const MKLaunchOptionsMapCenterKey;
NSString * const MKLaunchOptionsMapSpanKey;
NSString * const MKLaunchOptionsShowsTrafficKey;
Constants
MKLaunchOptionsDirectionsModeKey
The value of this key is an NSString corresponding to one of the values described in Directions Mode
Values (page 84). You specify this key to tell the Maps app to treat the provided map items as start
and end points for routing directions. If this key is not present, Maps displays pins at the specified locations.
Declared in MKMapItem.h.
Constants
83
MKLaunchOptionsMapTypeKey
The value of this key is an NSNumber object whose value is an integer corresponding to an
MKMapType (page 139) value. This value represents the type of map (standard, satellite, hybrid) to display.
MKLaunchOptionsMapCenterKey
The value of this key is an NSValue object that contains an encoded CLLocationCoordinate2D
structure. This value represents the location on which the map view should be centered.
MKLaunchOptionsMapSpanKey
The value of this key is an NSValue object that contains an encoded MKCoordinateSpan (page 308)
structure. This value represents the region that the map view should display.
MKLaunchOptionsShowsTrafficKey
The value of this key is an NSNumber object that contains a Boolean value. This value indicates whether
traffic information should be displayed on the map. If you do not specify this key, Maps uses its current
settings to determine whether or not to display traffic.
Discussion
You specify these keys in the launch options dictionary for the openMapsWithItems:launchOptions: (page
81) or openInMapsWithLaunchOptions: (page 82) method.
Directions Mode Values
Strings representing the possible values of the MKLaunchOptionsDirectionsModeKey (page 83) key.
NSString * const MKLaunchOptionsDirectionsModeDriving;
NSString * const MKLaunchOptionsDirectionsModeWalking;
Constants
84
Constants
MKLaunchOptionsDirectionsModeDriving
Tells the Maps app to display driving directions between the start and end points.
MKLaunchOptionsDirectionsModeWalking
Tells the Maps app to display walking directions between the start and end points.
Constants
85
Declared in MKMapSnapshot.h
Overview
An MKMapSnapshot object contains an image generated by a snapshotter object. You do not create instances
of this class directly. Instead, you use an MKMapSnapshotter object capture the map contents asynchronously.
Upon completion, the snapshotter object generates an image based on the options you provide and delivers
that image inside an instance of this class.
Snapshot images do not include any custom overlays or annotations that your app added to the map view. If
you want your annotations and overlays to appear on the final image, you must drawthemyourself. To position
those items correctly on the image, use the pointForCoordinate: (page 87) method of this class to translate
the overlay or annotation coordinate value to an appropriate location inside the images coordinate space.
Tasks
Getting the Snapshot Image
image (page ?) property
The image of the maps content. (read-only)
Getting Points on the Image
pointForCoordinate: (page 87)
Converts the specified map coordinate to a point in the coordinate space of the image.
86
MKMapSnapshot Class Reference
Properties
image
The image of the maps content. (read-only)
@property (nonatomic, readonly) UIImage *image;
Availability
Declared in
MKMapSnapshot.h
Instance Methods
pointForCoordinate:
Converts the specified map coordinate to a point in the coordinate space of the image.
- (CGPoint)pointForCoordinate:(CLLocationCoordinate2D)coordinate
Parameters
coordinate
A map coordinate that you want to convert.
Return Value
The point in the images coordinate space that corresponds to the map location.
Discussion
If you want to display additional views or content on top of the image, you can use this method to find an
appropriate point at which to draw those items.
Availability
Declared in
MKMapSnapshot.h
MKMapSnapshot Class Reference
Properties
87
NSObject (NSObject)
Declared in MKMapSnapshotOptions.h
Overview
The MKMapSnapshotOptions class specifies the options to use when capturing map-based imagery. After
creating and configuring an instance of this class, you pass that instance to an MKMapSnapshotter object.
The snapshotter uses the options you specify to determine the portion of the map to capture, the viewing
angle to use for the camera, and the map appearance.
Tasks
Configuring the Map Data
camera (page 89) property
The camera to use when taking the map snapshot.
The map region that you want to capture.
rect (page 90) property
The map rect that you want to capture.
mapType (page 89) property
The maps visual style.
showsPointsOfInterest (page 91) property
A Boolean indicating whether the map displays point-of-interest information.
88
MKMapSnapshotOptions Class Reference
showsBuildings (page 91) property
A Boolean indicating whether the map displays extruded building information.
Configuring the Image Output
size (page ?) property
The size of the image that you want to create.
scale (page 90) property
The scale factor to use when creating the image.
Properties
camera
The camera to use when taking the map snapshot.
@property (nonatomic, copy) MKMapCamera *camera
Discussion
Specify a camera object if you want to change the pitch, altitude, or heading information applied to the map.
Availability
Declared in
mapType
The maps visual style.
@property (nonatomic, assign) MKMapType mapType;
Discussion
The default value of this property is MKMapTypeStandard (page 140).
Availability
Properties
89
Declared in
rect
The map rect that you want to capture.
@property (nonatomic, assign) MKMapRect rect
Discussion
Use this property to specify the map using map view points. If you assign a value for this property, the value
in the region (page 90) property is updated to match the corresponding map rect as closely as possible.
The default value of this property is set to a map rect that encompasses the users country, as determined by
the current locale information.
region
The map region that you want to capture.
@property (nonatomic, assign) MKCoordinateRegion region;
Discussion
Use this property to specify the map using geographical coordinates. If you assign a value for this property,
the value in the rect (page 90) property is updated to match the corresponding region as closely as possible.
The default value of this property is set to a region that encompasses the users country, as determined by the
current locale information.
Availability
Declared in
scale
The scale factor to use when creating the image.
@property (nonatomic, assign) CGFloat scale;
Properties
90
Discussion
The value of this property is either 1.0 or 2.0, depending on whether the device has a standard or Retina
display. Set the value to 1.0 if you want to display the resulting image on a standard resolution display. Set
the value to 2.0 if you want to display the image on a Retina display or want to use the image for printing.
This property is set to a default value that corresponds to the resolution of the current devices display. You
can change the value as needed to generate an image suitable for display on a different device.
Availability
Declared in
showsBuildings
@property (nonatomic) BOOL showsBuildings;
Discussion
When this property is set to YES and the camera has a pitch angle greater than 0, the map extrudes buildings
so that they appear to extend above the map plane, creating a 3D effect. The mapType (page 89) property
must be set to MKMapTypeStandard (page 140) for extruded buildings to be displayed. The default value of this
property is YES.
Availability
Declared in
showsPointsOfInterest
@property (nonatomic) BOOL showsPointsOfInterest;
Discussion
When this property is set to YES, the map displays icons and labels for restaurants, schools, and other relevant
points of interest. The default value of this property is YES.
Properties
91
Availability
Declared in
size
The size of the image that you want to create.
@property (nonatomic, assign) CGSize size;
Discussion
The default value of this property is 256 by 256 points.
Availability
Declared in
Properties
92
Declared in MKMapSnapshotter.h
Overview
An MKMapSnapshotter object captures map-based imagery asynchronously. Use instances of this class in
situations where you want to capture the iOS-provided map content, including the map tiles and imagery. The
snapshotter object always captures the best image possible, loading all of the available map tiles before
capturing the image.
You use a snapshotter object in conjunction with an MKMapSnapshotOptions object. The snapshot options
specify the map configuration to use during the capture process, including which portion of the map you want
to capture.
Note: Snapshotter objects do not capture the visual representations of any overlays or annotations
that your app creates. If you want those items to appear in the final snapshot, you must draw them
on the resulting snapshot image. For more information about drawing custom content on map
snapshots, see MKMapSnapshot Class Reference .
Tasks
Initializing a Snapshotter Object
initWithOptions: (page 95)
Initializes and returns a snapshotter object based on the specified options.
93
MKMapSnapshotter Class Reference
Generating a Snapshot
startWithCompletionHandler: (page 95)
Submits the request to create a snapshot and delivers the results to the specified block.
startWithQueue:completionHandler: (page 96)
Submits the request to create a snapshot and executes the resulting block on the specified queue.
cancel (page 94)
Cancels the current request to create a snapshot.
loading (page 94) property
A Boolean indicating whether the snapshotter is currently generating an image. (read-only)
Properties
loading
A Boolean indicating whether the snapshotter is currently generating an image. (read-only)
@property (nonatomic, readonly, getter=isLoading) BOOL loading;
Availability
Declared in
MKMapSnapshotter.h
Instance Methods
cancel
Cancels the current request to create a snapshot.
- (void)cancel
Discussion
If the snapshotter is not in the process of generating the snapshot, calling this method does nothing.
Availability
Properties
94
Declared in
MKMapSnapshotter.h
initWithOptions:
Initializes and returns a snapshotter object based on the specified options.
- (instancetype)initWithOptions:(MKMapSnapshotOptions *)options
Parameters
options
The options to use when capturing the map imagery. If you specify nil for this property, the snapshotter
uses a set of default options that capture an image of the current users country.
Return Value
An initialized snapshotter option.
Availability
Declared in
MKMapSnapshotter.h
startWithCompletionHandler:
Submits the request to create a snapshot and delivers the results to the specified block.
- (void)startWithCompletionHandler:(MKMapSnapshotCompletionHandler)completionHandler
Parameters
completionHandler
The block to call with the resulting snapshot. This block is executed on the apps main thread and must
not be nil.
Discussion
Call this method to begin generating a snapshot image based on the specified parameters. This method
executes the request asynchronously.
The snapshotter delivers the final image to your app only when it is running in the foreground. The snapshotter
must render the final image while your app is in the foreground. If you start generating a snapshot while the
app is in the background, or if your app moves to the background while a snapshot is in progress, this behavior
delays the delivery of the snapshot until your app returns to the foreground.
Instance Methods
95
In OS X, this method creates both standard and high-resolution representations of the map data and includes
both in the returned image object. In iOS, you must specify the image scale you want using the snapshot
options, which default to the scale on the current device.
Availability
Declared in
MKMapSnapshotter.h
startWithQueue:completionHandler:
Submits the request to create a snapshot and executes the resulting block on the specified queue.
- (void)startWithQueue:(dispatch_queue_t)queue
completionHandler:(MKMapSnapshotCompletionHandler)completionHandler
Parameters
queue
The dispatch queue on which to execute the block specified by the completionHandler parameter.
completionHandler
The block to call with the resulting snapshot. This block must not be nil.
Discussion
Call this method to begin generating a snapshot image based on the specified parameters. This method
executes the request asynchronously. When rendering is complete, the snapshotter delivers the results to your
block on the dispatch queue in the queue parameter.
The snapshotter delivers the final image to your app only when it is running in the foreground. The snapshotter
must render the final image while your app is in the foreground. If you start generating a snapshot while the
app is in the background, or if your app moves to the background while a snapshot is in progress, this behavior
delays the delivery of the snapshot until your app returns to the foreground.
In OS X, this method creates both standard and high-resolution representations of the map data and includes
both in the returned image object. In iOS, you must specify the image scale you want using the snapshot
options, which default to the scale on the current device.
Availability
Declared in
MKMapSnapshotter.h
Instance Methods
96
Constants
MKMapSnapshotCompletionHandler
A block that processes the results of a snapshot request.
typedef void (^MKMapSnapshotCompletionHandler)(MKMapSnapshot *snapshot, NSError *error);
Discussion
This block takes the following parameters:
snapshot
The image data that was generated or nil if an error occurred
error
The error that occurred or nil if the snapshot was generated successfully.
Availability
Declared in
MKMapSnapshotter.h
Constants
97
Conforms to NSCoding
NSCoding (UIView)
NSObject (NSObject)
Declared in MapKit/MKMapView.h
Related sample code
Breadcrumb
KMLViewer
MapCallouts
PhotosByLocation
Regions
Overview
An MKMapView object provides an embeddable map interface, similar to the one provided by the Maps
application. You use this class as-is to display map information and to manipulate the map contents from your
application. 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.
98
MKMapView Class Reference
When you initialize a map view, you should specify the initial region for that map to display. You do this by
setting the region (page 109) property of the map. A region is defined by a center point and a horizontal and
vertical distance, referred to as the span. The span defines how much of the map at the given point should be
visible and is also how you set the zoom level. Specifying a large span results in the user seeing a wide
geographical area and corresponds to a low zoom level. Specifying a small span results in the user seeing a
more narrow geographical area and corresponds to a higher zoom level.
In addition to setting the span programmatically, the MKMapView class supports many standard interactions
for changing the position and zoom level of the map. In particular, map views support flick and pinch gestures
for scrolling around the map and zooming in and out. Support for these gestures is enabled by default but
can also be disabled using the scrollEnabled (page 111) and zoomEnabled (page 115) properties.
You can also use projected map coordinates instead of regions to specify some values. When you project the
curved surface of the globe onto a flat surface, you get a two-dimensional version of a map where longitude
lines appear to be parallel. To specify locations and distances, you use the MKMapPoint (page 309),
MKMapSize (page 310), and MKMapRect (page 311) data types.
Although you should not subclass the MKMapView class itself, you can get information about the map views
behavior by providing a delegate object. The map view calls the methods of your custom delegate to let it
knowabout changes in the map status and to coordinate the display of customannotations, which are described
in more detail in Annotating the Map (page 99). The delegate object can be any object in your application
as long as it conforms to the MKMapViewDelegate protocol. For more information about implementing the
delegate object, see MKMapViewDelegate Protocol Reference .
Annotating the Map
The MKMapView class supports the ability to annotate the map with custom information. Because a map may
have potentially large numbers of annotations, map views differentiate between the annotation objects used
to 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 are
typically implemented using existing classes in your applications data model. This allows you to manipulate
the annotation data directly but still make it available to the map view. Each annotation object contains
information about the annotations location on the map along with descriptive information that can be displayed
in a callout.
Overview
99
The presentation of annotation objects on the screen is handled by an annotation view, which is an instance
of the MKAnnotationView class. An annotation view is responsible for presenting the annotation data in a
way that makes sense. For example, the Maps application uses a pin icon to denote specific points of interest
on a map. (The Map Kit framework offers the MKPinAnnotationView class for similar annotations in your
own 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 mechanism
for queueing annotation views that are not in use. Annotation views with a reuse identifier can be detached
and queued internally by the map view when they move offscreen. This feature improves memory use by
keeping 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 view
uses the coordinate data in each annotation object to determine when the corresponding annotation view
needs to appear onscreen. When an annotation moves onscreen, the map view asks its delegate to create a
corresponding annotation view. If your application has different types of annotations, it can define different
annotation view classes to represent each type.
Adding Overlays to the Map
You can use overlays to layer content over a wide portion of the map. An overlay object is any object that
conforms to the MKOverlay protocol. An overlay object is a data object that contains the points needed to
specify the shape and size of the overlay and its location on the map. Overlays can represent shapes such as
circles, rectangles, multi-segment lines, and simple or complex polygons. You can also define your own custom
overlays to represent other shapes.
In iOS 7 and later, the presentation of an overlay is handled by an overlay renderer object, which is an instance
of the MKOverlayRenderer class. The job of the renderer is to draw the overlays content onto the screen
when 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 also
define a custom renderer that draws both the bus route and icons at the location of each bus stop. When
specifying overlays, you can add them to specific levels of the map, which allows them to be rendered above
or belowother types of map content. Prior to iOS 7, overlays are drawn on onscreen using overlay views, which
are instances of the MKOverlayView class.
When configuring your map interface, you can add overlay objects at any time. The map view uses the data
in each overlay object to determine when the corresponding overlay view needs to appear onscreen. When
an overlay moves onscreen, the map view asks its delegate to create a corresponding overlay renderer.
Overview
100
Tasks
Accessing Map Properties
mapType (page 108) property
The type of data displayed by the map view.
zoomEnabled (page 115) property
A Boolean value that determines whether the user may use pinch gestures to zoom in and out of the
map.
scrollEnabled (page 111) property
A Boolean value that determines whether the user may scroll around the map.
pitchEnabled (page 109) property
A Boolean value indicating whether the map cameras pitch information is used.
rotateEnabled (page 110) property
A Boolean value indicating whether the map cameras heading information is used.
Accessing the Delegate
delegate (page 108) property
The receivers delegate.
Manipulating the Visible Portion of the Map
The area currently displayed by the map view.
setRegion:animated: (page 135)
Changes the currently visible region and optionally animates the change.
centerCoordinate (page 107) property
setCenterCoordinate:animated: (page 134)
Changes the center coordinate of the map and optionally animates the change.
showAnnotations:animated: (page 138)
Sets the visible region so that the map displays the specified annotations.
visibleMapRect (page 114) property
Tasks
101
setVisibleMapRect:animated: (page 137)
Changes the currently visible portion of the map and optionally animates the change.
setVisibleMapRect:edgePadding:animated: (page 137)
Changes the currently visible portion of the map, allowing you to specify additional space around the
edges.
Configuring the Maps Appearance
camera (page 106) property
The camera used for determining the appearance of the map.
setCamera:animated: (page 134)
Changes the camera used for determining the maps viewing parameters and optionally animates the
change.
showsPointsOfInterest (page 112) property
showsBuildings (page 111) property
Displaying the Users Location
showsUserLocation (page 112) property
A Boolean value indicating whether the map should try to display the users location.
userLocationVisible (page 113) property
A Boolean value indicating whether the devices current location is visible in the map view. (read-only)
userLocation (page 113) property
The annotation object representing the users current location. (read-only)
userTrackingMode (page 114) property
The mode used to track the user location.
setUserTrackingMode:animated: (page 136)
Sets the mode used to track the user location with optional animation.
Tasks
102
Annotating the Map
annotations (page 105) property
The complete list of annotations associated with the receiver. (read-only)
addAnnotation: (page 115)
Adds the specified annotation to the map view.
addAnnotations: (page 116)
Adds an array of annotation objects to the map view.
removeAnnotation: (page 130)
Removes the specified annotation object from the map view.
removeAnnotations: (page 131)
Removes an array of annotation objects from the map view.
viewForAnnotation: (page 138)
Returns the annotation view associated with the specified annotation object, if any.
annotationsInMapRect: (page 119)
Returns the annotation objects located in the specified map rectangle.
annotationVisibleRect (page 106) property
The visible rectangle where annotation views are currently being displayed. (read-only)
dequeueReusableAnnotationViewWithIdentifier: (page 122)
Returns a reusable annotation view located by its identifier.
Managing Annotation Selections
selectedAnnotations (page 111) property
The annotations that are currently selected.
selectAnnotation:animated: (page 133)
Selects the specified annotation and displays a callout view for it.
deselectAnnotation:animated: (page 123)
Deselects the specified annotation and hides its callout view.
Accessing Overlays
overlays (page 108) property
The overlay objects currently associated with the map view. (read-only)
Tasks
103
overlaysInLevel: (page 129)
The overlay objects in the specified level of the map.
rendererForOverlay: (page 133)
Returns the renderer object used to draw the contents of the specified overlay object.
viewForOverlay: (page 139) Deprecated in iOS 7.0
Returns the view associated with the overlay object if any. (Deprecated. Use the
rendererForOverlay: (page 133) method instead.)
Adding and Inserting Overlays
addOverlay:level: (page 117)
Adds the overlay object to the map at the specified level.
addOverlays:level: (page 118)
Adds an array of overlay objects to the map at the specified level.
addOverlay: (page 116)
Adds a single overlay object to the map.
addOverlays: (page 118)
Adds an array of overlay objects to the map.
insertOverlay:atIndex:level: (page 126)
Inserts an overlay object into the level at the specified index.
insertOverlay:atIndex: (page 125)
Inserts an overlay object into the list associated with the map.
insertOverlay:aboveOverlay: (page 125)
Inserts one overlay object on top of another.
insertOverlay:belowOverlay: (page 127)
Inserts one overlay object below another.
exchangeOverlay:withOverlay: (page 123)
Exchanges the positions of the two overlay objects.
exchangeOverlayAtIndex:withOverlayAtIndex: (page 124)
Exchanges the position of two overlay objects.
Tasks
104
Removing Overlays
removeOverlay: (page 131)
Removes a single overlay object from the map.
removeOverlays: (page 132)
Removes one or more overlay objects from the map.
Converting Map Coordinates
convertCoordinate:toPointToView: (page 120)
Converts a map coordinate to a point in the specified view.
convertPoint:toCoordinateFromView: (page 120)
Converts a point in the specified views coordinate system to a map coordinate.
convertRegion:toRectToView: (page 122)
Converts a map region to a rectangle in the specified view.
convertRect:toRegionFromView: (page 121)
Converts a rectangle in the specified views coordinate system to a map region.
Adjusting Map Regions and Rectangles
regionThatFits: (page 129)
Adjusts the aspect ratio of the specified region to ensure that it fits in the map views frame.
mapRectThatFits: (page 127)
Adjusts the aspect ratio of the specified map rectangle to ensure that it fits in the map views frame.
mapRectThatFits:edgePadding: (page 128)
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)
Properties
105
@property(nonatomic, readonly) NSArray *annotations
Discussion
The objects in this array must adopt the MKAnnotation protocol. If no annotations are associated with the
map view, the value of this property is nil.
Availability
See Also
Declared in
MKMapView.h
annotationVisibleRect
The visible rectangle where annotation views are currently being displayed. (read-only)
@property(nonatomic, readonly) CGRect annotationVisibleRect
Availability
Declared in
MKMapView.h
camera
The camera used for determining the appearance of the map.
@property(nonatomic, copy) MKMapCamera *camera
Discussion
A camera object defines a point above the maps surface from which to view the map. Applying a camera to
a map has the effect of giving the map a 3D-like appearance. You can use a camera to rotate the map so that
it is oriented to match the users heading or to apply a pitch angle to tilt the plane of the map.
Properties
106
Assigning a new camera to this property updates the map immediately and without animating the change. If
you want to animate changes in camera position, use the setCamera:animated: (page 134) method instead.
You must not set this property to nil. To restore the map to a flat appearance, apply a camera with a pitch
angle of 0, which yields a camera looking straight down onto the map surface.
Availability
See Also
setCamera:animated: (page 134)
Declared in
MKMapView.h
centerCoordinate
@property(nonatomic) CLLocationCoordinate2D centerCoordinate
Discussion
Changing the value in this property centers the map on the new coordinate without changing the current
zoom level. It also updates the values in the region property to reflect the new center coordinate and the
new 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.
Availability
See Also
@property region (page 109)
Related Sample Code
Regions
Declared in
MKMapView.h
Properties
107
delegate
The receivers delegate.
@property(nonatomic, assign) id<MKMapViewDelegate> delegate
Discussion
A map view sends messages to its delegate regarding the loading of map data and changes in the portion of
the map being displayed. The delegate also manages the annotation views used to highlight points of interest
on the map.
The delegate should implement the methods of the MKMapViewDelegate protocol.
Availability
Declared in
MKMapView.h
mapType
The type of data displayed by the map view.
@property(nonatomic) MKMapType mapType
Discussion
Changing the value in this property may cause the receiver to begin loading new map content. For example,
changing fromMKMapTypeStandard to MKMapTypeSatellite might cause it to begin loading the satellite
imagery needed for the map. If new data is needed, however, it is loaded asynchronously and appropriate
messages are sent to the receivers delegate indicating the status of the operation.
Availability
Related Sample Code
GeocoderDemo
Declared in
MKMapView.h
overlays
The overlay objects currently associated with the map view. (read-only)
Properties
108
@property(nonatomic, readonly) NSArray *overlays
Discussion
This property contains the union of all overlays at the different levels of the map. The objects in this array must
adopt the MKOverlay protocol. If no overlays are associated with the map view, the value of this property is
an empty array.
The order of the objects in this array does not necessary reflect their visual order on the map.
Availability
Declared in
MKMapView.h
pitchEnabled
A Boolean value indicating whether the map cameras pitch information is used.
@property(nonatomic, getter=isPitchEnabled) BOOL pitchEnabled
Discussion
When this property is set to YES and a valid camera is associated with the map, the cameras pitch angle is
used to tilt the plane of the map. When this property is set to NO, the cameras pitch angle is ignored and the
map is always displayed as if the user is looking straight down onto it.
Availability
Declared in
MKMapView.h
region
@property(nonatomic) MKCoordinateRegion region
Discussion
The region encompasses both the latitude and longitude point on which the map is centered and the span of
coordinates to display. The span values provide an implicit zoom value for the map. The larger the displayed
area, the lower the amount of zoom. Similarly, the smaller the displayed area, the greater the amount of zoom.
Properties
109
Changing only the center coordinate of the region can still cause the span to change implicitly. The span might
change because the distances represented by a span change at different latitudes and longitudes and the map
viewmay need to adjust the span to account for the newlocation. If you want to change the center coordinate
without changing the zoom level, use the centerCoordinate instead.
Changing the value of this property updates the map view immediately. When setting this property, the map
may adjust the new region value so that it fits the visible area of the map precisely. This is normal and is done
to ensure that the value in this property always reflects the visible portion of the map. However, it does mean
that if you get the value of this property right after setting it, the returned value may not match the value you
set. (You can use the regionThatFits: (page 129) method to determine the region that will actually be set by
the map.)
If you want to animate the change in region, use the setRegion:animated: method instead.
Availability
See Also
setRegion:animated: (page 135)
@property centerCoordinate (page 107)
Declared in
MKMapView.h
rotateEnabled
A Boolean value indicating whether the map cameras heading information is used.
@property(nonatomic, getter=isRotateEnabled) BOOL rotateEnabled
Discussion
When this property is set to YES and a valid camera is associated with the map, the cameras heading angle
is used to rotate the plane of the map around its center point. When this property is set to NO, the cameras
heading angle is ignored and the map is always oriented so that true north is situated at the top of the map
view.
Availability
Declared in
MKMapView.h
Properties
110
scrollEnabled
A Boolean value that determines whether the user may scroll around the map.
@property(nonatomic, getter=isScrollEnabled) BOOL scrollEnabled
Discussion
This property controls only user interactions with the map. If you set the value of this property to NO, you may
still change the map location programmatically by changing the value in the region property.
The default value of this property is YES.
Availability
Declared in
MKMapView.h
selectedAnnotations
The annotations that are currently selected.
@property(nonatomic, copy) NSArray *selectedAnnotations
Discussion
Assigning a new array to this property selects only the first annotation in the array.
Availability
Declared in
MKMapView.h
showsBuildings
@property (nonatomic) BOOL showsBuildings;
Discussion
When this property is set to YES and the camera has a pitch angle greater than zero, the map extrudes buildings
so that they extend above the map plane, creating a 3D effect. The mapType (page 108) property must be set
to MKMapTypeStandard (page 140) for extruded buildings to be displayed. The default value of this property is
YES.
Properties
111
Availability
Declared in
MKMapView.h
showsPointsOfInterest
@property (nonatomic) BOOL showsPointsOfInterest;
Discussion
When this property is set to YES, the map displays icons and labels for restaurants, schools, and other relevant
points of interest. The default value of this property is YES.
Availability
Declared in
MKMapView.h
showsUserLocation
A Boolean value indicating whether the map should try to display the users location.
@property(nonatomic) BOOL showsUserLocation
Discussion
This property does not indicate whether the users position is actually visible on the map, only whether the
map view should try to display it. Setting this property to YES causes the map view to use the Core Location
framework to find the current location and try to display it on the map. As long as this property is YES, the
map view continues to track the users location and update it periodically. The default value of this property
is NO.
Showing the users location does not guarantee that the location is visible on the map. The user might have
scrolled the map to a different point, causing the current location to be offscreen. To determine whether the
users current location is currently displayed on the map, use the userLocationVisible property.
Availability
Properties
112
See Also
@property userLocationVisible (page 113)
Declared in
MKMapView.h
userLocation
The annotation object representing the users current location. (read-only)
@property(nonatomic, readonly) MKUserLocation *userLocation
Availability
See Also
@property showsUserLocation (page 112)
Declared in
MKMapView.h
userLocationVisible
A Boolean value indicating whether the devices current location is visible in the map view. (read-only)
@property(nonatomic, readonly, getter=isUserLocationVisible) BOOL userLocationVisible
Discussion
This property tells you whether the icon used to represent the users current location is visible in the map view.
When determining whether the current location is visible, this property factors in the horizontal accuracy of
the location data. Specifically, if the rectangle represented by the users current location plus or minus minus
the horizontal accuracy of that location intersects the maps visible rectangle, this property contains the value
YES. If that location rectangle does not intersect the maps visible rectangle, this property contains the value
NO.
If the users location cannot be determined, this property contains the value NO.
Availability
Declared in
MKMapView.h
Properties
113
userTrackingMode
The mode used to track the user location.
@property(nonatomic) MKUserTrackingMode userTrackingMode
Discussion
Possible values are described in MKUserTrackingMode (page 140).
Setting the tracking mode to MKUserTrackingModeFollow (page 141) or
MKUserTrackingModeFollowWithHeading (page 141) causes the map view to center the map on that location
and begin tracking the users location. If the map is zoomed out, the map view automatically zooms in on the
users location, effectively changing the current visible region.
Availability
See Also
Declared in
MKMapView.h
visibleMapRect
@property(nonatomic) MKMapRect visibleMapRect
Discussion
This property represents the same basic information as the region (page 109) property but specified as a map
rectangle 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.
Availability
Related Sample Code
KMLViewer
PhotosByLocation
Properties
114
Declared in
MKMapView.h
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
Discussion
This property controls only user interactions with the map. If you set the value of this property to NO, you may
still change the zoom level programmatically by changing the value in the region property.
The default value of this property is YES.
Availability
Declared in
MKMapView.h
Instance Methods
addAnnotation:
Adds the specified annotation to the map view.
- (void)addAnnotation:(id < MKAnnotation >)annotation
Parameters
annotation
The annotation object to add to the receiver. This object must conform to the MKAnnotation protocol.
The map view retains the specified object.
Availability
See Also
Related Sample Code
GeocoderDemo
Instance Methods
115
Regions
Declared in
MKMapView.h
addAnnotations:
Adds an array of annotation objects to the map view.
- (void)addAnnotations:(NSArray *)annotations
Parameters
annotations
An array of annotation objects. Each object in the array must conform to the MKAnnotation protocol.
The map view retains the individual annotation objects.
Availability
See Also
Declared in
MKMapView.h
addOverlay:
Adds a single overlay object to the map.
- (void)addOverlay:(id < MKOverlay >)overlay
Parameters
overlay
The overlay object to add. This object must conform to the MKOverlay protocol.
Discussion
The specified object is added to the group of overlay objects in the MKOverlayLevelAboveLabels (page 141)
level. Adding an overlay causes the map view to begin monitoring the area represented by that overlay. As
soon as the bounding rectangle of an overlay intersects the visible portion of the map, the map view adds a
corresponding overlay viewto the map. The overlay viewis provided by the mapView:viewForOverlay: (page
266) method of the map views delegate object.
Instance Methods
116
To remove an overlay from a map, use the removeOverlay: (page 131) method.
Availability
See Also
Related Sample Code
Regions
Declared in
MKMapView.h
addOverlay:level:
Adds the overlay object to the map at the specified level.
- (void)addOverlay:(id < MKOverlay >)overlay level:(MKOverlayLevel)level
Parameters
overlay
The overlay object to add. This object must conform to the MKOverlay protocol.
level
The map level at which to place the overlay. For a list of possible values for this parameter, see
MKOverlayLevel (page 141).
Discussion
Positioning an overlay at a specific level places that overlays visual representation in front of or behind other
map 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 an
overlay also causes the map view to begin monitoring the area they represent. As soon as the bounding
rectangle of the overlay intersects the visible portion of the map, the map view calls your delegates
mapView:rendererForOverlay: (page 265) method to get the renderer object to use when drawing the overlay.
To remove an overlay from a map, use the removeOverlay: (page 131) method.
Availability
Instance Methods
117
Declared in
MKMapView.h
addOverlays:
Adds an array of overlay objects to the map.
- (void)addOverlays:(NSArray *)overlays
Parameters
overlays
An array of objects, each of which must conform to the MKOverlay protocol.
Discussion
The specified objects are added to the group of overlay objects in the MKOverlayLevelAboveLabels (page
141) 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 tries
to 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 the
mapView:viewForOverlay: (page 266) method of the map views delegate object.
To remove multiple overlays from a map, use the removeOverlays: (page 132) method.
Availability
See Also
Declared in
MKMapView.h
addOverlays:level:
Adds an array of overlay objects to the map at the specified level.
- (void)addOverlays:(NSArray *)overlays level:(MKOverlayLevel)level
Instance Methods
118
Parameters
overlays
The array of overlay objects to add. Each object in the array must conform to the MKOverlay protocol.
level
The map level at which to place the overlays. For a list of possible values for this parameter, see
Discussion
Positioning an overlay at a specific level places that overlays visual representation in front of or behind other
This method adds the specified overlays to the end of the list of overlay objects at the given level. Adding the
overlays also causes the map view to begin monitoring the area they represent. As soon as the bounding
rectangle of an overlay intersects the visible portion of the map, the map view calls your delegates
mapView:rendererForOverlay: (page 265) method to get the renderer object to use when drawing that
overlay.
To remove multiple overlays from a map, use the removeOverlays: (page 132) method.
Availability
Declared in
MKMapView.h
annotationsInMapRect:
Returns the annotation objects located in the specified map rectangle.
- (NSSet *)annotationsInMapRect:(MKMapRect)mapRect
Parameters
mapRect
The portion of the map that you want to search for annotations.
Return Value
The set of annotation objects located in mapRect.
Discussion
This method offers a fast way to retrieve the annotation objects in a particular portion of the map. This method
is much faster than doing a linear search of the objects in the annotations (page 105) property yourself.
Instance Methods
119
Special Considerations
Prior to iOS 7 this method incorrectly did not return instances of MKUserLocation.
Availability
Declared in
MKMapView.h
convertCoordinate:toPointToView:
Converts a map coordinate to a point in the specified view.
- (CGPoint)convertCoordinate:(CLLocationCoordinate2D)coordinate toPointToView:(UIView
*)view
Parameters
coordinate
The map coordinate for which you want to find the corresponding point.
view
The view in whose coordinate system you want to locate the specified map coordinate. If this parameter
is nil, the returned point is specified in the windows coordinate system. If view is not nil, it must
belong to the same window as the map view.
Return Value
The point (in the appropriate view or window coordinate system) corresponding to the specified latitude and
longitude value.
Availability
See Also
convertPoint:toCoordinateFromView: (page 120)
Declared in
MKMapView.h
convertPoint:toCoordinateFromView:
Converts a point in the specified views coordinate system to a map coordinate.
Instance Methods
120
- (CLLocationCoordinate2D)convertPoint:(CGPoint)point toCoordinateFromView:(UIView
*)view
Parameters
point
The point you want to convert.
view
The view that serves as the reference coordinate system for the point parameter.
Return Value
The map coordinate at the specified point.
Availability
See Also
convertCoordinate:toPointToView: (page 120)
Declared in
MKMapView.h
convertRect:toRegionFromView:
Converts a rectangle in the specified views coordinate system to a map region.
- (MKCoordinateRegion)convertRect:(CGRect)rect toRegionFromView:(UIView *)view
Parameters
rect
The rectangle you want to convert.
view
The view that serves as the reference coordinate system for the rect parameter.
Return Value
The map region corresponding to the specified view rectangle.
Availability
See Also
convertRegion:toRectToView: (page 122)
Instance Methods
121
Declared in
MKMapView.h
convertRegion:toRectToView:
Converts a map region to a rectangle in the specified view.
- (CGRect)convertRegion:(MKCoordinateRegion)region toRectToView:(UIView *)view
Parameters
region
The map region for which you want to find the corresponding view rectangle.
view
The view in whose coordinate system you want to locate the specified map region. If this parameter is
nil, the returned rectangle is specified in the windows coordinate system. If view is not nil, it must
belong to the same window as the map view.
Return Value
The rectangle corresponding to the specified map region.
Availability
See Also
convertRect:toRegionFromView: (page 121)
Declared in
MKMapView.h
dequeueReusableAnnotationViewWithIdentifier:
Returns a reusable annotation view located by its identifier.
- (MKAnnotationView *)dequeueReusableAnnotationViewWithIdentifier:(NSString
*)identifier
Parameters
identifier
A string identifying the annotation view to be reused. This string is the same one you specify when
initializing the annotation view using the initWithAnnotation:reuseIdentifier: (page 24) method.
Instance Methods
122
Return Value
An annotation view with the specified identifier, or nil if no such object exists in the reuse queue.
Discussion
For performance reasons, you should generally reuse MKAnnotationView objects in your map views. As
annotation views move offscreen, the map view moves them to an internally managed reuse queue. As new
annotations move onscreen, and your code is prompted to provide a corresponding annotation view, you
should always attempt to dequeue an existing view before creating a new one. Dequeueing saves time and
memory during performance-critical operations such as scrolling.
Availability
Declared in
MKMapView.h
deselectAnnotation:animated:
Deselects the specified annotation and hides its callout view.
- (void)deselectAnnotation:(id < MKAnnotation >)annotation animated:(BOOL)animated
Parameters
annotation
The annotation object to deselect.
animated
If YES, the callout view is animated offscreen.
Availability
Declared in
MKMapView.h
exchangeOverlay:withOverlay:
Exchanges the positions of the two overlay objects.
- (void)exchangeOverlay:(id < MKOverlay >)overlay1 withOverlay:(id < MKOverlay
>)overlay2
Instance Methods
123
Parameters
overlay1
The first overlay object.
overlay2
The second overlay object.
Discussion
If the overlays are in the same map level, they exchange positions within that levels array of overlay objects.
If they are in different map levels, the two objects also swap levels. Swapping the position of the overlays
affects their visibility in the map view.
Availability
See Also
exchangeOverlayAtIndex:withOverlayAtIndex: (page 124)
Declared in
MKMapView.h
exchangeOverlayAtIndex:withOverlayAtIndex:
Exchanges the position of two overlay objects.
- (void)exchangeOverlayAtIndex:(NSUInteger)index1
withOverlayAtIndex:(NSUInteger)index2
Parameters
index1
The index of an overlay in the MKOverlayLevelAboveLabels (page 141) map level.
index2
The index of another overlay in the MKOverlayLevelAboveLabels map level.
Discussion
If you need to exchange overlays in other map levels, use the exchangeOverlay:withOverlay: method.
Availability
See Also
exchangeOverlay:withOverlay: (page 123)
Instance Methods
124
Declared in
MKMapView.h
insertOverlay:aboveOverlay:
Inserts one overlay object on top of another.
- (void)insertOverlay:(id < MKOverlay >)overlay aboveOverlay:(id < MKOverlay >)sibling
Parameters
overlay
The overlay object to insert.
sibling
An existing object in the overlays array. This object must exist in the array and must not be nil.
Discussion
This method inserts the overlay into the MKOverlayLevelAboveLabels (page 141) level and positions it relative
to the specified sibling. When displayed, this leads to the overlays contents being displayed above that of its
sibling. If sibling is not in the same map level, this method appends the overlay to the end of the list of overlays
at the indicated level.
Availability
See Also
Declared in
MKMapView.h
insertOverlay:atIndex:
Inserts an overlay object into the list associated with the map.
- (void)insertOverlay:(id < MKOverlay >)overlay atIndex:(NSUInteger)index
Parameters
overlay
Instance Methods
125
index
The index at which to insert the overlay object. If this value is greater than the number of objects in the
overlays (page 108) property, this method appends the object to the end of the array.
Discussion
This method inserts the overlay into the MKOverlayLevelAboveLabels (page 141) level.
Availability
See Also
Declared in
MKMapView.h
insertOverlay:atIndex:level:
Inserts an overlay object into the level at the specified index.
- (void)insertOverlay:(id < MKOverlay >)overlay atIndex:(NSUInteger)index
level:(MKOverlayLevel)level
Parameters
overlay
index
The index at which to insert the overlay object. If this value is greater than the number of objects in the
overlays (page 108) property, this method appends the object to the end of the array.
level
The map level at which to place the overlay. For a list of possible values for this parameter, see
Discussion
Inserting an overlay at a specific level places that overlays visual representation in front of or behind other
Availability
Instance Methods
126
Declared in
MKMapView.h
insertOverlay:belowOverlay:
Inserts one overlay object below another.
- (void)insertOverlay:(id < MKOverlay >)overlay belowOverlay:(id < MKOverlay >)sibling
Parameters
overlay
sibling
An existing object in the overlays (page 108) array. This object must exist in the array and must not be
nil.
Discussion
This method inserts the overlay into the MKOverlayLevelAboveLabels (page 141) level and positions it relative
to the specified sibling. When displayed, this leads to the overlays contents being displayed beneath that of
its sibling. If sibling is not in the same map level, this method appends the overlay to the end of the list of
overlays at the indicated level.
Availability
See Also
Declared in
MKMapView.h
mapRectThatFits:
Adjusts the aspect ratio of the specified map rectangle to ensure that it fits in the map views frame.
- (MKMapRect)mapRectThatFits:(MKMapRect)mapRect
Parameters
mapRect
The initial map rectangle whose width and height you want to adjust.
Instance Methods
127
Return Value
A map rectangle that is still centered on the same point of the map but whose width and height are adjusted
to fit in the map views frame.
Discussion
You can use this method to normalize map rectangle values before displaying the corresponding area. This
method returns a new map rectangle that both contains the specified rectangle and fits neatly inside the map
views frame.
Availability
See Also
mapRectThatFits:edgePadding: (page 128)
Declared in
MKMapView.h
mapRectThatFits:edgePadding:
Adjusts the aspect ratio of the specified map rectangle, incorporating the specified inset values.
- (MKMapRect)mapRectThatFits:(MKMapRect)mapRect edgePadding:(UIEdgeInsets)insets
Parameters
mapRect
The initial map rectangle whose width and height you want to adjust.
insets
The distance (measured in screen points) by which to inset the returned rectangle from the actual
boundaries of the map views frame.
Return Value
A map rectangle that is still centered on the same point of the map but whose width and height are adjusted
to fit in the map views frame minus the inset values.
Availability
See Also
mapRectThatFits: (page 127)
Instance Methods
128
Declared in
MKMapView.h
overlaysInLevel:
The overlay objects in the specified level of the map.
- (NSArray *)overlaysInLevel:(MKOverlayLevel)level
Parameters
level
The map level whose overlays you want. For a list of possible values for this parameter, see
Return Value
An array of objects conforming to the MKOverlay protocol that display in the specified map level. If there are
no overlays at the specified level, this method returns an empty array.
Discussion
You can use this method to get all of the overlays assigned to a specific map level, which might be a subset
of the complete set of overlay objects. For overlapping overlay objects, the order of objects in the array
represents their visual order when displayed on the map, with objects in the beginning of the array located
behind those at later indexes.
Availability
See Also
addOverlay:level: (page 117)
addOverlays:level: (page 118)
Declared in
MKMapView.h
regionThatFits:
Adjusts the aspect ratio of the specified region to ensure that it fits in the map views frame.
- (MKCoordinateRegion)regionThatFits:(MKCoordinateRegion)region
Instance Methods
129
Parameters
region
The initial region whose span you want to adjust.
Return Value
A region that is still centered on the same point of the map but whose span values are adjusted to fit in the
map views frame.
Discussion
You can use this method to normalize the region values before displaying them in the map. This method
returns a new region that both contains the specified region and fits neatly inside the map views frame.
Availability
Declared in
MKMapView.h
removeAnnotation:
Removes the specified annotation object from the map view.
- (void)removeAnnotation:(id < MKAnnotation >)annotation
Parameters
annotation
The annotation object to remove. This object must conform to the MKAnnotation protocol.
Discussion
If the annotation is currently associated with an annotation view, and that view has a reuse identifier, this
method removes the annotation viewand queues it internally for later reuse. You can retrieve queued annotation
views (and associate them with new annotations) using the
dequeueReusableAnnotationViewWithIdentifier: (page 122) method.
Removing an annotation object disassociates it fromthe map viewentirely, preventing it frombeing displayed
on the map. Thus, you would typically call this method only when you want to hide or delete a given annotation.
Availability
See Also
Instance Methods
130
Declared in
MKMapView.h
removeAnnotations:
Removes an array of annotation objects from the map view.
- (void)removeAnnotations:(NSArray *)annotations
Parameters
annotations
The array of annotations to remove. Objects in the array must conform to the MKAnnotation protocol.
Discussion
If 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 queued
annotation views (and associate them with new annotations) using the
dequeueReusableAnnotationViewWithIdentifier: (page 122) method.
Removing annotation objects disassociates them from the map view entirely, preventing them from being
displayed on the map. Thus, you would typically call this method only when you want to hide or delete the
specified annotations.
Availability
See Also
Declared in
MKMapView.h
removeOverlay:
Removes a single overlay object from the map.
- (void)removeOverlay:(id < MKOverlay >)overlay
Instance Methods
131
Parameters
overlay
The overlay object to remove.
Discussion
This method removes the overlay regardless of the level that it is in. Removing an overlay also removes its
corresponding renderer, if one is in use. If the specified overlay is not currently associated with the map view,
this method does nothing.
Availability
See Also
Related Sample Code
Regions
Declared in
MKMapView.h
removeOverlays:
Removes one or more overlay objects from the map.
- (void)removeOverlays:(NSArray *)overlays
Parameters
overlays
An array of objects, each of which conforms to the MKOverlay protocol.
Discussion
This method removes the specified overlays regardless of which level each one is in. Removing an overlay also
removes its corresponding renderer, if one is in use. If a given overlay object is not associated with the map
view, it is ignored.
Availability
See Also
Instance Methods
132
Declared in
MKMapView.h
rendererForOverlay:
Returns the renderer object used to draw the contents of the specified overlay object.
- (MKOverlayRenderer *)rendererForOverlay:(id < MKOverlay >)overlay
Parameters
overlay
The overlay object whose renderer you want.
Return Value
The renderer object in use for the specified overlay or nil if the overlay is not onscreen.
Discussion
This method returns the renderer object that your map delegate provided in its
mapView:rendererForOverlay: (page 265) method.
Availability
Declared in
MKMapView.h
selectAnnotation:animated:
Selects the specified annotation and displays a callout view for it.
- (void)selectAnnotation:(id < MKAnnotation >)annotation animated:(BOOL)animated
Parameters
annotation
The annotation object to select.
animated
If YES, the callout view is animated into position.
Instance Methods
133
Discussion
If the specified annotation is not onscreen, and therefore does not have an associated annotation view, this
method has no effect.
Availability
Declared in
MKMapView.h
setCamera:animated:
Changes the camera used for determining the maps viewing parameters and optionally animates the change.
- (void)setCamera:(MKMapCamera *)camera animated:(BOOL)animated
Parameters
camera
The camera object containing the viewing angle information. This parameter must not be nil.
animated
Specify YES if you want the change in viewing angle to be animated or NO if you want the map to reflect
the changes without animations.
Availability
See Also
@property camera (page 106)
Declared in
MKMapView.h
setCenterCoordinate:animated:
Changes the center coordinate of the map and optionally animates the change.
- (void)setCenterCoordinate:(CLLocationCoordinate2D)coordinate animated:(BOOL)animated
Parameters
coordinate
The new center coordinate for the map.
Instance Methods
134
animated
Specify YES if you want the map view to scroll to the new location or NO if you want the map to display
the new location immediately.
Discussion
Changing the center coordinate centers the map on the new coordinate without changing the current zoom
level. It also updates the value in the region property to reflect the new center coordinate and the new span
values needed to maintain the current zoom level.
Availability
See Also
@property centerCoordinate (page 107)
Declared in
MKMapView.h
setRegion:animated:
Changes the currently visible region and optionally animates the change.
- (void)setRegion:(MKCoordinateRegion)region animated:(BOOL)animated
Parameters
region
The new region to display in the map view.
animated
Specify YES if you want the map view to animate the transition to the new region or NO if you want the
map to center on the specified region immediately.
Discussion
Changing just the center coordinate of the region can still cause the span values to change implicitly. The span
values might change because that the distances represented by a span change at different latitudes and
longitudes and the map view may need to adjust the span to account for the new location. If you want to
change the center coordinate without changing the zoomlevel, use the setCenterCoordinate:animated:
instead.
Instance Methods
135
When setting a new region, the map may adjust the value in the region parameter so that it fits the visible
area of the map precisely. This adjustment is normal and is done to ensure that the value in the region (page
109) property always reflects the visible portion of the map. However, it does mean that if you get the value of
that property right after calling this method, the returned value may not match the value you set. (You can
use the regionThatFits: (page 129) method to determine the region that will actually be set by the map.)
Availability
See Also
Declared in
MKMapView.h
setUserTrackingMode:animated:
Sets the mode used to track the user location with optional animation.
- (void)setUserTrackingMode:(MKUserTrackingMode)mode animated:(BOOL)animated
Parameters
mode
The mode used to track the user location. Possible values are described in MKUserTrackingMode (page
140).
animated
If YES, the change fromthe current mode to the newmode is animated; otherwise, it is not. This parameter
affects only tracking mode changes. Changes to the user location or heading are always animated.
Discussion
Setting the tracking mode to MKUserTrackingModeFollow (page 141) or
MKUserTrackingModeFollowWithHeading (page 141) causes the map view to center the map on that location
and begin tracking the users location. If the map is zoomed out, the map view automatically zooms in on the
users location, effectively changing the current visible region.
Availability
See Also
@property userTrackingMode (page 114)
Instance Methods
136
mapView:didChangeUserTrackingMode:animated: (page 261)
mapView:didUpdateUserLocation: (page 263)
heading (page 242)
Declared in
MKMapView.h
setVisibleMapRect:animated:
Changes the currently visible portion of the map and optionally animates the change.
- (void)setVisibleMapRect:(MKMapRect)mapRect animated:(BOOL)animate
Parameters
mapRect
The map rectangle to make visible in the map view.
animate
Specify YES if you want the map view to animate the transition to the new map rectangle or NO if you
want the map to center on the specified rectangle immediately.
Availability
See Also
setVisibleMapRect:edgePadding:animated: (page 137)
Declared in
MKMapView.h
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)insets
animated:(BOOL)animate
Parameters
mapRect
The map rectangle to make visible in the map view.
insets
The amount of additional space (measured in screen points) to make visible around the specified rectangle.
Instance Methods
137
animate
Specify YES if you want the map view to animate the transition to the new map rectangle or NO if you
want the map to center on the specified rectangle immediately.
Availability
See Also
setVisibleMapRect:animated: (page 137)
Declared in
MKMapView.h
showAnnotations:animated:
Sets the visible region so that the map displays the specified annotations.
- (void)showAnnotations:(NSArray *)annotations animated:(BOOL)animated
Parameters
annotations
The annotations that you want to be visible in the map.
animated
YES if you want the map region change to be animated, or NO if you want the map to display the new
region immediately without animations.
Discussion
Calling this method updates the value in the region property and potentially other properties to reflect the
new map region.
Availability
Declared in
MKMapView.h
viewForAnnotation:
Returns the annotation view associated with the specified annotation object, if any.
- (MKAnnotationView *)viewForAnnotation:(id < MKAnnotation >)annotation
Instance Methods
138
Parameters
annotation
The annotation object whose view you want.
Return Value
The annotation view or nil if the view has not yet been created. This method may also return nil if the
annotation is not in the visible map region and therefore does not have an associated annotation view.
Availability
Declared in
MKMapView.h
viewForOverlay:
Returns the view associated with the overlay object if any. (Deprecated in iOS 7.0. Use the
rendererForOverlay: (page 133) method instead.)
- (MKOverlayView *)viewForOverlay:(id < MKOverlay >)overlay
Parameters
overlay
The overlay object whose view you want.
Return Value
The view associated with the overlay object or nil if the overlay is not onscreen.
Availability
Declared in
MKMapView.h
Constants
MKMapType
The type of map to display.
Constants
139
typedef enum : NSUInteger{
MKMapTypeStandard,
MKMapTypeSatellite,
MKMapTypeHybrid
} MKMapType;
Constants
MKMapTypeStandard
Displays a street map that shows the position of all roads and some road names.
Declared in MKTypes.h.
MKMapTypeSatellite
Displays satellite imagery of the area.
MKMapTypeHybrid
Displays 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;
Constants
MKUserTrackingModeNone
The map does not follow the user location.
Declared in MKMapView.h.
Constants
140
MKUserTrackingModeFollow
The map follows the user location.
MKUserTrackingModeFollowWithHeading
The 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 {
MKOverlayLevelAboveRoads = 0,
MKOverlayLevelAboveLabels
} MKOverlayLevel;
Constants
MKOverlayLevelAboveRoads
Place the overlay above roadways but below map labels, shields, or point-of-interest icons.
MKOverlayLevelAboveLabels
Place the overlay above map labels, shields, or point-of-interest icons but below annotations and 3D
projections of buildings.
Constants
141
Conforms to MKAnnotation (MKShape)
NSObject (NSObject)
Declared in MKMultiPoint.h
Overview
The MKMultiPoint class is an abstract superclass used to define shapes composed of multiple points. You
should not create instances of this class directly. Instead, you should create instances of the MKPolyline or
MKPolygon classes. However, you can use the method and properties of this class to access information about
the specific points associated with the line or polygon.
Tasks
Accessing the Points in the Shape
points (page 143) property
The array of points associated with the shape. (read-only)
142
MKMultiPoint Class Reference
pointCount (page 143) property
The number of points associated with the shape. (read-only)
Getting Coordinate Values
getCoordinates:range: (page 144)
Retrieves one or more points associated with the shape and converts them to coordinate values.
Properties
pointCount
The number of points associated with the shape. (read-only)
@property (nonatomic, readonly) NSUInteger pointCount
Availability
Declared in
MKMultiPoint.h
points
The array of points associated with the shape. (read-only)
@property (nonatomic, readonly) MKMapPoint *points
Discussion
The number of points in the array is specified by the pointCount (page 143) property.
Availability
Declared in
MKMultiPoint.h
Properties
143
Instance Methods
getCoordinates:range:
Retrieves one or more points associated with the shape and converts them to coordinate values.
- (void)getCoordinates:(CLLocationCoordinate2D *)coords range:(NSRange)range
Parameters
coords
On input, you must provide a C array of structures large enough to hold the desired number of coordinates.
On output, this structure contains the requested coordinate data.
range
The range of points you want. The location field indicates the first point you are requesting, with 0
being the first point, 1 being the second point, and so on. The length field indicates the number of
points you want. The array in coords must be large enough to accommodate the number of requested
coordinates.
Discussion
This method converts the map points into coordinates before returning them to you. If you want the value of
each point specified as a map point, you can access the values directly using the points (page 143) property.
Availability
Declared in
MKMultiPoint.h
Instance Methods
144
Inherits from MKOverlayRenderer : NSObject
Declared in MKOverlayPathRenderer.h
Overview
The MKOverlayPathRenderer class draws a map overlay whose shape is represented by a CGPathRef data
type. The default drawing behavior of this class is to apply the objects current fill attributes, fill the path, apply
the current stroke attributes, and then stroke the path.
You can use this class as-is or subclass to define additional drawing behaviors. If you subclass, you should
override the createPath (page 151) method and use that method to build the appropriate path object. To
change the path, invalidate it and recreate the path using whatever new data your subclass has obtained.
Tasks
Accessing the Drawing Attributes
fillColor (page ?) property
The fill color to use for the path.
strokeColor (page ?) property
The stroke color to use for the path.
lineWidth (page 148) property
The stroke width to use for the path.
145
MKOverlayPathRenderer Class Reference
lineJoin (page 148) property
The line join style to apply to corners of the path.
lineCap (page 147) property
The line cap style to apply to the open ends of the path.
miterLimit (page 149) property
The limiting value that helps avoid spikes at junctions between connected line segments.
lineDashPhase (page 148) property
The offset (in points) at which to start drawing the dash pattern.
lineDashPattern (page 147) property
An array of numbers specifying the dash pattern to use for the path.
Creating and Managing the Path
path (page 149) property
The path representing the overlays shape.
createPath (page 151)
Creates the path for the overlay.
invalidatePath (page 152)
Updates the path associated with the overlay renderer.
Drawing the Path
applyStrokePropertiesToContext:atZoomScale: (page 151)
Applies the receivers current stroke-related drawing properties to the specified graphics context.
applyFillPropertiesToContext:atZoomScale: (page 150)
Applies the receivers current fill-related drawing properties to the specified graphics context.
strokePath:inContext: (page 153)
Draws a line along the specified path.
fillPath:inContext: (page 152)
Fills the area enclosed by the specified path.
Tasks
146
Properties
fillColor
The fill color to use for the path.
@property(retain) UIColor *fillColor
Availability
Declared in
lineCap
The line cap style to apply to the open ends of the path.
@property CGLineCap lineCap
Discussion
The line cap style is applied to the start and end points of any open subpaths. This property does not affect
closed subpaths. The default line cap style is kCGLineCapRound.
Availability
Declared in
lineDashPattern
An array of numbers specifying the dash pattern to use for the path.
@property(copy) NSArray *lineDashPattern
Discussion
The array contains one or more NSNumber objects that indicate the lengths (measured in points) of the line
segments and gaps in the pattern. The values in the array alternate, starting with the first line segment length,
followed by the first gap length, followed by the second line segment length, and so on.
This property is set to nil by default, which indicates no line dash pattern.
Properties
147
Availability
Declared in
lineDashPhase
The offset (in points) at which to start drawing the dash pattern.
@property CGFloat lineDashPhase
Discussion
Use this property to start drawing a dashed line partway through a segment or gap. For example, a phase
value of 6 for the patter 5-2-3-2 would cause drawing to begin in the middle of the first gap.
The default value of this property is 0.
Availability
Declared in
lineJoin
The line join style to apply to corners of the path.
@property CGLineJoin lineJoin
Discussion
The default line join style is kCGLineJoinRound.
Availability
Declared in
lineWidth
The stroke width to use for the path.
Properties
148
@property CGFloat lineWidth
Discussion
Availability
Declared in
miterLimit
The limiting value that helps avoid spikes at junctions between connected line segments.
@property CGFloat miterLimit
Discussion
The miter limit helps you avoid spikes in paths that use the kCGLineJoinMiter join style. If the ratio of the
miter lengththat is, the diagonal length of the miter jointo the line thickness exceeds the miter limit, the
joint is converted to a bevel join. The default miter limit is 10, which results in the conversion of miters whose
angle at the joint is less than 11 degrees.
Availability
Declared in
path
The path representing the overlays shape.
@property CGPathRef path
Discussion
Getting the value of this property causes the path to be created (using the createPath (page 151) method) if
it does not already exist. You can assign a path object to this property explicitly. When assigning a new path
object to this property, the overlay renderer stores a strong reference to the path you provide.
Availability
Properties
149
Declared in
strokeColor
The stroke color to use for the path.
@property(retain) UIColor *strokeColor
Availability
Declared in
Instance Methods
applyFillPropertiesToContext:atZoomScale:
Applies the receivers current fill-related drawing properties to the specified graphics context.
- (void)applyFillPropertiesToContext:(CGContextRef)context
atZoomScale:(MKZoomScale)zoomScale
Parameters
context
The graphics context used to draw the views contents.
zoomScale
The current zoom scale used for drawing.
Discussion
This is a convenience method for applying all of the drawing properties used when filling a path. This method
applies the current fill color to the specified graphics context.
Availability
Declared in
Instance Methods
150
applyStrokePropertiesToContext:atZoomScale:
- (void)applyStrokePropertiesToContext:(CGContextRef)context
Parameters
context
zoomScale
Discussion
This is a convenience method for applying all of the drawing properties used when stroking a path. This method
applies the stroke color, line width, line join, line cap, miter limit, line dash phase, and line dash attributes to
the specified graphics context. This method applies the scale factor in the zoomScale parameter to the line
width and line dash pattern automatically so that lines scale appropriately.
This method does not save the current graphics state before applying the newattributes. If you want to preserve
the existing state, you must save it yourself and restore it later when you finish drawing.
Availability
Declared in
createPath
Creates the path for the overlay.
- (void)createPath
Discussion
The default implementation of this method does nothing. Subclasses should override it and use it to create
the CGPathRef data type to be used for drawing. After creating the path, your implementation should assign
it to the path (page 149) property.
Availability
Instance Methods
151
Declared in
fillPath:inContext:
Fills the area enclosed by the specified path.
- (void)fillPath:(CGPathRef)path inContext:(CGContextRef)context
Parameters
path
The path to fill.
context
The graphics context in which to draw the path.
Discussion
You must set the current fill color before calling this method. Typically you do this by calling the
applyFillPropertiesToContext:atZoomScale: method prior to drawing. If the fillColor property
is currently nil, this method does nothing.
Availability
See Also
Declared in
invalidatePath
Updates the path associated with the overlay renderer.
- (void)invalidatePath
Discussion
Call this method when a change in the path information would require you to recreate the overlays path. This
method sets the path (page 149) property to nil and tells the overlay renderer to redisplay its contents.
Availability
Instance Methods
152
Declared in
strokePath:inContext:
Draws a line along the specified path.
- (void)strokePath:(CGPathRef)path inContext:(CGContextRef)context
Parameters
path
The path to draw.
context
Discussion
You must set the current stroke color before calling this method. Typically you do this by calling the
applyStrokePropertiesToContext:atZoomScale: method prior to drawing. If the strokeColor
property is currently nil, this method does nothing.
Availability
See Also
Declared in
Instance Methods
153
Inherits from MKOverlayView : UIView : UIResponder : NSObject
NSObject (NSObject)
Declared in MKOverlayPathView.h
Related sample code
KMLViewer
Overview
The MKOverlayPathView class represents a generic overlay that draws its contents using a CGPathRef data
type. You can use this class to implement simple path-based overlay views or subclass it to define additional
drawing behaviors. The default drawing behavior of this class is to apply the objects current fill attributes, fill
the path, apply the current stroke attributes, and then stroke the path.
If you subclass, you should override the createPath (page 162) method and use that method to build the
appropriate path for the overlay. You can invalidate this path as needed and force the path to be recreated
using whatever new data your subclass has obtained.
154
MKOverlayPathView Class Reference
In iOS 7 and later, use the MKOverlayPathRenderer class to display path-based overlays instead.
Tasks
Accessing the Drawing Attributes
fillColor (page 156) property
The fill color to use for the path. (Deprecated. Use an MKOverlayPathRenderer object instead.)
strokeColor (page 160) property
The stroke color to use for the path. (Deprecated. Use an MKOverlayPathRenderer object instead.)
lineWidth (page 158) property
The stroke width to use for the path. (Deprecated. Use an MKOverlayPathRenderer object instead.)
lineJoin (page 158) property
The line join style to apply to corners of the path. (Deprecated. Use an MKOverlayPathRenderer object
instead.)
lineCap (page 157) property
The line cap style to apply to the open ends of the path. (Deprecated. Use an MKOverlayPathRenderer
object instead.)
miterLimit (page 159) property
The limiting value that helps avoid spikes at junctions between connected line segments. (Deprecated.
Use an MKOverlayPathRenderer object instead.)
lineDashPhase (page 158) property
The offset (in points) at which to start drawing the dash pattern. (Deprecated. Use an
MKOverlayPathRenderer object instead.)
lineDashPattern (page 157) property
An array of numbers indicating the dash pattern for paths. (Deprecated. Use an MKOverlayPathRenderer
object instead.)
Tasks
155
Creating and Managing the Path
path (page 159) property
The current path to use when drawing the overlay. (Deprecated. Use an MKOverlayPathRenderer
object instead.)
Creates the path for the overlay. (Deprecated. Use an MKOverlayPathRenderer object instead.)
Releases the path associated with the receiver. (Deprecated. Use an MKOverlayPathRenderer object
instead.)
Drawing the Path
(Deprecated. Use an MKOverlayPathRenderer object instead.)
Applies the receivers current fill-related drawing properties to the specified graphics context (Deprecated.
Draws a line along the specified path. (Deprecated. Use an MKOverlayPathRenderer object instead.)
Fills the area enclosed by the specified path. (Deprecated. Use an MKOverlayPathRenderer object
instead.)
Properties
fillColor
The fill color to use for the path. (Deprecated in iOS 7.0. Use an MKOverlayPathRenderer object instead.)
@property (retain) UIColor *fillColor
Availability
Properties
156
Related Sample Code
KMLViewer
Regions
Declared in
MKOverlayPathView.h
lineCap
The line capstyle toapply tothe openends of the path. (DeprecatediniOS 7.0. Use anMKOverlayPathRenderer
object instead.)
@property CGLineCap lineCap
Discussion
The line cap style is applied to the start and end points of any open subpaths. This property does not affect
closed subpaths. The default line cap style is kCGLineCapButt.
Availability
Declared in
MKOverlayPathView.h
lineDashPattern
An array of numbers indicating the dash pattern for paths. (Deprecated in iOS 7.0. Use an
@property (copy) NSArray *lineDashPattern
Discussion
The array contains one or more NSNumber objects that indicate the lengths (measured in points) of the line
segments and gaps in the pattern. The values in the array alternate, starting with the first line segment length,
followed by the first gap length, followed by the second line segment length, and so on.
This property is set to nil by default, which indicates no line dash pattern.
Availability
Properties
157
Declared in
MKOverlayPathView.h
lineDashPhase
The offset (in points) at which to start drawing the dash pattern. (Deprecated in iOS 7.0. Use an
@property CGFloat lineDashPhase
Availability
Declared in
MKOverlayPathView.h
lineJoin
The line join style to apply to corners of the path. (Deprecated in iOS 7.0. Use an MKOverlayPathRenderer
object instead.)
@property CGLineJoin lineJoin
Discussion
The default line join style is kCGLineJoinMiter.
Availability
Declared in
MKOverlayPathView.h
lineWidth
The stroke width to use for the path. (Deprecated in iOS 7.0. Use an MKOverlayPathRenderer object instead.)
Properties
158
@property CGFloat lineWidth
Discussion
Availability
Related Sample Code
KMLViewer
Declared in
MKOverlayPathView.h
miterLimit
The limiting value that helps avoid spikes at junctions between connected line segments. (Deprecated in iOS 7.0.
@property CGFloat miterLimit
Discussion
The miter limit helps you avoid spikes in paths that use the kCGLineJoinMiter join style. If the ratio of the
miter lengththat is, the diagonal length of the miter jointo the line thickness exceeds the miter limit, the
joint is converted to a bevel join. The default miter limit is 10, which results in the conversion of miters whose
angle at the joint is less than 11 degrees.
Availability
Declared in
MKOverlayPathView.h
path
The current path to use when drawing the overlay. (Deprecated in iOS 7.0. Use an MKOverlayPathRenderer
object instead.)
Properties
159
@property CGPathRef path
Discussion
Getting the value of this property causes the path to be created (using the createPath (page 162) method) if
it does not already exist. You can also assign a path object to this property explicitly.
When assigning a new path object to this property, the receiver retains the path you specify.
Availability
See Also
Declared in
MKOverlayPathView.h
strokeColor
The stroke color to use for the path. (Deprecated in iOS 7.0. Use an MKOverlayPathRenderer object instead.)
@property (retain) UIColor *strokeColor
Availability
Related Sample Code
KMLViewer
Regions
Declared in
MKOverlayPathView.h
Properties
160
Instance Methods
applyFillPropertiesToContext:atZoomScale:
Applies the receivers current fill-related drawing properties to the specified graphics context (Deprecated in iOS
7.0. Use an MKOverlayPathRenderer object instead.)
- (void)applyFillPropertiesToContext:(CGContextRef)context
Parameters
context
zoomScale
Discussion
This is a convenience method for applying all of the drawing properties used when filling a path. This method
applies the current fill color to the specified graphics context.
Availability
See Also
Declared in
MKOverlayPathView.h
applyStrokePropertiesToContext:atZoomScale:
Applies the receivers current stroke-related drawing properties to the specified graphics context. (Deprecated in
iOS 7.0. Use an MKOverlayPathRenderer object instead.)
- (void)applyStrokePropertiesToContext:(CGContextRef)context
Parameters
context
Instance Methods
161
zoomScale
Discussion
This is a convenience method for applying all of the drawing properties used when stroking a path. This method
applies the stroke color, line width, line join, line cap, miter limit, line dash phase, and line dash attributes to
the specified graphics context. This method applies the scale factor in the zoomScale parameter to the line
width and line dash pattern automatically so that lines scale appropriately.
This method does not save the current graphics state before applying the new attributes. You must save it
yourself and restore it later when you are done drawing.
Availability
See Also
Declared in
MKOverlayPathView.h
createPath
Creates the path for the overlay. (Deprecated in iOS 7.0. Use an MKOverlayPathRenderer object instead.)
- (void)createPath
Discussion
The default implementation of this method does nothing. Subclasses should override it and use it to create
the CGPathRef data type to be used for drawing. After creating the path, your implementation should then
assign it to the path (page 159) property.
Availability
Declared in
MKOverlayPathView.h
Instance Methods
162
fillPath:inContext:
Fills the area enclosed by the specified path. (Deprecated in iOS 7.0. Use an MKOverlayPathRenderer object
instead.)
- (void)fillPath:(CGPathRef)path inContext:(CGContextRef)context
Parameters
path
The path to fill.
context
Discussion
You must set the current fill color before calling this method. Typically you do this by calling the
applyFillPropertiesToContext:atZoomScale: method prior to drawing. If the fillColor (page 156)
property is currently nil, this method does nothing.
Availability
See Also
Declared in
MKOverlayPathView.h
invalidatePath
Releases the path associated with the receiver. (Deprecated in iOS 7.0. Use an MKOverlayPathRenderer object
instead.)
- (void)invalidatePath
Discussion
You can call this method at any time where a change in the path information would require you to recreate
the path. This method sets the path (page 159) property to nil, which causes the cached path to be released.
Availability
Instance Methods
163
Declared in
MKOverlayPathView.h
strokePath:inContext:
Draws a line along the specified path. (Deprecated in iOS 7.0. Use an MKOverlayPathRenderer object instead.)
- (void)strokePath:(CGPathRef)path inContext:(CGContextRef)context
Parameters
path
The path to draw.
context
Discussion
You must set the current stroke color before calling this method. Typically you do this by calling the
applyStrokePropertiesToContext:atZoomScale: method prior to drawing. If the strokeColor (page
160) property is currently nil, this method does nothing.
Availability
See Also
Declared in
MKOverlayPathView.h
Instance Methods
164
Declared in MKOverlayRenderer.h
Overview
The MKOverlayRenderer class defines the basic behavior associated with all map-based overlays. An overlay
renderer draws the visual representation of an overlay objectthat is, an object that conforms to the MKOverlay
protocol. This class defines the drawing infrastructure used by the map view. Subclasses are expected to
override the drawMapRect:zoomScale:inContext: method to draw the contents of the overlay.
The Map Kit framework provides several concrete instances of overlay renderers. Specifically, it provides
renderers for each of the concrete overlay objects. You can use one of these existing renderers or define your
own subclasses if you want to draw the overlay contents differently.
Subclassing Notes
You can subclass MKOverlayRenderer to create overlays based on custom shapes, content, or drawing
techniques. The only method subclasses are expected to override is the
drawMapRect:zoomScale:inContext: (page 169) method. However, if your class contains content that may
not be ready for drawing right away, you should also override the canDrawMapRect:zoomScale: (page 168)
method and use it to report when your class is ready and able to draw.
The map view may tile large overlays and distribute the rendering of each tile to separate threads. Therefore,
the implementation of your drawMapRect:zoomScale:inContext: method must be safe to run from
background threads and from multiple threads simultaneously.
165
MKOverlayRenderer Class Reference
Tasks
Initializing an Overlay View
initWithOverlay: (page 170)
Initializes and returns the overlay renderer and associates it with the specified overlay object.
Attributes of the Overlay
overlay (page 168) property
The overlay object containing the data for drawing. (read-only)
alpha (page 167) property
The amount of transparency to apply to the overlay.
contentScaleFactor (page 167) property
The scale factor used to draw the overlays content. (read-only)
Converting Points on the Map
pointForMapPoint: (page 172)
Returns the point in the overlay renderers drawing area corresponding to the specified point on the
map.
mapPointForPoint: (page 171)
Returns the point on the map that corresponds to the specified point in the overlay renderers drawing
area.
rectForMapRect: (page 172)
Returns the rectangle in the overlay renderers drawing area corresponding to the specified rectangle
on the map.
mapRectForRect: (page 171)
Returns the rectangle on the map that corresponds to the specified rectangle in the overlay renderers
drawing area.
Drawing the Overlay
canDrawMapRect:zoomScale: (page 168)
Returns a Boolean value indicating whether the overlay view is ready to draw its content.
Tasks
166
drawMapRect:zoomScale:inContext: (page 169)
Draws the overlays contents at the specified location on the map.
setNeedsDisplay (page 173)
Invalidates the entire contents of the overlay for all zoom scales.
setNeedsDisplayInMapRect:zoomScale: (page 174)
Invalidates the specified portion of the overlay but only at the specified zoom scale.
setNeedsDisplayInMapRect: (page 173) Deprecated in iOS 7.0
Invalidates the specified portion of the overlay at all zoom scales
Properties
alpha
The amount of transparency to apply to the overlay.
@property CGFloat alpha
Discussion
The value in this property can be in the range 0.0 to 1.0, where 0.0 represents total transparency and 1.0
represents total opacity. The default value of this property is 1.0.
Availability
Declared in
MKOverlayRenderer.h
contentScaleFactor
The scale factor used to draw the overlays content. (read-only)
@property(readonly) CGFloat contentScaleFactor
Discussion
The scale factor determines how content is mapped from the logical coordinate space (measured in points)
to the device coordinate space (measured in pixels). This value is typically either 1.0 or 2.0. Higher scale
factors indicate that each point is represented by more than one pixel on the screen. For example, if the scale
factor is 2.0 and the drawing rectangle size is 50 x 50 points, the size of the underlying area is 100 x 100 pixels.
Properties
167
When drawing the content for your overlays, you can use this value to determine how best to render your
content.
Availability
Declared in
MKOverlayRenderer.h
overlay
The overlay object containing the data for drawing. (read-only)
@property(nonatomic, readonly) id<MKOverlay> overlay
Discussion
The overlay object contains the coordinate at which to draw the overlay and other information that your app
provides.
Availability
Declared in
MKOverlayRenderer.h
Instance Methods
canDrawMapRect:zoomScale:
Returns a Boolean value indicating whether the overlay view is ready to draw its content.
- (BOOL)canDrawMapRect:(MKMapRect)mapRect zoomScale:(MKZoomScale)zoomScale
Parameters
mapRect
The map rectangle that needs to be updated.
zoomScale
The current scale factor applied to the map.
Return Value
YES if this overlay renderer is ready to draw its contents on the map or NO if it is not.
Instance Methods
168
Discussion
Overlay renderers can override this method in situations where they may depend on the availability of other
information to draw their contents. For example, a renderer showing traffic information might want to delay
drawing until it has all of the traffic data it needs. In such a case, it can return NO from this method to indicate
that it is not ready. An overlay renderer might also return NO if it does not draw content in the specified
rectangle.
If you return NO from this method, your application is responsible for calling the
setNeedsDisplayInMapRect:zoomScale: (page 174) methodwhenthe overlay renderer subsequently becomes
ready to draw its contents.
The default implementation of this method returns YES.
Availability
Declared in
MKOverlayRenderer.h
drawMapRect:zoomScale:inContext:
Draws the overlays contents at the specified location on the map.
- (void)drawMapRect:(MKMapRect)mapRect zoomScale:(MKZoomScale)zoomScale
inContext:(CGContextRef)context
Parameters
mapRect
The map rectangle that needs to be updated. Your drawing code should avoid drawing outside of this
rectangle.
zoomScale
The current zoom factor applied to the map content. You can use this value for configuring the stroke
width of lines or other attributes that might be affected by the scale of the maps contents.
context
The graphics context to use for drawing the overlays contents.
Discussion
The default implementation of this method does nothing. Subclasses are expected to override this method
and use it to draw the overlays contents.
Instance Methods
169
When determining where to draw content, make your initial calculations relative to the map itself. In other
words, compute the position and size of any overlay content using map points and map rectangles, convert
those values to regular CGPoint and CGRect types using the methods of this class, and then pass the converted
points to any drawing primitives.
It is recommended that you use Core Graphics to draw any content for your overlays. If you choose to draw
using UIKit classes and methods instead, you must push the specified graphics context onto the context stack
(using the UIGraphicsPushContext function) before making any drawing calls. When you are done drawing,
you must similarly pop the graphics context off the stack using the UIGraphicsPopContext. Overlay drawing
typically occurs on background threads to improve performance, so do not manipulate UIKit views or other
objects that can only be manipulated on the apps main thread.
To improve drawing performance, the map view may divide your overlay into multiple tiles and render each
one on a separate thread. Your implementation of this method must therefore be capable of safely running
frommultiple threads simultaneously. In addition, you should avoid drawing the entire contents of the overlay
each time this method is called. Instead, always take the mapRect parameter into consideration and avoid
drawing content outside that rectangle.
Availability
Declared in
MKOverlayRenderer.h
initWithOverlay:
Initializes and returns the overlay renderer and associates it with the specified overlay object.
- (id)initWithOverlay:(id < MKOverlay >)overlay
Parameters
overlay
The overlay object to use when drawing the overlay content on the map. This object provides the data
needed to draw the overlays shape. The overlay renderer stores a strong reference to this object.
Return Value
An initialized overlay renderer object.
Discussion
Initially, the overlay renderer assumes that the overlay is fully opaque and that it has a content scale factor of
1.0. You can change these values as needed using the alpha (page 167) and contentScaleFactor (page 167)
properties.
Instance Methods
170
Availability
Declared in
MKOverlayRenderer.h
mapPointForPoint:
Returns the point on the map that corresponds to the specified point in the overlay renderers drawing area.
- (MKMapPoint)mapPointForPoint:(CGPoint)point
Parameters
point
The point in the overlays drawing area that you want to convert.
Return Value
The point on the two-dimensional map projection corresponding to the specified point.
Discussion
You may call this method safely from your views drawMapRect:zoomScale:inContext: (page 169) method.
Availability
Declared in
MKOverlayRenderer.h
mapRectForRect:
Returns the rectangle on the map that corresponds to the specified rectangle in the overlay renderers drawing
area.
- (MKMapRect)mapRectForRect:(CGRect)rect
Parameters
rect
The rectangle in the overlays drawing area that you want to convert.
Return Value
The rectangle on the two-dimensional map projection corresponding to the specified rectangle.
Instance Methods
171
Discussion
Availability
Declared in
MKOverlayRenderer.h
pointForMapPoint:
Returns the point in the overlay renderers drawing area corresponding to the specified point on the map.
- (CGPoint)pointForMapPoint:(MKMapPoint)mapPoint
Parameters
mapPoint
A point on the two-dimensional map projection. If you have a coordinate value (latitude and longitude),
you can use the MKMapPointForCoordinate (page 286) function to convert that coordinate to a map
point.
Return Value
The point in the overlays drawing area that corresponds to the map point.
Discussion
Availability
Declared in
MKOverlayRenderer.h
rectForMapRect:
Returns the rectangle in the overlay renderers drawing area corresponding to the specified rectangle on the map.
- (CGRect)rectForMapRect:(MKMapRect)mapRect
Parameters
mapRect
A rectangle on the two-dimensional map projection.
Instance Methods
172
Return Value
The rectangle in the overlays drawing area that corresponds to the map rectangle.
Discussion
Availability
Declared in
MKOverlayRenderer.h
setNeedsDisplay
Invalidates the entire contents of the overlay for all zoom scales.
- (void)setNeedsDisplay
Discussion
This method causes the entire contents of the overlay to be redrawn during the next update cycle. This method
invalidates the overlay regardless of the current zoom scale associated with the map.
Availability
Declared in
MKOverlayRenderer.h
setNeedsDisplayInMapRect:
Invalidates the specified portion of the overlay at all zoom scales
- (void)setNeedsDisplayInMapRect:(MKMapRect)mapRect
Parameters
mapRect
The portion of the overlay to update. Specify this value using a map coordinates.
Discussion
Marking a rectangle as invalid causes that portion of the overlay to be redrawn during the next update cycle.
This method invalidates the overlay regardless of the current zoom scale associated with the map.
Instance Methods
173
Availability
Declared in
MKOverlayRenderer.h
setNeedsDisplayInMapRect:zoomScale:
Invalidates the specified portion of the overlay but only at the specified zoom scale.
- (void)setNeedsDisplayInMapRect:(MKMapRect)mapRect zoomScale:(MKZoomScale)zoomScale
Parameters
mapRect
The portion of the overlay to update. Specify this value using a map coordinates.
zoomScale
The zoom scale for which you want to invalidate the overlay.
Discussion
Marking a rectangle as invalid causes that portion of the overlay to be redrawn during the next update cycle.
This method invalidates the overlay only at the specified zoom scale.
Availability
Declared in
MKOverlayRenderer.h
Instance Methods
174
NSObject (NSObject)
Declared in MKOverlayView.h
Related sample code
Breadcrumb
KMLViewer
PhotosByLocation
Regions
Overview
The MKOverlayView class defines the basic behavior associated with all overlay views. An overlay viewprovides
the visual representation of an overlay objectthat is, an object that conforms to the MKOverlay protocol.
This class defines the drawing infrastructure used by the map view but does not do any actual drawing.
Subclasses are expected to override the drawMapRect:zoomScale:inContext: (page 179) method in order to
draw the contents of the overlay view.
The Map Kit framework provides several concrete instances of overlay views. Specifically, it provides overlay
views for each of the concrete overlay objects. You can use one of these existing overlay views or define your
own subclass if you want to draw the overlay contents differently.
175
MKOverlayView Class Reference
In iOS 7 and later, use the MKOverlayRenderer class to display overlays instead.
Subclassing Notes
You can subclass MKOverlayView to create overlays based on custom shapes and content. The only method
subclasses are expected to override is the drawMapRect:zoomScale:inContext: (page 179) method. However,
if your class contains content that may not be ready for drawing right away, you should also override the
canDrawMapRect:zoomScale: (page 178) method and use it to report when your class is ready and able to
draw.
The implementation of your drawMapRect:zoomScale:inContext: (page 179) method must be safe to run
from multiple threads simultaneously. To improve performance, the map view may tile overlays that are large
enough and distribute the rendering of each tile to separate threads.
Tasks
Initializing an Overlay View
initWithOverlay: (page 180)
Initializes and returns the overlay view and associates it with the specified overlay object. (Deprecated.
Use an MKOverlayRenderer object instead.)
Attributes of the Overlay
overlay (page 177) property
The overlay object containing the data for drawing. (read-only) (Deprecated. Use an MKOverlayRenderer
object instead.)
Tasks
176
Converting Points on the Map
Returns the point in the overlay view that corresponds to specified point on the map. (Deprecated. Use
an MKOverlayRenderer object instead.)
Returns the map point that corresponds to the specified point in the overlay view. (Deprecated. Use an
MKOverlayRenderer object instead.)
Returns the rectangle in the overlay view that corresponds to the specified rectangle on the map.
(Deprecated. Use an MKOverlayRenderer object instead.)
Returns the map rectangle that corresponds to the rectangle in the overlay views coordinate system.
(Deprecated. Use an MKOverlayRenderer object instead.)
Drawing the Overlay
Returns a Boolean value indicating whether the overlay view is ready to draw its content. (Deprecated.
drawMapRect:zoomScale:inContext: (page 179)
Draws the contents of the overlay view. (Deprecated. Use an MKOverlayRenderer object instead.)
setNeedsDisplayInMapRect: (page 184)
Invalidates the view in the given map rectangle at all zoom scales. (Deprecated. Use an
setNeedsDisplayInMapRect:zoomScale: (page 184)
Invalidates the view in the given map rectangle but only at the specified zoom scale. (Deprecated. Use
Properties
overlay
The overlay object containing the data for drawing. (read-only) (Deprecated in iOS 7.0. Use an
Properties
177
@property (nonatomic, readonly) id <MKOverlay> overlay
Availability
Related Sample Code
Breadcrumb
PhotosByLocation
Declared in
MKOverlayView.h
Instance Methods
canDrawMapRect:zoomScale:
Returns a Boolean value indicating whether the overlay view is ready to draw its content. (Deprecated in iOS 7.0.
- (BOOL)canDrawMapRect:(MKMapRect)mapRect zoomScale:(MKZoomScale)zoomScale
Parameters
mapRect
The map rectangle that needs to be updated.
zoomScale
The current scale factor applied to the map.
Return Value
YES if this view is ready to draw its contents or NO if it is not.
Discussion
Overlay views can override this method in situations where they may depend on the availability of other
information to draw their contents. For example, an overlay view showing traffic information might want to
delay drawing until it has all of the traffic data it needs. In such a case, it can return NO from this method to
indicate that it is not ready.
If you return NO from this method, your application is responsible for calling the
setNeedsDisplayInMapRect:zoomScale: (page 184) method when the overlay view subsequently becomes
ready to draw its contents.
Instance Methods
178
The default implementation of this method returns YES.
Availability
Declared in
MKOverlayView.h
drawMapRect:zoomScale:inContext:
Draws the contents of the overlay view. (Deprecated in iOS 7.0. Use an MKOverlayRenderer object instead.)
- (void)drawMapRect:(MKMapRect)mapRect zoomScale:(MKZoomScale)zoomScale
inContext:(CGContextRef)context
Parameters
mapRect
The map rectangle that needs to be updated. You can use this rectangle to limit drawing to only the
portion of the view that changed.
zoomScale
The current scale factor applied to the map content. You can use this value for configuring the stroke
width of lines or other attributes that might be affected by the scale of the views content.
context
The graphics context to use for drawing the views content.
Discussion
The default implementation of this method does nothing. Subclasses are expected to override this method
(instead of the drawRect: method) and use it to draw the contents of the view.
In your drawing code, you should specify the position of any rendered content relative to the map itself and
not relative to the views bounds or frame. In other words, compute the position and size of any overlay content
using map points and map rectangles, convert those values to CGPoint and CGRect types (using the methods
of this class), and then use the converted points to build paths or specify the rendering location for items.
You should also not make assumptions that the views frame matches the bounding rectangle of the overlay.
The views frame is actually bigger than the bounding rectangle to allow you to draw lines for things like roads
that might be located directly on the border of that rectangle. For some types of content, such as gradients,
this also means that you might need to apply a clipping rectangle to context to ensure drawing is contained
to the correct area.
Instance Methods
179
It is recommended that you use Core Graphics to drawany content for your overlays. If you choose to use UIKit
classes and methods for drawing instead, you must push the specified graphics context onto the context stack
(using the UIGraphicsPushContext function) before making any drawing calls. When you are done drawing,
you must similarly pop the graphics context off the stack using the UIGraphicsPopContext. During drawing,
you may draw content normally but should avoid manipulating views and other classes that are safe to use
only from the applications main thread.
To improve drawing performance, the map view may tile overlays that become large enough and render the
tiles from separate threads. Your implementation of this method must therefore be capable of safely running
frommultiple threads simultaneously. In addition, you should avoid drawing the entire contents of the overlay
each time this method is called. Instead, your implementation should always take the mapRect parameter into
consideration and avoid drawing content outside that rectangle. Failure to do so could lead to performance
problems.
Availability
See Also
Declared in
MKOverlayView.h
initWithOverlay:
Initializes and returns the overlay view and associates it with the specified overlay object. (Deprecated in iOS 7.0.
- (id)initWithOverlay:(id <MKOverlay>)overlay
Parameters
overlay
The overlay object to use when drawing the overlay on the map. This object provides the data needed
to draw the overlays shape. This object is retained by the overlay view.
Return Value
An initialized overlay object.
Instance Methods
180
Discussion
Upon initialization, the frame of the overlay viewis set to CGRectZero. The map viewsets the size and position
of the view at display time, and you should not change those values yourself.
Availability
Related Sample Code
Breadcrumb
PhotosByLocation
Regions
Declared in
MKOverlayView.h
mapPointForPoint:
Returns the map point that corresponds to the specified point in the overlay view. (Deprecated in iOS 7.0. Use an
- (MKMapPoint)mapPointForPoint:(CGPoint)point
Parameters
point
The point in the views coordinate system that you want to convert.
Return Value
The point on the two-dimensional map projection corresponding to the specified point.
Because the bounds and frame rectangles of an overlay view do not change after the view has been created,
you may call this method from multiple threads simultaneously. Therefore, you may call this method safely
from your views drawMapRect:zoomScale:inContext: (page 179) method.
Availability
See Also
Instance Methods
181
Declared in
MKOverlayView.h
mapRectForRect:
Returns the map rectangle that corresponds to the rectangle in the overlay views coordinate system. (Deprecated
in iOS 7.0. Use an MKOverlayRenderer object instead.)
- (MKMapRect)mapRectForRect:(CGRect)rect
Parameters
rect
The rectangle specified in the receivers coordinate system.
Return Value
The rectangle on the two-dimensional map project that corresponds to the specified view rectangle.
Availability
See Also
Declared in
MKOverlayView.h
pointForMapPoint:
Returns the point in the overlay view that corresponds to specified point on the map. (Deprecated in iOS 7.0. Use
- (CGPoint)pointForMapPoint:(MKMapPoint)mapPoint
Instance Methods
182
Parameters
mapPoint
A point on the two-dimensional map projection. If you have a coordinate value (latitude and longitude),
you can use the MKMapPointForCoordinate (page 286) function to convert that coordinate to a map
point.
Return Value
The point in the receivers coordinate system that corresponds to the map point.
Availability
See Also
Declared in
MKOverlayView.h
rectForMapRect:
Returns the rectangle in the overlay view that corresponds to the specified rectangle on the map. (Deprecated in
iOS 7.0. Use an MKOverlayRenderer object instead.)
- (CGRect)rectForMapRect:(MKMapRect)mapRect
Parameters
mapRect
A rectangle on the two-dimensional map projection.
Return Value
The rectangle specified in the receivers coordinate system.
Instance Methods
183
Availability
See Also
Declared in
MKOverlayView.h
setNeedsDisplayInMapRect:
Invalidates the view in the given map rectangle at all zoom scales. (Deprecated in iOS 7.0. Use an
- (void)setNeedsDisplayInMapRect:(MKMapRect)mapRect
Parameters
mapRect
The portion of the overlay that needs to be updated. This value is specified using a map rectangle and
not view coordinates. You can convert from a view rectangle to a map rectangle using the
mapRectForRect: (page 182) method.
Discussion
Marking a rectangle as invalid causes that portion of the viewto be redrawn during the next update cycle. This
method invalidates the overlay regardless of the current zoom scale associated with the map.
Availability
Declared in
MKOverlayView.h
setNeedsDisplayInMapRect:zoomScale:
Invalidates the view in the given map rectangle but only at the specified zoom scale. (Deprecated in iOS 7.0. Use
- (void)setNeedsDisplayInMapRect:(MKMapRect)mapRect zoomScale:(MKZoomScale)zoomScale
Instance Methods
184
Parameters
mapRect
The portion of the overlay that needs to be updated. This value is specified using a map rectangle and
not view coordinates. You can convert from a view rectangle to a map rectangle using the
mapRectForRect: (page 182) method.
zoomScale
The zoom scale for which you want to invalidate the overlay.
Discussion
Marking a rectangle as invalid causes that portion of the viewto be redrawn during the next update cycle. This
method invalidates the overlay only when it is drawn at the specified zoom scale.
Availability
Declared in
MKOverlayView.h
Instance Methods
185
Inherits from MKAnnotationView : UIView : UIResponder : NSObject
NSObject (NSObject)
Declared in MKAnnotationView.h
Related sample code
KMLViewer
MapCallouts
MapSearch
PhotosByLocation
Regions
Overview
The MKPinAnnotationView class provides a concrete annotation view that displays a pin icon like the ones
found in the Maps application. Using this class, you can configure the type of pin to drop and whether you
want the pin to be animated into place.
186
MKPinAnnotationView Class Reference
Tasks
Getting and Setting Attributes
pinColor (page 188) property
The color of the pin head.
animatesDrop (page 187) property
A Boolean value indicating whether the annotation view is animated onto the screen.
Properties
animatesDrop
A Boolean value indicating whether the annotation view is animated onto the screen.
@property (nonatomic) BOOL animatesDrop
Discussion
When this property is YES, the map view animates the appearance of pin annotation views by making them
appear to drop onto the map at the target point. This animation occurs whenever the view transitions from
offscreen to onscreen.
Availability
Related Sample Code
KMLViewer
MapCallouts
MapSearch
Declared in
Tasks
187
pinColor
The color of the pin head.
@property (nonatomic) MKPinAnnotationColor pinColor
Discussion
The Maps application uses different pin colors for different types of map annotations. Your own map annotation
should use the available pin colors in the same way. For a description of when to use each type of pin, see the
constants of MKPinAnnotationColor (page 188).
Availability
Related Sample Code
MapCallouts
Declared in
Constants
MKPinAnnotationColor
The supported colors for pin annotations.
enum {
MKPinAnnotationColorRed = 0,
MKPinAnnotationColorGreen,
MKPinAnnotationColorPurple
};
typedef NSUInteger MKPinAnnotationColor;
Constants
MKPinAnnotationColorRed
The head of the pin is red. Red pins indicate destination points on the map.
Declared in MKPinAnnotationView.h.
Constants
188
MKPinAnnotationColorGreen
The head of the pin is green. Green pins indicate starting points on the map.
MKPinAnnotationColorPurple
The head of the pin is purple. Purple pins indicate user-specified points on the map.
Constants
189
Inherits from CLPlacemark : NSObject
Conforms to MKAnnotation
NSCopying (CLPlacemark)
NSSecureCoding (CLPlacemark)
NSObject (NSObject)
Declared in MKPlacemark.h
Related sample code
CurrentAddress
Overview
A MKPlacemark object stores placemark data for a given latitude and longitude. Placemark data includes
information such as the country, state, city, and street address associated with the specified coordinate. You
can initialize a placemark using the initWithPlacemark: inherited method or the
initWithCoordinate:addressDictionary: (page 192) method specifying a coordinate and address dictionary.
Aplacemark is also an annotation and conforms to the MKAnnotation protocol, whose properties and methods
include the placemark coordinate and other information. Because they are annotations, you can add them
directly to the map view.
190
MKPlacemark Class Reference
Tasks
Initializing a Placemark Object
initWithCoordinate:addressDictionary: (page 192)
Initializes and returns a placemark object using the specified coordinate and Address Book dictionary.
Accessing the Placemark Attributes
countryCode (page 191) property Deprecated in iOS 7.0
The abbreviated country name. (read-only)
Properties
countryCode
The abbreviated country name. (read-only)
@property(nonatomic, readonly) NSString *countryCode
Discussion
This string is the standard abbreviation used to refer to the country. For example, if the placemark location
was Apples headquarters, the value for this property would be the string US.
Availability
Declared in
MKPlacemark.h
Tasks
191
Instance Methods
initWithCoordinate:addressDictionary:
Initializes and returns a placemark object using the specified coordinate and Address Book dictionary.
- (id)initWithCoordinate:(CLLocationCoordinate2D)coordinate
addressDictionary:(NSDictionary *)addressDictionary
Parameters
coordinate
The map coordinate to associate with the placemark.
addressDictionary
A dictionary containing keys and values from an Address Book record. For a list of strings that you can
use for the keys of this dictionary, see the Address Property constants in ABPerson Reference . All of the
keys in should be at the top level of the dictionary.
Return Value
An initialized MKPlacemark object.
Discussion
You can create placemark objects manually for entities for which you already have address information, such
as contacts in the Address Book. Creating a placemark object explicitly avoids the need to query the reverse
geocoder object for the same information.
Availability
Related Sample Code
Declared in
MKPlacemark.h
Instance Methods
192
Conforms to MKAnnotation (MKShape)
NSObject (NSObject)
Declared in MKPointAnnotation.h
Related sample code
KMLViewer
PhotosByLocation
Overview
The MKPointAnnotation class defines a concrete annotation object located at a specified point. You can use
this class, rather than define your own, in situations where all you want to do is associate a point on the map
with a title.
193
MKPointAnnotation Class Reference
Tasks
Accessing the Annotations Location
The coordinate point of the annotation, specified as a latitude and longitude.
Properties
coordinate
The coordinate point of the annotation, specified as a latitude and longitude.
@property (nonatomic, assign) CLLocationCoordinate2D coordinate
Availability
Related Sample Code
KMLViewer
PhotosByLocation
Declared in
MKPointAnnotation.h
MKPointAnnotation Class Reference
Tasks
194
Inherits from MKMultiPoint : MKShape : NSObject
NSObject (NSObject)
Declared in MKPolygon.h
Related sample code
KMLViewer
Overview
The MKPolygon class represents a shape consisting of one or more points that define a closed polygon. The
points are connected end-to-end in the order they are provided. The first and last points are connected to
each other to create the closed shape.
When creating a polygon, you can mask out portions of the polygon by specifying one or more interior polygons.
For the polygons you specify, this class uses the even-odd fill rule to determine the final occupied area. When
applied to overlapping polygons, this rule can cause specific regions to be masked out (and thereby removed)
from the total occupied area. For more information about how fill rules are applied to paths, see Paths in
Quartz 2D Programming Guide .
195
MKPolygon Class Reference
Tasks
Creating a Polygon Overlay
+ polygonWithPoints:count: (page 198)
Creates and returns an MKPolygon object from the specified set of map points.
+ polygonWithPoints:count:interiorPolygons: (page 199)
Creates and returns an MKPolygon object from the specified set of map points and interior polygons.
+ polygonWithCoordinates:count: (page 197)
Creates and returns an MKPolygon object from the specified set of coordinates.
+ polygonWithCoordinates:count:interiorPolygons: (page 197)
Creates and returns an MKPolygon object from the specified set of coordinates and interior polygons.
Accessing the Interior Polygons
interiorPolygons (page 196) property
The array of polygons nested inside the receiver. (read-only)
Properties
interiorPolygons
The array of polygons nested inside the receiver. (read-only)
@property (readonly) NSArray *interiorPolygons
Discussion
When a polygon is rendered on screen, the area occupied by any interior polygons is masked out and not
considered part of the polygon.
Tasks
196
Availability
Declared in
MKPolygon.h
Class Methods
polygonWithCoordinates:count:
Creates and returns an MKPolygon object from the specified set of coordinates.
+ (MKPolygon *)polygonWithCoordinates:(CLLocationCoordinate2D *)coords
Parameters
coords
The array of coordinates defining the shape. The data in this array is copied to the new object.
count
Return Value
A new polygon object.
Availability
Related Sample Code
KMLViewer
Declared in
MKPolygon.h
polygonWithCoordinates:count:interiorPolygons:
Creates and returns an MKPolygon object from the specified set of coordinates and interior polygons.
+ (MKPolygon *)polygonWithCoordinates:(CLLocationCoordinate2D *)coords
count:(NSUInteger)count interiorPolygons:(NSArray *)interiorPolygons
Class Methods
197
Parameters
coords
count
interiorPolygons
An array of MKPolygon objects that define one or more cutout regions for the receivers polygon.
Return Value
Availability
Related Sample Code
KMLViewer
Declared in
MKPolygon.h
polygonWithPoints:count:
Creates and returns an MKPolygon object from the specified set of map points.
+ (MKPolygon *)polygonWithPoints:(MKMapPoint *)points count:(NSUInteger)count
Parameters
points
The array of map points defining the shape. The data in this array is copied to the new object.
count
Return Value
Availability
Declared in
MKPolygon.h
Class Methods
198
polygonWithPoints:count:interiorPolygons:
Creates and returns an MKPolygon object from the specified set of map points and interior polygons.
+ (MKPolygon *)polygonWithPoints:(MKMapPoint *)points count:(NSUInteger)count
interiorPolygons:(NSArray *)interiorPolygons
Parameters
points
count
interiorPolygons
An array of MKPolygon objects that define one or more cutout regions for the receivers polygon.
Return Value
Availability
Declared in
MKPolygon.h
Class Methods
199
Declared in MKPolygonRenderer.h
Overview
The MKPolygonRenderer class provides the visual representation for an MKPolygon overlay object. This
renderer fills and strokes the polygon represented by first filling the shape and then stroking its outline. You
can change the color and other drawing attributes of the polygon by modifying the properties inherited from
the parent class. You typically use this class as is and do not subclass it.
Tasks
Initializing a Polygon Renderer
initWithPolygon: (page 201)
Initializes and returns a new renderer that handles drawing for the specified polygon overlay object.
Accessing the Polygon Overlay Object
polygon (page 201) property
The polygon object that contains the information used to draw the overlays contents. (read-only)
200
MKPolygonRenderer Class Reference
Properties
polygon
The polygon object that contains the information used to draw the overlays contents. (read-only)
@property(nonatomic, readonly) MKPolygon *polygon
Availability
Declared in
MKPolygonRenderer.h
Instance Methods
initWithPolygon:
Initializes and returns a new renderer that handles drawing for the specified polygon overlay object.
- (id)initWithPolygon:(MKPolygon *)polygon
Parameters
polygon
The polygon overlay containing information about the area to be drawn. This object must have at least
three points defining the polygon to draw. This parameter must not be nil.
Return Value
An initialized polygon renderer object.
Availability
Declared in
MKPolygonRenderer.h
MKPolygonRenderer Class Reference
Properties
201
NSObject (NSObject)
Declared in MKPolygonView.h
Related sample code
KMLViewer
Overview
The MKPolygonView class provides the visual representation for an MKPolygon annotation object. This view
fills and strokes the area represented by the annotation. You can change the color and other drawing attributes
of the polygon by modifying the properties inherited fromthe MKOverlayPathView class. This class is typically
used as is and not subclassed.
In iOS 7 and later, use the MKPolygonRenderer class to display polygon overlays instead.
202
MKPolygonView Class Reference
Tasks
Initializing a Polygon View
initWithPolygon: (page 203)
Initializes and returns a new overlay view using the specified polygon overlay object. (Deprecated. Use
an MKPolygonRenderer object instead.)
Accessing the Polygon Overlay
polygon (page 203) property
The polygon overlay object that contains the information used to drawthe overlay. (read-only) (Deprecated.
Use an MKPolygonRenderer object instead.)
Properties
polygon
The polygon overlay object that contains the information used to draw the overlay. (read-only) (Deprecated in
iOS 7.0. Use an MKPolygonRenderer object instead.)
@property (nonatomic, readonly) MKPolygon *polygon
Availability
Declared in
MKPolygonView.h
Instance Methods
initWithPolygon:
Initializes and returns a new overlay view using the specified polygon overlay object. (Deprecated in iOS 7.0. Use
an MKPolygonRenderer object instead.)
Tasks
203
- (id)initWithPolygon:(MKPolygon *)polygon
Parameters
polygon
The polygon overlay containing the information about the area to be drawn. This object must have at
least three points defining the polygon in order for this view to draw the corresponding path.
Return Value
A new polygon overlay view.
Availability
Related Sample Code
KMLViewer
Declared in
MKPolygonView.h
Instance Methods
204
Inherits from MKMultiPoint : MKShape : NSObject
NSObject (NSObject)
Declared in MKPolyline.h
Related sample code
KMLViewer
Overview
The MKPolyline class represents a shape consisting of one or more points that define connecting line segments.
The points are connected end-to-end in the order they are provided. The first and last points are not connected
to each other.
205
MKPolyline Class Reference
Tasks
Creating a Polyline Overlay
+ polylineWithPoints:count: (page 207)
Creates and returns an MKPolyline object from the specified set of map points.
+ polylineWithCoordinates:count: (page 206)
Creates and returns an MKPolyline object from the specified set of coordinates.
Class Methods
polylineWithCoordinates:count:
Creates and returns an MKPolyline object from the specified set of coordinates.
+ (instancetype)polylineWithCoordinates:(CLLocationCoordinate2D *)coords
Parameters
coords
count
Return Value
A new polyline object.
Availability
Related Sample Code
KMLViewer
Tasks
206
Declared in
MKPolyline.h
polylineWithPoints:count:
Creates and returns an MKPolyline object from the specified set of map points.
+ (instancetype)polylineWithPoints:(MKMapPoint *)points count:(NSUInteger)count
Parameters
points
count
Return Value
A new polyline object.
Availability
Declared in
MKPolyline.h
Class Methods
207
Declared in MKPolylineRenderer.h
Overview
The MKPolylineRenderer class provides the visual representation for an MKPolyline overlay object. This
renderer strokes the line only; it does not fill it. You can change the color and other drawing attributes of the
polygon by modifying the properties inherited from the parent class. You typically use this class as is and do
not subclass it.
Tasks
Initializing the Polyline Renderer
initWithPolyline: (page 209)
Initializes and returns a new overlay view using the specified polyline overlay object
Accessing the Polyline Overlay
polyline (page 209) property
The polyline overlay object that contains the information used to draw the overlay. (read-only)
208
MKPolylineRenderer Class Reference
Properties
polyline
The polyline overlay object that contains the information used to draw the overlay. (read-only)
@property(nonatomic, readonly) MKPolyline *polyline
Availability
Declared in
Instance Methods
initWithPolyline:
Initializes and returns a new overlay view using the specified polyline overlay object
- (id)initWithPolyline:(MKPolyline *)polyline
Parameters
polyline
The polyline overlay containing information about the area to be drawn. This object must have at least
two points defining the line segment to draw. This parameter must not be nil.
Return Value
An initialized polyline renderer object.
Availability
Declared in
MKPolylineRenderer Class Reference
Properties
209
NSObject (NSObject)
Declared in MKPolylineView.h
Related sample code
KMLViewer
Overview
The MKPolylineView class provides the visual representation for an MKPolyline annotation object. This
view strokes the path represented by the annotation. (This class does not fill the area enclosed by the path.)
You can change the color and other drawing attributes of the path by modifying the properties inherited from
the MKOverlayPathView class. This class is typically used as is and not subclassed.
In iOS 7 and later, use the MKPolylineRenderer class to display polyline overlays instead.
210
MKPolylineView Class Reference
Tasks
Initializing the Polyline View
initWithPolyline: (page 211)
Initializes and returns a new overlay view using the specified polyline overlay object (Deprecated. Use
an MKPolylineRenderer object instead.)
Accessing the Polyline Overlay
The polyline overlay object that contains the information used to drawthe overlay. (read-only) (Deprecated.
Use an MKPolylineRenderer object instead.)
Properties
polyline
The polyline overlay object that contains the information used to draw the overlay. (read-only) (Deprecated in
iOS 7.0. Use an MKPolylineRenderer object instead.)
@property (nonatomic, readonly) MKPolyline *polyline
Availability
Declared in
MKPolylineView.h
Instance Methods
initWithPolyline:
Initializes and returns a new overlay view using the specified polyline overlay object (Deprecated in iOS 7.0. Use
an MKPolylineRenderer object instead.)
Tasks
211
- (id)initWithPolyline:(MKPolyline *)polyline
Parameters
polyline
The polyline overlay object containing the information about the path to be stroked. This object must
have at least two points defined in order for this view to draw the corresponding path.
Return Value
A new polyline overlay view.
Availability
Related Sample Code
KMLViewer
Declared in
MKPolylineView.h
Instance Methods
212
Declared in MKReverseGeocoder.h
This class is deprecated in iOS 5.0. Use the CLGeocoder class instead.
Overview
The MKReverseGeocoder class provides services for converting a map coordinate (specified as a
latitude/longitude pair) into information about that coordinate, such as the country, city, or street. A reverse
geocoder object is a single-shot object that works with a network-based map service to look up placemark
information for its specified coordinate value.
The Google terms of service require that the reverse geocoding service be used in conjunction with a Google
map; take this into account when designing your application's user interface.
Each Map Kit application has a limited amount of reverse geocoding capacity, so it is to your advantage to use
reverse geocode requests sparingly. Here are some rules of thumb for using this class most effectively:

Send at most one reverse-geocoding request for any one user action.
213
MKReverseGeocoder Class Reference

If the user performs multiple actions that involve reverse-geocoding the same location, reuse the results
from the initial reverse-geocoding request instead of starting individual requests for each action.

When you want to update the location automatically (such as when the user is moving), reissue the
reverse-geocoding request only when the user's location has moved a significant distance and after a
reasonable amount of time has passed. For example, in a typical situation, you should not send more than
one reverse-geocode request per minute.

Do not start a reverse-geocoding request at a time when the user will not see the results immediately. For
example, do not start a request if your application recently resigned the active state (possibly because of
an interruption such as a phone call) and is waiting to become active again.
An iOS-based device must have access to the network in order for the reverse geocoder object to return valid
information. The reverse geocoder returns information through its associated delegate object, which is an
object that conforms to the MKReverseGeocoderDelegate protocol. If the reverse geocoder is unable to
retrieve the requested information, it similarly reports the error to its delegate object. For more information
on this protocol, see MKReverseGeocoderDelegate Protocol Reference .
Tasks
Initializing the Reverse Geocoder
initWithCoordinate: (page 217)
Initializes the reverse geocoder with the specified coordinate value. (Deprecated. Use the CLGeocoder
class instead.)
Accessing Reverse Geocoder Attributes
delegate (page 215) property
The reverse geocoders delegate object. (Deprecated. Use the CLGeocoder class instead.)
The coordinate whose placemark data you want to retrieve. (read-only) (Deprecated. Use the CLGeocoder
class instead.)
placemark (page 216) property
The result of the reverse-geocoding operation. (read-only) (Deprecated. Use the CLGeocoder class
instead. Note that placemarks in CLGeocoder always come back to the coordinate of the place, not the
requested coordinate.)
Tasks
214
Managing the Search
start (page 218)
Starts the reverse-geocoding process asynchronously. (Deprecated. Use the CLGeocoder class instead.)
querying (page 216) property
A Boolean value indicating whether the receiver is in the middle of reverse-geocoding its coordinate.
(read-only) (Deprecated. Use the CLGeocoder class instead.)
cancel (page 217)
Cancels a pending reverse-geocoding request. (Deprecated. Use the CLGeocoder class instead.)
Properties
coordinate
The coordinate whose placemark data you want to retrieve. (read-only) (Deprecated in iOS 5.0. Use the
CLGeocoder class instead.)
@property(nonatomic, readonly) CLLocationCoordinate2D coordinate
Availability
Declared in
MKReverseGeocoder.h
delegate
The reverse geocoders delegate object. (Deprecated in iOS 5.0. Use the CLGeocoder class instead.)
@property(nonatomic, assign) id<MKReverseGeocoderDelegate> delegate
Discussion
Areverse-geocoder object sends messages to its delegate regarding the successful (or unsuccessful) acquisition
of placemark data. You must provide a delegate object to receive this data.
For more information about the MKReverseGeocoderDelegate protocol, see MKReverseGeocoderDelegate
Protocol Reference .
Properties
215
Availability
Declared in
MKReverseGeocoder.h
placemark
The result of the reverse-geocoding operation. (read-only) (Deprecated in iOS 5.0. Use the CLGeocoder class
instead. Note that placemarks inCLGeocoderalways come back tothe coordinate of the place, not the requested
coordinate.)
@property(nonatomic, readonly) MKPlacemark *placemark
Discussion
The value of this property is nil by default. After a successful reverse-geocoding operation, it is set to the
placemark object that was generated.
Availability
Declared in
MKReverseGeocoder.h
querying
A Boolean value indicating whether the receiver is in the middle of reverse-geocoding its coordinate. (read-only)
(Deprecated in iOS 5.0. Use the CLGeocoder class instead.)
@property(nonatomic, readonly, getter=isQuerying) BOOL querying
Discussion
This property contains YES if the process is ongoing or NO if the process is done or has not yet been initiated.
Availability
Properties
216
Declared in
MKReverseGeocoder.h
Instance Methods
cancel
Cancels a pending reverse-geocoding request. (Deprecated in iOS 5.0. Use the CLGeocoder class instead.)
- (void)cancel
Discussion
You can use this method to cancel a pending request and free up the resources associated with that request.
If the request has already returned or has not yet begun, calling this method has no effect.
Availability
Declared in
MKReverseGeocoder.h
initWithCoordinate:
Initializes the reverse geocoder with the specified coordinate value. (Deprecated in iOS 5.0. Use the CLGeocoder
class instead.)
- (id)initWithCoordinate:(CLLocationCoordinate2D)coordinate
Parameters
coordinate
The map coordinate whose placemark information you want to retrieve.
Return Value
An initialized MKReverseGeocoder object.
Availability
Instance Methods
217
Declared in
MKReverseGeocoder.h
start
Starts the reverse-geocoding process asynchronously. (Deprecated in iOS 5.0. Use the CLGeocoderclass instead.)
- (void)start
Discussion
You should call this method only once to begin the reverse-geocoding process. This method submits the
coordinate value to the map server asynchronously and returns. Once the process is complete, the results are
delivered to the associated delegate object.
Availability
Declared in
MKReverseGeocoder.h
Instance Methods
218
Overview
The MKRoute class defines a single route that the user can follow between a requested start and end point.
The route object defines the geometry for the route and includes information you can display to the user in
association with that route, such as the name of the route, its distance, and the expected travel time.
You do not create instances of this class directly. Instead, you receive route objects when you request directions
from the Maps app. For more information about requesting directions, see MKDirections Class Reference .
Tasks
Getting the Route Geometry
The detailed route geometry. (read-only)
steps (page 222) property
The array of steps that comprise the overall route. (read-only)
Getting Additional Route Details
name (page 221) property
The name assigned to the route. (read-only)
219
MKRoute Class Reference
advisoryNotices (page 220) property
An array of advisory notice strings for the route. (read-only)
distance (page 220) property
The route distance in meters. (read-only)
expectedTravelTime (page 221) property
The overall route transport type. (read-only)
Properties
advisoryNotices
An array of advisory notice strings for the route. (read-only)
@property (nonatomic, readonly) NSArray *advisoryNotices
Discussion
This property contains an array of NSString objects. Each string is localized according to the users language
preferences. The strings contain additional information that is important for the user to know about the route.
For example, a string might note that a portion of the route is closed during the winter or after big storms.
Availability
Declared in
distance
The route distance in meters. (read-only)
@property (nonatomic, readonly) CLLocationDistance distance
Discussion
This property reflects the distance that the user covers while traversing the path of the route. It is not a direct
distance between the start and end points of the route.
Properties
220
Availability
Declared in
expectedTravelTime
@property (nonatomic, readonly) NSTimeInterval expectedTravelTime
Discussion
This expected travel time reflects the time it takes to traverse the route under ideal conditions. The actual
amount of time may vary based on conditions.
Availability
Declared in
name
The name assigned to the route. (read-only)
@property (nonatomic, readonly) NSString *name
Discussion
The string in this property is localized according to the users language preferences. You can display this string
to the user from your apps user interface so that the user can distinguish one route from another.
The string itself describes the route using one of the routes significant features. For example, a route that uses
a major highway for a significant portion of the route might use that highway for its name.
Availability
Declared in
Properties
221
polyline
The detailed route geometry. (read-only)
Discussion
The polyline object in this property reflects the complete path of the route, including all of its steps. You can
use the polyline object as an overlay in a map view.
Availability
Declared in
steps
The array of steps that comprise the overall route. (read-only)
@property (nonatomic, readonly) NSArray *steps
Discussion
The array contains one or more MKRouteStep objects representing distinct portions of the route. Each step
corresponds to a single direction that must be followed along the route.
Availability
Declared in
transportType
The overall route transport type. (read-only)
@property (nonatomic, readonly) MKDirectionsTransportType transportType
Discussion
This property reflects the primary transport type used for the route. Individual steps of the route might use
different transport types.
Properties
222
Availability
Declared in
Properties
223
Overview
An MKRouteStep object represents one part of an overall route. Each step in a route corresponds to a single
instruction that would need to be followed by the user. For example, a step might involve following a single
road until a turn is required.
You do not create instances of this class directly. Instead, you receive route steps as part of an overall MKRoute
object when you request directions from the Maps app. For more information about requesting directions,
see MKDirections Class Reference .
Tasks
Getting the Step Geometry
The detailed step geometry. (read-only)
Getting Additional Step Details
instructions (page 225) property
The written instructions for following the path represented by this step. (read-only)
notice (page 226) property
Additional notices that apply to the step. (read-only)
224
MKRouteStep Class Reference
distance (page 225) property
The step distance in meters. (read-only)
The transport type of the step. (read-only)
Properties
distance
The step distance in meters. (read-only)
@property (nonatomic, readonly) CLLocationDistance distance
Discussion
This property reflects the distance that the user covers while traversing the path of the step. It is not a direct
distance between the start and end points of the step.
Availability
Declared in
instructions
The written instructions for following the path represented by this step. (read-only)
@property (nonatomic, readonly) NSString *instructions
Discussion
The string in this property is localized according to the users language preferences. You can present this string
to the user from your apps interface.
Availability
Declared in
Properties
225
notice
Additional notices that apply to the step. (read-only)
@property (nonatomic, readonly) NSString *notice
Discussion
Notices may include legal information or warning notices that apply to the step. For example, if the step crosses
railroad tracks, it might contain a notice that warns the user not to cross the tracks when the lights are flashing.
Availability
Declared in
polyline
The detailed step geometry. (read-only)
Discussion
The polyline object in this property contains the geometry for this step. You can use the polyline object as an
overlay in a map view.
Availability
Declared in
transportType
The transport type of the step. (read-only)
@property (nonatomic, readonly) MKDirectionsTransportType transportType
Discussion
This property reflects the transport type employed by the step and may differ from the transport type of the
overall route.
Properties
226
Availability
Declared in
Properties
227
NSObject (NSObject)
Declared in MKShape.h
Related sample code
KMLViewer
Overview
The MKShape class is an abstract class that defines the basic properties for all shape-based annotation objects.
This class must be subclassed and cannot be used as is. Subclasses are responsible for defining the geometry
of the shape and providing an appropriate value for the coordinate (page 252) property inherited from the
MKAnnotation protocol.
228
MKShape Class Reference
Tasks
Accessing the Shape Attributes
title (page 229) property
The title of the shape annotation.
subtitle (page 229) property
The subtitle of the shape annotation.
Properties
subtitle
The subtitle of the shape annotation.
@property(nonatomic, copy) NSString *subtitle
Discussion
This string is displayed in the callout for the associated annotation view. The default value of this property is
nil.
Availability
Declared in
MKShape.h
title
The title of the shape annotation.
Tasks
229
@property(nonatomic, copy) NSString *title
Discussion
This string is displayed in the callout for the associated annotation view. The default value of this property is
nil.
Availability
Related Sample Code
KMLViewer
Declared in
MKShape.h
Properties
230
NSObject (NSObject)
Declared in MKTileOverlay.h
Overview
The MKTileOverlay class implements an overlay that is optimized for covering an area of the map using
individual bitmap tiles. (In general, a map tile is a prerendered map image that covers a specific geographic
area.) You can use tile overlay objects to represent your own tile-based content and to coordinate the display
of that content in a map view. Your tiles can supplement the underlying map content or replace it completely.
A tile overlay object coordinates the loading and management of the tiles while a corresponding
MKTileOverlayRenderer object handles the actual drawing of the tiles on the map.
You can use a single tile overlay object to represent all of the tiles at one or more zoom levels of the map. The
default tile overlay object uses a template string to build URLs so that it can locate the map tiles it needs. Each
URL incorporates the x and y index of the map tile, the zoom level it is intended for, and the scale factor
corresponding to the screen resolution on which to display the tile. The default class lets you specify map tiles
whose indexes start in either the upper-left corner or lower-left corner of the map. If you use a different indexing
scheme for your tiles, you can also subclass and override the URLForTilePath: (page 237) or
loadTileAtPath:result: (page 236) methods to map between the requested tile and your custom indexing
scheme.
231
MKTileOverlay Class Reference
Tasks
Initializing a Tile Overlay
initWithURLTemplate: (page 235)
Initializes and returns a tile overlay object using the specified tile-access template.
Accessing the Tile Attributes
tileSize (page 235) property
The size (in pixels) of your tile images.
geometryFlipped (page 233) property
A Boolean value that indicates the orientation of tile indexes along the y axis.
minimumZ (page 234) property
The minimum zoom level supported by the tiles of this overlay object.
canReplaceMapContent (page 232) property
A Boolean value that indicates whether the tile content is fully opaque.
maximumZ (page 233) property Deprecated in iOS 5.0 Deprecated in iOS 7.0 Deprecated in iOS 7.0
The maximum zoom level supported by the tiles of this overlay object.
Customizing the Loading of Tiles
URLTemplate (page 235) property
The template for generating tile image URLs. (read-only)
URLForTilePath: (page 237)
Returns the URL to use to access the specified tile.
loadTileAtPath:result: (page 236)
Loads the specified tile asynchronously.
Properties
canReplaceMapContent
A Boolean value that indicates whether the tile content is fully opaque.
Tasks
232
@property (nonatomic) BOOL canReplaceMapContent
Discussion
If the tile content you provide can cover the entire drawing area with opaque content, set this property to
YES. Doing so serves as a hint to the map viewthat it does not need to drawany additional content underneath
your tiles. Set this property to NO if your tiles contain any transparency.
The default value for this property is NO.
Availability
Declared in
MKTileOverlay.h
geometryFlipped
A Boolean value that indicates the orientation of tile indexes along the y axis.
@property(getter=isGeometryFlipped) BOOL geometryFlipped
Discussion
When set to NO, tile indexes start in the upper-left corner of the map and proceed down and to the right. Thus,
the tile at (0, 0)is in the upper-left corner of the map, the tile at (1, 0) is to its immediate right and the
tile at (0, 1) is immediately below it. Setting this property to YES causes the map to start indexes at the
lower-left corner of the map and proceed up and to the right.
The default value of this property is NO.
Availability
Declared in
MKTileOverlay.h
maximumZ
The maximum zoom level supported by the tiles of this overlay object.
Properties
233
@property NSInteger maximumZ
Discussion
If you use different overlay objects to represent different tiles at different zoom levels, use this property to
specify the maximum zoom level supported by this overlays tiles. At zoom level 0, tiles cover the entire world
map; at zoom level 1, tiles cover 1/4 of the world; at zoom level 2, tiles cover 1/16 of the world, and so on. The
map never tries to load tiles for a zoom level greater than the value specified by this property.
The default value of this property is 21. Setting the value of this property to a number greater than the default
does not guarantee the use of those extra zoom levels.
Availability
See Also
@property minimumZ (page 234)
Declared in
MKTileOverlay.h
minimumZ
The minimum zoom level supported by the tiles of this overlay object.
@property NSInteger minimumZ
Discussion
If you use different overlay objects to represent different tiles at different zoom levels, use this property to
specify the minimum zoom level supported by this overlays tiles. At zoom level 0, tiles cover the entire world
map; at zoom level 1, tiles cover 1/4 of the world; at zoom level 2, tiles cover 1/16 of the world, and so on. The
map never tries to load tiles for a zoom level less than the value specified by this property.
Availability
See Also
@property maximumZ (page 233)
Declared in
MKTileOverlay.h
Properties
234
tileSize
The size (in pixels) of your tile images.
@property CGSize tileSize
Discussion
On Retina displays, the images are rendered pixel for pixel and are not scaled. This means that if the tile size
is 256 x 256 pixels and the scale factor is 2.0, the image would be rendered as if it were 128 x 128 points in
size. This behavior causes the tile to appear smaller but preserves the original image data.
The default tile size is set to 256 x 256 pixels.
Availability
Declared in
MKTileOverlay.h
URLTemplate
The template for generating tile image URLs. (read-only)
@property(readonly) NSString *URLTemplate
Discussion
You specify this string at initialization time.
Availability
See Also
Declared in
MKTileOverlay.h
Instance Methods
initWithURLTemplate:
Initializes and returns a tile overlay object using the specified tile-access template.
Instance Methods
235
- (id)initWithURLTemplate:(NSString *)URLTemplate
Parameters
URLTemplate
A string that can be used to build a URL to access your tile images. The string you specify can point to a
local file or to an image on a remote server. To facilitate retrieving multiple tiles using the string, use the
placeholder values {x}, {y}, {z}, and {scale} as stand-ins for the x and y tile indexes, the zoom level,
and the resolution of the tile image. If this parameter is nil, you must provide custom implementations
for the tile-loading methods of this class.
Return Value
An initialized tile overlay object.
Discussion
The default tile overlay object uses the template string you specify to request tiles. This template string should
incorporate the {x}, {y}, {z}, and {scale} placeholder strings to facilitate the creation of a URL for requesting
the appropriate tile. For example, if you have a server that vends tiles when you provide a URL of the form
http://myserver/tile?x=0&y=0&z=0&scale=1.0, you would specify a template string of
http://myserver/tile?x={x}&y={y}&z={z}&scale={scale}. The tile overlay object substitutes actual
index values in for your templates placeholders before requesting the actual tile.
Availability
See Also
URLForTilePath: (page 237)
Declared in
MKTileOverlay.h
loadTileAtPath:result:
Loads the specified tile asynchronously.
- (void)loadTileAtPath:(MKTileOverlayPath)path result:(void (^)(NSData *tileData,
NSError *error))result
Parameters
path
The path structure that identifies the specific tile you want. This structure incorporates the tiles X-Y
coordinate at a given zoom level and scale factor.
Instance Methods
236
result
The completion block to call when the tile data is available. This block is executed on your apps main
thread and takes the following parameters:

The tileData parameter contains the raw data loaded from the corresponding image file. You
can use this data to initialize an image object. If an error occurred, this parameter is nil.

The error parameter contains an error object if there was a problem loading the tile image. If no
errors occurred, this parameter is nil.
Discussion
The default implementation of this method uses the URLForTilePath: (page 237) method to retrieve the URL
for the specified tile and then loads that tile into memory asynchronously using an NSURLConnection object.
The specified tile may be located either on the local file system or on a remote server. Subclasses may override
this method and implement their own custom tile-loading behavior.
When a tile overlay renderer (that is, an instance of MKTileOverlayRenderer) needs to display tiles, it uses
this method to request the data for each tile.
Availability
Declared in
MKTileOverlay.h
URLForTilePath:
Returns the URL to use to access the specified tile.
- (NSURL *)URLForTilePath:(MKTileOverlayPath)path
Parameters
path
The path structure that identifies the specific tile you want. This structure incorporates the tiles X-Y
coordinate at a given zoom level and scale factor.
Return Value
The URL to use to retrieve the tile.
Discussion
The default implementation of this method uses the template string you provided at initialization time to build
a URL to the specified tile image. Subclasses can override this method and use a different scheme to provide
URLs for tiles. Tiles can be located either on a local file system or on a remote server.
Instance Methods
237
Availability
See Also
@property URLTemplate (page 235)
Declared in
MKTileOverlay.h
Constants
MKTileOverlayPath
Use this structure to specify the index values for a single tile.
typedef struct {
NSInteger x;
NSInteger y;
NSInteger z;
CGFloat contentScaleFactor;
} MKTileOverlayPath;
Fields
x
The index of the tile along the x axis of the map.
y
The index of the tile along the y axis of the map.
z
The zoom level number for the tile. At level 0, the map displays the entire world; at level 1, the map
displays 1/4 of the world; at level 2, the map displays 1/16 of the world, and so on.
contentScaleFactor
The screen scale factor for which the tile is intended. This value is typically either 1.0 (for standard
resolution displays) or 2.0 (for Retina displays).
Availability
Declared in
MKTileOverlay.h
Constants
238
Inherits from MKOverlayRenderer : NSObject
Declared in MKTileOverlayRenderer.h
Overview
An MKTileOverlayRenderer object handles the drawing of tiles managed by an MKTileOverlay object.
You create instances of this class when tile overlays become visible on the map view. A renderer works closely
with its associated tile overlay object to coordinate the loading and drawing of tiles at appropriate times.
For information about how to specify the tiles to display on the map, see MKTileOverlay Class Reference .
Tasks
Initializing a Tile Renderer
initWithTileOverlay: (page 240)
Initializes and returns a tile renderer with the specified overlay object.
Reloading the Tile Data
reloadData (page 240)
Forces tiles to be reloaded and displayed.
239
MKTileOverlayRenderer Class Reference
Instance Methods
initWithTileOverlay:
Initializes and returns a tile renderer with the specified overlay object.
- (id)initWithTileOverlay:(MKTileOverlay *)overlay
Parameters
overlay
The tile overlay object whose contents you want to draw.
Return Value
An initialized tile renderer object.
Discussion
The returned renderer object works with the tile overlay object to coordinate the loading and display of its
map tiles.
Availability
Declared in
reloadData
Forces tiles to be reloaded and displayed.
- (void)reloadData
Discussion
Use this method to remove the overlays existing tile images and reload them from the original source. This
method automatically causes the renderer to redraw the new tiles as soon as they are loaded into memory.
Availability
Declared in
MKTileOverlayRenderer Class Reference
Instance Methods
240
NSObject (NSObject)
Declared in MKUserLocation.h
Related sample code
CurrentAddress
MapCallouts
Overview
The MKUserLocation class defines a specific type of annotation that identifies the users current location.
You do not create instances of this class directly. Instead, you retrieve an existing MKUserLocation object
from the userLocation (page 113) property of the map view displayed in your application.
241
MKUserLocation Class Reference
Tasks
Determining the Users Position
location (page 243) property
The current location of the device. (read-only)
updating (page 244) property
A Boolean value indicating whether the users location is currently being updated. (read-only)
heading (page 242) property
The heading of the user location. (read-only)
Accessing the User Annotation Text
The title to display for the user location annotation.
The subtitle to display for the user location annotation.
Properties
heading
The heading of the user location. (read-only)
@property(readonly, nonatomic, retain) CLHeading *heading
Discussion
This property is nil if the user location tracking mode is not MKUserTrackingModeFollowWithHeading.
Tasks
242
Availability
Declared in
MKUserLocation.h
location
The current location of the device. (read-only)
@property(readonly, retain, nonatomic) CLLocation *location
Discussion
This property contains nil if the map view is not currently showing the user location or if the users location
has not yet been determined.
Availability
Declared in
MKUserLocation.h
subtitle
The subtitle to display for the user location annotation.
@property(nonatomic, copy) NSString *subtitle
Availability
Declared in
MKUserLocation.h
title
The title to display for the user location annotation.
@property(nonatomic, copy) NSString *title
Availability
Properties
243
Declared in
MKUserLocation.h
updating
A Boolean value indicating whether the users location is currently being updated. (read-only)
@property(readonly, nonatomic, getter=isUpdating) BOOL updating
Availability
Declared in
MKUserLocation.h
Properties
244
Inherits from UIBarButtonItem : UIBarItem : NSObject
Conforms to NSCoding (UIBarButtonItem)
UIAppearance (UIBarItem)
NSObject (NSObject)
Declared in MKUserTrackingBarButtonItem.h
Overview
AMKUserTrackingBarButtonItem object is a specialized bar button item that allows the user to toggle
through the user tracking modes. For example, when the user taps the button, the map view toggles between
tracking the user with and without heading. The button also reflects the current user tracking mode if set
elsewhere. This bar button item is associated to a single map view.
Tasks
Initializing the Bar Button Item
initWithMapView: (page 246)
Initializes a newly created bar button item with the specified map view.
245
MKUserTrackingBarButtonItem Class Reference
Accessing the Owning Map
mapView (page 246) property
The map view associated with this bar button item.
Properties
mapView
The map view associated with this bar button item.
@property(nonatomic, retain) MKMapView *mapView
Availability
Declared in
Instance Methods
initWithMapView:
Initializes a newly created bar button item with the specified map view.
- (id)initWithMapView:(MKMapView *)mapView
Parameters
mapView
The map view used by this bar button item.
Return Value
The initialized bar button item.
Availability
Declared in
MKUserTrackingBarButtonItem Class Reference
Properties
246
Declared in MKGeometry.h
Overview
This category adds methods to the Foundation frameworks NSValue class. The methods in this category let
you represent map-related data using an NSValue object.
Tasks
Creating an NSValue
+ valueWithMKCoordinateSpan: (page 248) Deprecated in iOS 5.0 Deprecated in iOS 7.0 Deprecated in iOS
7.0 Deprecated in iOS 7.0 Deprecated in iOS 7.0 Deprecated in iOS 7.0
Creates and returns a value object that contains the specified coordinate span data.
+ valueWithMKCoordinate: (page 248) Deprecated in iOS 5.0 Deprecated in iOS 5.0 Deprecated in iOS 7.0
Deprecated in iOS 7.0 Deprecated in iOS 7.0 Deprecated in iOS 7.0 Deprecated in iOS 7.0
Creates and returns a value object that contains the specified coordinate data.
Accessing Data
MKCoordinateSpanValue (page 249) Deprecated in iOS 7.0 Deprecated in iOS 7.0
Returns a coordinate span structure representing the data in the receiver.
MKCoordinateValue (page 249) Deprecated in iOS 5.0 Deprecated in iOS 7.0 Deprecated in iOS 7.0
Returns a coordinate structure representing the data in the receiver.
247
NSValue MapKit Additions Reference
Class Methods
valueWithMKCoordinate:
Creates and returns a value object that contains the specified coordinate data.
+ (NSValue *)valueWithMKCoordinate:(CLLocationCoordinate2D)coordinate
Parameters
coordinate
The value for the new object.
Return Value
A new value object that contains the coordinate data.
Availability
Related Sample Code
Declared in
MKGeometry.h
valueWithMKCoordinateSpan:
Creates and returns a value object that contains the specified coordinate span data.
+ (NSValue *)valueWithMKCoordinateSpan:(MKCoordinateSpan)span
Parameters
span
The value for the new object.
Return Value
A new value object that contains the coordinate span data.
Availability
Related Sample Code
Class Methods
248
Declared in
MKGeometry.h
Instance Methods
MKCoordinateSpanValue
Returns a coordinate span structure representing the data in the receiver.
- (MKCoordinateSpan)MKCoordinateSpanValue
Return Value
A coordinate span structure containing the receivers value.
Availability
Declared in
MKGeometry.h
MKCoordinateValue
Returns a coordinate structure representing the data in the receiver.
- (CLLocationCoordinate2D)MKCoordinateValue
Return Value
A coordinate structure containing the receivers value.
Availability
Declared in
MKGeometry.h
Instance Methods
249

250
Protocols
Conforms to NSObject
Declared in MKAnnotation.h
Related sample code
KMLViewer
MapCallouts
MapSearch
PhotosByLocation
Regions
Overview
The MKAnnotation protocol is used to provide annotation-related information to a map view. To use this
protocol, you adopt it in any custom objects that store or represent annotation data. Each object then serves
as the source of information about a single map annotation and provides critical information, such as the
annotations location on the map. Annotation objects do not provide the visual representation of the annotation
but typically coordinate (in conjunction with the map views delegate) the creation of an appropriate
MKAnnotationView object to handle the display.
An object that adopts this protocol must implement the coordinate (page 252) property. The other methods
of this protocol are optional.
251
MKAnnotation Protocol Reference
Tasks
Position Attributes
The center point (specified as a map coordinate) of the annotation. (required) (read-only)
setCoordinate: (page 254)
Sets the new center point of the annotation.
Title Attributes
The string containing the annotations title.
The string containing the annotations subtitle.
Properties
coordinate
The center point (specified as a map coordinate) of the annotation. (required) (read-only)
Discussion
Your implementation of this property must be key-value observing (KVO) compliant. For more information on
how to implement support for KVO, see Key-Value Observing Programming Guide .
Availability
Tasks
252
Related Sample Code
CurrentAddress
MapCallouts
MapSearch
PhotosByLocation
Declared in
MKAnnotation.h
subtitle
The string containing the annotations subtitle.
@property (nonatomic, readonly, copy) NSString *subtitle
Discussion
This string is displayed in the callout for the associated annotation view.
Availability
Related Sample Code
MapCallouts
Declared in
MKAnnotation.h
title
The string containing the annotations title.
@property (nonatomic, readonly, copy) NSString *title
Discussion
Although this property is optional, if you support the selection of annotations in your map view, you are
expected to provide this property. This string is displayed in the callout for the associated annotation view.
Availability
Related Sample Code
MapCallouts
PhotosByLocation
Properties
253
Declared in
MKAnnotation.h
Instance Methods
setCoordinate:
Sets the new center point of the annotation.
- (void)setCoordinate:(CLLocationCoordinate2D)newCoordinate
Parameters
newCoordinate
The new center point for the annotation.
Discussion
Annotations that support dragging should implement this method to update the position of the annotation.
If you implement this method, you must update the value of the coordinate in a key-value observing (KVO)
compliant way. For more information on how to implement support for KVO, see Key-Value Observing
Programming Guide .
Availability
Declared in
MKAnnotation.h
Instance Methods
254
Declared in MapKit/MKMapView.h
Related sample code
Breadcrumb
CurrentAddress
MapCallouts
PhotosByLocation
Regions
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 viewcalls 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 objects
delegate (page 108) property to nil.
255
MKMapViewDelegate Protocol Reference
Tasks
Responding to Map Position Changes
mapView:regionWillChangeAnimated: (page 264)
Tells the delegate that the region displayed by the map view is about to change.
mapView:regionDidChangeAnimated: (page 264)
Tells the delegate that the region displayed by the map view just changed.
Loading the Map Data
mapViewWillStartLoadingMap: (page 269)
Tells the delegate that the specified map view is about to retrieve some map data.
mapViewDidFinishLoadingMap: (page 267)
Tells the delegate that the specified map view successfully loaded the needed map data.
mapViewDidFailLoadingMap:withError: (page 267)
Tells the delegate that the specified view was unable to load the map data.
mapViewWillStartRenderingMap: (page 270)
Tells the delegate that the map view is about to start rendering some of its tiles.
mapViewDidFinishRenderingMap:fullyRendered: (page 268)
Tells the delegate that the map view has finished rendering all visible tiles.
Tracking the User Location
mapViewWillStartLocatingUser: (page 270)
Tells the delegate that the map view will start tracking the users position.
mapViewDidStopLocatingUser: (page 269)
Tells the delegate that the map view stopped tracking the users location.
Tasks
256
Tells the delegate that the location of the user was updated.
mapView:didFailToLocateUserWithError: (page 262)
Tells the delegate that an attempt to locate the users position failed.
mapView:didChangeUserTrackingMode:animated: (page 261)
Tells the delegate that the user tracking mode changed.
Managing Annotation Views
mapView:viewForAnnotation: (page 265)
Returns the view associated with the specified annotation object.
mapView:didAddAnnotationViews: (page 259)
Tells the delegate that one or more annotation views were added to the map.
mapView:annotationView:calloutAccessoryControlTapped: (page 258)
Tells the delegate that the user tapped one of the annotation views accessory buttons.
Dragging an Annotation View
mapView:annotationView:didChangeDragState:fromOldState: (page 259)
Tells the delegate that the drag state of one of its annotation views changed.
Selecting Annotation Views
mapView:didSelectAnnotationView: (page 262)
Tells the delegate that one of its annotation views was selected.
mapView:didDeselectAnnotationView: (page 261)
Tells the delegate that one of its annotation views was deselected.
Managing the Display of Overlays
mapView:rendererForOverlay: (page 265)
Asks the delegate for a renderer object to use when drawing the specified overlay.
mapView:didAddOverlayRenderers: (page 260)
Tells the delegate that one or more renderer objects were added to the map.
Tasks
257
mapView:viewForOverlay: (page 266)
Asks the delegate for the overlay view to use when displaying the specified overlay object. (Deprecated.
Implement the mapView:rendererForOverlay: (page 265) method instead.)
mapView:didAddOverlayViews: (page 260)
Tells the delegate that one or more overlay views were added to the map. (Deprecated. Implement the
mapView:didAddOverlayRenderers: (page 260) method instead.)
Instance Methods
mapView:annotationView:calloutAccessoryControlTapped:
Tells the delegate that the user tapped one of the annotation views 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 customcontent 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 viewcalls 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
Declared in
MKMapView.h
Instance Methods
258
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
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.
Instance Methods
259
Availability
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 viewadds renderer objects when it needs themto drawtheir 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
Declared in
MKMapView.h
mapView:didAddOverlayViews:
Tells the delegate that one or more overlay views were added to the map. (Deprecated in iOS 7.0. Implement the
mapView:didAddOverlayRenderers: (page 260) method instead.)
- (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.
Instance Methods
260
Discussion
By the time this method is called, the specified views are already added to the map.
Availability
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 users location.
animated
If YES, the change fromthe current mode to the newmode is animated; otherwise, it is not. This parameter
affects only tracking mode changes. Changes to the user location or heading are always animated.
Availability
See Also
Declared in
MKMapView.h
mapView:didDeselectAnnotationView:
Tells the delegate that one of its annotation views was deselected.
Instance Methods
261
- (void)mapView:(MKMapView *)mapView didDeselectAnnotationView:(MKAnnotationView
*)view
Parameters
mapView
view
The annotation view that was deselected.
Discussion
You can use this method to track changes in the selection state of annotation views.
Availability
Declared in
MKMapView.h
mapView:didFailToLocateUserWithError:
Tells the delegate that an attempt to locate the users position failed.
- (void)mapView:(MKMapView *)mapView didFailToLocateUserWithError:(NSError *)error
Parameters
mapView
The map view that is tracking the users location.
error
An error object containing the reason why location tracking failed.
Availability
Declared in
MKMapView.h
mapView:didSelectAnnotationView:
Tells the delegate that one of its annotation views was selected.
- (void)mapView:(MKMapView *)mapView didSelectAnnotationView:(MKAnnotationView *)view
Instance Methods
262
Parameters
mapView
view
The annotation view that was selected.
Discussion
You can use this method to track changes in the selection state of annotation views.
Availability
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
userLocation
The location object representing the users latest location. This property may be nil.
Discussion
While the showsUserLocation (page 112) property is set to YES, this method is called whenever a newlocation
update is received by the map view. This method is also called if the map views user tracking mode is set to
MKUserTrackingModeFollowWithHeading (page 141) 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
Declared in
MKMapView.h
Instance Methods
263
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
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
Instance Methods
264
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
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.
Instance Methods
265
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 users current location.
Return Value
The annotation viewto 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: (page 122) 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 users location. To display the users 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
Declared in
MKMapView.h
mapView:viewForOverlay:
Asks the delegate for the overlay view to use when displaying the specified overlay object. (Deprecated in iOS 7.0.
Implement the mapView:rendererForOverlay: (page 265) method instead.)
- (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.
Instance Methods
266
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.
Availability
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
Declared in
MKMapView.h
mapViewDidFinishLoadingMap:
Tells the delegate that the specified map view successfully loaded the needed map data.
Instance Methods
267
- (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
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 viewwas 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
Instance Methods
268
See Also
mapViewWillStartRenderingMap: (page 270)
Declared in
MKMapView.h
mapViewDidStopLocatingUser:
Tells the delegate that the map view stopped tracking the users location.
- (void)mapViewDidStopLocatingUser:(MKMapView *)mapView
Parameters
mapView
The map view that stopped tracking the users location.
Discussion
This method is called when the value of the showsUserLocation (page 112) property changes to NO.
Availability
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 newgroup of map tiles need to be downloaded fromthe 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
Instance Methods
269
Declared in
MKMapView.h
mapViewWillStartLocatingUser:
Tells the delegate that the map view will start tracking the users position.
- (void)mapViewWillStartLocatingUser:(MKMapView *)mapView
Parameters
mapView
Discussion
This method is called when the value of the showsUserLocation (page 112) property changes to YES.
Availability
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
See Also
mapViewDidFinishRenderingMap:fullyRendered: (page 268)
Declared in
MKMapView.h
Instance Methods
270
Declared in MKOverlay.h
Related sample code
Breadcrumb
KMLViewer
PhotosByLocation
Overview
The MKOverlay protocol defines a specific type of annotation that represents both a point and an area on a
map. Overlay objects are essentially data objects that contain the geographic data needed to represent the
map area. For example, overlays can take the form of common shapes such as rectangles and circles. They can
also describe polygons and other complex shapes.
You use overlays to layer more sophisticated content on top of a map view. For example, you could use an
overlay to showthe boundaries of a national park or trace a bus route along city streets. The Map Kit framework
defines several concrete classes that conform to this protocol and define standard shapes.
Because overlays are also annotations, they have similar usage pattern to annotations. When added to a map
view using the addOverlay: (page 116) method, that view detects whenever the overlays defined region
intersects the visible portion of the map. At that point, the map view asks its delegate to provide a special
overlay view to draw the visual representation of the overlay. If you add an overlay to a map view as an
annotation instead, it is treated as an annotation with a single point.
271
MKOverlay Protocol Reference
Tasks
Describing the Overlay Geometry
The approximate center point of the overlay area. (required) (read-only)
boundingMapRect (page 272) property
The projected rectangle that encompasses the overlay. (required) (read-only)
Determining Map Intersections
intersectsMapRect: (page 274)
Returns a Boolean indicating whether the specified rectangle intersects the receivers shape.
Optimizing Map Rendering
canReplaceMapContent (page 273)
Returns a Boolean indicating whether the overlay content replaces the underlying map content.
Properties
boundingMapRect
The projected rectangle that encompasses the overlay. (required) (read-only)
Tasks
272
@property (nonatomic, readonly) MKMapRect boundingMapRect
Discussion
This property contains the smallest rectangle that completely encompasses the overlay. Implementers of this
protocol must set this area when implementing their overlay class, and after setting it, you must not change
it. The rectangle should be specified using projected coordinatesthat is, coordinates obtained by projecting
the globe onto a two-dimensional surface.
Availability
Declared in
MKOverlay.h
coordinate
The approximate center point of the overlay area. (required) (read-only)
Discussion
This point is typically set to the center point of the maps bounding rectangle. It is used as the anchor point
for any callouts displayed for the annotation.
Availability
Related Sample Code
Breadcrumb
PhotosByLocation
Declared in
MKOverlay.h
Instance Methods
canReplaceMapContent
Returns a Boolean indicating whether the overlay content replaces the underlying map content.
- (BOOL)canReplaceMapContent
Instance Methods
273
Return Value
YES if the map view can skip the loading and drawing of the underlying map tiles or NO if the map tiles should
still be drawn.
Discussion
The map view uses the return value of this method as a hint to determine whether it should load and render
its tiles. If your overlay covers its designated region entirely with opaque content, and effectively replaces the
content of underlying map tiles, implement this method and return YES. Doing so alleviates the need for the
map to render its tiles.
If you do not implement this method, or if you return NO from it, the map view continues to load and render
its tiles.
Availability
Declared in
MKOverlay.h
intersectsMapRect:
Returns a Boolean indicating whether the specified rectangle intersects the receivers shape.
- (BOOL)intersectsMapRect:(MKMapRect)mapRect
Parameters
mapRect
The rectangle to intersect with the receivers area.
Return Value
YES if any part of the map rectangle intersects the receivers shape or NO if it does not.
Discussion
You can implement this method to provide more specific bounds checking for an overlay. If you do not
implement it, the bounding rectangle is used to detect intersections.
Availability
Declared in
MKOverlay.h
Instance Methods
274
Declared in MKReverseGeocoder.h
This protocol is deprecated in iOS 5.0. Use the CLGeocoder class instead.
Overview
The MKReverseGeocoderDelegate protocol defines the interface for receiving messages from an
MKReverseGeocoder object. You use this protocol to receive the placemark information for a given coordinate
or to retrieve any errors that occurred during the reverse-geocoding process.
Delegates must implement both methods of this protocol.
The Google terms of service require that the reverse geocoding service be used in conjunction with a Google
map; take this into account when designing your application's user interface.
Each Map Kit application has a limited amount of reverse geocoding capacity, so it is to your advantage to use
reverse geocode requests sparingly. For more information about when to initiate reverse-geocoding requests,
see MKReverseGeocoder Class Reference .
275
MKReverseGeocoderDelegate Protocol Reference
Tasks
Processing Placemark Searches
reverseGeocoder:didFindPlacemark: (page 277)
Tells the delegate that a reverse geocoder successfully obtained placemark information for its coordinate.
(required) (Deprecated. Use the CLGeocoder class instead.)
reverseGeocoder:didFailWithError: (page 276)
Tells the delegate that the specified reverse geocoder failed to obtain information about its coordinate.
(required) (Deprecated. Use the CLGeocoder class instead.)
Instance Methods
reverseGeocoder:didFailWithError:
Tells the delegate that the specified reverse geocoder failed to obtain information about its coordinate. (required)
- (void)reverseGeocoder:(MKReverseGeocoder *)geocoder didFailWithError:(NSError
*)error
Parameters
geocoder
The reverse geocoder object that was unable to complete its request.
error
An error object indicating the reason the request did not succeed.
Availability
Declared in
MKReverseGeocoder.h
Tasks
276
reverseGeocoder:didFindPlacemark:
Tells thedelegatethat areversegeocoder successfullyobtainedplacemarkinformationfor its coordinate. (required)
- (void)reverseGeocoder:(MKReverseGeocoder *)geocoder didFindPlacemark:(MKPlacemark
*)placemark
Parameters
geocoder
The reverse geocoder object that completed its request successfully.
placemark
The object containing the placemark data.
Discussion
You can get the map coordinate for the associated request from either the reverse geocoder object or from
the placemark object, which itself supports the MKAnnotation protocol.
Availability
Declared in
MKReverseGeocoder.h
Instance Methods
277

278
Functions
Framework MapKit/MapKit.h
Declared in MKTypes.h
Overview
This document describes the functions found in the Map Kit framework.
Functions by Task
The functions of the MapKit framework provide convenient ways to package map-related data structures.
Making Coordinate Structures
MKCoordinateSpanMake (page 285)
Creates a new MKCoordinateSpan (page 308) from the specified values.
MKCoordinateRegionMake (page 284)
Creates a new MKCoordinateRegion (page 309) from the specified coordinate and span values.
MKCoordinateRegionMakeWithDistance (page 284) Deprecated in iOS 5.0 Deprecated in iOS 7.0
Creates a new MKCoordinateRegion (page 309) from the specified coordinate and distance values.
279
Map Kit Functions Reference
Making Map Point Structures
MKMapPointMake (page 287)
Creates a new MKMapPoint (page 309) structure from the specified values.
MKMapRectMake (page 298) Deprecated in iOS 5.0 Deprecated in iOS 7.0 Deprecated in iOS 7.0
Creates a new MKMapRect (page 311) structure from the specified values.
MKMapSizeMake (page 302) Deprecated in iOS 5.0 Deprecated in iOS 7.0 Deprecated in iOS 7.0
Creates a new MKMapSize (page 310) structure from the specified values.
Converting Between Data Types
MKCoordinateForMapPoint (page 282) Deprecated in iOS 7.0
Returns the latitude and longitude that corresponds to the specified map point.
MKCoordinateRegionForMapRect (page 283) Deprecated in iOS 7.0 Deprecated in iOS 7.0
Returns the region that corresponds to the specified map rectangle.
MKMapPointForCoordinate (page 286) Deprecated in iOS 5.0 Deprecated in iOS 7.0 Deprecated in iOS 7.0
Returns the map point data structure that corresponds to the specified coordinate.
Getting Map Units
MKRoadWidthAtZoomScale (page 304)
Returns the width (in screen points) of roads on a map at the specified zoom level.
MKMapPointsPerMeterAtLatitude (page 287) Deprecated in iOS 7.0
Returns the number of map points that represent one meter at the given latitude.
MKMetersPerMapPointAtLatitude (page 303) Deprecated in iOS 7.0
Returns the distance spanned by one map point at the specified latitude.
MKMetersBetweenMapPoints (page 303) Deprecated in iOS 7.0
Returns the number of meters between two map points.
Getting Points Along a Map Rectangle
MKMapRectGetMinX (page 293)
Returns the minimum x-axis value of the specified rectangle.
Functions by Task
280
MKMapRectGetMinY (page 294)
Returns the minimum y-axis value of the specified rectangle.
MKMapRectGetMidX (page 292)
Returns the mid-point along the x-axis of the specified rectangle.
MKMapRectGetMidY (page 293)
Returns the mid-point along the y-axis of the specified rectangle.
MKMapRectGetMaxX (page 291)
Returns the maximum x-axis value of the specified rectangle.
MKMapRectGetHeight (page 291)
Returns the height of the map rectangle.
MKMapRectGetWidth (page 294) Deprecated in iOS 7.0
Returns the width of the map rectangle.
MKMapRectGetMaxY (page 292) Deprecated in iOS 7.0
Returns the maximum y-axis value of the specified rectangle.
Comparing Map Values
MKMapPointEqualToPoint (page 286)
Returns a Boolean value indicating whether the two map points are equal.
MKMapSizeEqualToSize (page 302)
Returns a Boolean value indicating whether the two map sizes are equal.
MKMapRectEqualToRect (page 290)
Returns a Boolean value indicating whether the two map rectangles are equal
MKMapRectContainsPoint (page 288)
Returns a Boolean value indicating whether the specified map point lies within the rectangle.
MKMapRectContainsRect (page 289)
Returns Boolean value indicating whether one rectangle contains another.
MKMapRectIntersectsRect (page 296)
Returns a Boolean value indicating whether two rectangles intersect each other.
MKMapRectIsNull (page 298)
Returns a Boolean indicating whether the specified rectangle is null.
MKMapRectIsEmpty (page 297)
Returns a Boolean value indicating whether the specified rectangle has no area.
Functions by Task
281
Modifying Map Rectangles
MKMapRectUnion (page 301)
Returns a rectangle representing the union of the two rectangles.
MKMapRectIntersection (page 296)
Returns the rectangle representing the intersection of two rectangles.
MKMapRectInset (page 295)
Returns the specified rectangle inset by the specified amounts.
MKMapRectOffset (page 299)
Returns a rectangle whose origin point is shifted by the specified amount.
MKMapRectDivide (page 289)
Divides the specified rectangle into two smaller rectangles.
Getting Strings for Map Values
MKStringFromMapPoint (page 305)
Returns a formatted string for the specified map point.
MKStringFromMapSize (page 306)
Returns a formatted string for the specified map size.
MKStringFromMapRect (page 305)
Returns a formatted string for the specified map rectangle.
Determining Map Boundaries
MKMapRectSpans180thMeridian (page 300)
Returns a Boolean value that indicates whether the specified map rectangle crosses the 180th meridian.
MKMapRectRemainder (page 300)
Normalizes the portion of the specified rectangle that lies outside the world map boundaries.
Functions
MKCoordinateForMapPoint
Returns the latitude and longitude that corresponds to the specified map point.
Functions
282
CLLocationCoordinate2D MKCoordinateForMapPoint(
MKMapPoint mapPoint
);
Parameters
mapPoint
The map point value that corresponds to the desired point on a two-dimensional map projection.
Return Value
The coordinate structure containing the latitude and longitude values for the specified point.
Availability
Related Sample Code
Breadcrumb
PhotosByLocation
Declared in
MKGeometry.h
MKCoordinateRegionForMapRect
Returns the region that corresponds to the specified map rectangle.
MKCoordinateRegion MKCoordinateRegionForMapRect(
MKMapRect rect
);
Parameters
rect
The map rectangle that corresponds to the desired region on a two-dimensional map projection.
Return Value
The region structure specifying the latitude, longitude, and span values for the specified rectangle.
Availability
Declared in
MKGeometry.h
Functions
283
MKCoordinateRegionMake
Creates a new MKCoordinateRegion (page 309) from the specified coordinate and span values.
UIKIT_STATIC_INLINE MKCoordinateRegion MKCoordinateRegionMake(
CLLocationCoordinate2D centerCoordinate,
MKCoordinateSpan span
);
Parameters
centerCoordinate
The center point of the region.
span
The horizontal and vertical span representing the amount of map to display. The size of the span also
reflects the current zoom level.
Return Value
A region with the specified values.
Availability
Declared in
MKGeometry.h
MKCoordinateRegionMakeWithDistance
Creates a new MKCoordinateRegion (page 309) from the specified coordinate and distance values.
MKCoordinateRegion MKCoordinateRegionMakeWithDistance(
CLLocationCoordinate2D centerCoordinate,
CLLocationDistance latitudinalMeters,
CLLocationDistance longitudinalMeters
);
Parameters
centerCoordinate
The center point of the new coordinate region.
latitudinalMeters
The amount of north-to-south distance (measured in meters) to use for the span.
Functions
284
longitudinalMeters
The amount of east-to-west distance (measured in meters) to use for the span.
Return Value
A region with the specified values.
Availability
Related Sample Code
Breadcrumb
GeocoderDemo
PhotosByLocation
Regions
Declared in
MKGeometry.h
MKCoordinateSpanMake
Creates a new MKCoordinateSpan (page 308) from the specified values.
UIKIT_STATIC_INLINE MKCoordinateSpan MKCoordinateSpanMake(
CLLocationDegrees latitudeDelta,
CLLocationDegrees longitudeDelta
);
Parameters
latitudeDelta
The amount of north-to-south distance (measured in degrees) to use for the span. Unlike longitudinal
distances, which vary based on the latitude, one degree of latitude is approximately 111 kilometers (69
miles) at all times.
longitudeDelta
The amount of east-to-west distance (measured in degrees) to use for the span. The number of kilometers
spanned by a longitude range varies based on the current latitude. For example, one degree of longitude
spans a distance of approximately 111 kilometers (69 miles) at the equator but shrinks to 0 kilometers at
the poles.
Return Value
A span with the specified delta values.
Functions
285
Availability
Declared in
MKGeometry.h
MKMapPointEqualToPoint
Returns a Boolean value indicating whether the two map points are equal.
BOOL MKMapPointEqualToPoint(
MKMapPoint point1,
MKMapPoint point2
);
Parameters
point1
The first map point.
point2
The second point.
Return Value
YES if the x and y values in both points are exactly the same or NO if one or both values are different.
Availability
Declared in
MKGeometry.h
MKMapPointForCoordinate
Returns the map point data structure that corresponds to the specified coordinate.
MKMapPoint MKMapPointForCoordinate(
CLLocationCoordinate2D coordinate
);
Parameters
coordinate
The coordinate containing the latitude and longitude values for the desired point.
Functions
286
Return Value
The map point value that corresponds to the specified coordinate on a two-dimensional map projection.
Availability
Related Sample Code
Breadcrumb
KMLViewer
PhotosByLocation
Declared in
MKGeometry.h
MKMapPointMake
Creates a new MKMapPoint (page 309) structure from the specified values.
MKMapPoint MKMapPointMake(
double x,
double y
);
Parameters
x
The point along the east-west axis of the map projection.
y
The point along the north-south axis of the map projection.
Return Value
A map point with the specified values.
Availability
Declared in
MKGeometry.h
MKMapPointsPerMeterAtLatitude
Returns the number of map points that represent one meter at the given latitude.
Functions
287
double MKMapPointsPerMeterAtLatitude(
CLLocationDegrees latitude
);
Parameters
latitude
The latitude for which to return the value.
Return Value
The number of map points that span one meter.
Discussion
The number of map points per meter increases as the latitude approaches the poles.
Availability
Declared in
MKGeometry.h
MKMapRectContainsPoint
Returns a Boolean value indicating whether the specified map point lies within the rectangle.
BOOL MKMapRectContainsPoint(
MKMapRect rect,
MKMapPoint point
);
Parameters
rect
The map rectangle being tested.
point
The point to check.
Return Value
YES if the rectangle is not null or empty and the point is located inside the rectangle; otherwise, NO.
Discussion
A point is considered to be inside the rectangle if its coordinates lie inside the rectangle or on the minimum
X or minimum Y edge.
Functions
288
Availability
Declared in
MKGeometry.h
MKMapRectContainsRect
Returns Boolean value indicating whether one rectangle contains another.
BOOL MKMapRectContainsRect(
MKMapRect rect1,
MKMapRect rect2
);
Parameters
rect1
The containing rectangle.
rect2
The rectangle that might be contained in rect1.
Return Value
YES if rect2 is null or lies entirely inside rect1; otherwise, returns NO if rect1 is null or does not completely
enclose rect2.
Availability
Declared in
MKGeometry.h
MKMapRectDivide
Divides the specified rectangle into two smaller rectangles.
void MKMapRectDivide(
MKMapRect rect,
MKMapRect *slice,
MKMapRect *remainder,
double amount,
CGRectEdge edge
);
Functions
289
Parameters
rect
The rectangle to divide.
slice
On input, a pointer to a map rectangle. On output, this parameter contains the portion of rect that was
removed.
remainder
On input, a pointer to a map rectangle. On output, this parameter contains the remaining portion of
rect that was not removed.
amount
The amount of rect to remove along the specified edge. If this value is negative, it is set to 0.
edge
The edge from which to remove the specified amount.
Availability
Declared in
MKGeometry.h
MKMapRectEqualToRect
Returns a Boolean value indicating whether the two map rectangles are equal
BOOL MKMapRectEqualToRect(
MKMapRect rect1,
MKMapRect rect2
);
Parameters
rect1
The first map rectangle.
rect2
The second map rectangle.
Return Value
YES if the rectangles are exactly the same or NO if the origin point or size values are different.
Functions
290
Availability
Declared in
MKGeometry.h
MKMapRectGetHeight
Returns the height of the map rectangle.
double MKMapRectGetHeight(
MKMapRect rect
);
Parameters
rect
The map rectangle to test.
Return Value
The rectangles height.
Availability
Declared in
MKGeometry.h
MKMapRectGetMaxX
Returns the maximum x-axis value of the specified rectangle.
double MKMapRectGetMaxX(
MKMapRect rect
);
Parameters
rect
Return Value
The maximum x-axis value.
Functions
291
Availability
Declared in
MKGeometry.h
MKMapRectGetMaxY
Returns the maximum y-axis value of the specified rectangle.
double MKMapRectGetMaxY(
MKMapRect rect
);
Parameters
rect
Return Value
The maximum y-axis value.
Availability
Declared in
MKGeometry.h
MKMapRectGetMidX
Returns the mid-point along the x-axis of the specified rectangle.
double MKMapRectGetMidX(
MKMapRect rect
);
Parameters
rect
Return Value
The midpoint value along the x-axis.
Functions
292
Availability
Related Sample Code
PhotosByLocation
Declared in
MKGeometry.h
MKMapRectGetMidY
Returns the mid-point along the y-axis of the specified rectangle.
double MKMapRectGetMidY(
MKMapRect rect
);
Parameters
rect
Return Value
The midpoint value along the y-axis.
Availability
Related Sample Code
PhotosByLocation
Declared in
MKGeometry.h
MKMapRectGetMinX
Returns the minimum x-axis value of the specified rectangle.
double MKMapRectGetMinX(
MKMapRect rect
);
Functions
293
Parameters
rect
Return Value
The minimum x-axis value.
Availability
Declared in
MKGeometry.h
MKMapRectGetMinY
Returns the minimum y-axis value of the specified rectangle.
double MKMapRectGetMinY(
MKMapRect rect
);
Parameters
rect
Return Value
The minimum y-axis value.
Availability
Declared in
MKGeometry.h
MKMapRectGetWidth
Returns the width of the map rectangle.
double MKMapRectGetWidth(
MKMapRect rect
);
Functions
294
Parameters
rect
Return Value
The rectangles width.
Availability
Declared in
MKGeometry.h
MKMapRectInset
Returns the specified rectangle inset by the specified amounts.
MKMapRect MKMapRectInset(
MKMapRect rect,
double dx,
double dy
);
Parameters
rect
The original rectangle.
dx
The amount (in map points) to subtract from both sides along the x-axis.
dy
The amount (in map points) to subtract from both sides along the y-axis.
Return Value
The inset rectangle. If the original rectangle was null, that rectangle is returned instead.
Availability
Related Sample Code
Breadcrumb
PhotosByLocation
Declared in
MKGeometry.h
Functions
295
MKMapRectIntersection
Returns the rectangle representing the intersection of two rectangles.
MKMapRect MKMapRectIntersection(
MKMapRect rect1,
MKMapRect rect2
);
Parameters
rect1
The first rectangle.
rect2
The second rectangle.
Return Value
The rectangle representing the intersection of the two rectangles or MKMapRectNull (page 314) if there is no
intersection.
Availability
Related Sample Code
Breadcrumb
Declared in
MKGeometry.h
MKMapRectIntersectsRect
Returns a Boolean value indicating whether two rectangles intersect each other.
BOOL MKMapRectIntersectsRect(
MKMapRect rect1,
MKMapRect rect2
);
Parameters
rect1
The first rectangle to test.
Functions
296
rect2
The second rectangle to test.
Return Value
YES if rect1 and rect2 intersect each other or NO if they do not intersect or either rectangle is null.
Discussion
The rectangles are not considered to be intersecting if the only intersection occurs along an edge. To be
considered a true intersection, the rectangles must both enclose a single rectangular area whose width and
height are both greater than 0.
Availability
Related Sample Code
Breadcrumb
PhotosByLocation
Declared in
MKGeometry.h
MKMapRectIsEmpty
Returns a Boolean value indicating whether the specified rectangle has no area.
BOOL MKMapRectIsEmpty(
MKMapRect rect
);
Parameters
rect
The rectangle to test.
Return Value
YES if the rectangle is null or its width or height are equal to 0; otherwise, NO.
Availability
Declared in
MKGeometry.h
Functions
297
MKMapRectIsNull
Returns a Boolean indicating whether the specified rectangle is null.
BOOL MKMapRectIsNull(
MKMapRect rect
);
Parameters
rect
Return Value
YES if the rectangle is null or NO if it is not null.
Discussion
A rectangle is considered null if its origin point contains an invalid or infinite value.
Availability
Related Sample Code
Breadcrumb
KMLViewer
PhotosByLocation
Declared in
MKGeometry.h
MKMapRectMake
Creates a new MKMapRect (page 311) structure from the specified values.
MKMapRect MKMapRectMake(
double x,
double y,
double width,
double height
);
Parameters
x
The point along the east-west axis of the map projection to use for the origin.
Functions
298
y
The point along the north-south axis of the map projection to use for the origin.
width
The width of the rectangle (measured using map points).
height
The height of the rectangle (measured using map points).
Return Value
A map rectangle with the specified values.
Availability
Related Sample Code
Breadcrumb
KMLViewer
PhotosByLocation
Declared in
MKGeometry.h
MKMapRectOffset
Returns a rectangle whose origin point is shifted by the specified amount.
MKMapRect MKMapRectOffset(
MKMapRect rect,
double dx,
double dy
);
Parameters
rect
The original rectangle.
dx
The amount (in map points) by which to shift the x-coordinate of the origin point.
dy
The amount (in map points) by which to shift the y-coordinate of the origin point.
Return Value
The offset rectangle. If the original rectangle was null, that rectangle is returned instead.
Functions
299
Availability
Declared in
MKGeometry.h
MKMapRectRemainder
Normalizes the portion of the specified rectangle that lies outside the world map boundaries.
MKMapRect MKMapRectRemainder(
MKMapRect rect
);
Parameters
rect
The rectangle to check.
Discussion
For a rectangle that lies on the 180th meridian, this function isolates the portion that lies outside the boundary,
wraps it to the opposite side of the map, and returns that rectangle.
Availability
Declared in
MKGeometry.h
MKMapRectSpans180thMeridian
Returns a Boolean value that indicates whether the specified map rectangle crosses the 180th meridian.
BOOL MKMapRectSpans180thMeridian(
MKMapRect rect
);
Parameters
rect
Functions
300
Return Value
YES if the rectangle spans the 180th meridian or NO if it is contained wholly within the world map.
Availability
Declared in
MKGeometry.h
MKMapRectUnion
Returns a rectangle representing the union of the two rectangles.
MKMapRect MKMapRectUnion(
MKMapRect rect1,
MKMapRect rect2
);
Parameters
rect1
The first rectangle.
rect2
The second rectangle.
Return Value
A rectangle whose area encompasses the two rectangles and the space between them.
Discussion
If either rectangle is null, this method returns the other rectangle. The origin point of the returned rectangle
is set to the smaller of the x and y values for the two rectangles. Similarly, the size and width of the rectangle
are computed by taking the maximum x and y values and subtracting the x and y values for the new origin
point.
Availability
Related Sample Code
KMLViewer
PhotosByLocation
Declared in
MKGeometry.h
Functions
301
MKMapSizeEqualToSize
Returns a Boolean value indicating whether the two map sizes are equal.
BOOL MKMapSizeEqualToSize(
MKMapSize size1,
MKMapSize size2
);
Parameters
size1
The first map size.
size2
The second map size.
Return Value
YES if the width and height values in both sizes are exactly the same or NO if one or both values are different.
Availability
Declared in
MKGeometry.h
MKMapSizeMake
Creates a new MKMapSize (page 310) structure from the specified values.
MKMapSize MKMapSizeMake(
double width,
double height
);
Parameters
width
The distance (measured using map points) along the east-west axis of the map projection.
height
The distance (measured using map points) along the north-south axis of the map projection.
Return Value
A map size with the specified values.
Functions
302
Availability
Declared in
MKGeometry.h
MKMetersBetweenMapPoints
Returns the number of meters between two map points.
CLLocationDistance MKMetersBetweenMapPoints(
MKMapPoint a,
MKMapPoint b
);
Parameters
a
The first map point.
b
The second map point.
Return Value
The number of meters between the specified map points.
Discussion
This distance reflects the actual distance between the two points on the surface of the globe, taking into
account the curvature of the Earth.
Availability
Related Sample Code
Breadcrumb
PhotosByLocation
Declared in
MKGeometry.h
MKMetersPerMapPointAtLatitude
Returns the distance spanned by one map point at the specified latitude.
Functions
303
CLLocationDistance MKMetersPerMapPointAtLatitude(
CLLocationDegrees latitude
);
Parameters
latitude
The latitude for which to return the value.
Return Value
The distance (in meters) spanned by a single map point.
Discussion
The distance between map points decreases as the latitude approaches the poles. This relationship parallels
the relationship between longitudinal coordinates at different latitudes.
Availability
Declared in
MKGeometry.h
MKRoadWidthAtZoomScale
Returns the width (in screen points) of roads on a map at the specified zoom level.
CGFloat MKRoadWidthAtZoomScale(
MKZoomScale zoomScale
);
Parameters
zoomScale
The scale factor currently applied to the map view.
Return Value
The width of roads, measured in screen points. You can use the returned value to set the width of lines in
drawing code that traces the path of a road.
Availability
Related Sample Code
Breadcrumb
Functions
304
PhotosByLocation
Declared in
MKOverlayView.h
MKStringFromMapPoint
Returns a formatted string for the specified map point.
NSString *MKStringFromMapPoint(
MKMapPoint point
);
Parameters
point
The map point to format.
Return Value
A formatted string containing the x and y coordinates of the map point.
Availability
Declared in
MKGeometry.h
MKStringFromMapRect
Returns a formatted string for the specified map rectangle.
NSString *MKStringFromMapRect(
MKMapRect rect
);
Parameters
rect
The map rectangle to format.
Return Value
A formatted string containing the origin and size values of the map rectangle.
Functions
305
Availability
Declared in
MKGeometry.h
MKStringFromMapSize
Returns a formatted string for the specified map size.
NSString *MKStringFromMapSize(
MKMapSize size
);
Parameters
size
The map size to format.
Return Value
A formatted string containing the width and height values of the map size.
Availability
Declared in
MKGeometry.h
Functions
306

307
Data Types
Overview
This document describes the data types found in the Map Kit framework.
Data Types
MKCoordinateSpan
A structure that defines the area spanned by a map region.
typedef struct {
CLLocationDegrees latitudeDelta;
CLLocationDegrees longitudeDelta;
} MKCoordinateSpan;
Fields
latitudeDelta
The amount of north-to-south distance (measured in degrees) to display on the map. Unlike longitudinal
distances, which vary based on the latitude, one degree of latitude is always approximately 111 kilometers
(69 miles).
longitudeDelta
The amount of east-to-west distance (measured in degrees) to display for the map region. The number
of kilometers spanned by a longitude range varies based on the current latitude. For example, one degree
of longitude spans a distance of approximately 111 kilometers (69 miles) at the equator but shrinks to 0
kilometers at the poles.
308
Map Kit Data Types Reference
Discussion
You use the delta values in this structure to indicate the desired zoom level of the map, with smaller delta
values corresponding to a higher zoom level.
Availability
Declared in
MKGeometry.h
MKCoordinateRegion
A structure that defines which portion of the map to display.
typedef struct {
CLLocationCoordinate2D center;
MKCoordinateSpan span;
} MKCoordinateRegion;
Fields
center
The center point of the region.
span
The horizontal and vertical span representing the amount of map to display. The span also defines the
current zoom level used by the map view object.
Availability
Declared in
MKGeometry.h
MKMapPoint
A point on a two-dimensional map projection.
typedef struct {
double x;
double y;
} MKMapPoint;
Data Types
309
Fields
x
The location of the point along the x-axis of the map.
y
The location of the point along the y-axis of the map.
Discussion
If you project the curved surface of the globe onto a flat surface, what you get is a two-dimensional version
of a map where longitude lines appear to be parallel. Such maps are often used to show the entire surface of
the globe all at once. An MKMapPoint data structure represents a point on this two-dimensional map.
The actual units of a map point are tied to the underlying units used to draw the contents of an MKMapView,
but you should never need to worry about these units directly. You use map points primarily to simplify
computations that would be complex to do using coordinate values on a curved surface. By converting to map
points, you can performthose calculations on a flat surface, which is generally much simpler, and then convert
back as needed. You can map between coordinate values and map points using the
MKMapPointForCoordinate (page 286) and MKCoordinateForMapPoint (page 282) functions.
When saving map-related data to a file, you should always save coordinate values (latitude and longitude) and
not map points.
Availability
Declared in
MKGeometry.h
MKMapSize
Size information as measured on a two-dimensional map projection.
typedef struct {
double width;
double height;
} MKMapSize;
Fields
width
The width value. The units of this value are map points.
height
The height value. The units of this value are map points.
Data Types
310
Discussion
the globe all at once. An MKMapSize data structure represents a horizontal and vertical distance as measured
on this two-dimensional map.
Availability
Declared in
MKGeometry.h
MKMapRect
A rectangular area as measured on a two-dimensional map projection.
typedef struct {
MKMapPoint origin;
MKMapSize size;
} MKMapRect;
Fields
origin
The origin point of the rectangle.
size
The width and height of the rectangle, starting from the origin point.
Discussion
the globe all at once. An MKMapRect data structure represents a rectangular area as seen on this two-dimensional
map.
Availability
Declared in
MKGeometry.h
Data Types
311
MKZoomScale
A scale factor being used in conjunction with a map.
typedef CGFloat MKZoomScale;
Availability
Declared in
MKGeometry.h
Data Types
312

313
Constants
Overview
This document describes the constants found in the Map Kit framework
Constants
Null Map Rectangle
The null map rectangle
const MKMapRect MKMapRectNull;
Constants
MKMapRectNull
You can use this constant when you want to specify an invalid map rectangle.
Declared in MKGeometry.h.
World Map Constants
Map constants for the two-dimensional map projection.
const MKMapSize MKMapSizeWorld;
const MKMapRect MKMapRectWorld;
314
Map Kit Constants Reference
Constants
MKMapSizeWorld
Specifies the width and height (in map points) of the world in the two-dimensional map projection.
MKMapRectWorld
The map rectangle that represents the world in the two-dimensional map projection.
Error Domain
The error domain for Map Kit.
NSString *MKErrorDomain
Constants
MKErrorDomain
The Map Kit error domain.
MKErrorCode
Error constants for the Map Kit framework.
enum MKErrorCode {
MKErrorUnknown = 1,
MKErrorServerFailure,
MKErrorLoadingThrottled,
MKErrorPlacemarkNotFound,
MKErrorDirectionsNotFound
};
Constants
MKErrorUnknown
An unknown error occurred.
Constants
315
MKErrorServerFailure
The map server was unable to return the desired information.
MKErrorLoadingThrottled
The data was not loaded because data throttling is in effect. This error can occur if an app makes frequent
requests for data over a short period of time.
MKErrorPlacemarkNotFound
The specified placemark could not be found.
MKErrorDirectionsNotFound
The specified directions could not be found.
Constants
316
This table describes the changes to Map Kit Framework Reference .
Notes Date
Added classes introduced in iOS 7. 2013-09-18
Added new classes related to local map searches. 2013-01-28
Added new classes introduced in iOS 6. 2012-09-19
Updated for iOS 5.0. 2011-10-12
Added new classes and protocols introduced in iOS 4.0. 2010-05-11
New document that describes the classes, methods, and functions of the
MapKit framework.
2009-05-12
317
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 any
form or by any means, mechanical, electronic,
photocopying, recording, or otherwise, without
prior written permission of Apple Inc., with the
following exceptions: Any person is hereby
authorized to store documentation on a single
computer for personal use only and to print
copies of documentation for personal use
provided that the documentation contains
Apples copyright notice.
No licenses, express or implied, are granted with
respect to any of the technology described in this
document. Apple retains all intellectual property
rights associated with the technology described
in this document. This document is intended to
assist application developers to develop
applications only for Apple-labeled computers.
Apple Inc.
1 Infinite Loop
Cupertino, CA 95014
408-996-1010
Apple, the Apple logo, OS X, and Quartz are
trademarks of Apple Inc., registered in the U.S.
and other countries.
Retina is a trademark of Apple Inc.
iOS is a trademark or registered trademark of
Cisco in the U.S. and other countries and is used
under license.
Even though Apple has reviewed this document,
APPLE MAKES NO WARRANTY OR REPRESENTATION,
EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS
DOCUMENT, ITS QUALITY, ACCURACY,
MERCHANTABILITY, OR FITNESS FOR A PARTICULAR
PURPOSE. ASARESULT, THISDOCUMENTISPROVIDED
AS IS, AND YOU, THE READER, ARE ASSUMING THE
ENTIRE RISK AS TO ITS QUALITY AND ACCURACY.
IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT,
INDIRECT, SPECIAL, INCIDENTAL, ORCONSEQUENTIAL
DAMAGES RESULTING FROM ANY DEFECT OR
INACCURACY IN THIS DOCUMENT, even if advised of
the possibility of such damages.
THE WARRANTY AND REMEDIES SET FORTH ABOVE
ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL
OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer,
agent, or employee is authorized to make any
modification, extension, or addition to this warranty.
Some states do not allow the exclusion or limitation
of implied warranties or liability for incidental or
consequential damages, so the above limitation or
exclusion may not apply to you. This warranty gives
you specific legal rights, and you may also have other
rights which vary from state to state.

MapKit Framework Reference

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

MapKit Framework Reference

Uploaded by

Copyright:

Available Formats

Map Kit Framework Reference

You might also like