[osx] Default callout view controller

include/mbgl/osx/MGLMapView.h

@@ -374,6 +374,22 @@ IB_DESIGNABLE
     @param annotation The annotation object to deselect. */
 - (void)deselectAnnotation:(id <MGLAnnotation>)annotation;
 
+/** A common view controller for managing a 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.
+    
+    This property defines a common view controller that is used for every
+    annotation’s callout view. If you set this property to `nil`, a default
+    view controller will be used that manages a simple title label and subtitle
+    label. If you need distinct view controllers for different annotations, the
+    map view’s delegate should implement
+    -mapView:calloutViewControllerForAnnotation: instead. */
+@property (nonatomic, strong, null_resettable) IBOutlet NSViewController *calloutViewController;
+
 #pragma mark Finding annotations
 /** @name Finding Annotations */
 
@@ -482,7 +498,7 @@ IB_DESIGNABLE
 /** The options that determine which debugging aids are shown on the map.
     
     These options are all disabled by default and should remain disabled in
-    released software. */
+    released software for performance and aesthetic reasons. */
 @property (nonatomic) MGLMapDebugMaskOptions debugMask;
 
 @end

include/mbgl/osx/MGLMapViewDelegate.h

@@ -186,6 +186,9 @@ NS_ASSUME_NONNULL_BEGIN
     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 instance’s -setCalloutViewController: method instead.
+    
     @param mapView The map view that is requesting a callout view controller.
     @param annotation The object representing the annotation.
     @return A view controller for the given annotation. */

platform/osx/src/MGLMapView.mm

@@ -1587,11 +1587,14 @@ public:
     
     NSViewController *viewController;
     if ([self.delegate respondsToSelector:@selector(mapView:calloutViewControllerForAnnotation:)]) {
-        viewController = [self.delegate mapView:self calloutViewControllerForAnnotation:annotation];
+        NSViewController *viewControllerFromDelegate = [self.delegate mapView:self
+                                           calloutViewControllerForAnnotation:annotation];
+        if (viewControllerFromDelegate) {
+            viewController = viewControllerFromDelegate;
+        }
     }
     if (!viewController) {
-        viewController = [[NSViewController alloc] initWithNibName:@"MGLAnnotationCallout"
-                                                            bundle:[NSBundle mgl_frameworkBundle]];
+        viewController = self.calloutViewController;
     }
     NSAssert(viewController, @"Unable to load MGLAnnotationCallout view controller");
     // The popover’s view controller can bind to KVO-compliant key paths of the
@@ -1602,6 +1605,15 @@ public:
     return callout;
 }
 
+- (NSViewController *)calloutViewController {
+    // Lazily load a default view controller.
+    if (!_calloutViewController) {
+        _calloutViewController = [[NSViewController alloc] initWithNibName:@"MGLAnnotationCallout"
+                                                                    bundle:[NSBundle mgl_frameworkBundle]];
+    }
+    return _calloutViewController;
+}
+
 /// Returns the rectangle that represents the annotation image of the annotation
 /// with the given tag. This rectangle is fitted to the image’s alignment rect
 /// and is appropriate for positioning a popover.