[ios, osx] Optionally animate content insets change

4 files changed, 91 insertions, 21 deletions

diff --git a/include/mbgl/ios/MGLMapView.h b/include/mbgl/ios/MGLMapView.h
index 847864e29a..2d28fd3a14 100644
--- a/include/mbgl/ios/MGLMapView.h
+++ b/include/mbgl/ios/MGLMapView.h
@@ -615,9 +615,34 @@ IB_DESIGNABLE
  When the map view’s superview is an instance of `UIViewController` whose
  `automaticallyAdjustsScrollViewInsets` property is `YES`, the value of this
  property may be overridden at any time.
+ 
+ Changing the value of this property updates the map view immediately. If you
+ want to animate the change, use the `-setContentInset:animated:` method
+ instead.
  */
 @property (nonatomic, assign) UIEdgeInsets contentInset;
 
+/**
+ Sets the distance from the edges of the map view’s frame to the edges of the
+ map view’s logical viewport with an optional transition animation.
+ 
+ When the value of this property is equal to `UIEdgeInsetsZero`, viewport
+ properties such as `centerCoordinate` assume a viewport that matches the map
+ view’s frame. Otherwise, those properties are inset, excluding part of the
+ frame from the viewport. For instance, if the only the top edge is inset, the
+ map center is effectively shifted downward.
+ 
+ When the map view’s superview is an instance of `UIViewController` whose
+ `automaticallyAdjustsScrollViewInsets` property is `YES`, the value of this
+ property may be overridden at any time.
+ 
+ @param contentInset The new values to inset the content by.
+ @param animated Specify `YES` if you want the map view to animate the change to
+    the content inset or `NO` if you want the map to inset the content
+    immediately.
+ */
+- (void)setContentInset:(UIEdgeInsets)contentInset animated:(BOOL)animated;
+
 #pragma mark Converting Geographic Coordinates
 
 /**
diff --git a/include/mbgl/osx/MGLMapView.h b/include/mbgl/osx/MGLMapView.h
index 971477b42e..62a689fa19 100644
--- a/include/mbgl/osx/MGLMapView.h
+++ b/include/mbgl/osx/MGLMapView.h
@@ -330,9 +330,31 @@ IB_DESIGNABLE
     the map center is effectively shifted downward.
     
     When the value of the `automaticallyAdjustsContentInsets` property is `YES`,
-    the value of this property may be overridden at any time. */
+    the value of this property may be overridden at any time.
+    
+    Changing the value of this property updates the map view immediately. If you
+    want to animate the change, use the `-setContentInsets:animated:` method
+    instead. */
 @property (nonatomic, assign) NSEdgeInsets contentInsets;
 
+/** Sets the distance from the edges of the map view’s frame to the edges of the
+    map view’s logical viewport, with an optional transition animation.
+    
+    When the value of this property is equal to `NSEdgeInsetsZero`, viewport
+    properties such as `centerCoordinate` assume a viewport that matches the map
+    view’s frame. Otherwise, those properties are inset, excluding part of the
+    frame from the viewport. For instance, if the only the top edge is inset,
+    the map center is effectively shifted downward.
+    
+    When the value of the `automaticallyAdjustsContentInsets` property is `YES`,
+    the value of this property may be overridden at any time.
+    
+    @param contentInsets The new values to inset the content by.
+    @param animated Specify `YES` if you want the map view to animate the change
+        to the content insets or `NO` if you want the map to inset the content
+        immediately. */
+- (void)setContentInsets:(NSEdgeInsets)contentInsets animated:(BOOL)animated;
+
 #pragma mark Configuring gesture recognition
 /** @name Configuring How the User Interacts with the Map */
 
diff --git a/platform/ios/src/MGLMapView.mm b/platform/ios/src/MGLMapView.mm
index 93b30cb177..d1639f4583 100644
--- a/platform/ios/src/MGLMapView.mm
+++ b/platform/ios/src/MGLMapView.mm
@@ -810,24 +810,37 @@ std::chrono::steady_clock::duration MGLDurationInSeconds(float duration)
         return;
     }
     
-    UIEdgeInsets contentInsets = UIEdgeInsetsZero;
+    UIEdgeInsets contentInset = UIEdgeInsetsZero;
     CGPoint topPoint = CGPointMake(0, viewController.topLayoutGuide.length);
-    contentInsets.top = [self convertPoint:topPoint fromView:viewController.view].y;
+    contentInset.top = [self convertPoint:topPoint fromView:viewController.view].y;
     CGPoint bottomPoint = CGPointMake(0, CGRectGetMaxY(viewController.view.bounds)
                                       - viewController.bottomLayoutGuide.length);
-    contentInsets.bottom = (CGRectGetMaxY(self.bounds) - [self convertPoint:bottomPoint
-                                                                   fromView:viewController.view].y);
-    
-    if ( ! UIEdgeInsetsEqualToEdgeInsets(contentInsets, self.contentInset))
+    contentInset.bottom = (CGRectGetMaxY(self.bounds)
+                           - [self convertPoint:bottomPoint fromView:viewController.view].y);
+    self.contentInset = contentInset;
+}
+
+- (void)setContentInset:(UIEdgeInsets)contentInset
+{
+    [self setContentInset:contentInset animated:NO];
+}
+
+- (void)setContentInset:(UIEdgeInsets)contentInset animated:(BOOL)animated
+{
+    if (UIEdgeInsetsEqualToEdgeInsets(contentInset, self.contentInset))
     {
-        // After adjusting the content insets, move the center coordinate from
-        // the old frame of reference to the new one represented by the newly
-        // set content insets.
-        CLLocationCoordinate2D oldCenter = self.centerCoordinate;
-        self.contentInset = contentInsets;
-        // Don’t call -setCenterCoordinate:, which resets the user tracking mode.
-        [self _setCenterCoordinate:oldCenter animated:NO];
+        return;
     }
+    
+    // After adjusting the content inset, move the center coordinate from the
+    // old frame of reference to the new one represented by the newly set
+    // content inset.
+    CLLocationCoordinate2D oldCenter = self.centerCoordinate;
+    
+    _contentInset = contentInset;
+    
+    // Don’t call -setCenterCoordinate:, which resets the user tracking mode.
+    [self _setCenterCoordinate:oldCenter animated:animated];
 }
 
 /// Returns the frame of inset content within the map view.
diff --git a/platform/osx/src/MGLMapView.mm b/platform/osx/src/MGLMapView.mm
index 9c32e7204d..e1c472409e 100644
--- a/platform/osx/src/MGLMapView.mm
+++ b/platform/osx/src/MGLMapView.mm
@@ -1117,14 +1117,24 @@ public:
         contentInsets = NSEdgeInsetsZero;
     }
     
-    if (!NSEdgeInsetsEqual(contentInsets, self.contentInsets)) {
-        // After adjusting the content insets, move the center coordinate from
-        // the old frame of reference to the new one represented by the newly
-        // set content insets.
-        CLLocationCoordinate2D oldCenter = self.centerCoordinate;
-        self.contentInsets = contentInsets;
-        self.centerCoordinate = oldCenter;
+    self.contentInsets = contentInsets;
+}
+
+- (void)setContentInsets:(NSEdgeInsets)contentInsets {
+    [self setContentInsets:contentInsets animated:NO];
+}
+
+- (void)setContentInsets:(NSEdgeInsets)contentInsets animated:(BOOL)animated {
+    if (NSEdgeInsetsEqual(contentInsets, self.contentInsets)) {
+        return;
     }
+    
+    // After adjusting the content insets, move the center coordinate from the
+    // old frame of reference to the new one represented by the newly set
+    // content insets.
+    CLLocationCoordinate2D oldCenter = self.centerCoordinate;
+    _contentInsets = contentInsets;
+    [self setCenterCoordinate:oldCenter animated:animated];
 }
 
 #pragma mark Mouse events and gestures