MGLMapViewDelegate Protocol Reference
| Conforms to | NSObject |
| Declared in | MGLMapView.h |
Overview
The MGLMapViewDelegate protocol defines a set of optional methods that you can use to receive map-related update messages. Because many map operations require the MGLMapView 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 marker symbology and to manage interactions with those markers.
Tasks
Responding to Map Position Changes
Loading the Map
Tracking User Location
-
– mapViewWillStartLocatingUser: -
– mapViewDidStopLocatingUser: -
– mapView:didUpdateUserLocation: -
– mapView:didFailToLocateUserWithError: -
– mapView:didChangeUserTrackingMode:animated:
Managing the Display of Annotations
-
– mapView:imageForAnnotation: -
– mapView:alphaForShapeAnnotation: -
– mapView:strokeColorForShapeAnnotation: -
– mapView:fillColorForPolygonAnnotation: -
– mapView:lineWidthForPolylineAnnotation: -
– mapView:annotationCanShowCallout: -
– mapView:leftCalloutAccessoryViewForAnnotation: -
– mapView:rightCalloutAccessoryViewForAnnotation:
Managing Annotations
Selecting Annotations
Instance Methods
mapView:alphaForShapeAnnotation:
Returns the alpha value to use when rendering a shape annotation. Defaults to 1.0.
- (CGFloat)mapView:(MGLMapView *)mapView alphaForShapeAnnotation:(MGLShape *)annotationParameters
- mapView
The map view rendering the shape annotation.
- annotation
The annotation being rendered.
Return Value
An alpha value between 0 and 1.0.
Discussion
Returns the alpha value to use when rendering a shape annotation. Defaults to 1.0.
Declared In
MGLMapView.hmapView:annotation:calloutAccessoryControlTapped:
Tells the delegate that the user tapped one of the annotation’s accessory buttons.
- (void)mapView:(MGLMapView *)mapView annotation:(id<MGLAnnotation>)annotation calloutAccessoryControlTapped:(UIControl *)controlParameters
- mapView
The map view containing the specified annotation.
- annotation
The annotation whose button was tapped.
- control
The control that was tapped.
Discussion
Tells the delegate that the user tapped one of the annotation’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
MGLMapView.hmapView:annotationCanShowCallout:
Returns a Boolean value indicating whether the annotation is able to display extra information in a callout bubble.
- (BOOL)mapView:(MGLMapView *)mapView annotationCanShowCallout:(id<MGLAnnotation>)annotationParameters
- mapView
The map view that requested the annotation callout ability.
- annotation
The object representing the annotation.
Return Value
A Boolean indicating whether the annotation should show a callout.
Discussion
Returns a Boolean value indicating whether the annotation is able to display extra information in a callout bubble.
If the value returned is YES, a standard callout bubble is shown when the user taps a selected annotation. The callout uses the title and subtitle text from the associated annotation object. If there is no title text, though, the annotation will not show a callout. The callout also displays any custom callout views returned by the delegate for the left and right callout accessory views.
If the value returned is NO, the value of the title and subtitle strings are ignored.
Declared In
MGLMapView.hmapView:didChangeUserTrackingMode:animated:
Tells the delegate that the map view’s user tracking mode has changed.
- (void)mapView:(MGLMapView *)mapView didChangeUserTrackingMode:(MGLUserTrackingMode)mode animated:(BOOL)animatedParameters
- mapView
The map view that changed its tracking mode.
- mode
The new tracking mode.
- animated
Whether the change caused an animated effect on the map.
Discussion
Tells the delegate that the map view’s user tracking mode has changed.
This method is called after the map view asynchronously changes to reflect the new user tracking mode, for example by beginning to zoom or rotate.
Declared In
MGLMapView.hmapView:didDeselectAnnotation:
Tells the delegate that one of its annotations was deselected.
- (void)mapView:(MGLMapView *)mapView didDeselectAnnotation:(id<MGLAnnotation>)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
MGLMapView.hmapView:didFailToLocateUserWithError:
Tells the delegate that an attempt to locate the user’s position failed.
- (void)mapView:(MGLMapView *)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
MGLMapView.hmapView:didSelectAnnotation:
Tells the delegate that one of its annotations was selected.
- (void)mapView:(MGLMapView *)mapView didSelectAnnotation:(id<MGLAnnotation>)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
MGLMapView.hmapView:didUpdateUserLocation:
Tells the delegate that the location of the user was updated.
- (void)mapView:(MGLMapView *)mapView didUpdateUserLocation:(nullable MGLUserLocation *)userLocationParameters
- 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
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 MGLUserTrackingModeFollowWithHeading and the heading changes, or if it is set to MGLUserTrackingModeFollowWithCourse and the course 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
MGLMapView.hmapView:fillColorForPolygonAnnotation:
Returns the fill color to use when rendering a polygon annotation. Defaults to blue.
- (UIColor *)mapView:(MGLMapView *)mapView fillColorForPolygonAnnotation:(MGLPolygon *)annotationParameters
- mapView
The map view rendering the polygon annotation.
- annotation
The annotation being rendered.
Return Value
A color to use for the polygon interior.
Discussion
Returns the fill color to use when rendering a polygon annotation. Defaults to blue.
Declared In
MGLMapView.hmapView:imageForAnnotation:
Returns an image object to use for the marker for the specified point annotation object.
- (nullable MGLAnnotationImage *)mapView:(MGLMapView *)mapView imageForAnnotation:(id<MGLAnnotation>)annotationParameters
- mapView
The map view that requested the annotation image.
- annotation
The object representing the annotation that is about to be displayed.
Return Value
The image object to display for the specified annotation or nil if you want to display the default marker image.
Discussion
Returns an image object to use for the marker for the specified point annotation object.
Declared In
MGLMapView.hmapView:leftCalloutAccessoryViewForAnnotation:
Return the view to display on the left side of the standard callout bubble.
- (nullable UIView *)mapView:(MGLMapView *)mapView leftCalloutAccessoryViewForAnnotation:(id<MGLAnnotation>)annotationParameters
- mapView
The map view presenting the annotation callout.
- annotation
The object representing the annotation with the callout.
Return Value
The accessory view to display.
Discussion
Return the view to display on the left side of the standard callout bubble.
The default value is treated as if 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.
Declared In
MGLMapView.hmapView:lineWidthForPolylineAnnotation:
Returns the line width to use when rendering a polyline annotation. Defaults to 3.0.
- (CGFloat)mapView:(MGLMapView *)mapView lineWidthForPolylineAnnotation:(MGLPolyline *)annotationParameters
- mapView
The map view rendering the polygon annotation.
- annotation
The annotation being rendered.
Return Value
A line width for the polyline.
Discussion
Returns the line width to use when rendering a polyline annotation. Defaults to 3.0.
Declared In
MGLMapView.hmapView:regionDidChangeAnimated:
Tells the delegate that the region displayed by the map view just changed.
- (void)mapView:(MGLMapView *)mapView regionDidChangeAnimated:(BOOL)animatedParameters
- mapView
The map view whose visible region changed.
- animated
Whether the change caused an animated effect on the map.
Discussion
Tells the delegate that the region displayed by the map view just changed.
This method is called whenever the currently displayed map region has finished changing.
Declared In
MGLMapView.hmapView:regionWillChangeAnimated:
Tells the delegate that the region displayed by the map view is about to change.
- (void)mapView:(MGLMapView *)mapView regionWillChangeAnimated:(BOOL)animatedParameters
- mapView
The map view whose visible region will change.
- animated
Whether the change will cause an animated effect on the map.
Discussion
Tells the delegate that the region displayed by the map view is about to change.
This method is called whenever the currently displayed map region will start changing.
Declared In
MGLMapView.hmapView:rightCalloutAccessoryViewForAnnotation:
Return the view to display on the right side of the standard callout bubble.
- (nullable UIView *)mapView:(MGLMapView *)mapView rightCalloutAccessoryViewForAnnotation:(id<MGLAnnotation>)annotationParameters
- mapView
The map view presenting the annotation callout.
- annotation
The object representing the annotation with the callout.
Return Value
The accessory view to display.
Discussion
Return the view to display on the right side of the standard callout bubble.
The default value is treated is if nil. The right callout view is 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.
Declared In
MGLMapView.hmapView:strokeColorForShapeAnnotation:
Returns the stroke color to use when rendering a shape annotation. Defaults to black.
- (UIColor *)mapView:(MGLMapView *)mapView strokeColorForShapeAnnotation:(MGLShape *)annotationParameters
- mapView
The map view rendering the shape annotation.
- annotation
The annotation being rendered.
Return Value
A color to use for the shape outline.
Discussion
Returns the stroke color to use when rendering a shape annotation. Defaults to black.
Declared In
MGLMapView.hmapView:tapOnCalloutForAnnotation:
Tells the delegate that the user tapped on an annotation’s callout view.
- (void)mapView:(MGLMapView *)mapView tapOnCalloutForAnnotation:(id<MGLAnnotation>)annotationParameters
- mapView
The map view containing the specified annotation.
- annotation
The annotation whose callout was tapped.
Discussion
Tells the delegate that the user tapped on an annotation’s callout view.
Declared In
MGLMapView.hmapViewDidFinishLoadingMap:
Tells the delegate that the map view has finished loading.
- (void)mapViewDidFinishLoadingMap:(MGLMapView *)mapViewParameters
- mapView
The map view that has finished loading.
Discussion
Tells the delegate that the map view has finished loading.
This method is called whenever the map view finishes loading, either after the initial load or after a style change has forced a reload.
Declared In
MGLMapView.hmapViewDidStopLocatingUser:
Tells the delegate that the map view has stopped tracking the user’s location.
- (void)mapViewDidStopLocatingUser:(MGLMapView *)mapViewParameters
- mapView
The map view that is tracking the user’s location.
Discussion
Tells the delegate that the map view has stopped tracking the user’s location.
This method is called when the value of the showsUserLocation property changes to NO.
Declared In
MGLMapView.hmapViewRegionIsChanging:
Tells the delegate that the region displayed by the map view is changing.
- (void)mapViewRegionIsChanging:(MGLMapView *)mapViewParameters
- mapView
The map view whose visible region is changing.
Discussion
Tells the delegate that the region displayed by the map view is changing.
This method is called whenever the currently displayed map region changes. During movement, 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 performance.
Declared In
MGLMapView.hmapViewWillStartLoadingMap:
Tells the delegate that the map view will begin to load.
- (void)mapViewWillStartLoadingMap:(MGLMapView *)mapViewParameters
- mapView
The map view that is starting to load.
Discussion
Tells the delegate that the map view will begin to load.
This method is called whenever the map view starts loading, including when a new style has been set and the map must reload.
Declared In
MGLMapView.hmapViewWillStartLocatingUser:
Tells the delegate that the map view will begin tracking the user’s location.
- (void)mapViewWillStartLocatingUser:(MGLMapView *)mapViewParameters
- mapView
The map view that is tracking the user’s location.
Discussion
Tells the delegate that the map view will begin tracking the user’s location.
This method is called when the value of the showsUserLocation property changes to YES.
Declared In
MGLMapView.h