RMMapViewDelegate Protocol Reference
| Conforms to | NSObject |
| Declared in | RMMapViewDelegate.h |
Overview
The RMMapViewDelegate protocol defines a set of optional methods that you can use to receive map-related update messages. Because many map operations require the RMMapView class to load data asynchronously, the map view calls these methods to notify your application when specific operations complete. The map view also uses these methods to request annotation layers and to manage interactions with those layers.
Tasks
Working With Annotation Layers
-
– mapView:layerForAnnotation: -
– annotationSortingComparatorForMapView: -
– mapView:willHideLayerForAnnotation: -
– mapView:didHideLayerForAnnotation: -
– mapView:didSelectAnnotation: -
– mapView:didDeselectAnnotation:
Responding to Map Position Changes
-
– beforeMapMove:byUser: -
– afterMapMove:byUser: -
– beforeMapZoom:byUser: -
– afterMapZoom:byUser: -
– mapViewRegionDidChange:
Responding to Map Gestures
Responding to User Annotation Gestures
-
– tapOnAnnotation:onMap: -
– doubleTapOnAnnotation:onMap: -
– longPressOnAnnotation:onMap: -
– tapOnLabelForAnnotation:onMap: -
– doubleTapOnLabelForAnnotation:onMap: -
– tapOnCalloutAccessoryControl:forAnnotation:onMap: -
– mapView:shouldDragAnnotation: -
– mapView:annotation:didChangeDragState:fromOldState:
Tracking the User Location
Instance Methods
afterMapMove:byUser:
Tells the delegate when a map has finished moving.
- (void)afterMapMove:(RMMapView *)map byUser:(BOOL)wasUserActionParameters
- map
The map view that has finished moving.
- wasUserAction
A Boolean indicating whether the map move was in response to a user action or not.
Discussion
Tells the delegate when a map has finished moving.
Declared In
RMMapViewDelegate.hafterMapZoom:byUser:
Tells the delegate when a map has finished zooming.
- (void)afterMapZoom:(RMMapView *)map byUser:(BOOL)wasUserActionParameters
- map
The map view that has finished zooming.
- wasUserAction
A Boolean indicating whether the map zoom was in response to a user action or not.
Discussion
Tells the delegate when a map has finished zooming.
Declared In
RMMapViewDelegate.hannotationSortingComparatorForMapView:
Returns a block used for determining the display sort order of annotation layers. The block will be called repeatedly during map change events to ensure annotation layers stay sorted in the desired order.
- (NSComparator)annotationSortingComparatorForMapView:(RMMapView *)mapViewParameters
- mapView
The map view whose annotations need sorting.
Return Value
A comparison block to use in order to sort the annotations.
Discussion
Returns a block used for determining the display sort order of annotation layers. The block will be called repeatedly during map change events to ensure annotation layers stay sorted in the desired order.
If you do not implement this method, a default sort order will be used as follows:
User location annotations are below all others. These can be distinguished by
annotation.isUserLocationAnnotation = YES.Amongst user location annotations, the accuracy circle is below the tracking halo, which is below the user location. These can be distinguished by
annotation.annotationType = kRMTrackingHaloAnnotationTypeName,annotation.annotationType = kRMAccuracyCircleAnnotationTypeName, and checking annotation object type against RMUserLocation.Cluster annotations are above non-cluster annotations. These can be distinguished by
annotation.isClusterAnnotation = YES.Markers are above shapes. These can be distinguished by checking annotation object type against RMMarker.
The remaining annotations are sorted with those closer to the bottom of the view above those closer to the top of the view. This includes during user tracking mode map rotation events, when markers always remain upright and their relative layer positions change.
In all cases, any currently selected annotation (and its callout, if visible) are shown above all other annotations. When deselected, the desired sort order is reapplied.
Your implementation of this method should be as lightweight as possible to avoid affecting map renderering performance.
See Also
Declared In
RMMapViewDelegate.hbeforeMapMove:byUser:
Tells the delegate when a map is about to move.
- (void)beforeMapMove:(RMMapView *)map byUser:(BOOL)wasUserActionParameters
- map
The map view that is about to move.
- wasUserAction
A Boolean indicating whether the map move is in response to a user action or not.
Discussion
Tells the delegate when a map is about to move.
Declared In
RMMapViewDelegate.hbeforeMapZoom:byUser:
Tells the delegate when a map is about to zoom.
- (void)beforeMapZoom:(RMMapView *)map byUser:(BOOL)wasUserActionParameters
- map
The map view that is about to zoom.
- wasUserAction
A Boolean indicating whether the map zoom is in response to a user action or not.
Discussion
Tells the delegate when a map is about to zoom.
Declared In
RMMapViewDelegate.hdoubleTapOnAnnotation:onMap:
Tells the delegate when the user double-taps the layer for an annotation.
- (void)doubleTapOnAnnotation:(RMAnnotation *)annotation onMap:(RMMapView *)mapParameters
- annotation
The annotation that was double-tapped.
- map
The map view.
Discussion
Tells the delegate when the user double-taps the layer for an annotation.
Declared In
RMMapViewDelegate.hdoubleTapOnLabelForAnnotation:onMap:
Tells the delegate when the user double-taps the label for an annotation.
- (void)doubleTapOnLabelForAnnotation:(RMAnnotation *)annotation onMap:(RMMapView *)mapParameters
- annotation
The annotation whose label was was double-tapped.
- map
The map view.
Discussion
Tells the delegate when the user double-taps the label for an annotation.
Declared In
RMMapViewDelegate.hdoubleTapOnMap:at:
Tells the delegate when the user double-taps a map view.
- (void)doubleTapOnMap:(RMMapView *)map at:(CGPoint)pointParameters
- map
The map that was double-tapped.
- point
The point at which the map was double-tapped.
Discussion
Tells the delegate when the user double-taps a map view.
Declared In
RMMapViewDelegate.hlongPressOnAnnotation:onMap:
Tells the delegate when the user long-presses the layer for an annotation.
- (void)longPressOnAnnotation:(RMAnnotation *)annotation onMap:(RMMapView *)mapParameters
- annotation
The annotation that was long-pressed.
- map
The map view.
Discussion
Tells the delegate when the user long-presses the layer for an annotation.
Declared In
RMMapViewDelegate.hlongPressOnMap:at:
Tells the delegate when the user long-presses a map view.
- (void)longPressOnMap:(RMMapView *)map at:(CGPoint)pointParameters
- map
The map that was long-pressed.
- point
The point at which the map was long-pressed.
Discussion
Tells the delegate when the user long-presses a map view.
Declared In
RMMapViewDelegate.hmapView:annotation:didChangeDragState:fromOldState:
Tells the delegate that the drag state of one of its annotations changed.
- (void)mapView:(RMMapView *)mapView annotation:(RMAnnotation *)annotation didChangeDragState:(RMMapLayerDragState)newState fromOldState:(RMMapLayerDragState)oldStateParameters
- mapView
The map view containing the annotation layer.
- annotation
The annotation whose drag state changed.
- newState
The new drag state of the annotation layer.
- oldState
The previous drag state of the annotation layer.
Discussion
Tells the delegate that the drag state of one of its annotations changed.
The drag state typically changes in response to user interactions with the annotation layer. However, the annotation layer itself is responsible for changing that state as well.
Declared In
RMMapViewDelegate.hmapView:didChangeUserTrackingMode:animated:
Tells the delegate that the user tracking mode changed.
- (void)mapView:(RMMapView *)mapView didChangeUserTrackingMode:(RMUserTrackingMode)mode animated:(BOOL)animatedParameters
- mapView
The map view whose user tracking mode changed.
- mode
The mode used to track the user’s location.
- animated
If YES, the change from the current mode to the new mode is animated; otherwise, it is not. This parameter affects only tracking mode changes. Changes to the user location or heading are always animated.
Discussion
Tells the delegate that the user tracking mode changed.
Declared In
RMMapViewDelegate.hmapView:didDeselectAnnotation:
Tells the delegate that one of its annotations was deselected.
- (void)mapView:(RMMapView *)mapView didDeselectAnnotation:(RMAnnotation *)annotationParameters
- mapView
The map view containing the annotation.
- annotation
The annotation that was deselected.
Discussion
Tells the delegate that one of its annotations was deselected.
You can use this method to track changes in the selection state of annotations.
Declared In
RMMapViewDelegate.hmapView:didFailToLocateUserWithError:
Tells the delegate that an attempt to locate the user’s position failed.
- (void)mapView:(RMMapView *)mapView didFailToLocateUserWithError:(NSError *)errorParameters
- mapView
The map view that is tracking the user’s location.
- error
An error object containing the reason why location tracking failed.
Discussion
Tells the delegate that an attempt to locate the user’s position failed.
Declared In
RMMapViewDelegate.hmapView:didHideLayerForAnnotation:
Tells the delegate that the visible layer for an annotation has been hidden from view due to scrolling or zooming the map.
- (void)mapView:(RMMapView *)mapView didHideLayerForAnnotation:(RMAnnotation *)annotationParameters
- mapView
The map view whose annotation layer was hidden.
- annotation
The annotation whose layer was hidden.
Discussion
Tells the delegate that the visible layer for an annotation has been hidden from view due to scrolling or zooming the map.
Declared In
RMMapViewDelegate.hmapView:didSelectAnnotation:
Tells the delegate that one of its annotations was selected.
- (void)mapView:(RMMapView *)mapView didSelectAnnotation:(RMAnnotation *)annotationParameters
- mapView
The map view containing the annotation.
- annotation
The annotation that was selected.
Discussion
Tells the delegate that one of its annotations was selected.
You can use this method to track changes in the selection state of annotations.
Declared In
RMMapViewDelegate.hmapView:didUpdateUserLocation:
Tells the delegate that the location of the user was updated.
- (void)mapView:(RMMapView *)mapView didUpdateUserLocation:(RMUserLocation *)userLocationParameters
- mapView
The map view that is tracking the user’s location.
- userLocation
The location object representing the user’s latest location.
Discussion
Tells the delegate that the location of the user was updated.
While the showsUserLocation property is set to YES, this method is called whenever a new location update is received by the map view. This method is also called if the map view’s user tracking mode is set to RMUserTrackingModeFollowWithHeading 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.
Declared In
RMMapViewDelegate.hmapView:layerForAnnotation:
Returns (after creating or reusing) the layer associated with the specified annotation object.
- (RMMapLayer *)mapView:(RMMapView *)mapView layerForAnnotation:(RMAnnotation *)annotationParameters
- mapView
The map view that requested the annotation layer.
- annotation
The object representing the annotation that is about to be displayed. In addition to your custom annotations, this object could be an RMUserLocation object representing the user’s current location.
Return Value
The annotation layer to display for the specified annotation or nil if you do not want to display a layer.
Discussion
Returns (after creating or reusing) the layer associated with the specified annotation object.
An annotation layer can be created using RMMapLayer and its subclasses, such as RMMarker for points and RMShape for shapes such as lines and polygons.
If the object in the annotation parameter is an instance of the RMUserLocation class, you can provide a custom layer to denote the user’s location. To display the user’s location using the default system layer, 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 does not display a layer for the annotation.
Declared In
RMMapViewDelegate.hmapView:shouldDragAnnotation:
Asks the delegate whether the user should be allowed to drag the layer for an annotation.
- (BOOL)mapView:(RMMapView *)mapView shouldDragAnnotation:(RMAnnotation *)annotationParameters
- mapView
The map view.
- annotation
The annotation the user is attempting to drag.
Return Value
A Boolean value indicating whether the user should be allowed to drag the annotation’s layer.
Discussion
Asks the delegate whether the user should be allowed to drag the layer for an annotation.
Declared In
RMMapViewDelegate.hmapView:willHideLayerForAnnotation:
Tells the delegate that the visible layer for an annotation is about to be hidden from view due to scrolling or zooming the map.
- (void)mapView:(RMMapView *)mapView willHideLayerForAnnotation:(RMAnnotation *)annotationParameters
- mapView
The map view whose annotation alyer will be hidden.
- annotation
The annotation whose layer will be hidden.
Discussion
Tells the delegate that the visible layer for an annotation is about to be hidden from view due to scrolling or zooming the map.
Declared In
RMMapViewDelegate.hmapViewDidStopLocatingUser:
Tells the delegate that the map view stopped tracking the user’s location.
- (void)mapViewDidStopLocatingUser:(RMMapView *)mapViewParameters
- mapView
The map view that stopped tracking the user’s location.
Discussion
Tells the delegate that the map view stopped tracking the user’s location.
This method is called when the value of the showsUserLocation property changes to NO.
Declared In
RMMapViewDelegate.hmapViewRegionDidChange:
Tells the delegate that the region displayed by the map view just changed.
- (void)mapViewRegionDidChange:(RMMapView *)mapViewParameters
- mapView
The map view whose visible region changed.
Discussion
Tells the delegate that the region displayed by the map view just changed.
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.
Declared In
RMMapViewDelegate.hmapViewWillStartLocatingUser:
Tells the delegate that the map view will start tracking the user’s position.
- (void)mapViewWillStartLocatingUser:(RMMapView *)mapViewParameters
- mapView
The map view that is tracking the user’s location.
Discussion
Tells the delegate that the map view will start tracking the user’s position.
This method is called when the value of the showsUserLocation property changes to YES.
Declared In
RMMapViewDelegate.hsingleTapOnMap:at:
Tells the delegate when the user taps a map view.
- (void)singleTapOnMap:(RMMapView *)map at:(CGPoint)pointParameters
- map
The map that was tapped.
- point
The point at which the map was tapped.
Discussion
Tells the delegate when the user taps a map view.
Declared In
RMMapViewDelegate.hsingleTapTwoFingersOnMap:at:
Tells the delegate when the user taps a map view with two fingers.
- (void)singleTapTwoFingersOnMap:(RMMapView *)map at:(CGPoint)pointParameters
- map
The map that was tapped.
- point
The center point at which the map was tapped.
Discussion
Tells the delegate when the user taps a map view with two fingers.
Declared In
RMMapViewDelegate.htapOnAnnotation:onMap:
Tells the delegate when the user taps the layer for an annotation.
- (void)tapOnAnnotation:(RMAnnotation *)annotation onMap:(RMMapView *)mapParameters
- annotation
The annotation that was tapped.
- map
The map view.
Discussion
Tells the delegate when the user taps the layer for an annotation.
Declared In
RMMapViewDelegate.htapOnCalloutAccessoryControl:forAnnotation:onMap:
Tells the delegate that the user tapped one of the annotation layer’s accessory buttons.
- (void)tapOnCalloutAccessoryControl:(UIControl *)control forAnnotation:(RMAnnotation *)annotation onMap:(RMMapView *)mapParameters
- control
The control that was tapped.
- annotation
The annotation whose callout control was tapped.
- map
The map view containing the specified annotation.
Discussion
Tells the delegate that the user tapped one of the annotation layer’s accessory buttons.
Accessory views contain custom content and are positioned on either side of the annotation title text. If a view you specify is a descendant of the UIControl class, the map view calls this method as a convenience whenever the user taps your view. You can use this method to respond to taps and perform any actions associated with that control. For example, if your control displayed additional information about the annotation, you could use this method to present a modal panel with that information.
If your custom accessory views are not descendants of the UIControl class, the map view does not call this method.
Declared In
RMMapViewDelegate.htapOnLabelForAnnotation:onMap:
Tells the delegate when the user taps the label for an annotation.
- (void)tapOnLabelForAnnotation:(RMAnnotation *)annotation onMap:(RMMapView *)mapParameters
- annotation
The annotation whose label was was tapped.
- map
The map view.
Discussion
Tells the delegate when the user taps the label for an annotation.
Declared In
RMMapViewDelegate.h