[ios] Adds camera change delegate methods with reason parameter. (#11151)

Added missing notification handler for UIApplicationWillResignActiveNotification.

7 files changed, 325 insertions, 73 deletions

diff --git a/platform/ios/app/MBXViewController.m b/platform/ios/app/MBXViewController.m
index 2c3d26b489..1046644f8c 100644
--- a/platform/ios/app/MBXViewController.m
+++ b/platform/ios/app/MBXViewController.m
@@ -1279,6 +1279,7 @@ typedef NS_ENUM(NSInteger, MBXSettingsMiscellaneousRows) {
 - (void)styleDynamicPointCollection
 {
     [self.mapView setCenterCoordinate:CLLocationCoordinate2DMake(36.9979, -109.0441) zoomLevel:14 animated:NO];
+
     CLLocationCoordinate2D coordinates[] = {
         {37.00145594210082, -109.04960632324219},
         {37.00173012609867, -109.0404224395752},
@@ -1884,7 +1885,8 @@ typedef NS_ENUM(NSInteger, MBXSettingsMiscellaneousRows) {
     [self updateHUD];
 }
 
-- (void)mapView:(MGLMapView *)mapView regionDidChangeAnimated:(BOOL)animated {
+- (void)mapView:(MGLMapView *)mapView regionDidChangeWithReason:(MGLCameraChangeReason)reason animated:(BOOL)animated
+{
     [self updateHUD];
 }
 
diff --git a/platform/ios/ios.xcodeproj/project.pbxproj b/platform/ios/ios.xcodeproj/project.pbxproj
index 2325f3d3ce..bbd4067534 100644
--- a/platform/ios/ios.xcodeproj/project.pbxproj
+++ b/platform/ios/ios.xcodeproj/project.pbxproj
@@ -251,6 +251,8 @@
 		AC518E00201BB55A00EBC820 /* MGLTelemetryConfig.h in Headers */ = {isa = PBXBuildFile; fileRef = AC518DFD201BB55A00EBC820 /* MGLTelemetryConfig.h */; };
 		AC518E03201BB56000EBC820 /* MGLTelemetryConfig.m in Sources */ = {isa = PBXBuildFile; fileRef = AC518DFE201BB55A00EBC820 /* MGLTelemetryConfig.m */; };
 		AC518E04201BB56100EBC820 /* MGLTelemetryConfig.m in Sources */ = {isa = PBXBuildFile; fileRef = AC518DFE201BB55A00EBC820 /* MGLTelemetryConfig.m */; };
+		CA55CD41202C16AA00CE7095 /* MGLCameraChangeReason.h in Headers */ = {isa = PBXBuildFile; fileRef = CA55CD3E202C16AA00CE7095 /* MGLCameraChangeReason.h */; settings = {ATTRIBUTES = (Public, ); }; };
+		CA55CD42202C16AA00CE7095 /* MGLCameraChangeReason.h in Headers */ = {isa = PBXBuildFile; fileRef = CA55CD3E202C16AA00CE7095 /* MGLCameraChangeReason.h */; settings = {ATTRIBUTES = (Public, ); }; };
 		DA00FC8E1D5EEB0D009AABC8 /* MGLAttributionInfo.h in Headers */ = {isa = PBXBuildFile; fileRef = DA00FC8C1D5EEB0D009AABC8 /* MGLAttributionInfo.h */; settings = {ATTRIBUTES = (Public, ); }; };
 		DA00FC8F1D5EEB0D009AABC8 /* MGLAttributionInfo.h in Headers */ = {isa = PBXBuildFile; fileRef = DA00FC8C1D5EEB0D009AABC8 /* MGLAttributionInfo.h */; settings = {ATTRIBUTES = (Public, ); }; };
 		DA00FC901D5EEB0D009AABC8 /* MGLAttributionInfo.mm in Sources */ = {isa = PBXBuildFile; fileRef = DA00FC8D1D5EEB0D009AABC8 /* MGLAttributionInfo.mm */; };
@@ -756,6 +758,7 @@
 		96F3F73B1F5711F1003E2D2C /* MGLUserLocationHeadingIndicator.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = MGLUserLocationHeadingIndicator.h; sourceTree = "<group>"; };
 		AC518DFD201BB55A00EBC820 /* MGLTelemetryConfig.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = MGLTelemetryConfig.h; sourceTree = "<group>"; };
 		AC518DFE201BB55A00EBC820 /* MGLTelemetryConfig.m */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.objc; path = MGLTelemetryConfig.m; sourceTree = "<group>"; };
+		CA55CD3E202C16AA00CE7095 /* MGLCameraChangeReason.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = MGLCameraChangeReason.h; sourceTree = "<group>"; };
 		DA00FC8C1D5EEB0D009AABC8 /* MGLAttributionInfo.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = MGLAttributionInfo.h; sourceTree = "<group>"; };
 		DA00FC8D1D5EEB0D009AABC8 /* MGLAttributionInfo.mm */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.objcpp; path = MGLAttributionInfo.mm; sourceTree = "<group>"; };
 		DA0CD58F1CF56F6A00A5F5A5 /* MGLFeatureTests.mm */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.objcpp; name = MGLFeatureTests.mm; path = ../../darwin/test/MGLFeatureTests.mm; sourceTree = "<group>"; };
@@ -1449,19 +1452,20 @@
 		DA8848331CBAFB2A00AB86E3 /* Kit */ = {
 			isa = PBXGroup;
 			children = (
-				355ADFF91E9281C300F3939D /* Views */,
-				35CE617F1D4165C2004F2359 /* Categories */,
 				DAD165841CF4D06B001FF4B9 /* Annotations */,
+				35CE617F1D4165C2004F2359 /* Categories */,
+				DA88487F1CBB033F00AB86E3 /* Fabric */,
+				DA8848881CBB036000AB86E3 /* SMCalloutView */,
 				DAD165851CF4D08B001FF4B9 /* Telemetry */,
+				355ADFF91E9281C300F3939D /* Views */,
+				CA55CD3E202C16AA00CE7095 /* MGLCameraChangeReason.h */,
 				DA704CC01F65A475004B3F28 /* MGLMapAccessibilityElement.h */,
 				DA704CC11F65A475004B3F28 /* MGLMapAccessibilityElement.mm */,
-				DA8848361CBAFB8500AB86E3 /* MGLMapView.h */,
 				DA17BE2F1CC4BAC300402C41 /* MGLMapView_Private.h */,
+				DA8848361CBAFB8500AB86E3 /* MGLMapView.h */,
+				DA88484A1CBAFB9800AB86E3 /* MGLMapView.mm */,
 				DA8848371CBAFB8500AB86E3 /* MGLMapView+IBAdditions.h */,
 				DA737EE01D056A4E005BDA16 /* MGLMapViewDelegate.h */,
-				DA88484A1CBAFB9800AB86E3 /* MGLMapView.mm */,
-				DA88487F1CBB033F00AB86E3 /* Fabric */,
-				DA8848881CBB036000AB86E3 /* SMCalloutView */,
 			);
 			name = Kit;
 			path = src;
@@ -1764,6 +1768,7 @@
 				350098DC1D484E60004B2AF0 /* NSValue+MGLStyleAttributeAdditions.h in Headers */,
 				DA8848231CBAFA6200AB86E3 /* MGLOfflineStorage_Private.h in Headers */,
 				404326891D5B9B27007111BD /* MGLAnnotationContainerView_Private.h in Headers */,
+				CA55CD41202C16AA00CE7095 /* MGLCameraChangeReason.h in Headers */,
 				1FB7DAAF1F2A4DBD00410606 /* MGLVectorSource+MGLAdditions.h in Headers */,
 				DA88483B1CBAFB8500AB86E3 /* MGLCalloutView.h in Headers */,
 				35E0CFE61D3E501500188327 /* MGLStyle_Private.h in Headers */,
@@ -1896,6 +1901,7 @@
 				3510FFF11D6D9D8C00F413B2 /* NSExpression+MGLAdditions.h in Headers */,
 				35D3A1E71E9BE7EC002B38EE /* MGLScaleBar.h in Headers */,
 				35E0CFE71D3E501500188327 /* MGLStyle_Private.h in Headers */,
+				CA55CD42202C16AA00CE7095 /* MGLCameraChangeReason.h in Headers */,
 				DABFB86D1CBE9A0F00D62B32 /* MGLAnnotationImage.h in Headers */,
 				DABFB8721CBE9A0F00D62B32 /* MGLUserLocation.h in Headers */,
 				927FBD001F4DB05500F8BF1F /* MGLMapSnapshotter.h in Headers */,
diff --git a/platform/ios/src/MGLCameraChangeReason.h b/platform/ios/src/MGLCameraChangeReason.h
new file mode 100644
index 0000000000..6c6b3636ba
--- /dev/null
+++ b/platform/ios/src/MGLCameraChangeReason.h
@@ -0,0 +1,61 @@
+#import "MGLFoundation.h"
+
+/**
+ :nodoc:
+ Bitmask values that describe why a camera move occurred.
+
+ Values of this type are passed to the `MGLMapView`'s delegate in the following methods:
+
+ - `-mapView:shouldChangeFromCamera:toCamera:reason:`
+ - `-mapView:regionWillChangeWithReason:animated:`
+ - `-mapView:regionIsChangingWithReason:`
+ - `-mapView:regionDidChangeWithReason:animated:`
+
+ It's important to note that it's almost impossible to perform a rotate without zooming (in or out),
+ so if you'll often find `MGLCameraChangeReasonGesturePinch` set alongside `MGLCameraChangeReasonGestureRotate`.
+
+ Since there are several reasons why a zoom or rotation has occurred, it is worth considering
+ creating a combined constant, for example:
+
+ ```
+ static const MGLCameraChangeReason anyZoom = MGLCameraChangeReasonGesturePinch |
+                                                MGLCameraChangeReasonGestureZoomIn |
+                                                MGLCameraChangeReasonGestureZoomOut |
+                                                MGLCameraChangeReasonGestureOneFingerZoom;
+
+ static const MGLCameraChangeReason anyRotation = MGLCameraChangeReasonResetNorth | MGLCameraChangeReasonGestureRotate;
+ ```
+ */
+typedef NS_OPTIONS(NSUInteger, MGLCameraChangeReason)
+{
+    /// :nodoc: The reason for the camera change has not be specified.
+    MGLCameraChangeReasonNone = 0,
+
+    /// :nodoc: Set when a public API that moves the camera is called. This may be set for some gestures,
+    /// for example MGLCameraChangeReasonResetNorth.
+    MGLCameraChangeReasonProgrammatic = 1 << 0,
+
+    /// :nodoc: The user tapped the compass to reset the map orientation so North is up.
+    MGLCameraChangeReasonResetNorth = 1 << 1,
+
+    /// :nodoc: The user panned the map.
+    MGLCameraChangeReasonGesturePan = 1 << 2,
+
+    /// :nodoc: The user pinched to zoom in/out.
+    MGLCameraChangeReasonGesturePinch = 1 << 3,
+
+    // :nodoc: The user rotated the map.
+    MGLCameraChangeReasonGestureRotate = 1 << 4,
+
+    /// :nodoc: The user zoomed the map in (one finger double tap).
+    MGLCameraChangeReasonGestureZoomIn = 1 << 5,
+
+    /// :nodoc: The user zoomed the map out (two finger single tap).
+    MGLCameraChangeReasonGestureZoomOut = 1 << 6,
+
+    /// :nodoc: The user long pressed on the map for a quick zoom (single tap, then long press and drag up/down).
+    MGLCameraChangeReasonGestureOneFingerZoom = 1 << 7,
+
+    // :nodoc: The user panned with two fingers to tilt the map (two finger drag).
+    MGLCameraChangeReasonGestureTilt = 1 << 8
+};
diff --git a/platform/ios/src/MGLMapView.mm b/platform/ios/src/MGLMapView.mm
index 0849cbd12f..f2141c3840 100644
--- a/platform/ios/src/MGLMapView.mm
+++ b/platform/ios/src/MGLMapView.mm
@@ -209,6 +209,8 @@ public:
 @property (nonatomic) UILongPressGestureRecognizer *quickZoom;
 @property (nonatomic) UIPanGestureRecognizer *twoFingerDrag;
 
+@property (nonatomic) MGLCameraChangeReason cameraChangeReasonBitmask;
+
 /// Mapping from reusable identifiers to annotation images.
 @property (nonatomic) NS_MUTABLE_DICTIONARY_OF(NSString *, MGLAnnotationImage *) *annotationImagesByIdentifier;
 
@@ -502,10 +504,6 @@ public:
     _doubleTap.numberOfTapsRequired = 2;
     [self addGestureRecognizer:_doubleTap];
 
-    _singleTapGestureRecognizer = [[UITapGestureRecognizer alloc] initWithTarget:self action:@selector(handleSingleTapGesture:)];
-    [_singleTapGestureRecognizer requireGestureRecognizerToFail:_doubleTap];
-    _singleTapGestureRecognizer.delegate = self;
-    [self addGestureRecognizer:_singleTapGestureRecognizer];
 
     _twoFingerDrag = [[UIPanGestureRecognizer alloc] initWithTarget:self action:@selector(handleTwoFingerDragGesture:)];
     _twoFingerDrag.minimumNumberOfTouches = 2;
@@ -530,16 +528,25 @@ public:
     [_quickZoom requireGestureRecognizerToFail:_doubleTap];
     [self addGestureRecognizer:_quickZoom];
 
+    _singleTapGestureRecognizer = [[UITapGestureRecognizer alloc] initWithTarget:self action:@selector(handleSingleTapGesture:)];
+    [_singleTapGestureRecognizer requireGestureRecognizerToFail:_doubleTap];
+    _singleTapGestureRecognizer.delegate = self;
+    [_singleTapGestureRecognizer requireGestureRecognizerToFail:_quickZoom];
+    [self addGestureRecognizer:_singleTapGestureRecognizer];
+
     // observe app activity
     //
     [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(willTerminate) name:UIApplicationWillTerminateNotification object:nil];
     [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(sleepGL:) name:UIApplicationDidEnterBackgroundNotification object:nil];
     [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(wakeGL:) name:UIApplicationWillEnterForegroundNotification object:nil];
+    [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(sleepGL:) name:UIApplicationWillResignActiveNotification object:nil];
     [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(wakeGL:) name:UIApplicationDidBecomeActiveNotification object:nil];
+
     [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(didReceiveMemoryWarning) name:UIApplicationDidReceiveMemoryWarningNotification object:nil];
     [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(deviceOrientationDidChange:) name:UIDeviceOrientationDidChangeNotification object:nil];
     [[UIDevice currentDevice] beginGeneratingDeviceOrientationNotifications];
 
+
     // set initial position
     //
     mbgl::CameraOptions options;
@@ -547,6 +554,9 @@ public:
     mbgl::EdgeInsets padding = MGLEdgeInsetsFromNSEdgeInsets(self.contentInset);
     options.padding = padding;
     options.zoom = 0;
+
+    _cameraChangeReasonBitmask = MGLCameraChangeReasonNone;
+
     _mbglMap->jumpTo(options);
     _pendingLatitude = NAN;
     _pendingLongitude = NAN;
@@ -1233,6 +1243,8 @@ public:
 
 - (void)handleCompassTapGesture:(__unused id)sender
 {
+    self.cameraChangeReasonBitmask |= MGLCameraChangeReasonResetNorth;
+
     [self resetNorthAnimated:YES];
 
     if (self.userTrackingMode == MGLUserTrackingModeFollowWithHeading ||
@@ -1255,6 +1267,7 @@ public:
 
 - (void)notifyGestureDidBegin {
     BOOL animated = NO;
+
     [self cameraWillChangeAnimated:animated];
     _mbglMap->setGestureInProgress(true);
     _changeDelimiterSuppressionDepth++;
@@ -1278,6 +1291,23 @@ public:
     return _changeDelimiterSuppressionDepth > 0;
 }
 
+- (BOOL)_shouldChangeFromCamera:(nonnull MGLMapCamera *)oldCamera toCamera:(nonnull MGLMapCamera *)newCamera
+{
+    // Check delegates first
+    if ([self.delegate respondsToSelector:@selector(mapView:shouldChangeFromCamera:toCamera:reason:)])
+    {
+        return [self.delegate mapView:self shouldChangeFromCamera:oldCamera toCamera:newCamera reason:self.cameraChangeReasonBitmask];
+    }
+    else if ([self.delegate respondsToSelector:@selector(mapView:shouldChangeFromCamera:toCamera:)])
+    {
+        return [self.delegate mapView:self shouldChangeFromCamera:oldCamera toCamera:newCamera];
+    }
+    else
+    {
+        return YES;
+    }
+}
+
 - (void)handlePanGesture:(UIPanGestureRecognizer *)pan
 {
     if ( ! self.isScrollEnabled) return;
@@ -1285,7 +1315,9 @@ public:
     _mbglMap->cancelTransitions();
 
     MGLMapCamera *oldCamera = self.camera;
-    
+
+    self.cameraChangeReasonBitmask |= MGLCameraChangeReasonGesturePan;
+
     if (pan.state == UIGestureRecognizerStateBegan)
     {
         [self trackGestureEvent:MGLEventGesturePanStart forRecognizer:pan];
@@ -1299,9 +1331,8 @@ public:
         CGPoint delta = [pan translationInView:pan.view];
 
         MGLMapCamera *toCamera = [self cameraByPanningWithTranslation:delta panGesture:pan];
-        
-        if (![self.delegate respondsToSelector:@selector(mapView:shouldChangeFromCamera:toCamera:)] ||
-            [self.delegate mapView:self shouldChangeFromCamera:oldCamera toCamera:toCamera])
+
+        if ([self _shouldChangeFromCamera:oldCamera toCamera:toCamera])
         {
             _mbglMap->moveBy({ delta.x, delta.y });
             [pan setTranslation:CGPointZero inView:pan.view];
@@ -1323,9 +1354,8 @@ public:
         {
             CGPoint offset = CGPointMake(velocity.x * self.decelerationRate / 4, velocity.y * self.decelerationRate / 4);
             MGLMapCamera *toCamera = [self cameraByPanningWithTranslation:offset panGesture:pan];
-            
-            if (![self.delegate respondsToSelector:@selector(mapView:shouldChangeFromCamera:toCamera:)] ||
-                [self.delegate mapView:self shouldChangeFromCamera:oldCamera toCamera:toCamera])
+
+            if ([self _shouldChangeFromCamera:oldCamera toCamera:toCamera])
             {
                 _mbglMap->moveBy({ offset.x, offset.y }, MGLDurationFromTimeInterval(self.decelerationRate));
             }
@@ -1356,6 +1386,8 @@ public:
     CGPoint centerPoint = [self anchorPointForGesture:pinch];
     MGLMapCamera *oldCamera = self.camera;
 
+    self.cameraChangeReasonBitmask |= MGLCameraChangeReasonGesturePinch;
+
     if (pinch.state == UIGestureRecognizerStateBegan)
     {
         [self trackGestureEvent:MGLEventGesturePinchStart forRecognizer:pinch];
@@ -1372,9 +1404,8 @@ public:
 
         // Calculates the final camera zoom, has no effect within current map camera.
         MGLMapCamera *toCamera = [self cameraByZoomingToZoomLevel:newZoom aroundAnchorPoint:centerPoint];
-        
-        if (![self.delegate respondsToSelector:@selector(mapView:shouldChangeFromCamera:toCamera:)] ||
-            [self.delegate mapView:self shouldChangeFromCamera:oldCamera toCamera:toCamera])
+
+        if ([self _shouldChangeFromCamera:oldCamera toCamera:toCamera])
         {
             _mbglMap->setZoom(newZoom, mbgl::ScreenCoordinate { centerPoint.x, centerPoint.y });
             // The gesture recognizer only reports the gesture’s current center
@@ -1426,9 +1457,8 @@ public:
         // Calculates the final camera zoom, this has no effect within current map camera.
         double zoom = log2(newScale);
         MGLMapCamera *toCamera = [self cameraByZoomingToZoomLevel:zoom aroundAnchorPoint:centerPoint];
-        
-        if ([self.delegate respondsToSelector:@selector(mapView:shouldChangeFromCamera:toCamera:)]
-            && ![self.delegate mapView:self shouldChangeFromCamera:oldCamera toCamera:toCamera])
+
+        if ([self _shouldChangeFromCamera:oldCamera toCamera:toCamera])
         {
             drift = NO;
         } else {
@@ -1454,7 +1484,9 @@ public:
 
     CGPoint centerPoint = [self anchorPointForGesture:rotate];
     MGLMapCamera *oldCamera = self.camera;
-    
+
+    self.cameraChangeReasonBitmask |= MGLCameraChangeReasonGestureRotate;
+
     if (rotate.state == UIGestureRecognizerStateBegan)
     {
         [self trackGestureEvent:MGLEventGestureRotateStart forRecognizer:rotate];
@@ -1481,9 +1513,8 @@ public:
         }
         
         MGLMapCamera *toCamera = [self cameraByRotatingToDirection:newDegrees aroundAnchorPoint:centerPoint];
-        
-        if (![self.delegate respondsToSelector:@selector(mapView:shouldChangeFromCamera:toCamera:)] ||
-            [self.delegate mapView:self shouldChangeFromCamera:oldCamera toCamera:toCamera])
+
+        if ([self _shouldChangeFromCamera:oldCamera toCamera:toCamera])
         {
            _mbglMap->setBearing(newDegrees, mbgl::ScreenCoordinate { centerPoint.x, centerPoint.y });
         }
@@ -1501,9 +1532,8 @@ public:
             CGFloat newDegrees = MGLDegreesFromRadians(newRadians) * -1;
 
             MGLMapCamera *toCamera = [self cameraByRotatingToDirection:newDegrees aroundAnchorPoint:centerPoint];
-            
-            if (![self.delegate respondsToSelector:@selector(mapView:shouldChangeFromCamera:toCamera:)] ||
-                [self.delegate mapView:self shouldChangeFromCamera:oldCamera toCamera:toCamera])
+
+            if ([self _shouldChangeFromCamera:oldCamera toCamera:toCamera])
             {
                 _mbglMap->setBearing(newDegrees, mbgl::ScreenCoordinate { centerPoint.x, centerPoint.y }, MGLDurationFromTimeInterval(decelerationRate));
                 
@@ -1548,6 +1578,7 @@ public:
         }
         [self deselectAnnotation:self.selectedAnnotation animated:YES];
         UIAccessibilityPostNotification(UIAccessibilityScreenChangedNotification, nextElement);
+
         return;
     }
 
@@ -1558,7 +1589,7 @@ public:
         CGRect positionRect = [self positioningRectForAnnotation:annotation defaultCalloutPoint:calloutPoint];
         [self selectAnnotation:annotation animated:YES calloutPositioningRect:positionRect];
     }
-    else
+    else if (self.selectedAnnotation)
     {
         [self deselectAnnotation:self.selectedAnnotation animated:YES];
     }
@@ -1640,6 +1671,8 @@ public:
 
     if (doubleTap.state == UIGestureRecognizerStateEnded)
     {
+        self.cameraChangeReasonBitmask |= MGLCameraChangeReasonGestureZoomIn;
+
         MGLMapCamera *oldCamera = self.camera;
 
         double newZoom = round(self.zoomLevel) + 1.0;
@@ -1647,9 +1680,8 @@ public:
         CGPoint gesturePoint = [self anchorPointForGesture:doubleTap];
 
         MGLMapCamera *toCamera = [self cameraByZoomingToZoomLevel:newZoom aroundAnchorPoint:gesturePoint];
-        
-        if (![self.delegate respondsToSelector:@selector(mapView:shouldChangeFromCamera:toCamera:)] ||
-            [self.delegate mapView:self shouldChangeFromCamera:oldCamera toCamera:toCamera])
+
+        if ([self _shouldChangeFromCamera:oldCamera toCamera:toCamera])
         {
             [self trackGestureEvent:MGLEventGestureDoubleTap forRecognizer:doubleTap];
             
@@ -1676,9 +1708,13 @@ public:
 
     _mbglMap->cancelTransitions();
 
+    self.cameraChangeReasonBitmask |= MGLCameraChangeReasonGestureZoomOut;
+
     if (twoFingerTap.state == UIGestureRecognizerStateBegan)
     {
         [self trackGestureEvent:MGLEventGestureTwoFingerSingleTap forRecognizer:twoFingerTap];
+
+        [self notifyGestureDidBegin];
     }
     else if (twoFingerTap.state == UIGestureRecognizerStateEnded)
     {
@@ -1689,9 +1725,8 @@ public:
         CGPoint gesturePoint = [self anchorPointForGesture:twoFingerTap];
 
         MGLMapCamera *toCamera = [self cameraByZoomingToZoomLevel:newZoom aroundAnchorPoint:gesturePoint];
-        
-        if (![self.delegate respondsToSelector:@selector(mapView:shouldChangeFromCamera:toCamera:)] ||
-            [self.delegate mapView:self shouldChangeFromCamera:oldCamera toCamera:toCamera])
+
+        if ([self _shouldChangeFromCamera:oldCamera toCamera:toCamera])
         {
             mbgl::ScreenCoordinate center(gesturePoint.x, gesturePoint.y);
             _mbglMap->setZoom(newZoom, center, MGLDurationFromTimeInterval(MGLAnimationDuration));
@@ -1711,7 +1746,9 @@ public:
     if ( ! self.isZoomEnabled) return;
 
     _mbglMap->cancelTransitions();
-    
+
+    self.cameraChangeReasonBitmask |= MGLCameraChangeReasonGestureOneFingerZoom;
+
     if (quickZoom.state == UIGestureRecognizerStateBegan)
     {
         [self trackGestureEvent:MGLEventGestureQuickZoom forRecognizer:quickZoom];
@@ -1734,9 +1771,8 @@ public:
         
         MGLMapCamera *oldCamera = self.camera;
         MGLMapCamera *toCamera = [self cameraByZoomingToZoomLevel:newZoom aroundAnchorPoint:centerPoint];
-        
-        if (![self.delegate respondsToSelector:@selector(mapView:shouldChangeFromCamera:toCamera:)] ||
-            [self.delegate mapView:self shouldChangeFromCamera:oldCamera toCamera:toCamera])
+
+        if ([self _shouldChangeFromCamera:oldCamera toCamera:toCamera])
         {
             _mbglMap->setZoom(newZoom, mbgl::ScreenCoordinate { centerPoint.x, centerPoint.y });
         }
@@ -1756,6 +1792,8 @@ public:
 
     _mbglMap->cancelTransitions();
 
+    self.cameraChangeReasonBitmask |= MGLCameraChangeReasonGestureTilt;
+
     if (twoFingerDrag.state == UIGestureRecognizerStateBegan)
     {
         [self trackGestureEvent:MGLEventGesturePitchStart forRecognizer:twoFingerDrag];
@@ -1775,8 +1813,7 @@ public:
         MGLMapCamera *oldCamera = self.camera;
         MGLMapCamera *toCamera = [self cameraByTiltingToPitch:pitchNew];
 
-        if (![self.delegate respondsToSelector:@selector(mapView:shouldChangeFromCamera:toCamera:)] ||
-            [self.delegate mapView:self shouldChangeFromCamera:oldCamera toCamera:toCamera])
+        if ([self _shouldChangeFromCamera:oldCamera toCamera:toCamera])
         {
             _mbglMap->setPitch(pitchNew, mbgl::ScreenCoordinate { centerPoint.x, centerPoint.y });
         }
@@ -2852,6 +2889,8 @@ public:
 {
     self.userTrackingMode = MGLUserTrackingModeNone;
 
+    self.cameraChangeReasonBitmask |= MGLCameraChangeReasonProgrammatic;
+
     [self _setCenterCoordinate:centerCoordinate edgePadding:self.contentInset zoomLevel:zoomLevel direction:direction duration:animated ? MGLAnimationDuration : 0 animationTimingFunction:nil completionHandler:completion];
 }
 
@@ -2901,6 +2940,9 @@ public:
     }
     
     _mbglMap->cancelTransitions();
+
+    self.cameraChangeReasonBitmask |= MGLCameraChangeReasonProgrammatic;
+
     _mbglMap->easeTo(cameraOptions, animationOptions);
 }
 
@@ -2924,6 +2966,8 @@ public:
     if (zoomLevel == self.zoomLevel) return;
     _mbglMap->cancelTransitions();
 
+    self.cameraChangeReasonBitmask |= MGLCameraChangeReasonProgrammatic;
+
     CGFloat duration = animated ? MGLAnimationDuration : 0;
 
     _mbglMap->setZoom(zoomLevel,
@@ -3012,6 +3056,9 @@ public:
 - (void)setVisibleCoordinates:(const CLLocationCoordinate2D *)coordinates count:(NSUInteger)count edgePadding:(UIEdgeInsets)insets direction:(CLLocationDirection)direction duration:(NSTimeInterval)duration animationTimingFunction:(nullable CAMediaTimingFunction *)function completionHandler:(nullable void (^)(void))completion
 {
     self.userTrackingMode = MGLUserTrackingModeNone;
+
+    self.cameraChangeReasonBitmask |= MGLCameraChangeReasonProgrammatic;
+
     [self _setVisibleCoordinates:coordinates count:count edgePadding:insets direction:direction duration:duration animationTimingFunction:function completionHandler:completion];
 }
 
@@ -3061,6 +3108,9 @@ public:
     
     [self willChangeValueForKey:@"visibleCoordinateBounds"];
     _mbglMap->cancelTransitions();
+
+    self.cameraChangeReasonBitmask |= MGLCameraChangeReasonProgrammatic;
+
     _mbglMap->easeTo(cameraOptions, animationOptions);
     [self didChangeValueForKey:@"visibleCoordinateBounds"];
 }
@@ -3094,6 +3144,8 @@ public:
 
     CGFloat duration = animated ? MGLAnimationDuration : 0;
 
+    self.cameraChangeReasonBitmask |= MGLCameraChangeReasonProgrammatic;
+
     if (self.userTrackingMode == MGLUserTrackingModeNone)
     {
         _mbglMap->setBearing(direction,
@@ -3178,6 +3230,9 @@ public:
 
     [self willChangeValueForKey:@"camera"];
     _mbglMap->cancelTransitions();
+
+    self.cameraChangeReasonBitmask |= MGLCameraChangeReasonProgrammatic;
+
     mbgl::CameraOptions cameraOptions = [self cameraOptionsObjectForAnimatingToCamera:camera edgePadding:edgePadding];
     _mbglMap->easeTo(cameraOptions, animationOptions);
     [self didChangeValueForKey:@"camera"];
@@ -3234,6 +3289,9 @@ public:
 
     [self willChangeValueForKey:@"camera"];
     _mbglMap->cancelTransitions();
+
+    self.cameraChangeReasonBitmask |= MGLCameraChangeReasonProgrammatic;
+
     mbgl::CameraOptions cameraOptions = [self cameraOptionsObjectForAnimatingToCamera:camera edgePadding:insets];
     _mbglMap->flyTo(cameraOptions, animationOptions);
     [self didChangeValueForKey:@"camera"];
@@ -3394,6 +3452,13 @@ public:
     return [self metersPerPointAtLatitude:latitude];
 }
 
+#pragma mark - Camera Change Reason -
+
+- (void)resetCameraChangeReason
+{
+    self.cameraChangeReasonBitmask = MGLCameraChangeReasonNone;
+}
+
 #pragma mark - Styling -
 
 - (NS_ARRAY_OF(NSURL *) *)bundledStyleURLs
@@ -5340,9 +5405,16 @@ public:
         }
     }
 
-    if ( ! [self isSuppressingChangeDelimiters] && [self.delegate respondsToSelector:@selector(mapView:regionWillChangeAnimated:)])
+    if ( ! [self isSuppressingChangeDelimiters] )
     {
-        [self.delegate mapView:self regionWillChangeAnimated:animated];
+        if ([self.delegate respondsToSelector:@selector(mapView:regionWillChangeWithReason:animated:)])
+        {
+            [self.delegate mapView:self regionWillChangeWithReason:self.cameraChangeReasonBitmask animated:animated];
+        }
+        else if ([self.delegate respondsToSelector:@selector(mapView:regionWillChangeAnimated:)])
+        {
+            [self.delegate mapView:self regionWillChangeAnimated:animated];
+        }
     }
 }
 
@@ -5356,8 +5428,12 @@ public:
     if (!self.scaleBar.hidden) {
         [(MGLScaleBar *)self.scaleBar setMetersPerPoint:[self metersPerPointAtLatitude:self.centerCoordinate.latitude]];
     }
-    
-    if ([self.delegate respondsToSelector:@selector(mapViewRegionIsChanging:)])
+
+    if ([self.delegate respondsToSelector:@selector(mapView:regionIsChangingWithReason:)])
+    {
+        [self.delegate mapView:self regionIsChangingWithReason:self.cameraChangeReasonBitmask];
+    }
+    else if ([self.delegate respondsToSelector:@selector(mapViewRegionIsChanging:)])
     {
         [self.delegate mapViewRegionIsChanging:self];
     }
@@ -5370,9 +5446,13 @@ public:
 
     [self updateCompass];
 
-    if ( ! [self isSuppressingChangeDelimiters] && [self.delegate respondsToSelector:@selector(mapView:regionDidChangeAnimated:)])
+    if ( ! [self isSuppressingChangeDelimiters])
     {
-        if ([UIApplication sharedApplication].applicationState == UIApplicationStateActive)
+        BOOL respondsToSelector = [self.delegate respondsToSelector:@selector(mapView:regionDidChangeAnimated:)];
+        BOOL respondsToSelectorWithReason = [self.delegate respondsToSelector:@selector(mapView:regionDidChangeWithReason:animated:)];
+
+        if ((respondsToSelector || respondsToSelectorWithReason) &&
+            ([UIApplication sharedApplication].applicationState == UIApplicationStateActive))
         {
             _featureAccessibilityElements = nil;
             _visiblePlaceFeatures = nil;
@@ -5384,7 +5464,17 @@ public:
                 UIAccessibilityPostNotification(UIAccessibilityLayoutChangedNotification, nil);
             }
         }
-        [self.delegate mapView:self regionDidChangeAnimated:animated];
+
+        if (respondsToSelectorWithReason)
+        {
+            [self.delegate mapView:self regionDidChangeWithReason:self.cameraChangeReasonBitmask animated:animated];
+        }
+        else if (respondsToSelector)
+        {
+            [self.delegate mapView:self regionDidChangeAnimated:animated];
+        }
+
+        [self resetCameraChangeReason];
     }
 }
 
diff --git a/platform/ios/src/MGLMapViewDelegate.h b/platform/ios/src/MGLMapViewDelegate.h
index 096711fcbb..0368d8413c 100644
--- a/platform/ios/src/MGLMapViewDelegate.h
+++ b/platform/ios/src/MGLMapViewDelegate.h
@@ -1,6 +1,7 @@
 #import <UIKit/UIKit.h>
 
 #import "MGLTypes.h"
+#import "MGLCameraChangeReason.h"
 
 NS_ASSUME_NONNULL_BEGIN
 
@@ -22,17 +23,80 @@ NS_ASSUME_NONNULL_BEGIN
 #pragma mark Responding to Map Position Changes
 
 /**
+ 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.
+
+ @param mapView The map view that the user is manipulating.
+ @param 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.
+ @param newCamera The expected camera after the gesture completes. If this
+ method returns `YES`, this camera becomes the map view’s camera.
+ @return A Boolean value indicating whether the map view should stay at
+ `oldCamera` or change to `newCamera`.
+ */
+- (BOOL)mapView:(MGLMapView *)mapView shouldChangeFromCamera:(MGLMapCamera *)oldCamera toCamera:(MGLMapCamera *)newCamera;
+
+/**
+ :nodoc:
+ 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.
+
+ @param mapView The map view that the user is manipulating.
+ @param 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.
+ @param newCamera The expected camera after the gesture completes. If this
+ method returns `YES`, this camera becomes the map view’s camera.
+ @param reason The reason for the camera change.
+ @return A Boolean value indicating whether the map view should stay at
+ `oldCamera` or change to `newCamera`.
+
+ @note If this method is implemented `-mapView:shouldChangeFromCamera:toCamera:` will not be called.
+ */
+- (BOOL)mapView:(MGLMapView *)mapView shouldChangeFromCamera:(MGLMapCamera *)oldCamera toCamera:(MGLMapCamera *)newCamera reason:(MGLCameraChangeReason)reason;
+
+/**
  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.
- 
+
  @param mapView The map view whose viewpoint will change.
  @param animated Whether the change will cause an animated effect on the map.
  */
 - (void)mapView:(MGLMapView *)mapView regionWillChangeAnimated:(BOOL)animated;
 
 /**
+ :nodoc:
+ 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.
+
+ @param mapView The map view whose viewpoint will change.
+ @param animated Whether the change will cause an animated effect on the map.
+ @param reason The reason for the camera change.
+
+ @note If this method is implemented `-mapView:regionWillChangeAnimated:` will not be called.
+ */
+- (void)mapView:(MGLMapView *)mapView regionWillChangeWithReason:(MGLCameraChangeReason)reason animated:(BOOL)animated;
+
+/**
  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
@@ -49,6 +113,26 @@ NS_ASSUME_NONNULL_BEGIN
 - (void)mapViewRegionIsChanging:(MGLMapView *)mapView;
 
 /**
+ :nodoc:
+ 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.
+
+ @param mapView The map view whose viewpoint is changing.
+ @param reason The reason for the camera change.
+
+ @note If this method is implemented `-mapViewRegionIsChanging:` will not be called.
+ */
+- (void)mapView:(MGLMapView *)mapView regionIsChangingWithReason:(MGLCameraChangeReason)reason;
+
+/**
  Tells the delegate that the viewpoint depicted by the map view has finished
  changing.
 
@@ -62,26 +146,21 @@ NS_ASSUME_NONNULL_BEGIN
 - (void)mapView:(MGLMapView *)mapView regionDidChangeAnimated:(BOOL)animated;
 
 /**
- 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.
- 
- @param mapView The map view that the user is manipulating.
- @param 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.
- @param newCamera The expected camera after the gesture completes. If this
-    method returns `YES`, this camera becomes the map view’s camera.
- @return A Boolean value indicating whether the map view should stay at
-    `oldCamera` or change to `newCamera`.
+ :nodoc:
+ 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. Therefore,
+ this method can be called before `-mapViewDidFinishLoadingMap:` is called.
+
+ @param mapView The map view whose viewpoint has changed.
+ @param animated Whether the change caused an animated effect on the map.
+ @param reason The reason for the camera change.
+
+ @note If this method is implemented `-mapView:regionDidChangeAnimated:` will not be called.
  */
-- (BOOL)mapView:(MGLMapView *)mapView shouldChangeFromCamera:(MGLMapCamera *)oldCamera toCamera:(MGLMapCamera *)newCamera;
+- (void)mapView:(MGLMapView *)mapView regionDidChangeWithReason:(MGLCameraChangeReason)reason animated:(BOOL)animated;
 
 #pragma mark Loading the Map
 
diff --git a/platform/ios/test/MGLMapViewDelegateIntegrationTests.swift b/platform/ios/test/MGLMapViewDelegateIntegrationTests.swift
index 50f101e86b..4d11b000b9 100644
--- a/platform/ios/test/MGLMapViewDelegateIntegrationTests.swift
+++ b/platform/ios/test/MGLMapViewDelegateIntegrationTests.swift
@@ -13,6 +13,10 @@ extension MGLMapViewDelegateIntegrationTests: MGLMapViewDelegate {
 
     func mapViewRegionIsChanging(_ mapView: MGLMapView) {}
 
+    func mapViewRegionIsChanging(_ mapView: MGLMapView, reason: MGLCameraChangeReason) {}
+
+    func mapView(_ mapView: MGLMapView, regionIsChangingWith reason: MGLCameraChangeReason) {}
+
     func mapView(_ mapView: MGLMapView, didChange mode: MGLUserTrackingMode, animated: Bool) {}
 
     func mapViewDidFinishLoadingMap(_ mapView: MGLMapView) {}
@@ -33,10 +37,16 @@ extension MGLMapViewDelegateIntegrationTests: MGLMapViewDelegate {
 
     func mapView(_ mapView: MGLMapView, didDeselect annotation: MGLAnnotation) {}
 
+    func mapView(_ mapView: MGLMapView, didSingleTapAt coordinate: CLLocationCoordinate2D) {}
+
     func mapView(_ mapView: MGLMapView, regionDidChangeAnimated animated: Bool) {}
 
+    func mapView(_ mapView: MGLMapView, regionDidChangeWith reason: MGLCameraChangeReason, animated: Bool) {}
+
     func mapView(_ mapView: MGLMapView, regionWillChangeAnimated animated: Bool) {}
 
+    func mapView(_ mapView: MGLMapView, regionWillChangeWith reason: MGLCameraChangeReason, animated: Bool) {}
+
     func mapViewDidFailLoadingMap(_ mapView: MGLMapView, withError error: Error) {}
 
     func mapView(_ mapView: MGLMapView, didUpdate userLocation: MGLUserLocation?) {}
@@ -79,4 +89,5 @@ extension MGLMapViewDelegateIntegrationTests: MGLMapViewDelegate {
 
     func mapView(_ mapView: MGLMapView, shouldChangeFrom oldCamera: MGLMapCamera, to newCamera: MGLMapCamera) -> Bool { return false }
 
+    func mapView(_ mapView: MGLMapView, shouldChangeFrom oldCamera: MGLMapCamera, to newCamera: MGLMapCamera, reason: MGLCameraChangeReason) -> Bool { return false }
 }
diff --git a/platform/ios/uitest/MapViewTests.m b/platform/ios/uitest/MapViewTests.m
index 4ed3d89399..ba15af918a 100644
--- a/platform/ios/uitest/MapViewTests.m
+++ b/platform/ios/uitest/MapViewTests.m
@@ -538,10 +538,13 @@
                                                       userInfo:@{ @"animated" : @(animated) }];
 }
 
-- (void)mapView:(MGLMapView *)mapView regionDidChangeAnimated:(BOOL)animated {
+- (void)mapView:(MGLMapView *)mapView regionDidChangeWithReason:(MGLCameraChangeReason)reason animated:(BOOL)animated {
+
     [[NSNotificationCenter defaultCenter] postNotificationName:@"regionDidChangeAnimated"
                                                         object:mapView
-                                                      userInfo:@{ @"animated" : @(animated) }];
+                                                      userInfo:@{ @"animated" : @(animated),
+                                                                  @"reason" : @(reason)
+                                                                  }];
 }
 
 - (void)testDelegatesStartStopLocatingUser {