[macos] Add `showAnnotations:` methods (#5749)

SDK
- Ported `showAnnotations:animated:` and `showAnnotations:edgePadding:animated:` from the iOS SDK.

Demo App
- Added "Show All Annotations" debug menu item with ⇧⌘A shortcut key.
- Disabled "Add Animated Annotation" debug menu item when the annotation already shown.

5 files changed, 86 insertions, 7 deletions

diff --git a/platform/macos/CHANGELOG.md b/platform/macos/CHANGELOG.md
index b2e7199919..aff6b8581a 100644
--- a/platform/macos/CHANGELOG.md
+++ b/platform/macos/CHANGELOG.md
@@ -1,5 +1,9 @@
 # Changelog for Mapbox macOS SDK
 
+## master
+
+* Added `showAnnotations:animated:` and `showAnnotations:edgePadding:animated:`, which moves the map viewport to show the specified annotations. ([#5749](https://github.com/mapbox/mapbox-gl-native/pull/5749))
+
 ## 0.2.1
 
 * Fixed a crash that occurred when a sprite URL lacks a file extension. See [this comment](https://github.com/mapbox/mapbox-gl-native/issues/5722#issuecomment-233701251) to determine who may be affected by this bug. ([#5723](https://github.com/mapbox/mapbox-gl-native/pull/5723))
diff --git a/platform/macos/app/Base.lproj/MainMenu.xib b/platform/macos/app/Base.lproj/MainMenu.xib
index 6b636eb8ad..4d81289314 100644
--- a/platform/macos/app/Base.lproj/MainMenu.xib
+++ b/platform/macos/app/Base.lproj/MainMenu.xib
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<document type="com.apple.InterfaceBuilder3.Cocoa.XIB" version="3.0" toolsVersion="11163.2" systemVersion="15F34" targetRuntime="MacOSX.Cocoa" propertyAccessControl="none" useAutolayout="YES" customObjectInstantitationMethod="direct">
+<document type="com.apple.InterfaceBuilder3.Cocoa.XIB" version="3.0" toolsVersion="10117" systemVersion="15G26a" targetRuntime="MacOSX.Cocoa" propertyAccessControl="none" useAutolayout="YES" customObjectInstantitationMethod="direct">
     <dependencies>
-        <plugIn identifier="com.apple.InterfaceBuilder.CocoaPlugin" version="11163.2"/>
+        <plugIn identifier="com.apple.InterfaceBuilder.CocoaPlugin" version="10117"/>
     </dependencies>
     <objects>
         <customObject id="-2" userLabel="File's Owner" customClass="NSApplication">
@@ -505,6 +505,12 @@
                                     <action selector="drawAnimatedAnnotation:" target="-1" id="CYM-WB-s97"/>
                                 </connections>
                             </menuItem>
+                            <menuItem title="Show All Annnotations" keyEquivalent="A" id="yMj-uM-8SN">
+                                <modifierMask key="keyEquivalentModifierMask" shift="YES" command="YES"/>
+                                <connections>
+                                    <action selector="showAllAnnotations:" target="-1" id="ahr-OR-Em2"/>
+                                </connections>
+                            </menuItem>
                             <menuItem title="Remove All Annotations" id="6rC-68-vk0">
                                 <string key="keyEquivalent" base64-UTF8="YES">
 CA
diff --git a/platform/macos/app/MapDocument.m b/platform/macos/app/MapDocument.m
index f30b83274a..81fd85e156 100644
--- a/platform/macos/app/MapDocument.m
+++ b/platform/macos/app/MapDocument.m
@@ -65,6 +65,7 @@ NS_ARRAY_OF(id <MGLAnnotation>) *MBXFlattenedShapes(NS_ARRAY_OF(id <MGLAnnotatio
     BOOL _randomizesCursorsOnDroppedPins;
     BOOL _isTouringWorld;
     BOOL _isShowingPolygonAndPolylineAnnotations;
+    BOOL _isShowingAnimatedAnnotation;
 }
 
 #pragma mark Lifecycle
@@ -329,9 +330,14 @@ NS_ARRAY_OF(id <MGLAnnotation>) *MBXFlattenedShapes(NS_ARRAY_OF(id <MGLAnnotatio
     }
 }
 
+- (IBAction)showAllAnnotations:(id)sender {
+    [self.mapView showAnnotations:self.mapView.annotations animated:YES];
+}
+
 - (IBAction)removeAllAnnotations:(id)sender {
     [self.mapView removeAnnotations:self.mapView.annotations];
     _isShowingPolygonAndPolylineAnnotations = NO;
+    _isShowingAnimatedAnnotation = NO;
 }
 
 - (IBAction)startWorldTour:(id)sender {
@@ -409,6 +415,8 @@ NS_ARRAY_OF(id <MGLAnnotation>) *MBXFlattenedShapes(NS_ARRAY_OF(id <MGLAnnotatio
     DroppedPinAnnotation *annotation = [[DroppedPinAnnotation alloc] init];
     [self.mapView addAnnotation:annotation];
 
+    _isShowingAnimatedAnnotation = YES;
+
     [NSTimer scheduledTimerWithTimeInterval:1.0/60.0
                                      target:self
                                    selector:@selector(updateAnimatedAnnotation:)
@@ -632,10 +640,13 @@ NS_ARRAY_OF(id <MGLAnnotation>) *MBXFlattenedShapes(NS_ARRAY_OF(id <MGLAnnotatio
     if (menuItem.action == @selector(dropManyPins:)) {
         return YES;
     }
+    if (menuItem.action == @selector(drawPolygonAndPolyLineAnnotations:)) {
+        return !_isShowingPolygonAndPolylineAnnotations;
+    }
     if (menuItem.action == @selector(drawAnimatedAnnotation:)) {
-        return YES;
+        return !_isShowingAnimatedAnnotation;
     }
-    if (menuItem.action == @selector(removeAllAnnotations:)) {
+    if (menuItem.action == @selector(showAllAnnotations:) || menuItem.action == @selector(removeAllAnnotations:)) {
         return self.mapView.annotations.count > 0;
     }
     if (menuItem.action == @selector(startWorldTour:)) {
@@ -644,9 +655,6 @@ NS_ARRAY_OF(id <MGLAnnotation>) *MBXFlattenedShapes(NS_ARRAY_OF(id <MGLAnnotatio
     if (menuItem.action == @selector(stopWorldTour:)) {
         return _isTouringWorld;
     }
-    if (menuItem.action == @selector(drawPolygonAndPolyLineAnnotations:)) {
-        return !_isShowingPolygonAndPolylineAnnotations;
-    }
     if (menuItem.action == @selector(addOfflinePack:)) {
         NSURL *styleURL = self.mapView.styleURL;
         return !styleURL.isFileURL;
diff --git a/platform/macos/src/MGLMapView.h b/platform/macos/src/MGLMapView.h
index 69927bf970..7c464fe83a 100644
--- a/platform/macos/src/MGLMapView.h
+++ b/platform/macos/src/MGLMapView.h
@@ -387,6 +387,35 @@ IB_DESIGNABLE
 - (void)setVisibleCoordinateBounds:(MGLCoordinateBounds)bounds edgePadding:(NSEdgeInsets)insets animated:(BOOL)animated;
 
 /**
+ Sets the visible region so that the map displays the specified annotations.
+
+ Calling this method updates the value in the `visibleCoordinateBounds` property
+ and potentially other properties to reflect the new map region. A small amount
+ of padding is reserved around the edges of the map view. To specify a different
+ amount of padding, use the `-showAnnotations:edgePadding:animated:` method.
+
+ @param annotations The annotations that you want to be visible in the map.
+ @param 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.
+ */
+- (void)showAnnotations:(NS_ARRAY_OF(id <MGLAnnotation>) *)annotations animated:(BOOL)animated;
+
+/**
+ Sets the visible region so that the map displays the specified annotations with
+ the specified amount of padding on each side.
+
+ Calling this method updates the value in the `visibleCoordinateBounds` property
+ and potentially other properties to reflect the new map region.
+
+ @param annotations The annotations that you want to be visible in the map.
+ @param insets The minimum padding (in screen points) around the edges of the
+ map view to keep clear of annotations.
+ @param 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.
+ */
+- (void)showAnnotations:(NS_ARRAY_OF(id <MGLAnnotation>) *)annotations edgePadding:(NSEdgeInsets)insets animated:(BOOL)animated;
+
+/**
  Returns the camera that best fits the given coordinate bounds.
  
  @param bounds The coordinate bounds to fit to the receiver’s viewport.
diff --git a/platform/macos/src/MGLMapView.mm b/platform/macos/src/MGLMapView.mm
index 5785f56e01..7b0aad1db9 100644
--- a/platform/macos/src/MGLMapView.mm
+++ b/platform/macos/src/MGLMapView.mm
@@ -1998,6 +1998,38 @@ public:
     }
 }
 
+- (void)showAnnotations:(NS_ARRAY_OF(id <MGLAnnotation>) *)annotations animated:(BOOL)animated {
+    CGFloat maximumPadding = 100;
+    CGFloat yPadding = (NSHeight(self.bounds) / 5 <= maximumPadding) ? (NSHeight(self.bounds) / 5) : maximumPadding;
+    CGFloat xPadding = (NSWidth(self.bounds) / 5 <= maximumPadding) ? (NSWidth(self.bounds) / 5) : maximumPadding;
+
+    NSEdgeInsets edgeInsets = NSEdgeInsetsMake(yPadding, xPadding, yPadding, xPadding);
+
+    [self showAnnotations:annotations edgePadding:edgeInsets animated:animated];
+}
+
+- (void)showAnnotations:(NS_ARRAY_OF(id <MGLAnnotation>) *)annotations edgePadding:(NSEdgeInsets)insets animated:(BOOL)animated {
+    if ( ! annotations || ! annotations.count) return;
+
+    mbgl::LatLngBounds bounds = mbgl::LatLngBounds::empty();
+
+    for (id <MGLAnnotation> annotation in annotations)
+    {
+        if ([annotation conformsToProtocol:@protocol(MGLOverlay)])
+        {
+            bounds.extend(MGLLatLngBoundsFromCoordinateBounds(((id <MGLOverlay>)annotation).overlayBounds));
+        }
+        else
+        {
+            bounds.extend(MGLLatLngFromLocationCoordinate2D(annotation.coordinate));
+        }
+    }
+
+    [self setVisibleCoordinateBounds:MGLCoordinateBoundsFromLatLngBounds(bounds)
+                         edgePadding:insets
+                            animated:animated];
+}
+
 /// Returns a popover detailing the annotation.
 - (NSPopover *)calloutForAnnotation:(id <MGLAnnotation>)annotation {
     NSPopover *callout = [[NSPopover alloc] init];