[ios, osx] Optionally animate content insets change

2 files changed, 48 insertions, 1 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 */