MGLMapViewDelegate

 
@protocol MGLMapViewDelegate <NSObject>

The MGLMapViewDelegate protocol defines a set of optional methods that you can use to receive messages from an MGLMapView instance. 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 information about annotations displayed on the map, such as the styles and interaction modes to apply to individual annotations.

Responding to Map Viewpoint Changes

  • Tells the delegate that the viewpoint depicted by the map view is about to change.

    This method is called whenever the currently displayed map camera will start changing for any reason.

    Declaration

    Objective-C

    - (void)mapView:(nonnull MGLMapView *)mapView
    cameraWillChangeAnimated:(BOOL)animated;

    Swift

    optional func mapView(_ mapView: MGLMapView, cameraWillChangeAnimated animated: Bool)

    Parameters

    mapView

    The map view whose viewpoint will change.
    animated

    Whether the change will cause an animated effect on the map.
    View Source on GitHub

  • Tells the delegate that the viewpoint depicted by the map view is changing.

    This method is called as the currently displayed map camera changes as part of an animation, whether due to a user gesture or due to a call to a method such as -[MGLMapView setCamera:animated:]. This method can be called before -mapViewDidFinishLoadingMap: is called.

    During the animation, this method may be called many times to report updates to the viewpoint. Therefore, your implementation of this method should be as lightweight as possible to avoid affecting performance.

    Declaration

    Objective-C

    - (void)mapViewCameraIsChanging:(nonnull MGLMapView *)mapView;

    Swift

    optional func mapViewCameraIsChanging(_ mapView: MGLMapView)

    Parameters

    mapView

    The map view whose viewpoint is changing.
    View Source on GitHub

  • Tells the delegate that the viewpoint depicted by the map view has finished changing.

    This method is called whenever the currently displayed map camera has finished changing, after any calls to -mapViewRegionIsChanging: due to animation. This method can be called before -mapViewDidFinishLoadingMap: is called.

    Declaration

    Objective-C

    - (void)mapView:(nonnull MGLMapView *)mapView
    cameraDidChangeAnimated:(BOOL)animated;

    Swift

    optional func mapView(_ mapView: MGLMapView, cameraDidChangeAnimated animated: Bool)

    Parameters

    mapView

    The map view whose viewpoint has changed.
    animated

    Whether the change caused an animated effect on the map.
    View Source on GitHub

  • Asks the delegate whether the map view should be allowed to change from the existing camera to the new camera in response to a user gesture.

    This method is called as soon as the user gesture is recognized. It is not called in response to a programmatic camera change, such as by setting the centerCoordinate property or calling -flyToCamera:completionHandler:.

    This method is called many times during gesturing, so you should avoid performing complex or performance-intensive tasks in your implementation.

    Declaration

    Objective-C

    - (BOOL)mapView:(nonnull MGLMapView *)mapView
    shouldChangeFromCamera:(nonnull MGLMapCamera *)oldCamera
                  toCamera:(nonnull MGLMapCamera *)newCamera;

    Swift

    optional func mapView(_ mapView: MGLMapView, shouldChangeFromCamera oldCamera: Any!, toCamera newCamera: Any!) -> Bool

    Parameters

    mapView

    The map view that the user is manipulating.
    oldCamera

    The camera representing the viewpoint at the moment the gesture is recognized. If this method returns NO, the map view’s camera continues to be this camera.
    newCamera

    The expected camera after the gesture completes. If this method returns YES, this camera becomes the map view’s camera.

    Return Value

    A Boolean value indicating whether the map view should stay at oldCamera or change to newCamera.

    View Source on GitHub

Loading the Map

  • 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.

    Declaration

    Objective-C

    - (void)mapViewWillStartLoadingMap:(nonnull MGLMapView *)mapView;

    Swift

    optional func mapViewWillStartLoadingMap(_ mapView: MGLMapView)

    Parameters

    mapView

    The map view that is starting to load.
    View Source on GitHub

  • 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.

    Declaration

    Objective-C

    - (void)mapViewDidFinishLoadingMap:(nonnull MGLMapView *)mapView;

    Swift

    optional func mapViewDidFinishLoadingMap(_ mapView: MGLMapView)

    Parameters

    mapView

    The map view that has finished loading.
    View Source on GitHub

  • Tells the delegate that the map view was unable to load data needed for displaying the map.

    This method may be called for a variety of reasons, including a network connection failure or a failure to fetch the style from the server. You can use the given error message to notify the user that map data is unavailable.

    Declaration

    Objective-C

    - (void)mapViewDidFailLoadingMap:(nonnull MGLMapView *)mapView
                       withError:(nonnull NSError *)error;

    Swift

    optional func mapViewDidFailLoadingMap(_ mapView: MGLMapView, withError error: Error)

    Parameters

    mapView

    The map view that is unable to load the data.
    error

    The reason the data could not be loaded.
    View Source on GitHub

  • Tells the delegate that the map view is about to redraw.

    This method is called any time the map view needs to redraw due to a change in the viewpoint or style property transition. This method may be called very frequently, even moreso than -mapViewRegionIsChanging:. Therefore, your implementation of this method should be as lightweight as possible to avoid affecting performance.

    Declaration

    Objective-C

    - (void)mapViewWillStartRenderingFrame:(nonnull MGLMapView *)mapView;

    Swift

    optional func mapViewWillStartRenderingFrame(_ mapView: MGLMapView)

    Parameters

    mapView

    The map view that is about to redraw.
    View Source on GitHub

  • Tells the delegate that the map view has just redrawn.

    This method is called any time the map view needs to redraw due to a change in the viewpoint or style property transition. This method may be called very frequently, even moreso than -mapViewRegionIsChanging:. Therefore, your implementation of this method should be as lightweight as possible to avoid affecting performance.

    Declaration

    Objective-C

    - (void)mapViewDidFinishRenderingFrame:(nonnull MGLMapView *)mapView
                         fullyRendered:(BOOL)fullyRendered;

    Swift

    optional func mapViewDidFinishRenderingFrame(_ mapView: MGLMapView, fullyRendered: Bool)

    Parameters

    mapView

    The map view that has just redrawn.
    View Source on GitHub

  • Tells the delegate that the map view is entering an idle state, and no more drawing will be necessary until new data is loaded or there is some interaction with the map.

    • No camera transitions are in progress
    • All currently requested tiles have loaded

    • All fade/transition animations have completed

    Declaration

    Objective-C

    - (void)mapViewDidBecomeIdle:(nonnull MGLMapView *)mapView;

    Swift

    optional func mapViewDidBecomeIdle(_ mapView: MGLMapView)

    Parameters

    mapView

    The map view that has just entered the idle state.
    View Source on GitHub

  • Tells the delegate that the map has just finished loading a style.

    This method is called during the initialization of the map view and after any subsequent loading of a new style. This method is called between the -mapViewWillStartRenderingMap: and -mapViewDidFinishRenderingMap: delegate methods. Changes to sources or layers of the current style do not cause this method to be called.

    This method is the earliest opportunity to modify the layout or appearance of the current style before the map view is displayed to the user.

    Declaration

    Objective-C

    - (void)mapView:(nonnull MGLMapView *)mapView
    didFinishLoadingStyle:(nonnull MGLStyle *)style;

    Swift

    optional func mapView(_ mapView: MGLMapView, didFinishLoadingStyle style: Any!)

    Parameters

    mapView

    The map view that has just loaded a style.
    style

    The style that was loaded.
    View Source on GitHub

  • Asks the delegate whether the map view should evict cached images.

    This method is called in two scenarios: when the cumulative size of unused images exceeds the cache size or when the last tile that includes the image is removed from memory.

    Declaration

    Objective-C

    - (BOOL)mapView:(nonnull MGLMapView *)mapView
    shouldRemoveStyleImage:(nonnull NSString *)imageName;

    Swift

    optional func mapView(_ mapView: MGLMapView, shouldRemoveStyleImage imageName: String) -> Bool

    Parameters

    mapView

    The map view that is evicting the image.
    imageName

    The image name that is going to be removed.

    Return Value

    A Boolean value indicating whether the map view should evict the cached image.

    View Source on GitHub

Managing the Appearance of Annotations

  • Returns an annotation image object to mark the given point annotation object on the map.

    Declaration

    Objective-C

    - (nullable MGLAnnotationImage *)mapView:(nonnull MGLMapView *)mapView
                      imageForAnnotation:(nonnull id<MGLAnnotation>)annotation;

    Swift

    optional func mapView(_ mapView: MGLMapView, imageForAnnotation annotation: Any) -> MGLAnnotationImage?

    Parameters

    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 given annotation or nil if you want to display the default marker image.

    View Source on GitHub

  • Returns the alpha value to use when rendering a shape annotation.

    A value of 0.0 results in a completely transparent shape. A value of 1.0, the default, results in a completely opaque shape.

    This method sets the opacity of an entire shape, inclusive of its stroke and fill. To independently set the values for stroke or fill, specify an alpha component in the color returned by -mapView:strokeColorForShapeAnnotation: or -mapView:fillColorForPolygonAnnotation:.

    Declaration

    Objective-C

    - (CGFloat)mapView:(nonnull MGLMapView *)mapView
    alphaForShapeAnnotation:(nonnull MGLShape *)annotation;

    Swift

    optional func mapView(_ mapView: MGLMapView, alphaForShapeAnnotation annotation: MGLShape) -> CGFloat

    Parameters

    mapView

    The map view rendering the shape annotation.
    annotation

    The annotation being rendered.

    Return Value

    An alpha value between 0 and 1.0.

    View Source on GitHub

  • Returns the color to use when rendering the outline of a shape annotation.

    The default stroke color is the selected menu item color. If a pattern color is specified, the result is undefined.

    Opacity may be set by specifying an alpha component. The default alpha value is 1.0 and results in a completely opaque stroke.

    Declaration

    Objective-C

    - (nonnull NSColor *)mapView:(nonnull MGLMapView *)mapView
    strokeColorForShapeAnnotation:(nonnull MGLShape *)annotation;

    Swift

    optional func mapView(_ mapView: MGLMapView, strokeColorForShapeAnnotation annotation: MGLShape) -> Any!

    Parameters

    mapView

    The map view rendering the shape annotation.
    annotation

    The annotation being rendered.

    Return Value

    A color to use for the shape outline.

    View Source on GitHub

  • Returns the color to use when rendering the fill of a polygon annotation.

    The default fill color is the selected menu item color. If a pattern color is specified, the result is undefined.

    Opacity may be set by specifying an alpha component. The default alpha value is 1.0 and results in a completely opaque shape.

    Declaration

    Objective-C

    - (nonnull NSColor *)mapView:(nonnull MGLMapView *)mapView
    fillColorForPolygonAnnotation:(nonnull MGLPolygon *)annotation;

    Swift

    optional func mapView(_ mapView: MGLMapView, fillColorForPolygonAnnotation annotation: MGLPolygon) -> Any!

    Parameters

    mapView

    The map view rendering the polygon annotation.
    annotation

    The annotation being rendered.

    Return Value

    The polygon’s interior fill color.

    View Source on GitHub

  • Returns the line width in points to use when rendering the outline of a polyline annotation.

    By default, the polyline is outlined with a line 3.0 points wide.

    Declaration

    Objective-C

    - (CGFloat)mapView:(nonnull MGLMapView *)mapView
    lineWidthForPolylineAnnotation:(nonnull MGLPolyline *)annotation;

    Swift

    optional func mapView(_ mapView: MGLMapView, lineWidthForPolylineAnnotation annotation: MGLPolyline) -> CGFloat

    Parameters

    mapView

    The map view rendering the polygon annotation.
    annotation

    The annotation being rendered.

    Return Value

    A line width for the polyline, measured in points.

    View Source on GitHub

Selecting Annotations

  • Returns a Boolean value indicating whether the shape annotation can be selected.

    If the return value is YES, the user can select the annotation by clicking on it. If the delegate does not implement this method, the default value is YES.

    Declaration

    Objective-C

    - (BOOL)mapView:(nonnull MGLMapView *)mapView
    shapeAnnotationIsEnabled:(nonnull MGLShape *)annotation;

    Swift

    optional func mapView(_ mapView: MGLMapView, shapeAnnotationIsEnabled annotation: MGLShape) -> Bool

    Parameters

    mapView

    The map view that has selected the annotation.
    annotation

    The object representing the shape annotation.

    Return Value

    A Boolean value indicating whether the annotation can be selected.

    View Source on GitHub

  • Tells the delegate that one of its annotations has been selected.

    You can use this method to track changes to the selection state of annotations.

    Declaration

    Objective-C

    - (void)mapView:(nonnull MGLMapView *)mapView
    didSelectAnnotation:(nonnull id<MGLAnnotation>)annotation;

    Swift

    optional func mapView(_ mapView: MGLMapView, didSelectAnnotation annotation: Any)

    Parameters

    mapView

    The map view containing the annotation.
    annotation

    The annotation that was selected.
    View Source on GitHub

  • Tells the delegate that one of its annotations has been deselected.

    You can use this method to track changes in the selection state of annotations.

    Declaration

    Objective-C

    - (void)mapView:(nonnull MGLMapView *)mapView
    didDeselectAnnotation:(nonnull id<MGLAnnotation>)annotation;

    Swift

    optional func mapView(_ mapView: MGLMapView, didDeselectAnnotation annotation: Any)

    Parameters

    mapView

    The map view containing the annotation.
    annotation

    The annotation that was deselected.
    View Source on GitHub

Managing Callout Popovers

  • Returns a Boolean value indicating whether the annotation is able to display extra information in a callout popover.

    This method is called after an annotation is selected, before any callout is displayed for the annotation.

    If the return value is YES, a callout popover is shown when the user clicks on an annotation, selecting it. The default callout displays the annotation’s title and subtitle. You can customize the popover’s contents by implementing the -mapView:calloutViewControllerForAnnotation: method.

    If the return value is NO, or if this method is absent from the delegate, or if the annotation lacks a title, the annotation will not show a callout even when selected.

    Declaration

    Objective-C

    - (BOOL)mapView:(nonnull MGLMapView *)mapView
    annotationCanShowCallout:(nonnull id<MGLAnnotation>)annotation;

    Swift

    optional func mapView(_ mapView: MGLMapView, annotationCanShowCallout annotation: Any) -> Bool

    Parameters

    mapView

    The map view that has selected the annotation.
    annotation

    The object representing the annotation.

    Return Value

    A Boolean value indicating whether the annotation should show a callout.

    View Source on GitHub

  • Returns a view controller to manage the callout popover’s content view.

    Like any instance of NSPopover, an annotation callout manages its contents with a view controller. The annotation object is the view controller’s represented object. This means that you can bind controls in the view controller’s content view to KVO-compliant properties of the annotation object, such as title and subtitle.

    If each annotation should have an identical callout, you can set the MGLMapView.calloutViewController property instead.

    Declaration

    Objective-C

    - (nullable NSViewController *)mapView:(nonnull MGLMapView *)mapView
    calloutViewControllerForAnnotation:(nonnull id<MGLAnnotation>)annotation;

    Swift

    optional func mapView(_ mapView: MGLMapView, calloutViewControllerForAnnotation annotation: Any) -> Any!

    Parameters

    mapView

    The map view that is requesting a callout view controller.
    annotation

    The object representing the annotation.

    Return Value

    A view controller for the given annotation.

    View Source on GitHub