MapKit Framework Reference

Map Kit Framework ReferenceContents 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 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 4 Contents Instance Methods 115 Constants 139 MKMultiPoint Class Reference 142 Overview 142 Tasks 142 Properties 143 Instance Methods 144 MKOverlayPathRenderer Class Reference 145 Overview 145 Tasks 145 Properties 147 Instance Methods 150 MKOverlayPathView Class Reference 154 Overview 154 Tasks 155 Properties 156 Instance Methods 161 MKOverlayRenderer Class Reference 165 Overview 165 Tasks 166 Properties 167 Instance Methods 168 MKOverlayView Class Reference 175 Overview 175 Tasks 176 Properties 177 Instance Methods 178 MKPinAnnotationView Class Reference 186 Overview 186 Tasks 187 Properties 187 Constants 188 MKPlacemark Class Reference 190 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 5 Contents Overview 190 Tasks 191 Properties 191 Instance Methods 192 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 Instance Methods 201 MKPolygonView Class Reference 202 Overview 202 Tasks 203 Properties 203 Instance Methods 203 MKPolyline Class Reference 205 Overview 205 Tasks 206 Class Methods 206 MKPolylineRenderer Class Reference 208 Overview 208 Tasks 208 Properties 209 Instance Methods 209 MKPolylineView Class Reference 210 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 6 Contents Overview 210 Tasks 211 Properties 211 Instance Methods 211 MKReverseGeocoder Class Reference 213 Overview 213 Tasks 214 Properties 215 Instance Methods 217 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 Instance Methods 235 Constants 238 MKTileOverlayRenderer Class Reference 239 Overview 239 Tasks 239 Instance Methods 240 MKUserLocation Class Reference 241 Overview 241 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 7 Contents Tasks 242 Properties 242 MKUserTrackingBarButtonItem Class Reference 245 Overview 245 Tasks 245 Properties 246 Instance Methods 246 NSValue MapKit Additions Reference 247 Overview 247 Tasks 247 Class Methods 248 Instance Methods 249 Protocols 250 MKAnnotation Protocol Reference 251 Overview 251 Tasks 252 Properties 252 Instance Methods 254 MKMapViewDelegate Protocol Reference 255 Overview 255 Tasks 256 Instance Methods 258 MKOverlay Protocol Reference 271 Overview 271 Tasks 272 Properties 272 Instance Methods 273 MKReverseGeocoderDelegate Protocol Reference 275 Overview 275 Tasks 276 Instance Methods 276 Functions 278 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 11 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 12 Classes Inherits from UIView : UIResponder : NSObject Conforms to NSCoding (UIView) UIAppearance (UIView) UIAppearanceContainer (UIView) UIDynamicItem (UIView) NSObject (NSObject) Framework /System/Library/Frameworks/MapKit.framework Availability Available in iOS 3.0 and later. Declared in MKAnnotationView.h Companion guide Location and Maps Programming Guide 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 annotation’s 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. 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 13 MKAnnotationView Class Reference 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. 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 view’s 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 view’s 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 view’s 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. MKAnnotationView Class Reference Overview 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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. MKAnnotationView Class Reference Tasks 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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. MKAnnotationView Class Reference Tasks 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 view’s 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 Available in iOS 3.0 and later. MKAnnotationView Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 3.0 and later. 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. MKAnnotationView Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 3.0 and later. 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 Available in iOS 4.0 and later. Declared in MKAnnotationView.h dragState The current drag state of the annotation view. MKAnnotationView Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 4.0 and later. See Also @property draggable (page 19) Declared in MKAnnotationView.h MKAnnotationView Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 3.0 and later. 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 view’s bounds. Availability Available in iOS 3.0 and later. 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 view’s frame so that it matches the width and height of the new image. The position of the view’s frame does not change. MKAnnotationView Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 21 Availability Available in iOS 3.0 and later. 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 view’s 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 Available in iOS 3.0 and later. 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) MKAnnotationView Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 3.0 and later. 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 view’s 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 Available in iOS 3.0 and later. See Also @property canShowCallout (page 18) Related Sample Code MapCallouts PhotosByLocation MKAnnotationView Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 3.0 and later. 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. MKAnnotationView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 3.0 and later. 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 Available in iOS 3.0 and later. See Also dequeueReusableAnnotationViewWithIdentifier: (page 122) (MKMapView) Related Sample Code PhotosByLocation Declared in MKAnnotationView.h MKAnnotationView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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. MKAnnotationView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 26 Availability Available in iOS 4.2 and later. 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 Available in iOS 3.0 and later. 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, MKAnnotationView Class Reference Constants 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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. Available in iOS 4.0 and later. 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. Available in iOS 4.0 and later. Declared in MKAnnotationView.h. MKAnnotationViewDragStateDragging The view is in the middle of a drag operation and is tracking progress. Available in iOS 4.0 and later. Declared in MKAnnotationView.h. 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. Available in iOS 4.0 and later. Declared in MKAnnotationView.h. 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. Available in iOS 4.0 and later. Declared in MKAnnotationView.h. Notifications MKAnnotationCalloutInfoDidChangeNotification Notifies observers that the title or subtitle information of an annotation object changed. (#Deprecated. Use KVO notifications instead.) MKAnnotationView Class Reference Notifications 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 3.0 and later. Declared in MKAnnotationView.h MKAnnotationView Class Reference Notifications 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 29 Inherits from MKShape : NSObject Conforms to MKOverlay MKAnnotation (MKShape) NSObject (NSObject) Framework /System/Library/Frameworks/MapKit.framework Availability Available in iOS 4.0 and later. Declared in MKCircle.h Companion guide Location and Maps Programming Guide 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. 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 30 MKCircle Class Reference 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. 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 Overlay’s 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) MKCircle Class Reference Tasks 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 4.0 and later. 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 Available in iOS 4.0 and later. 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 Available in iOS 4.0 and later. Declared in MKCircle.h MKCircle Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 4.0 and later. 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. MKCircle Class Reference Class Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 33 Availability Available in iOS 4.0 and later. Declared in MKCircle.h MKCircle Class Reference Class Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 34 Inherits from MKOverlayPathRenderer : MKOverlayRenderer : NSObject Conforms to NSObject (NSObject) Framework /System/Library/Frameworks/MapKit.framework Availability Available in iOS 7.0 and later. 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 delegate’s 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) 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 7.0 and later. 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 Available in iOS 7.0 and later. Declared in MKCircleRenderer.h MKCircleRenderer Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 36 Inherits from MKOverlayPathView : MKOverlayView : UIView : UIResponder : NSObject Conforms to NSCoding (UIView) UIAppearance (UIView) UIAppearanceContainer (UIView) UIDynamicItem (UIView) NSObject (NSObject) Framework /System/Library/Frameworks/MapKit.framework Availability Available in iOS 4.0 and later. Declared in MKCircleView.h Companion guide Location and Maps Programming Guide 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. 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. Use of this class is discouraged in iOS 7 and later. Use the MKCircleRenderer class instead. 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 4.0 and later. 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.) MKCircleView Class Reference Tasks 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 4.0 and later. Deprecated in iOS 7.0. Declared in MKCircleView.h MKCircleView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 39 Inherits from NSObject Conforms to NSObject (NSObject) Framework /System/Library/Frameworks/MapKit.framework Availability Available in iOS 7.0 and later. Declared in MKDirections.h Companion guide Location and Maps Programming Guide 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. 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 7.0 and later. 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. MKDirections Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 app’s 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 Available in iOS 7.0 and later. 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 app’s 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 Available in iOS 7.0 and later. MKDirections Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 7.0 and later. 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 Available in iOS 7.0 and later. Declared in MKDirections.h MKDirections Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 7.0 and later. Declared in MKDirections.h MKETAHandler The block to use for processing travel-time information. typedef void (^MKETAHandler)(MKETAResponse *response, NSError *error); Discussion This block takes two parameters: ● 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. MKDirections Class Reference Constants 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 7.0 and later. Declared in MKDirections.h MKDirections Class Reference Constants 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 45 Inherits from NSObject Conforms to NSObject (NSObject) Framework /System/Library/Frameworks/MapKit.framework Availability Available in iOS 6.0 and later. Declared in MKDirectionsRequest.h Companion guide Location and Maps Programming Guide 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 delegate’s 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. 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 MKDirectionsRequest Class Reference Tasks 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 7.0 and later. Declared in MKDirectionsRequest.h departureDate The departure date for the trip. @property (nonatomic, retain) NSDate *departureDate; MKDirectionsRequest Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 7.0 and later. Declared in MKDirectionsRequest.h 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 Available in iOS 7.0 and later. Declared in MKDirectionsRequest.h 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). MKDirectionsRequest Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 49 Availability Available in iOS 7.0 and later. Declared in MKDirectionsRequest.h 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 Available in iOS 6.0 and later. Declared in MKDirectionsRequest.h Instance Methods destination Returns the end point for routing directions - (MKMapItem *)destination Return Value The end point for routing directions. Availability Available in iOS 6.0 and later. MKDirectionsRequest Class Reference Class Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 50 Declared in MKDirectionsRequest.h 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 Available in iOS 6.0 and later. Declared in MKDirectionsRequest.h 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 Available in iOS 7.0 and later. Declared in MKDirectionsRequest.h MKDirectionsRequest Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 7.0 and later. Declared in MKDirectionsRequest.h source Returns the starting point for routing directions. - (MKMapItem *)source Return Value The starting point for routing directions. Availability Available in iOS 6.0 and later. Declared in MKDirectionsRequest.h Constants MKDirectionsTransportType Constants that specify the type of conveyance to be used. typedef enum { MKDirectionsTransportTypeAutomobile = 1 << 0, MKDirectionsTransportTypeWalking = 1 << 1, MKDirectionsRequest Class Reference Constants 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 52 MKDirectionsTransportTypeAny = NSUIntegerMax } MKDirectionsTransportType; Constants MKDirectionsTransportTypeAutomobile Directions suitable for use while driving. Available in iOS 7.0 and later. Declared in MKDirectionsTypes.h. MKDirectionsTransportTypeWalking Directions suitable for a pedestrian. Available in iOS 7.0 and later. Declared in MKDirectionsTypes.h. MKDirectionsTransportTypeAny Directions suitable for any transportation option. Available in iOS 7.0 and later. Declared in MKDirectionsTypes.h. MKDirectionsRequest Class Reference Constants 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 53 Inherits from NSObject Conforms to NSObject (NSObject) Availability Available in iOS 7.0 and later. 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) 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 54 MKDirectionsResponse Class Reference Properties destination The end point of the route. (read-only) @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 Available in iOS 7.0 and later. Declared in MKDirectionsResponse.h 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 app’s 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 Available in iOS 7.0 and later. Declared in MKDirectionsResponse.h source The start point of the route. (read-only) MKDirectionsResponse Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 55 @property (nonatomic, readonly) MKMapItem *source 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 Available in iOS 7.0 and later. Declared in MKDirectionsResponse.h MKDirectionsResponse Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 56 Inherits from NSObject Conforms to NSObject (NSObject) Framework /System/Library/Frameworks/MapKit.framework Availability Available in iOS 7.0 and later. Declared in MKDirectionsResponse.h Companion guide Location and Maps Programming Guide 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 The start point of the route. (read-only) destination (page 58) property The end point of the route. (read-only) 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 57 MKETAResponse Class Reference Getting the Travel Time expectedTravelTime (page 58) property The expected travel time in seconds. (read-only) Properties destination The end point of the route. (read-only) @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 Available in iOS 7.0 and later. Declared in MKDirectionsResponse.h expectedTravelTime The expected travel time in seconds. (read-only) @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 Available in iOS 7.0 and later. Declared in MKDirectionsResponse.h MKETAResponse Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 58 source The start point of the route. (read-only) @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 create the MKDirectionsRequest object. Availability Available in iOS 7.0 and later. Declared in MKDirectionsResponse.h MKETAResponse Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 59 Inherits from MKPolyline : MKMultiPoint : MKShape : NSObject Conforms to MKOverlay (MKPolyline) MKAnnotation (MKShape) NSObject (NSObject) Framework /System/Library/Frameworks/MapKit.framework Availability Available in iOS 7.0 and later. 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. 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 7.0 and later. Declared in MKGeodesicPolyline.h 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 Available in iOS 7.0 and later. MKGeodesicPolyline Class Reference Class Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 61 Declared in MKGeodesicPolyline.h MKGeodesicPolyline Class Reference Class Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 62 Inherits from NSObject Conforms to NSObject (NSObject) Framework /System/Library/Frameworks/MapKit.framework Availability Available in iOS 6.1 and later. Declared in MKLocalSearch.h Companion guide Location and Maps Programming Guide 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. 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 6.1 and later. 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. MKLocalSearch Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 64 Availability Available in iOS 6.1 and later. 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 Available in iOS 6.1 and later. 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. MKLocalSearch Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 app’s 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 Available in iOS 6.1 and later. Declared in MKLocalSearch.h Constants MKLocalSearchCompletionHandler A completion handler block for a search operation. typedef void (^MKLocalSearchCompletionHandler)(MKLocalSearchResponse *response, NSError *error); Discussion This block takes two parameters: 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 Available in iOS 6.1 and later. Declared in MKLocalSearch.h MKLocalSearch Class Reference Constants 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 66 Inherits from NSObject Conforms to NSCopying NSObject (NSObject) Framework /System/Library/Frameworks/MapKit.framework Availability Available in iOS 6.1 and later. Declared in MKLocalSearchRequest.h Companion guide Location and Maps Programming Guide 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. 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 6.1 and later. Declared in MKLocalSearchRequest.h 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 Available in iOS 6.1 and later. Declared in MKLocalSearchRequest.h MKLocalSearchRequest Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 68 Inherits from NSObject Conforms to NSObject (NSObject) Framework /System/Library/Frameworks/MapKit.framework Availability Available in iOS 6.1 and later. Declared in MKLocalSearchResponse.h Companion guide Location and Maps Programming Guide 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) 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 6.1 and later. Declared in MKLocalSearchResponse.h 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 Available in iOS 6.1 and later. Declared in MKLocalSearchResponse.h MKLocalSearchResponse Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 70 Inherits from NSObject Conforms to NSCopying NSSecureCoding NSObject (NSObject) Availability Available in iOS 7.0 and later. 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 camera’s viewing direction, the pitch of the camera relative to the map perpendicular, and the camera’s 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 object’s centerCoordinate (page 72) property, updating the map’s own region information in the process. The map also takes the camera’s 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. 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 7.0 and later. Declared in MKMapCamera.h centerCoordinate The map coordinate at the center of the map view. MKMapCamera Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 7.0 and later. 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 Available in iOS 7.0 and later. 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. MKMapCamera Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 73 Availability Available in iOS 7.0 and later. 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 Available in iOS 7.0 and later. 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. MKMapCamera Class Reference Class Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 7.0 and later. Declared in MKMapCamera.h MKMapCamera Class Reference Class Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 75 Inherits from NSObject Conforms to NSObject (NSObject) Framework /System/Library/Frameworks/MapKit.framework Availability Available in iOS 6.0 and later. Declared in MKMapItem.h Companion guide Location and Maps Programming Guide 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 user’s current location. For privacy reasons, and because the user’s 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. 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 device’s 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 user’s 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. MKMapItem Class Reference Tasks 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 user’s current location. @property (nonatomic, readonly) BOOL isCurrentLocation Discussion If the value of this property is YES, the map item represents the user’s current location. If YES, the value in the placemark (page 79) property is set to nil. Availability Available in iOS 6.0 and later. 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. MKMapItem Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 78 If this map item represents the user’s current location, the value in property is set to a localized version of “Current Location”. Availability Available in iOS 6.0 and later. 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 Available in iOS 6.0 and later. 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 Available in iOS 6.0 and later. Related Sample Code MapSearch MKMapItem Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 6.0 and later. Related Sample Code MapSearch Declared in MKMapItem.h Class Methods mapItemForCurrentLocation Creates and returns a singleton map item object representing the device’s current location. + (MKMapItem *)mapItemForCurrentLocation Return Value An MKMapItem object representing the current location. Availability Available in iOS 6.0 and later. Declared in MKMapItem.h MKMapItem Class Reference Class Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 user’s 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 Available in iOS 6.0 and later. Declared in MKMapItem.h MKMapItem Class Reference Class Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 user’s current location. To do that, use the mapItemForCurrentLocation (page 80) method instead. Availability Available in iOS 6.0 and later. 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. MKMapItem Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 user’s 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 Available in iOS 6.0 and later. Related Sample Code Using NSXMLParser to parse XML documents 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. Available in iOS 6.0 and later. Declared in MKMapItem.h. MKMapItem Class Reference Constants 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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. Available in iOS 6.0 and later. Declared in MKMapItem.h. 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. Available in iOS 6.0 and later. Declared in MKMapItem.h. 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. Available in iOS 6.0 and later. Declared in MKMapItem.h. 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. Available in iOS 6.0 and later. Declared in MKMapItem.h. 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; MKMapItem Class Reference Constants 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 84 Constants MKLaunchOptionsDirectionsModeDriving Tells the Maps app to display driving directions between the start and end points. Available in iOS 6.0 and later. Declared in MKMapItem.h. MKLaunchOptionsDirectionsModeWalking Tells the Maps app to display walking directions between the start and end points. Available in iOS 6.0 and later. Declared in MKMapItem.h. MKMapItem Class Reference Constants 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 85 Inherits from NSObject Conforms to NSObject (NSObject) Availability Available in iOS 7.0 and later. 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 image’s coordinate space. Tasks Getting the Snapshot Image image (page ?) property The image of the map’s 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. 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 86 MKMapSnapshot Class Reference Properties image The image of the map’s content. (read-only) @property (nonatomic, readonly) UIImage *image; Availability Available in iOS 7.0 and later. 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 image’s 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 Available in iOS 7.0 and later. Declared in MKMapSnapshot.h MKMapSnapshot Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 87 Inherits from NSObject Conforms to NSCopying NSObject (NSObject) Availability Available in iOS 7.0 and later. 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. region (page 90) property 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 map’s visual style. showsPointsOfInterest (page 91) property A Boolean indicating whether the map displays point-of-interest information. 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 7.0 and later. Declared in MKMapSnapshotOptions.h mapType The map’s visual style. @property (nonatomic, assign) MKMapType mapType; Discussion The default value of this property is MKMapTypeStandard (page 140). Availability Available in iOS 7.0 and later. MKMapSnapshotOptions Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 89 Declared in MKMapSnapshotOptions.h 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 user’s 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 user’s country, as determined by the current locale information. Availability Available in iOS 7.0 and later. Declared in MKMapSnapshotOptions.h scale The scale factor to use when creating the image. @property (nonatomic, assign) CGFloat scale; MKMapSnapshotOptions Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 device’s display. You can change the value as needed to generate an image suitable for display on a different device. Availability Available in iOS 7.0 and later. Declared in MKMapSnapshotOptions.h showsBuildings A Boolean indicating whether the map displays extruded building information. @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 Available in iOS 7.0 and later. Declared in MKMapSnapshotOptions.h showsPointsOfInterest A Boolean indicating whether the map displays point-of-interest information. @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. MKMapSnapshotOptions Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 91 Availability Available in iOS 7.0 and later. Declared in MKMapSnapshotOptions.h 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 Available in iOS 7.0 and later. Declared in MKMapSnapshotOptions.h MKMapSnapshotOptions Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 92 Inherits from NSObject Conforms to NSObject (NSObject) Availability Available in iOS 7.0 and later. 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. 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 7.0 and later. 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 Available in iOS 7.0 and later. MKMapSnapshotter Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 user’s country. Return Value An initialized snapshotter option. Availability Available in iOS 7.0 and later. 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 app’s 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. MKMapSnapshotter Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 7.0 and later. 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 Available in iOS 7.0 and later. Declared in MKMapSnapshotter.h MKMapSnapshotter Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 7.0 and later. Declared in MKMapSnapshotter.h MKMapSnapshotter Class Reference Constants 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 97 Inherits from UIView : UIResponder : NSObject Conforms to NSCoding NSCoding (UIView) UIAppearance (UIView) UIAppearanceContainer (UIView) UIDynamicItem (UIView) NSObject (NSObject) Framework /System/Library/Frameworks/MapKit.framework Availability Available in iOS 3.0 and later. Declared in MapKit/MKMapView.h Companion guide Location and Maps Programming Guide 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. 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 98 MKMapView Class Reference 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. 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 view’s 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 application’s 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 annotation’s location on the map along with descriptive information that can be displayed in a callout. MKMapView Class Reference Overview 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 overlay’s 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. MKMapView Class Reference Overview 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 camera’s pitch information is used. rotateEnabled (page 110) property A Boolean value indicating whether the map camera’s heading information is used. Accessing the Delegate delegate (page 108) property The receiver’s delegate. Manipulating the Visible Portion of the Map region (page 109) property 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 The map coordinate at the center of the map view. – 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 The area currently displayed by the map view. MKMapView Class Reference Tasks 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Map’s 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 map’s viewing parameters and optionally animates the change. showsPointsOfInterest (page 112) property A Boolean indicating whether the map displays point-of-interest information. showsBuildings (page 111) property A Boolean indicating whether the map displays extruded building information. Displaying the User’s Location showsUserLocation (page 112) property A Boolean value indicating whether the map should try to display the user’s location. userLocationVisible (page 113) property A Boolean value indicating whether the device’s current location is visible in the map view. (read-only) userLocation (page 113) property The annotation object representing the user’s 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. MKMapView Class Reference Tasks 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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) MKMapView Class Reference Tasks 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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. MKMapView Class Reference Tasks 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 view’s 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 view’s 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 view’s frame. – mapRectThatFits: (page 127) Adjusts the aspect ratio of the specified map rectangle to ensure that it fits in the map view’s 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) MKMapView Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 3.0 and later. See Also – addAnnotation: (page 115) – addAnnotations: (page 116) – removeAnnotation: (page 130) – removeAnnotations: (page 131) Declared in MKMapView.h annotationVisibleRect The visible rectangle where annotation views are currently being displayed. (read-only) @property(nonatomic, readonly) CGRect annotationVisibleRect Availability Available in iOS 3.0 and later. 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 map’s 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 user’s heading or to apply a pitch angle to tilt the plane of the map. MKMapView Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 7.0 and later. See Also – setCamera:animated: (page 134) Declared in MKMapView.h centerCoordinate The map coordinate at the center of the map view. @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 Available in iOS 3.0 and later. See Also – setCenterCoordinate:animated: (page 134) @property region (page 109) Related Sample Code Regions Declared in MKMapView.h MKMapView Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 107 delegate The receiver’s 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 Available in iOS 3.0 and later. 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 receiver’s delegate indicating the status of the operation. Availability Available in iOS 3.0 and later. Related Sample Code GeocoderDemo Declared in MKMapView.h overlays The overlay objects currently associated with the map view. (read-only) MKMapView Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 4.0 and later. Declared in MKMapView.h pitchEnabled A Boolean value indicating whether the map camera’s 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 camera’s pitch angle is used to tilt the plane of the map. When this property is set to NO, the camera’s pitch angle is ignored and the map is always displayed as if the user is looking straight down onto it. Availability Available in iOS 7.0 and later. Declared in MKMapView.h region The area currently displayed by the map view. @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. MKMapView Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 3.0 and later. See Also – setRegion:animated: (page 135) @property centerCoordinate (page 107) Declared in MKMapView.h rotateEnabled A Boolean value indicating whether the map camera’s 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 camera’s heading angle is used to rotate the plane of the map around its center point. When this property is set to NO, the camera’s heading angle is ignored and the map is always oriented so that true north is situated at the top of the map view. Availability Available in iOS 7.0 and later. Declared in MKMapView.h MKMapView Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 3.0 and later. 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 Available in iOS 3.0 and later. Declared in MKMapView.h showsBuildings A Boolean indicating whether the map displays extruded building information. @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. MKMapView Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 111 Availability Available in iOS 7.0 and later. Declared in MKMapView.h showsPointsOfInterest A Boolean indicating whether the map displays point-of-interest information. @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 Available in iOS 7.0 and later. Declared in MKMapView.h showsUserLocation A Boolean value indicating whether the map should try to display the user’s location. @property(nonatomic) BOOL showsUserLocation Discussion This property does not indicate whether the user’s 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 user’s location and update it periodically. The default value of this property is NO. Showing the user’s 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 user’s current location is currently displayed on the map, use the userLocationVisible property. Availability Available in iOS 3.0 and later. MKMapView Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 112 See Also @property userLocationVisible (page 113) Declared in MKMapView.h userLocation The annotation object representing the user’s current location. (read-only) @property(nonatomic, readonly) MKUserLocation *userLocation Availability Available in iOS 3.0 and later. See Also @property showsUserLocation (page 112) Declared in MKMapView.h userLocationVisible A Boolean value indicating whether the device’s current location is visible in the map view. (read-only) @property(nonatomic, readonly, getter=isUserLocationVisible) BOOL userLocationVisible Discussion This property tells you whether the icon used to represent the user’s current location is visible in the map view. When determining whether the current location is visible, this property factors in the horizontal accuracy of the location data. Specifically, if the rectangle represented by the user’s current location plus or minus minus the horizontal accuracy of that location intersects the map’s visible rectangle, this property contains the value YES. If that location rectangle does not intersect the map’s visible rectangle, this property contains the value NO. If the user’s location cannot be determined, this property contains the value NO. Availability Available in iOS 3.0 and later. Declared in MKMapView.h MKMapView Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 user’s location. If the map is zoomed out, the map view automatically zooms in on the user’s location, effectively changing the current visible region. Availability Available in iOS 5.0 and later. See Also – setUserTrackingMode:animated: (page 136) Declared in MKMapView.h visibleMapRect The area currently displayed by the map view. @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 Available in iOS 4.0 and later. Related Sample Code KMLViewer PhotosByLocation MKMapView Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 3.0 and later. 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 Available in iOS 3.0 and later. See Also – addAnnotations: (page 116) – removeAnnotation: (page 130) Related Sample Code GeocoderDemo MKMapView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 3.0 and later. See Also – addAnnotation: (page 115) – removeAnnotations: (page 131) 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 view’s delegate object. MKMapView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 116 To remove an overlay from a map, use the removeOverlay: (page 131) method. Availability Available in iOS 4.0 and later. See Also – addOverlays: (page 118) – removeOverlay: (page 131) – removeOverlays: (page 132) 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 overlay’s 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 delegate’s 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 Available in iOS 7.0 and later. MKMapView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 view’s delegate object. To remove multiple overlays from a map, use the removeOverlays: (page 132) method. Availability Available in iOS 4.0 and later. See Also – addOverlay: (page 116) – removeOverlay: (page 131) – removeOverlays: (page 132) 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 MKMapView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 “MKOverlayLevel” (page 141). Discussion Positioning an overlay at a specific level places that overlay’s visual representation in front of or behind other map content such as map labels and point-of-interest icons. This method adds the specified overlays to the end of the list of overlay objects at the given level. Adding 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 delegate’s 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 Available in iOS 7.0 and later. 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. MKMapView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 119 Special Considerations Prior to iOS 7 this method incorrectly did not return instances of MKUserLocation. Availability Available in iOS 4.2 and later. 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 window’s 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 Available in iOS 3.0 and later. See Also – convertPoint:toCoordinateFromView: (page 120) Declared in MKMapView.h convertPoint:toCoordinateFromView: Converts a point in the specified view’s coordinate system to a map coordinate. MKMapView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 3.0 and later. See Also – convertCoordinate:toPointToView: (page 120) Declared in MKMapView.h convertRect:toRegionFromView: Converts a rectangle in the specified view’s 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 Available in iOS 3.0 and later. See Also – convertRegion:toRectToView: (page 122) MKMapView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 window’s 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 Available in iOS 3.0 and later. 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. MKMapView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 3.0 and later. 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 Available in iOS 3.0 and later. Declared in MKMapView.h exchangeOverlay:withOverlay: Exchanges the positions of the two overlay objects. - (void)exchangeOverlay:(id < MKOverlay >)overlay1 withOverlay:(id < MKOverlay >)overlay2 MKMapView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 level’s 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 Available in iOS 7.0 and later. 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 Available in iOS 4.0 and later. See Also – exchangeOverlay:withOverlay: (page 123) MKMapView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 overlay’s 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 Available in iOS 4.0 and later. See Also – insertOverlay:atIndex: (page 125) – insertOverlay:belowOverlay: (page 127) 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 The overlay object to insert. MKMapView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 4.0 and later. See Also – insertOverlay:aboveOverlay: (page 125) – insertOverlay:belowOverlay: (page 127) 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 The overlay object to insert. 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 “MKOverlayLevel” (page 141). Discussion Inserting an overlay at a specific level places that overlay’s visual representation in front of or behind other map content such as map labels and point-of-interest icons. Availability Available in iOS 7.0 and later. MKMapView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 126 Declared in MKMapView.h insertOverlay:belowOverlay: Inserts one overlay object below another. - (void)insertOverlay:(id < MKOverlay >)overlay belowOverlay:(id < MKOverlay >)sibling Parameters overlay The overlay object to insert. 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 overlay’s 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 Available in iOS 4.0 and later. See Also – insertOverlay:atIndex: (page 125) – insertOverlay:aboveOverlay: (page 125) Declared in MKMapView.h mapRectThatFits: Adjusts the aspect ratio of the specified map rectangle to ensure that it fits in the map view’s frame. - (MKMapRect)mapRectThatFits:(MKMapRect)mapRect Parameters mapRect The initial map rectangle whose width and height you want to adjust. MKMapView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 view’s 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 view’s frame. Availability Available in iOS 4.0 and later. 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 view’s 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 view’s frame minus the inset values. Availability Available in iOS 4.0 and later. See Also – mapRectThatFits: (page 127) MKMapView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 “MKOverlayLevel” (page 141). 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 Available in iOS 7.0 and later. 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 view’s frame. - (MKCoordinateRegion)regionThatFits:(MKCoordinateRegion)region MKMapView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 view’s 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 view’s frame. Availability Available in iOS 3.0 and later. 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 Available in iOS 3.0 and later. See Also – removeAnnotations: (page 131) MKMapView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 130 – addAnnotation: (page 115) 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 Available in iOS 3.0 and later. See Also – removeAnnotation: (page 130) – addAnnotations: (page 116) Declared in MKMapView.h removeOverlay: Removes a single overlay object from the map. - (void)removeOverlay:(id < MKOverlay >)overlay MKMapView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 4.0 and later. See Also – addOverlay: (page 116) – addOverlays: (page 118) – removeOverlays: (page 132) 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 Available in iOS 4.0 and later. See Also – addOverlay: (page 116) MKMapView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 132 – addOverlays: (page 118) – removeOverlay: (page 131) 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 Available in iOS 7.0 and later. 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. MKMapView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 133 Discussion If the specified annotation is not onscreen, and therefore does not have an associated annotation view, this method has no effect. Availability Available in iOS 3.0 and later. Declared in MKMapView.h setCamera:animated: Changes the camera used for determining the map’s viewing parameters and optionally animates the change. - (void)setCamera:(MKMapCamera *)camera animated:(BOOL)animated 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 Available in iOS 7.0 and later. 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. MKMapView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 3.0 and later. See Also @property centerCoordinate (page 107) @property region (page 109) 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. MKMapView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 3.0 and later. See Also @property region (page 109) – setCenterCoordinate:animated: (page 134) 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 user’s location. If the map is zoomed out, the map view automatically zooms in on the user’s location, effectively changing the current visible region. Availability Available in iOS 5.0 and later. See Also @property userTrackingMode (page 114) MKMapView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 4.0 and later. 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. MKMapView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 4.0 and later. 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 Available in iOS 7.0 and later. Declared in MKMapView.h viewForAnnotation: Returns the annotation view associated with the specified annotation object, if any. - (MKAnnotationView *)viewForAnnotation:(id < MKAnnotation >)annotation MKMapView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 3.0 and later. 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 Available in iOS 4.0 and later. Deprecated in iOS 7.0. Declared in MKMapView.h Constants MKMapType The type of map to display. MKMapView Class Reference Constants 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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. Available in iOS 3.0 and later. Declared in MKTypes.h. MKMapTypeSatellite Displays satellite imagery of the area. Available in iOS 3.0 and later. Declared in MKTypes.h. MKMapTypeHybrid Displays a satellite image of the area with road and road name information layered on top. Available in iOS 3.0 and later. Declared in MKTypes.h. 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. Available in iOS 5.0 and later. Declared in MKMapView.h. MKMapView Class Reference Constants 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 140 MKUserTrackingModeFollow The map follows the user location. Available in iOS 5.0 and later. Declared in MKMapView.h. MKUserTrackingModeFollowWithHeading The map follows the user location and rotates when the heading changes. Available in iOS 5.0 and later. Declared in MKMapView.h. 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. Available in iOS 7.0 and later. Declared in MKMapView.h. MKOverlayLevelAboveLabels Place the overlay above map labels, shields, or point-of-interest icons but below annotations and 3D projections of buildings. Available in iOS 7.0 and later. Declared in MKMapView.h. MKMapView Class Reference Constants 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 141 Inherits from MKShape : NSObject Conforms to MKAnnotation (MKShape) NSObject (NSObject) Framework /System/Library/Frameworks/MapKit.framework Availability Available in iOS 4.0 and later. Declared in MKMultiPoint.h Companion guide Location and Maps Programming Guide 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. 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. Tasks Accessing the Points in the Shape points (page 143) property The array of points associated with the shape. (read-only) 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 4.0 and later. 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 Available in iOS 4.0 and later. Declared in MKMultiPoint.h MKMultiPoint Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 4.0 and later. Declared in MKMultiPoint.h MKMultiPoint Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 144 Inherits from MKOverlayRenderer : NSObject Conforms to NSObject (NSObject) Framework /System/Library/Frameworks/MapKit.framework Availability Available in iOS 7.0 and later. Declared in MKOverlayPathRenderer.h Companion guide Location and Maps Programming Guide 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 object’s 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. 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 overlay’s 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 receiver’s current stroke-related drawing properties to the specified graphics context. – applyFillPropertiesToContext:atZoomScale: (page 150) Applies the receiver’s 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. MKOverlayPathRenderer Class Reference Tasks 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 146 Properties fillColor The fill color to use for the path. @property(retain) UIColor *fillColor Availability Available in iOS 7.0 and later. Declared in MKOverlayPathRenderer.h 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 Available in iOS 7.0 and later. Declared in MKOverlayPathRenderer.h 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. MKOverlayPathRenderer Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 147 Availability Available in iOS 7.0 and later. Declared in MKOverlayPathRenderer.h 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 Available in iOS 7.0 and later. Declared in MKOverlayPathRenderer.h lineJoin The line join style to apply to corners of the path. @property CGLineJoin lineJoin Discussion The default line join style is kCGLineJoinRound. Availability Available in iOS 7.0 and later. Declared in MKOverlayPathRenderer.h lineWidth The stroke width to use for the path. MKOverlayPathRenderer Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 148 @property CGFloat lineWidth Discussion The default value of this property is 0. Availability Available in iOS 7.0 and later. Declared in MKOverlayPathRenderer.h 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 length—that is, the diagonal length of the miter join—to 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 Available in iOS 7.0 and later. Declared in MKOverlayPathRenderer.h path The path representing the overlay’s 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 Available in iOS 7.0 and later. MKOverlayPathRenderer Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 149 Declared in MKOverlayPathRenderer.h strokeColor The stroke color to use for the path. @property(retain) UIColor *strokeColor Availability Available in iOS 7.0 and later. Declared in MKOverlayPathRenderer.h Instance Methods applyFillPropertiesToContext:atZoomScale: Applies the receiver’s 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 view’s 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 Available in iOS 7.0 and later. Declared in MKOverlayPathRenderer.h MKOverlayPathRenderer Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 150 applyStrokePropertiesToContext:atZoomScale: Applies the receiver’s current stroke-related drawing properties to the specified graphics context. - (void)applyStrokePropertiesToContext:(CGContextRef)context atZoomScale:(MKZoomScale)zoomScale Parameters context The graphics context used to draw the view’s contents. zoomScale The current zoom scale used for drawing. 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 Available in iOS 7.0 and later. Declared in MKOverlayPathRenderer.h 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 Available in iOS 7.0 and later. MKOverlayPathRenderer Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 151 Declared in MKOverlayPathRenderer.h 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 Available in iOS 7.0 and later. See Also – applyFillPropertiesToContext:atZoomScale: (page 150) Declared in MKOverlayPathRenderer.h 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 overlay’s path. This method sets the path (page 149) property to nil and tells the overlay renderer to redisplay its contents. Availability Available in iOS 7.0 and later. MKOverlayPathRenderer Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 152 Declared in MKOverlayPathRenderer.h strokePath:inContext: Draws a line along the specified path. - (void)strokePath:(CGPathRef)path inContext:(CGContextRef)context Parameters path The path to draw. context The graphics context in which to draw the path. 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 Available in iOS 7.0 and later. See Also – applyStrokePropertiesToContext:atZoomScale: (page 151) Declared in MKOverlayPathRenderer.h MKOverlayPathRenderer Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 153 Inherits from MKOverlayView : UIView : UIResponder : NSObject Conforms to NSCoding (UIView) UIAppearance (UIView) UIAppearanceContainer (UIView) UIDynamicItem (UIView) NSObject (NSObject) Framework /System/Library/Frameworks/MapKit.framework Availability Available in iOS 4.0 and later. Declared in MKOverlayPathView.h Companion guide Location and Maps Programming Guide 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 object’s 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. 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 154 MKOverlayPathView Class Reference 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. 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.) MKOverlayPathView Class Reference Tasks 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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.) – createPath (page 162) Creates the path for the overlay. (Deprecated. Use an MKOverlayPathRenderer object instead.) – invalidatePath (page 163) Releases the path associated with the receiver. (Deprecated. Use an MKOverlayPathRenderer object instead.) Drawing the Path – applyStrokePropertiesToContext:atZoomScale: (page 161) Applies the receiver’s current stroke-related drawing properties to the specified graphics context. (Deprecated. Use an MKOverlayPathRenderer object instead.) – applyFillPropertiesToContext:atZoomScale: (page 161) Applies the receiver’s current fill-related drawing properties to the specified graphics context (Deprecated. Use an MKOverlayPathRenderer object instead.) – strokePath:inContext: (page 164) Draws a line along the specified path. (Deprecated. Use an MKOverlayPathRenderer object instead.) – fillPath:inContext: (page 163) 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 Available in iOS 4.0 and later. MKOverlayPathView Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 156 Deprecated in iOS 7.0. 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 Available in iOS 4.0 and later. Deprecated in iOS 7.0. Declared in MKOverlayPathView.h lineDashPattern An array of numbers indicating the dash pattern for paths. (Deprecated in iOS 7.0. Use an MKOverlayPathRenderer object instead.) @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 Available in iOS 4.0 and later. MKOverlayPathView Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 157 Deprecated in iOS 7.0. Declared in MKOverlayPathView.h lineDashPhase The offset (in points) at which to start drawing the dash pattern. (Deprecated in iOS 7.0. Use an MKOverlayPathRenderer object instead.) @property CGFloat lineDashPhase Availability Available in iOS 4.0 and later. Deprecated in iOS 7.0. 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 Available in iOS 4.0 and later. Deprecated in iOS 7.0. Declared in MKOverlayPathView.h lineWidth The stroke width to use for the path. (Deprecated in iOS 7.0. Use an MKOverlayPathRenderer object instead.) MKOverlayPathView Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 158 @property CGFloat lineWidth Discussion The default value of this property is 0. Availability Available in iOS 4.0 and later. Deprecated in iOS 7.0. 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. Use an MKOverlayPathRenderer object instead.) @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 length—that is, the diagonal length of the miter join—to 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 Available in iOS 4.0 and later. Deprecated in iOS 7.0. Declared in MKOverlayPathView.h path The current path to use when drawing the overlay. (Deprecated in iOS 7.0. Use an MKOverlayPathRenderer object instead.) MKOverlayPathView Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 4.0 and later. Deprecated in iOS 7.0. See Also – createPath (page 162) – invalidatePath (page 163) 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 Available in iOS 4.0 and later. Deprecated in iOS 7.0. Related Sample Code KMLViewer Regions Declared in MKOverlayPathView.h MKOverlayPathView Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 160 Instance Methods applyFillPropertiesToContext:atZoomScale: Applies the receiver’s current fill-related drawing properties to the specified graphics context (Deprecated in iOS 7.0. Use an MKOverlayPathRenderer object instead.) - (void)applyFillPropertiesToContext:(CGContextRef)context atZoomScale:(MKZoomScale)zoomScale Parameters context The graphics context used to draw the view’s 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 Available in iOS 4.0 and later. Deprecated in iOS 7.0. See Also – fillPath:inContext: (page 163) Declared in MKOverlayPathView.h applyStrokePropertiesToContext:atZoomScale: Applies the receiver’s current stroke-related drawing properties to the specified graphics context. (Deprecated in iOS 7.0. Use an MKOverlayPathRenderer object instead.) - (void)applyStrokePropertiesToContext:(CGContextRef)context atZoomScale:(MKZoomScale)zoomScale Parameters context The graphics context used to draw the view’s contents. MKOverlayPathView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 161 zoomScale The current zoom scale used for drawing. 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 Available in iOS 4.0 and later. Deprecated in iOS 7.0. See Also – strokePath:inContext: (page 164) 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 Available in iOS 4.0 and later. Deprecated in iOS 7.0. Declared in MKOverlayPathView.h MKOverlayPathView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 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 (page 156) property is currently nil, this method does nothing. Availability Available in iOS 4.0 and later. Deprecated in iOS 7.0. See Also – applyFillPropertiesToContext:atZoomScale: (page 161) 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 Available in iOS 4.0 and later. MKOverlayPathView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 163 Deprecated in iOS 7.0. 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 The graphics context in which to draw the path. 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 Available in iOS 4.0 and later. Deprecated in iOS 7.0. See Also – applyStrokePropertiesToContext:atZoomScale: (page 161) Declared in MKOverlayPathView.h MKOverlayPathView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 164 Inherits from NSObject Conforms to NSObject (NSObject) Framework /System/Library/Frameworks/MapKit.framework Availability Available in iOS 7.0 and later. 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 object—that 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. 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 overlay’s content. (read-only) Converting Points on the Map – pointForMapPoint: (page 172) Returns the point in the overlay renderer’s 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 renderer’s drawing area. – rectForMapRect: (page 172) Returns the rectangle in the overlay renderer’s 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 renderer’s drawing area. Drawing the Overlay – canDrawMapRect:zoomScale: (page 168) Returns a Boolean value indicating whether the overlay view is ready to draw its content. MKOverlayRenderer Class Reference Tasks 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 166 – drawMapRect:zoomScale:inContext: (page 169) Draws the overlay’s 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 Available in iOS 7.0 and later. Declared in MKOverlayRenderer.h contentScaleFactor The scale factor used to draw the overlay’s 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. MKOverlayRenderer Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 167 When drawing the content for your overlays, you can use this value to determine how best to render your content. Availability Available in iOS 7.0 and later. 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 Available in iOS 7.0 and later. 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. MKOverlayRenderer Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 7.0 and later. Declared in MKOverlayRenderer.h drawMapRect:zoomScale:inContext: Draws the overlay’s 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 map’s contents. context The graphics context to use for drawing the overlay’s contents. Discussion The default implementation of this method does nothing. Subclasses are expected to override this method and use it to draw the overlay’s contents. MKOverlayRenderer Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 app’s 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 Available in iOS 7.0 and later. 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 overlay’s 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. MKOverlayRenderer Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 170 Availability Available in iOS 7.0 and later. Declared in MKOverlayRenderer.h mapPointForPoint: Returns the point on the map that corresponds to the specified point in the overlay renderer’s drawing area. - (MKMapPoint)mapPointForPoint:(CGPoint)point Parameters point The point in the overlay’s 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 view’s drawMapRect:zoomScale:inContext: (page 169) method. Availability Available in iOS 7.0 and later. Declared in MKOverlayRenderer.h mapRectForRect: Returns the rectangle on the map that corresponds to the specified rectangle in the overlay renderer’s drawing area. - (MKMapRect)mapRectForRect:(CGRect)rect Parameters rect The rectangle in the overlay’s drawing area that you want to convert. Return Value The rectangle on the two-dimensional map projection corresponding to the specified rectangle. MKOverlayRenderer Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 171 Discussion You may call this method safely from your view’s drawMapRect:zoomScale:inContext: (page 169) method. Availability Available in iOS 7.0 and later. Declared in MKOverlayRenderer.h pointForMapPoint: Returns the point in the overlay renderer’s 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 overlay’s drawing area that corresponds to the map point. Discussion You may call this method safely from your view’s drawMapRect:zoomScale:inContext: (page 169) method. Availability Available in iOS 7.0 and later. Declared in MKOverlayRenderer.h rectForMapRect: Returns the rectangle in the overlay renderer’s drawing area corresponding to the specified rectangle on the map. - (CGRect)rectForMapRect:(MKMapRect)mapRect Parameters mapRect A rectangle on the two-dimensional map projection. MKOverlayRenderer Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 172 Return Value The rectangle in the overlay’s drawing area that corresponds to the map rectangle. Discussion You may call this method safely from your view’s drawMapRect:zoomScale:inContext: (page 169) method. Availability Available in iOS 7.0 and later. 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 Available in iOS 7.0 and later. 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. MKOverlayRenderer Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 173 Availability Available in iOS 7.0 and later. 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 Available in iOS 7.0 and later. Declared in MKOverlayRenderer.h MKOverlayRenderer Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 174 Inherits from UIView : UIResponder : NSObject Conforms to NSCoding (UIView) UIAppearance (UIView) UIAppearanceContainer (UIView) UIDynamicItem (UIView) NSObject (NSObject) Framework /System/Library/Frameworks/MapKit.framework Availability Available in iOS 4.0 and later. Declared in MKOverlayView.h Companion guide Location and Maps Programming Guide 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 object—that 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. 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 175 MKOverlayView Class Reference 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. 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.) MKOverlayView Class Reference Tasks 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 176 Converting Points on the Map – pointForMapPoint: (page 182) Returns the point in the overlay view that corresponds to specified point on the map. (Deprecated. Use an MKOverlayRenderer object instead.) – mapPointForPoint: (page 181) Returns the map point that corresponds to the specified point in the overlay view. (Deprecated. Use an MKOverlayRenderer object instead.) – rectForMapRect: (page 183) Returns the rectangle in the overlay view that corresponds to the specified rectangle on the map. (Deprecated. Use an MKOverlayRenderer object instead.) – mapRectForRect: (page 182) Returns the map rectangle that corresponds to the rectangle in the overlay view’s coordinate system. (Deprecated. Use an MKOverlayRenderer object instead.) Drawing the Overlay – canDrawMapRect:zoomScale: (page 178) Returns a Boolean value indicating whether the overlay view is ready to draw its content. (Deprecated. Use an MKOverlayRenderer object instead.) – 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 MKOverlayRenderer object instead.) – setNeedsDisplayInMapRect:zoomScale: (page 184) Invalidates the view in the given map rectangle but only at the specified zoom scale. (Deprecated. Use an MKOverlayRenderer object instead.) Properties overlay The overlay object containing the data for drawing. (read-only) (Deprecated in iOS 7.0. Use an MKOverlayRenderer object instead.) MKOverlayView Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 177 @property (nonatomic, readonly) id <MKOverlay> overlay Availability Available in iOS 4.0 and later. Deprecated in iOS 7.0. 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. Use an MKOverlayRenderer object instead.) - (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. MKOverlayView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 178 The default implementation of this method returns YES. Availability Available in iOS 4.0 and later. Deprecated in iOS 7.0. 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 view’s content. context The graphics context to use for drawing the view’s 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 view’s 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 view’s frame matches the bounding rectangle of the overlay. The view’s 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. MKOverlayView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 application’s 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 Available in iOS 4.0 and later. Deprecated in iOS 7.0. See Also – canDrawMapRect:zoomScale: (page 178) – pointForMapPoint: (page 182) – rectForMapRect: (page 183) Declared in MKOverlayView.h initWithOverlay: Initializes and returns the overlay view and associates it with the specified overlay object. (Deprecated in iOS 7.0. Use an MKOverlayRenderer object instead.) - (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 overlay’s shape. This object is retained by the overlay view. Return Value An initialized overlay object. MKOverlayView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 4.0 and later. Deprecated in iOS 7.0. 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 MKOverlayRenderer object instead.) - (MKMapPoint)mapPointForPoint:(CGPoint)point Parameters point The point in the view’s coordinate system that you want to convert. Return Value The point on the two-dimensional map projection corresponding to the specified point. Special Considerations 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 view’s drawMapRect:zoomScale:inContext: (page 179) method. Availability Available in iOS 4.0 and later. Deprecated in iOS 7.0. See Also – pointForMapPoint: (page 182) MKOverlayView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 181 Declared in MKOverlayView.h mapRectForRect: Returns the map rectangle that corresponds to the rectangle in the overlay view’s coordinate system. (Deprecated in iOS 7.0. Use an MKOverlayRenderer object instead.) - (MKMapRect)mapRectForRect:(CGRect)rect Parameters rect The rectangle specified in the receiver’s coordinate system. Return Value The rectangle on the two-dimensional map project that corresponds to the specified view rectangle. Special Considerations 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 view’s drawMapRect:zoomScale:inContext: (page 179) method. Availability Available in iOS 4.0 and later. Deprecated in iOS 7.0. See Also – rectForMapRect: (page 183) 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 an MKOverlayRenderer object instead.) - (CGPoint)pointForMapPoint:(MKMapPoint)mapPoint MKOverlayView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 receiver’s coordinate system that corresponds to the map point. Special Considerations 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 view’s drawMapRect:zoomScale:inContext: (page 179) method. Availability Available in iOS 4.0 and later. Deprecated in iOS 7.0. See Also – mapPointForPoint: (page 181) 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 receiver’s coordinate system. Special Considerations 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 view’s drawMapRect:zoomScale:inContext: (page 179) method. MKOverlayView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 183 Availability Available in iOS 4.0 and later. Deprecated in iOS 7.0. See Also – mapRectForRect: (page 182) Declared in MKOverlayView.h setNeedsDisplayInMapRect: Invalidates the view in the given map rectangle at all zoom scales. (Deprecated in iOS 7.0. Use an MKOverlayRenderer object instead.) - (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 Available in iOS 4.0 and later. Deprecated in iOS 7.0. 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 an MKOverlayRenderer object instead.) - (void)setNeedsDisplayInMapRect:(MKMapRect)mapRect zoomScale:(MKZoomScale)zoomScale MKOverlayView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 4.0 and later. Deprecated in iOS 7.0. Declared in MKOverlayView.h MKOverlayView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 185 Inherits from MKAnnotationView : UIView : UIResponder : NSObject Conforms to NSCoding (UIView) UIAppearance (UIView) UIAppearanceContainer (UIView) UIDynamicItem (UIView) NSObject (NSObject) Framework /System/Library/Frameworks/MapKit.framework Availability Available in iOS 3.0 and later. Declared in MKAnnotationView.h Companion guide Location and Maps Programming Guide 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. 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 186 MKPinAnnotationView Class Reference 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. 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 Available in iOS 3.0 and later. Related Sample Code KMLViewer MapCallouts MapSearch Declared in MKPinAnnotationView.h MKPinAnnotationView Class Reference Tasks 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 3.0 and later. Related Sample Code MapCallouts Declared in MKPinAnnotationView.h 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. Available in iOS 3.0 and later. Declared in MKPinAnnotationView.h. MKPinAnnotationView Class Reference Constants 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 188 MKPinAnnotationColorGreen The head of the pin is green. Green pins indicate starting points on the map. Available in iOS 3.0 and later. Declared in MKPinAnnotationView.h. MKPinAnnotationColorPurple The head of the pin is purple. Purple pins indicate user-specified points on the map. Available in iOS 3.0 and later. Declared in MKPinAnnotationView.h. MKPinAnnotationView Class Reference Constants 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 189 Inherits from CLPlacemark : NSObject Conforms to MKAnnotation NSCopying (CLPlacemark) NSSecureCoding (CLPlacemark) NSObject (NSObject) Framework /System/Library/Frameworks/MapKit.framework Availability Available in iOS 3.0 and later. Declared in MKPlacemark.h Companion guide Location and Maps Programming Guide Related sample code CurrentAddress Using NSXMLParser to parse XML documents 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. 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 190 MKPlacemark Class Reference 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. 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 Apple’s headquarters, the value for this property would be the string “US”. Availability Available in iOS 3.0 and later. Declared in MKPlacemark.h MKPlacemark Class Reference Tasks 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 3.0 and later. Related Sample Code Using NSXMLParser to parse XML documents Declared in MKPlacemark.h MKPlacemark Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 192 Inherits from MKShape : NSObject Conforms to MKAnnotation (MKShape) NSObject (NSObject) Framework /System/Library/Frameworks/MapKit.framework Availability Available in iOS 4.0 and later. Declared in MKPointAnnotation.h Companion guide Location and Maps Programming Guide 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. 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 193 MKPointAnnotation Class Reference 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. Tasks Accessing the Annotation’s Location coordinate (page 194) property 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 Available in iOS 4.0 and later. Related Sample Code KMLViewer PhotosByLocation Declared in MKPointAnnotation.h MKPointAnnotation Class Reference Tasks 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 194 Inherits from MKMultiPoint : MKShape : NSObject Conforms to MKOverlay MKAnnotation (MKShape) NSObject (NSObject) Framework /System/Library/Frameworks/MapKit.framework Availability Available in iOS 4.0 and later. Declared in MKPolygon.h Companion guide Location and Maps Programming Guide 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 . 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 195 MKPolygon Class Reference 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. 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. MKPolygon Class Reference Tasks 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 196 Availability Available in iOS 4.0 and later. Declared in MKPolygon.h Class Methods polygonWithCoordinates:count: Creates and returns an MKPolygon object from the specified set of coordinates. + (MKPolygon *)polygonWithCoordinates:(CLLocationCoordinate2D *)coords count:(NSUInteger)count Parameters coords The array of coordinates defining the shape. The data in this array is copied to the new object. count The number of items in the coords array. Return Value A new polygon object. Availability Available in iOS 4.0 and later. 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 MKPolygon Class Reference Class Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 197 Parameters coords The array of coordinates defining the shape. The data in this array is copied to the new object. count The number of items in the coords array. interiorPolygons An array of MKPolygon objects that define one or more cutout regions for the receiver’s polygon. Return Value A new polygon object. Availability Available in iOS 4.0 and later. 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 The number of items in the points array. Return Value A new polygon object. Availability Available in iOS 4.0 and later. Declared in MKPolygon.h MKPolygon Class Reference Class Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 The array of map points defining the shape. The data in this array is copied to the new object. count The number of items in the points array. interiorPolygons An array of MKPolygon objects that define one or more cutout regions for the receiver’s polygon. Return Value A new polygon object. Availability Available in iOS 4.0 and later. Declared in MKPolygon.h MKPolygon Class Reference Class Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 199 Inherits from MKOverlayPathRenderer : MKOverlayRenderer : NSObject Conforms to NSObject (NSObject) Framework /System/Library/Frameworks/MapKit.framework Availability Available in iOS 7.0 and later. 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 overlay’s contents. (read-only) 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 200 MKPolygonRenderer Class Reference Properties polygon The polygon object that contains the information used to draw the overlay’s contents. (read-only) @property(nonatomic, readonly) MKPolygon *polygon Availability Available in iOS 7.0 and later. 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 Available in iOS 7.0 and later. Declared in MKPolygonRenderer.h MKPolygonRenderer Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 201 Inherits from MKOverlayPathView : MKOverlayView : UIView : UIResponder : NSObject Conforms to NSCoding (UIView) UIAppearance (UIView) UIAppearanceContainer (UIView) UIDynamicItem (UIView) NSObject (NSObject) Framework /System/Library/Frameworks/MapKit.framework Availability Available in iOS 4.0 and later. Declared in MKPolygonView.h Companion guide Location and Maps Programming Guide 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. 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. In iOS 7 and later, use the MKPolygonRenderer class to display polygon overlays instead. 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 4.0 and later. Deprecated in iOS 7.0. 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.) MKPolygonView Class Reference Tasks 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 4.0 and later. Deprecated in iOS 7.0. Related Sample Code KMLViewer Declared in MKPolygonView.h MKPolygonView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 204 Inherits from MKMultiPoint : MKShape : NSObject Conforms to MKOverlay MKAnnotation (MKShape) NSObject (NSObject) Framework /System/Library/Frameworks/MapKit.framework Availability Available in iOS 4.0 and later. Declared in MKPolyline.h Companion guide Location and Maps Programming Guide 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. 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 205 MKPolyline Class Reference 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. 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 count:(NSUInteger)count Parameters coords The array of coordinates defining the shape. The data in this array is copied to the new object. count The number of items in the coords array. Return Value A new polyline object. Availability Available in iOS 4.0 and later. Related Sample Code KMLViewer MKPolyline Class Reference Tasks 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 The array of map points defining the shape. The data in this array is copied to the new object. count The number of items in the points array. Return Value A new polyline object. Availability Available in iOS 4.0 and later. Declared in MKPolyline.h MKPolyline Class Reference Class Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 207 Inherits from MKOverlayPathRenderer : MKOverlayRenderer : NSObject Conforms to NSObject (NSObject) Framework /System/Library/Frameworks/MapKit.framework Availability Available in iOS 7.0 and later. 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) 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 7.0 and later. Declared in MKPolylineRenderer.h 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 Available in iOS 7.0 and later. Declared in MKPolylineRenderer.h MKPolylineRenderer Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 209 Inherits from MKOverlayPathView : MKOverlayView : UIView : UIResponder : NSObject Conforms to NSCoding (UIView) UIAppearance (UIView) UIAppearanceContainer (UIView) UIDynamicItem (UIView) NSObject (NSObject) Framework /System/Library/Frameworks/MapKit.framework Availability Available in iOS 4.0 and later. Declared in MKPolylineView.h Companion guide Location and Maps Programming Guide 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. 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. In iOS 7 and later, use the MKPolylineRenderer class to display polyline overlays instead. 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 polyline (page 211) property 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 Available in iOS 4.0 and later. Deprecated in iOS 7.0. 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.) MKPolylineView Class Reference Tasks 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 4.0 and later. Deprecated in iOS 7.0. Related Sample Code KMLViewer Declared in MKPolylineView.h MKPolylineView Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 212 Inherits from NSObject Conforms to NSObject (NSObject) Framework /System/Library/Frameworks/MapKit.framework Availability Available in iOS 3.0 and later. Deprecated in iOS 5.0. Declared in MKReverseGeocoder.h Companion guide Location and Maps Programming Guide 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. 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. 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. 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 geocoder’s delegate object. (Deprecated. Use the CLGeocoder class instead.) coordinate (page 215) property 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.) MKReverseGeocoder Class Reference Tasks 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 3.0 and later. Deprecated in iOS 5.0. Declared in MKReverseGeocoder.h delegate The reverse geocoder’s 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 . MKReverseGeocoder Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 215 Availability Available in iOS 3.0 and later. Deprecated in iOS 5.0. 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 Available in iOS 3.2 and later. Deprecated in iOS 5.0. 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 Available in iOS 3.0 and later. Deprecated in iOS 5.0. MKReverseGeocoder Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 3.0 and later. Deprecated in iOS 5.0. 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 Available in iOS 3.0 and later. Deprecated in iOS 5.0. MKReverseGeocoder Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 3.0 and later. Deprecated in iOS 5.0. Declared in MKReverseGeocoder.h MKReverseGeocoder Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 218 Inherits from NSObject Conforms to NSObject (NSObject) Availability Available in iOS 7.0 and later. Declared in MKDirectionsResponse.h 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 polyline (page 222) property 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) 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 expected travel time in seconds. (read-only) transportType (page 222) 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 user’s 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 Available in iOS 7.0 and later. Declared in MKDirectionsResponse.h 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. MKRoute Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 220 Availability Available in iOS 7.0 and later. Declared in MKDirectionsResponse.h expectedTravelTime The expected travel time in seconds. (read-only) @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 Available in iOS 7.0 and later. Declared in MKDirectionsResponse.h 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 user’s language preferences. You can display this string to the user from your app’s user interface so that the user can distinguish one route from another. The string itself describes the route using one of the route’s 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 Available in iOS 7.0 and later. Declared in MKDirectionsResponse.h MKRoute Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 221 polyline The detailed route geometry. (read-only) @property (nonatomic, readonly) MKPolyline *polyline 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 Available in iOS 7.0 and later. Declared in MKDirectionsResponse.h 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 Available in iOS 7.0 and later. Declared in MKDirectionsResponse.h 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. MKRoute Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 222 Availability Available in iOS 7.0 and later. Declared in MKDirectionsResponse.h MKRoute Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 223 Inherits from NSObject Conforms to NSObject (NSObject) Availability Available in iOS 7.0 and later. Declared in MKDirectionsResponse.h 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 polyline (page 226) property 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) 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 224 MKRouteStep Class Reference distance (page 225) property The step distance in meters. (read-only) transportType (page 226) property 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 Available in iOS 7.0 and later. Declared in MKDirectionsResponse.h 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 user’s language preferences. You can present this string to the user from your app’s interface. Availability Available in iOS 7.0 and later. Declared in MKDirectionsResponse.h MKRouteStep Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 7.0 and later. Declared in MKDirectionsResponse.h polyline The detailed step geometry. (read-only) @property (nonatomic, readonly) MKPolyline *polyline 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 Available in iOS 7.0 and later. Declared in MKDirectionsResponse.h 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. MKRouteStep Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 226 Availability Available in iOS 7.0 and later. Declared in MKDirectionsResponse.h MKRouteStep Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 227 Inherits from NSObject Conforms to MKAnnotation NSObject (NSObject) Framework /System/Library/Frameworks/MapKit.framework Availability Available in iOS 4.0 and later. Declared in MKShape.h Companion guide Location and Maps Programming Guide 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. 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 228 MKShape Class Reference 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. 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 Available in iOS 4.0 and later. Declared in MKShape.h title The title of the shape annotation. MKShape Class Reference Tasks 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 4.0 and later. Related Sample Code KMLViewer Declared in MKShape.h MKShape Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 230 Inherits from NSObject Conforms to MKOverlay NSObject (NSObject) Framework /System/Library/Frameworks/MapKit.framework Availability Available in iOS 7.0 and later. Declared in MKTileOverlay.h Companion guide Location and Maps Programming Guide 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. 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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. MKTileOverlay Class Reference Tasks 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 7.0 and later. 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 Available in iOS 7.0 and later. Declared in MKTileOverlay.h maximumZ The maximum zoom level supported by the tiles of this overlay object. MKTileOverlay Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 overlay’s 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 Available in iOS 7.0 and later. 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 overlay’s 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. The default value of this property is 0. Availability Available in iOS 7.0 and later. See Also @property maximumZ (page 233) Declared in MKTileOverlay.h MKTileOverlay Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 7.0 and later. 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 Available in iOS 7.0 and later. See Also – initWithURLTemplate: (page 235) Declared in MKTileOverlay.h Instance Methods initWithURLTemplate: Initializes and returns a tile overlay object using the specified tile-access template. MKTileOverlay Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 template’s placeholders before requesting the actual tile. Availability Available in iOS 7.0 and later. 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 tile’s X-Y coordinate at a given zoom level and scale factor. MKTileOverlay Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 236 result The completion block to call when the tile data is available. This block is executed on your app’s 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 Available in iOS 7.0 and later. 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 tile’s 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. MKTileOverlay Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 237 Availability Available in iOS 7.0 and later. See Also – initWithURLTemplate: (page 235) @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 Available in iOS 7.0 and later. Declared in MKTileOverlay.h MKTileOverlay Class Reference Constants 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 238 Inherits from MKOverlayRenderer : NSObject Conforms to NSObject (NSObject) Framework /System/Library/Frameworks/MapKit.framework Availability Available in iOS 7.0 and later. Declared in MKTileOverlayRenderer.h Companion guide Location and Maps Programming Guide 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. 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 7.0 and later. Declared in MKTileOverlayRenderer.h reloadData Forces tiles to be reloaded and displayed. - (void)reloadData Discussion Use this method to remove the overlay’s 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 Available in iOS 7.0 and later. Declared in MKTileOverlayRenderer.h MKTileOverlayRenderer Class Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 240 Inherits from NSObject Conforms to MKAnnotation NSObject (NSObject) Framework /System/Library/Frameworks/MapKit.framework Availability Available in iOS 3.0 and later. Declared in MKUserLocation.h Companion guide Location and Maps Programming Guide Related sample code CurrentAddress MapCallouts Overview The MKUserLocation class defines a specific type of annotation that identifies the user’s 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. 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 241 MKUserLocation Class Reference 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. Tasks Determining the User’s Position location (page 243) property The current location of the device. (read-only) updating (page 244) property A Boolean value indicating whether the user’s location is currently being updated. (read-only) heading (page 242) property The heading of the user location. (read-only) Accessing the User Annotation Text title (page 243) property The title to display for the user location annotation. subtitle (page 243) property 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. MKUserLocation Class Reference Tasks 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 242 Availability Available in iOS 5.0 and later. 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 user’s location has not yet been determined. Availability Available in iOS 3.0 and later. Declared in MKUserLocation.h subtitle The subtitle to display for the user location annotation. @property(nonatomic, copy) NSString *subtitle Availability Available in iOS 3.0 and later. Declared in MKUserLocation.h title The title to display for the user location annotation. @property(nonatomic, copy) NSString *title Availability Available in iOS 3.0 and later. MKUserLocation Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 243 Declared in MKUserLocation.h updating A Boolean value indicating whether the user’s location is currently being updated. (read-only) @property(readonly, nonatomic, getter=isUpdating) BOOL updating Availability Available in iOS 3.0 and later. Declared in MKUserLocation.h MKUserLocation Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 244 Inherits from UIBarButtonItem : UIBarItem : NSObject Conforms to NSCoding (UIBarButtonItem) UIAppearance (UIBarItem) NSObject (NSObject) Framework /System/Library/Frameworks/MapKit.framework Availability Available in iOS 5.0 and later. Declared in MKUserTrackingBarButtonItem.h Companion guide Location and Maps Programming Guide 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. 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. Tasks Initializing the Bar Button Item – initWithMapView: (page 246) Initializes a newly created bar button item with the specified map view. 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 5.0 and later. Declared in MKUserTrackingBarButtonItem.h 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 Available in iOS 5.0 and later. Declared in MKUserTrackingBarButtonItem.h MKUserTrackingBarButtonItem Class Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 246 Framework /System/Library/Frameworks/MapKit.framework Availability Available in iOS 6.0 and later. Declared in MKGeometry.h Companion guide Location and Maps Programming Guide Overview This category adds methods to the Foundation framework’s 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. 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 6.0 and later. Related Sample Code Using NSXMLParser to parse XML documents 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 Available in iOS 6.0 and later. Related Sample Code Using NSXMLParser to parse XML documents NSValue MapKit Additions Reference Class Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 receiver’s value. Availability Available in iOS 6.0 and later. Declared in MKGeometry.h MKCoordinateValue Returns a coordinate structure representing the data in the receiver. - (CLLocationCoordinate2D)MKCoordinateValue Return Value A coordinate structure containing the receiver’s value. Availability Available in iOS 6.0 and later. Declared in MKGeometry.h NSValue MapKit Additions Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 249 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 250 Protocols Conforms to NSObject Framework /System/Library/Frameworks/MapKit.framework Availability Available in iOS 3.0 and later. Declared in MKAnnotation.h Companion guide Location and Maps Programming Guide 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 annotation’s location on the map. Annotation objects do not provide the visual representation of the annotation but typically coordinate (in conjunction with the map view’s 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. 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 251 MKAnnotation Protocol Reference 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. Tasks Position Attributes coordinate (page 252) property 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 title (page 253) property The string containing the annotation’s title. subtitle (page 253) property The string containing the annotation’s subtitle. Properties coordinate The center point (specified as a map coordinate) of the annotation. (required) (read-only) @property (nonatomic, readonly) CLLocationCoordinate2D coordinate 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 Available in iOS 3.0 and later. MKAnnotation Protocol Reference Tasks 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 252 Related Sample Code CurrentAddress MapCallouts MapSearch PhotosByLocation Declared in MKAnnotation.h subtitle The string containing the annotation’s subtitle. @property (nonatomic, readonly, copy) NSString *subtitle Discussion This string is displayed in the callout for the associated annotation view. Availability Available in iOS 5.0 and later. Related Sample Code MapCallouts Declared in MKAnnotation.h title The string containing the annotation’s 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 Available in iOS 5.0 and later. Related Sample Code MapCallouts PhotosByLocation MKAnnotation Protocol Reference Properties 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 4.0 and later. Declared in MKAnnotation.h MKAnnotation Protocol Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 254 Conforms to NSObject Framework /System/Library/Frameworks/MapKit.framework Availability Available in iOS 3.0 and later. Declared in MapKit/MKMapView.h Companion guide Location and Maps Programming Guide 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 object’s delegate (page 108) property to nil. 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 255 MKMapViewDelegate Protocol Reference 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. 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 user’s position. – mapViewDidStopLocatingUser: (page 269) Tells the delegate that the map view stopped tracking the user’s location. MKMapViewDelegate Protocol Reference Tasks 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 256 – mapView:didUpdateUserLocation: (page 263) Tells the delegate that the location of the user was updated. – mapView:didFailToLocateUserWithError: (page 262) Tells the delegate that an attempt to locate the user’s 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 view’s 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. MKMapViewDelegate Protocol Reference Tasks 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 view’s accessory buttons. - (void)mapView:(MKMapView *)mapView annotationView:(MKAnnotationView *)view calloutAccessoryControlTapped:(UIControl *)control Parameters mapView The map view containing the specified annotation view. view The annotation view whose button was tapped. control The control that was tapped. Discussion Accessory views contain 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 Available in iOS 3.0 and later. Declared in MKMapView.h MKMapViewDelegate Protocol Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 4.0 and later. Declared in MKMapView.h mapView:didAddAnnotationViews: Tells the delegate that one or more annotation views were added to the map. - (void)mapView:(MKMapView *)mapView didAddAnnotationViews:(NSArray *)views Parameters mapView The map view that added the annotation views. views An array of MKAnnotationView objects representing the views that were added. Discussion By the time this method is called, the specified views are already added to the map. MKMapViewDelegate Protocol Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 259 Availability Available in iOS 3.0 and later. Declared in MKMapView.h mapView:didAddOverlayRenderers: Tells the delegate that one or more renderer objects were added to the map. - (void)mapView:(MKMapView *)mapView didAddOverlayRenderers:(NSArray *)renderers Parameters mapView The map view that added the renderer objects. renderers The renderer objects that were added. Discussion The map 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 Available in iOS 7.0 and later. 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. MKMapViewDelegate Protocol Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 260 Discussion By the time this method is called, the specified views are already added to the map. Availability Available in iOS 4.0 and later. Deprecated in iOS 7.0. Declared in MKMapView.h mapView:didChangeUserTrackingMode:animated: Tells the delegate that the user tracking mode changed. - (void)mapView:(MKMapView *)mapView didChangeUserTrackingMode:(MKUserTrackingMode)mode animated:(BOOL)animated Parameters mapView The map view whose user tracking mode changed. mode The mode used to track the user’s location. animated If YES, the change 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 Available in iOS 5.0 and later. See Also setUserTrackingMode:animated: (page 136) – mapView:didUpdateUserLocation: (page 263) Declared in MKMapView.h mapView:didDeselectAnnotationView: Tells the delegate that one of its annotation views was deselected. MKMapViewDelegate Protocol Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 261 - (void)mapView:(MKMapView *)mapView didDeselectAnnotationView:(MKAnnotationView *)view Parameters mapView The map view containing the annotation view. view The annotation view that was deselected. Discussion You can use this method to track changes in the selection state of annotation views. Availability Available in iOS 4.0 and later. Declared in MKMapView.h mapView:didFailToLocateUserWithError: Tells the delegate that an attempt to locate the user’s position failed. - (void)mapView:(MKMapView *)mapView didFailToLocateUserWithError:(NSError *)error Parameters mapView The map view that is tracking the user’s location. error An error object containing the reason why location tracking failed. Availability Available in iOS 4.0 and later. Declared in MKMapView.h mapView:didSelectAnnotationView: Tells the delegate that one of its annotation views was selected. - (void)mapView:(MKMapView *)mapView didSelectAnnotationView:(MKAnnotationView *)view MKMapViewDelegate Protocol Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 262 Parameters mapView The map view containing the annotation view. view The annotation view that was selected. Discussion You can use this method to track changes in the selection state of annotation views. Availability Available in iOS 4.0 and later. Declared in MKMapView.h mapView:didUpdateUserLocation: Tells the delegate that the location of the user was updated. - (void)mapView:(MKMapView *)mapView didUpdateUserLocation:(MKUserLocation *)userLocation Parameters mapView The map view that is tracking the user’s location. userLocation The location object representing the user’s latest location. This property may be nil. Discussion While the showsUserLocation (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 view’s 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 Available in iOS 4.0 and later. Declared in MKMapView.h MKMapViewDelegate Protocol Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 3.0 and later. Declared in MKMapView.h mapView:regionWillChangeAnimated: Tells the delegate that the region displayed by the map view is about to change. - (void)mapView:(MKMapView *)mapView regionWillChangeAnimated:(BOOL)animated Parameters mapView The map view whose visible region is about to change. animated If YES, the change to the new region will be animated. If NO, the change will be made immediately. Discussion This method is called whenever the currently displayed map region changes. During scrolling, this method may be called many times to report updates to the map position. Therefore, your implementation of this method should be as lightweight as possible to avoid affecting scrolling performance. Availability Available in iOS 3.0 and later. MKMapViewDelegate Protocol Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 7.0 and later. Declared in MKMapView.h mapView:viewForAnnotation: Returns the view associated with the specified annotation object. - (MKAnnotationView *)mapView:(MKMapView *)mapView viewForAnnotation:(id < MKAnnotation >)annotation Parameters mapView The map view that requested the annotation view. MKMapViewDelegate Protocol Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 user’s 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 user’s location. To display the user’s location using the default system view, return nil. If you do not implement this method, or if you return nil from your implementation for annotations other than the user location annotation, the map view uses a standard pin annotation view. Availability Available in iOS 3.0 and later. Declared in MKMapView.h 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. MKMapViewDelegate Protocol Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 4.0 and later. Deprecated in iOS 7.0. Declared in MKMapView.h mapViewDidFailLoadingMap:withError: Tells the delegate that the specified view was unable to load the map data. - (void)mapViewDidFailLoadingMap:(MKMapView *)mapView withError:(NSError *)error Parameters mapView The map view that started the load operation. error The reason that the map data could not be loaded. Discussion This method might be called in situations where the device does not have access to the network or is unable to load the map data for some reason. It may also be called if a request for additional map tiles comes in while a previous request for tiles is still pending. You can use this message to notify the user that the map data is unavailable. Availability Available in iOS 3.0 and later. Declared in MKMapView.h mapViewDidFinishLoadingMap: Tells the delegate that the specified map view successfully loaded the needed map data. MKMapViewDelegate Protocol Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 3.0 and later. Declared in MKMapView.h mapViewDidFinishRenderingMap:fullyRendered: Tells the delegate that the map view has finished rendering all visible tiles. - (void)mapViewDidFinishRenderingMap:(MKMapView *)mapView fullyRendered:(BOOL)fullyRendered Parameters mapView The map view that was rendering its tiles. fullyRendered This parameter is set to YES if the map 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 Available in iOS 7.0 and later. MKMapViewDelegate Protocol Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 268 See Also – mapViewWillStartRenderingMap: (page 270) Declared in MKMapView.h mapViewDidStopLocatingUser: Tells the delegate that the map view stopped tracking the user’s location. - (void)mapViewDidStopLocatingUser:(MKMapView *)mapView Parameters mapView The map view that stopped tracking the user’s location. Discussion This method is called when the value of the showsUserLocation (page 112) property changes to NO. Availability Available in iOS 4.0 and later. Declared in MKMapView.h mapViewWillStartLoadingMap: Tells the delegate that the specified map view is about to retrieve some map data. - (void)mapViewWillStartLoadingMap:(MKMapView *)mapView Parameters mapView The map view that began loading the data. Discussion This method is called whenever a 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 Available in iOS 3.0 and later. MKMapViewDelegate Protocol Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 269 Declared in MKMapView.h mapViewWillStartLocatingUser: Tells the delegate that the map view will start tracking the user’s position. - (void)mapViewWillStartLocatingUser:(MKMapView *)mapView Parameters mapView The map view that is tracking the user’s location. Discussion This method is called when the value of the showsUserLocation (page 112) property changes to YES. Availability Available in iOS 4.0 and later. Declared in MKMapView.h mapViewWillStartRenderingMap: Tells the delegate that the map view is about to start rendering some of its tiles. - (void)mapViewWillStartRenderingMap:(MKMapView *)mapView Parameters mapView The map view that is about to start rendering. Discussion The map view calls this method when one or more tiles are revealed and require rendering. Availability Available in iOS 7.0 and later. See Also – mapViewDidFinishRenderingMap:fullyRendered: (page 268) Declared in MKMapView.h MKMapViewDelegate Protocol Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 270 Conforms to MKAnnotation Framework /System/Library/Frameworks/MapKit.framework Availability Available in iOS 4.0 and later. Declared in MKOverlay.h Companion guide Location and Maps Programming Guide 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 overlay’s 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. 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 271 MKOverlay Protocol Reference 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. Tasks Describing the Overlay Geometry coordinate (page 273) property 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 receiver’s 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) MKOverlay Protocol Reference Tasks 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 coordinates—that is, coordinates obtained by projecting the globe onto a two-dimensional surface. Availability Available in iOS 4.0 and later. Declared in MKOverlay.h coordinate The approximate center point of the overlay area. (required) (read-only) @property (nonatomic, readonly) CLLocationCoordinate2D coordinate Discussion This point is typically set to the center point of the map’s bounding rectangle. It is used as the anchor point for any callouts displayed for the annotation. Availability Available in iOS 4.0 and later. 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 MKOverlay Protocol Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 7.0 and later. Declared in MKOverlay.h intersectsMapRect: Returns a Boolean indicating whether the specified rectangle intersects the receiver’s shape. - (BOOL)intersectsMapRect:(MKMapRect)mapRect Parameters mapRect The rectangle to intersect with the receiver’s area. Return Value YES if any part of the map rectangle intersects the receiver’s 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 Available in iOS 4.0 and later. Declared in MKOverlay.h MKOverlay Protocol Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 274 Conforms to NSObject Framework /System/Library/Frameworks/MapKit.framework Availability Available in iOS 3.0 and later. Deprecated in iOS 5.0. Declared in MKReverseGeocoder.h Companion guide Location and Maps Programming Guide 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. 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. 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 . 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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) (Deprecated in iOS 5.0. Use the CLGeocoder class instead.) - (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 Available in iOS 3.0 and later. Deprecated in iOS 5.0. Declared in MKReverseGeocoder.h MKReverseGeocoderDelegate Protocol Reference Tasks 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 276 reverseGeocoder:didFindPlacemark: Tells thedelegatethat areversegeocoder successfullyobtainedplacemarkinformationfor its coordinate. (required) (Deprecated in iOS 5.0. Use the CLGeocoder class instead.) - (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 Available in iOS 3.0 and later. Deprecated in iOS 5.0. Declared in MKReverseGeocoder.h MKReverseGeocoderDelegate Protocol Reference Instance Methods 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 277 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 278 Functions Framework MapKit/MapKit.h Declared in MKTypes.h Companion guide Location and Maps Programming Guide 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. 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. 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. 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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. Map Kit Functions Reference Functions by Task 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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. Map Kit Functions Reference Functions by Task 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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. Map Kit Functions Reference Functions 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 4.0 and later. 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 Available in iOS 4.0 and later. Declared in MKGeometry.h Map Kit Functions Reference Functions 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 3.0 and later. 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. Map Kit Functions Reference Functions 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 3.0 and later. 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. Map Kit Functions Reference Functions 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 285 Availability Available in iOS 3.0 and later. 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 Available in iOS 4.0 and later. 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. Map Kit Functions Reference Functions 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 286 Return Value The map point value that corresponds to the specified coordinate on a two-dimensional map projection. Availability Available in iOS 4.0 and later. 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 Available in iOS 4.0 and later. Declared in MKGeometry.h MKMapPointsPerMeterAtLatitude Returns the number of map points that represent one meter at the given latitude. Map Kit Functions Reference Functions 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 4.0 and later. 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. Map Kit Functions Reference Functions 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 288 Availability Available in iOS 4.0 and later. 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 Available in iOS 4.0 and later. 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 ); Map Kit Functions Reference Functions 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 4.0 and later. 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. Map Kit Functions Reference Functions 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 290 Availability Available in iOS 4.0 and later. 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 rectangle’s height. Availability Available in iOS 4.0 and later. Declared in MKGeometry.h MKMapRectGetMaxX Returns the maximum x-axis value of the specified rectangle. double MKMapRectGetMaxX( MKMapRect rect ); Parameters rect The map rectangle to test. Return Value The maximum x-axis value. Map Kit Functions Reference Functions 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 291 Availability Available in iOS 4.0 and later. Declared in MKGeometry.h MKMapRectGetMaxY Returns the maximum y-axis value of the specified rectangle. double MKMapRectGetMaxY( MKMapRect rect ); Parameters rect The map rectangle to test. Return Value The maximum y-axis value. Availability Available in iOS 4.0 and later. Declared in MKGeometry.h MKMapRectGetMidX Returns the mid-point along the x-axis of the specified rectangle. double MKMapRectGetMidX( MKMapRect rect ); Parameters rect The map rectangle to test. Return Value The midpoint value along the x-axis. Map Kit Functions Reference Functions 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 292 Availability Available in iOS 4.0 and later. 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 The map rectangle to test. Return Value The midpoint value along the y-axis. Availability Available in iOS 4.0 and later. Related Sample Code PhotosByLocation Declared in MKGeometry.h MKMapRectGetMinX Returns the minimum x-axis value of the specified rectangle. double MKMapRectGetMinX( MKMapRect rect ); Map Kit Functions Reference Functions 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 293 Parameters rect The map rectangle to test. Return Value The minimum x-axis value. Availability Available in iOS 4.0 and later. Declared in MKGeometry.h MKMapRectGetMinY Returns the minimum y-axis value of the specified rectangle. double MKMapRectGetMinY( MKMapRect rect ); Parameters rect The map rectangle to test. Return Value The minimum y-axis value. Availability Available in iOS 4.0 and later. Declared in MKGeometry.h MKMapRectGetWidth Returns the width of the map rectangle. double MKMapRectGetWidth( MKMapRect rect ); Map Kit Functions Reference Functions 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 294 Parameters rect The map rectangle to test. Return Value The rectangle’s width. Availability Available in iOS 4.0 and later. 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 Available in iOS 4.0 and later. Related Sample Code Breadcrumb PhotosByLocation Declared in MKGeometry.h Map Kit Functions Reference Functions 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 4.0 and later. 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. Map Kit Functions Reference Functions 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 4.0 and later. 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 Available in iOS 4.0 and later. Declared in MKGeometry.h Map Kit Functions Reference Functions 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 297 MKMapRectIsNull Returns a Boolean indicating whether the specified rectangle is null. BOOL MKMapRectIsNull( MKMapRect rect ); Parameters rect The rectangle to test. 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 Available in iOS 4.0 and later. 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. Map Kit Functions Reference Functions 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 4.0 and later. 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. Map Kit Functions Reference Functions 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 299 Availability Available in iOS 4.0 and later. 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 Available in iOS 4.0 and later. 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 The rectangle to test. Map Kit Functions Reference Functions 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 300 Return Value YES if the rectangle spans the 180th meridian or NO if it is contained wholly within the world map. Availability Available in iOS 4.0 and later. 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 Available in iOS 4.0 and later. Related Sample Code KMLViewer PhotosByLocation Declared in MKGeometry.h Map Kit Functions Reference Functions 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 4.0 and later. 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. Map Kit Functions Reference Functions 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 302 Availability Available in iOS 4.0 and later. 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 Available in iOS 4.0 and later. Related Sample Code Breadcrumb PhotosByLocation Declared in MKGeometry.h MKMetersPerMapPointAtLatitude Returns the distance spanned by one map point at the specified latitude. Map Kit Functions Reference Functions 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 4.0 and later. 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 Available in iOS 4.0 and later. Related Sample Code Breadcrumb Map Kit Functions Reference Functions 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 4.0 and later. 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. Map Kit Functions Reference Functions 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 305 Availability Available in iOS 4.0 and later. 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 Available in iOS 4.0 and later. Declared in MKGeometry.h Map Kit Functions Reference Functions 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 306 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 307 Data Types Framework MapKit/MapKit.h Companion guide Location and Maps Programming Guide 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. 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 3.0 and later. 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 Available in iOS 3.0 and later. Declared in MKGeometry.h MKMapPoint A point on a two-dimensional map projection. typedef struct { double x; double y; } MKMapPoint; Map Kit Data Types Reference Data Types 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Available in iOS 4.0 and later. 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. Map Kit Data Types Reference Data Types 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 310 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 MKMapSize data structure represents a horizontal and vertical distance as measured on this two-dimensional map. Availability Available in iOS 4.0 and later. 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 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 MKMapRect data structure represents a rectangular area as seen on this two-dimensional map. Availability Available in iOS 4.0 and later. Declared in MKGeometry.h Map Kit Data Types Reference Data Types 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 311 MKZoomScale A scale factor being used in conjunction with a map. typedef CGFloat MKZoomScale; Availability Available in iOS 4.0 and later. Declared in MKGeometry.h Map Kit Data Types Reference Data Types 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 312 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 313 Constants Framework MapKit/MapKit.h Companion guide Location and Maps Programming Guide 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. Available in iOS 4.0 and later. Declared in MKGeometry.h. World Map Constants Map constants for the two-dimensional map projection. const MKMapSize MKMapSizeWorld; const MKMapRect MKMapRectWorld; 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 314 Map Kit Constants Reference Constants MKMapSizeWorld Specifies the width and height (in map points) of the world in the two-dimensional map projection. Available in iOS 4.0 and later. Declared in MKGeometry.h. MKMapRectWorld The map rectangle that represents the world in the two-dimensional map projection. Available in iOS 4.0 and later. Declared in MKGeometry.h. Error Domain The error domain for Map Kit. NSString *MKErrorDomain Constants MKErrorDomain The Map Kit error domain. Available in iOS 3.0 and later. Declared in MKTypes.h. MKErrorCode Error constants for the Map Kit framework. enum MKErrorCode { MKErrorUnknown = 1, MKErrorServerFailure, MKErrorLoadingThrottled, MKErrorPlacemarkNotFound, MKErrorDirectionsNotFound }; Constants MKErrorUnknown An unknown error occurred. Available in iOS 3.0 and later. Declared in MKTypes.h. Map Kit Constants Reference Constants 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 315 MKErrorServerFailure The map server was unable to return the desired information. Available in iOS 3.0 and later. Declared in MKTypes.h. 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. Available in iOS 3.0 and later. Declared in MKTypes.h. MKErrorPlacemarkNotFound The specified placemark could not be found. Available in iOS 3.0 and later. Declared in MKTypes.h. MKErrorDirectionsNotFound The specified directions could not be found. Available in iOS 7.0 and later. Declared in MKTypes.h. Map Kit Constants Reference Constants 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 2013-09-18 | Copyright © 2013 Apple Inc. All Rights Reserved. 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 Apple’s 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.