Removed selection animation delegate method. Renamed "move onscreen" delegate method to indicate narrowed focus.

4 files changed, 26 insertions, 49 deletions

diff --git a/platform/ios/src/MGLMapView.h b/platform/ios/src/MGLMapView.h
index 8fdd346379..22b9dcedc1 100644
--- a/platform/ios/src/MGLMapView.h
+++ b/platform/ios/src/MGLMapView.h
@@ -1318,10 +1318,6 @@ MGL_EXPORT IB_DESIGNABLE
 @property (nonatomic, copy) NSArray<id <MGLAnnotation>> *selectedAnnotations;
 
 /**
- TODO: update documentation
- TODO: consider deprecation, and replacing with a `selectAnnotation:` that uses the proposed delegate
- methods.
-
  Selects an annotation and displays its callout view.
 
  The `animated` parameter determines whether the map is panned to bring the
@@ -1330,17 +1326,15 @@ MGL_EXPORT IB_DESIGNABLE
  | `animated` parameter | Effect |
  |------------------|--------|
  | `NO`             | The annotation is selected, and the callout is presented. However the map is not panned to bring the annotation or callout onscreen.
- | `YES`            | The annotation is selected, and the callout is presented. If the annotation is offscreen *and* is of type `MGLPointAnnotation`, the map is panned so that the annotation and its callout are brought just onscreen. The annotation is *not* centered within the viewport. |
+ | `YES`            | The annotation is selected, and the callout is presented. If the annotation is offscreen, the map is panned so that the annotation and its callout are brought just onscreen. The annotation is *not* centered within the viewport. |
 
+ Note that a selection initiated by a single tap gesture is always animated.
+ 
  @param annotation The annotation object to select.
  @param animated If `YES`, the annotation and callout view are moved on-screen.
 
  @note In versions prior to `4.0.0` selecting an offscreen annotation did not
  change the camera.
- 
- @note The `animated` parameter can be considered the same as the value returned from
- `-[MGLMapViewDelgate mapView:shouldMoveOnscreenWhenSelectingAnnotation:]`.
- See also `-[MGLMapViewDelegate mapView:shouldAnimateAnnotationSelection:` for animation control
  */
 - (void)selectAnnotation:(id <MGLAnnotation>)annotation animated:(BOOL)animated;
 
diff --git a/platform/ios/src/MGLMapView.mm b/platform/ios/src/MGLMapView.mm
index 7fb47a640f..79fe9b8ea0 100644
--- a/platform/ios/src/MGLMapView.mm
+++ b/platform/ios/src/MGLMapView.mm
@@ -1715,11 +1715,11 @@ public:
         
         BOOL moveOnscreen = YES;
         
-        if ([self.delegate respondsToSelector:@selector(mapView:shouldMoveOnscreenWhenSelectingAnnotation:)]) {
-            moveOnscreen = [self.delegate mapView:self shouldMoveOnscreenWhenSelectingAnnotation:annotation];
+        if ([self.delegate respondsToSelector:@selector(mapView:shouldMoveAnnotationOnscreenInResponseToUserSelection:)]) {
+            moveOnscreen = [self.delegate mapView:self shouldMoveAnnotationOnscreenInResponseToUserSelection:annotation];
         }
         
-        [self selectAnnotation:annotation moveOnscreen:moveOnscreen calloutPositioningRect:positionRect];
+        [self selectAnnotation:annotation animated:YES moveOnscreen:moveOnscreen calloutPositioningRect:positionRect];
     }
     else if (self.selectedAnnotation)
     {
@@ -4370,12 +4370,17 @@ public:
 
 - (void)selectAnnotation:(id <MGLAnnotation>)annotation animated:(BOOL)animated
 {
+    [self selectAnnotation:annotation animated:animated moveOnscreen:animated];
+}
+
+- (void)selectAnnotation:(id <MGLAnnotation>)annotation animated:(BOOL)animated moveOnscreen:(BOOL)moveOnscreen
+{
     CGRect positioningRect = [self positioningRectForAnnotation:annotation defaultCalloutPoint:CGPointZero];
     
-    [self selectAnnotation:annotation moveOnscreen:animated calloutPositioningRect:positioningRect];
+    [self selectAnnotation:annotation animated:animated moveOnscreen:moveOnscreen calloutPositioningRect:positioningRect];
 }
 
-- (void)selectAnnotation:(id <MGLAnnotation>)annotation moveOnscreen:(BOOL)moveOnscreen calloutPositioningRect:(CGRect)calloutPositioningRect
+- (void)selectAnnotation:(id <MGLAnnotation>)annotation animated:(BOOL)animated moveOnscreen:(BOOL)moveOnscreen calloutPositioningRect:(CGRect)calloutPositioningRect
 {
     if ( ! annotation) return;
 
@@ -4383,12 +4388,6 @@ public:
 
     [self deselectAnnotation:self.selectedAnnotation animated:NO];
 
-    BOOL animateSelection = YES;
-    
-    if ([self.delegate respondsToSelector:@selector(mapView:shouldAnimateAnnotationSelection:)]) {
-        animateSelection = [self.delegate mapView:self shouldAnimateAnnotationSelection:annotation];
-    }
-    
     // Add the annotation to the map if it hasn’t been added yet.
     MGLAnnotationTag annotationTag = [self annotationTagForAnnotation:annotation];
     if (annotationTag == MGLAnnotationTagNotFound && annotation != self.userLocation)
@@ -4409,7 +4408,7 @@ public:
                 calloutPositioningRect = annotationView.frame;
                 [annotationView.superview bringSubviewToFront:annotationView];
 
-                [annotationView setSelected:YES animated:animateSelection];
+                [annotationView setSelected:YES animated:animated];
             }
         }
 
@@ -4545,7 +4544,7 @@ public:
     [calloutView presentCalloutFromRect:calloutPositioningRect
                                  inView:self.glView
                       constrainedToRect:constrainedRect
-                               animated:animateSelection];
+                               animated:animated];
 
     // notify delegate
     if ([self.delegate respondsToSelector:@selector(mapView:didSelectAnnotation:)])
@@ -4562,7 +4561,7 @@ public:
     {
         CGPoint center = CGPointMake(CGRectGetMidX(constrainedRect), CGRectGetMidY(constrainedRect));
         CLLocationCoordinate2D centerCoord = [self convertPoint:center toCoordinateFromView:self];
-        [self setCenterCoordinate:centerCoord animated:animateSelection];
+        [self setCenterCoordinate:centerCoord animated:animated];
     }
 }
 
diff --git a/platform/ios/src/MGLMapViewDelegate.h b/platform/ios/src/MGLMapViewDelegate.h
index 596124ff93..9c2caf8bb8 100644
--- a/platform/ios/src/MGLMapViewDelegate.h
+++ b/platform/ios/src/MGLMapViewDelegate.h
@@ -461,32 +461,19 @@ NS_ASSUME_NONNULL_BEGIN
 
 
 /**
- TODO: document
- Returns a Boolean value indicating whether the annotation should be moved on-screen.
+ Returns a Boolean value indicating whether the annotation should be moved on-screen
+ in response to a single tap selection.
  
- If the delegate does not implement this method, the default is `YES`.
+ If the delegate does not implement this method, the default value is `YES`.
  
- This method is useful in cases where the selection is not programmatic (e.g. user taps an annotation)
- The value returned from this method can be considered the same as the `animated` parameter passed to
- `-selectAnnotation:animated:`
- */
-- (BOOL)mapView:(MGLMapView *)mapView shouldMoveOnscreenWhenSelectingAnnotation:(id <MGLAnnotation>)annotation;
-
-
-/**
- TODO: document
- Returns a Boolean value indicating whether the annotation's visual changes should be animated.
- Specifically this controls:
- - The annotation's selection change
- - The presentation of the annotation's callout (if applicable)
- - When moving an off-screen annotation, whether that movement is animated.
+ Note that user-initiated selections are always animated.
  
- If the delegate does not implement this method, the default is `YES`.
- 
- The value returned from this method is NOT the same as the `animated` parameter passed to
- `-selectAnnotation:animated:`
+ @param mapView The map view that has selected the annotation.
+ @param annotation The object representing the shape annotation.
+ @return A Boolean value indicating whether the annotation should be moved onscreen if it and its callout (if it has one) are offscreen.
  */
-- (BOOL)mapView:(MGLMapView *)mapView shouldAnimateAnnotationSelection:(id <MGLAnnotation>)annotation;
+- (BOOL)mapView:(MGLMapView *)mapView shouldMoveAnnotationOnscreenInResponseToUserSelection:(id <MGLAnnotation>)annotation;
+
 
 /**
  Tells the delegate that one of its annotations was selected.
diff --git a/platform/ios/test/MGLMapViewDelegateIntegrationTests.swift b/platform/ios/test/MGLMapViewDelegateIntegrationTests.swift
index 5310955ef4..649c16d11e 100644
--- a/platform/ios/test/MGLMapViewDelegateIntegrationTests.swift
+++ b/platform/ios/test/MGLMapViewDelegateIntegrationTests.swift
@@ -33,10 +33,7 @@ extension MGLMapViewDelegateIntegrationTests: MGLMapViewDelegate {
 
     func mapView(_ mapView: MGLMapView, didFinishLoading style: MGLStyle) {}
 
-    func mapView(_ mapView: MGLMapView, shouldMoveOnscreenWhenSelecting annotation: MGLAnnotation) -> Bool { return true }
-    
-    func mapView(_ mapView: MGLMapView, shouldAnimateAnnotationSelection annotation: MGLAnnotation) -> Bool { return true }
-    
+    func mapView(_ mapView: MGLMapView, shouldMoveAnnotationOnscreenInResponseToUserSelection annotation: MGLAnnotation) -> Bool { return true }
     func mapView(_ mapView: MGLMapView, didSelect annotation: MGLAnnotation) {}
 
     func mapView(_ mapView: MGLMapView, didDeselect annotation: MGLAnnotation) {}