[ios,macos] Tweaks to documentation and method parameters for clarity.

8 files changed, 95 insertions, 55 deletions

diff --git a/platform/ios/app/MBXViewController.m b/platform/ios/app/MBXViewController.m
index 020cebddf0..c612a7fa95 100644
--- a/platform/ios/app/MBXViewController.m
+++ b/platform/ios/app/MBXViewController.m
@@ -54,7 +54,7 @@ typedef NS_ENUM(NSInteger, MBXSettingsAnnotationsRows) {
     MBXSettingsAnnotationsQueryAnnotations,
     MBXSettingsAnnotationsCustomUserDot,
     MBXSettingsAnnotationsRemoveAnnotations,
-    MBXSettingsAnnotationSelectRandomOffscreenAnnotation,
+    MBXSettingsAnnotationSelectRandomOffscreenPointAnnotation,
     MBXSettingsAnnotationCenterSelectedAnnotation,
     MBXSettingsAnnotationAddVisibleAreaPolyline
 };
@@ -343,7 +343,7 @@ typedef NS_ENUM(NSInteger, MBXSettingsMiscellaneousRows) {
                 @"Query Annotations",
                 [NSString stringWithFormat:@"%@ Custom User Dot", (_customUserLocationAnnnotationEnabled ? @"Disable" : @"Enable")],
                 @"Remove Annotations",
-                @"Select an offscreen annotation",
+                @"Select an offscreen point annotation",
                 @"Center selected annotation",
                 @"Add visible area polyline"
             ]];
@@ -474,8 +474,8 @@ typedef NS_ENUM(NSInteger, MBXSettingsMiscellaneousRows) {
                 case MBXSettingsAnnotationsRemoveAnnotations:
                     [self.mapView removeAnnotations:self.mapView.annotations];
                     break;
-                case MBXSettingsAnnotationSelectRandomOffscreenAnnotation:
-                    [self selectAnOffscreenAnnotation];
+                case MBXSettingsAnnotationSelectRandomOffscreenPointAnnotation:
+                    [self selectAnOffscreenPointAnnotation];
                     break;
 
                 case MBXSettingsAnnotationCenterSelectedAnnotation:
@@ -1569,13 +1569,18 @@ typedef NS_ENUM(NSInteger, MBXSettingsMiscellaneousRows) {
     [self presentViewController:alertController animated:YES completion:nil];
 }
 
-- (id<MGLAnnotation>)randomOffscreenAnnotation {
-    NSArray *annotations = self.mapView.annotations;
+- (id<MGLAnnotation>)randomOffscreenPointAnnotation {
+
+    NSPredicate *pointAnnotationPredicate = [NSPredicate predicateWithBlock:^BOOL(id  _Nullable evaluatedObject, NSDictionary<NSString *,id> * _Nullable bindings) {
+        return [evaluatedObject isKindOfClass:[MGLPointAnnotation class]];
+    }];
+
+    NSArray *annotations = [self.mapView.annotations filteredArrayUsingPredicate:pointAnnotationPredicate];
 
     if (annotations.count == 0)
         return nil;
 
-    NSArray *visibleAnnotations = self.mapView.visibleAnnotations;
+    NSArray *visibleAnnotations = [self.mapView.visibleAnnotations filteredArrayUsingPredicate:pointAnnotationPredicate];
 
     if (visibleAnnotations.count == annotations.count)
         return nil;
@@ -1591,8 +1596,8 @@ typedef NS_ENUM(NSInteger, MBXSettingsMiscellaneousRows) {
     return invisibleAnnotations[index];
 }
 
-- (void)selectAnOffscreenAnnotation {
-    id<MGLAnnotation> annotation = [self randomOffscreenAnnotation];
+- (void)selectAnOffscreenPointAnnotation {
+    id<MGLAnnotation> annotation = [self randomOffscreenPointAnnotation];
     if (annotation) {
         [self.mapView selectAnnotation:annotation animated:YES];
 
diff --git a/platform/ios/src/MGLCalloutView.h b/platform/ios/src/MGLCalloutView.h
index 057d5f2bcc..7e7cf2d02e 100644
--- a/platform/ios/src/MGLCalloutView.h
+++ b/platform/ios/src/MGLCalloutView.h
@@ -59,14 +59,19 @@ NS_ASSUME_NONNULL_BEGIN
  If implemented, should provide margins to expand the rect the callout is presented from.
 
  These are used to determine positioning. Currently only the top and bottom properties of the return
- value are used. For example, `{ .top = -50.0, .left = 0.0, .bottom = 0.0, .right = 0.0 }` indicates
- a 50 point margin above the presentation origin rect, in which the callout is assumed to be displayed.
+ value are used. For example, `{ .top = -50.0, .left = -10.0, .bottom = 0.0, .right = -10.0 }` indicates
+ a 50 point margin above the presentation origin rect (and 10 point margins to the left and the right)
+ in which the callout is assumed to be displayed.
 
- @param rect rect that the callout is presented from. This should be the same as the one passed in
- `-presentCalloutFromRect:inView:constrainedToRect:animated:`
- @return margins. Since this is a UIEdgeInsets, values should be negative.
+ There are no assumed defaults for these margins, as they should be calculated from the callout that
+ is to be presented. For example, `SMCalloutView` generates the top margin from the callout height, but
+ the left and right margins from a minimum width that the callout should have.
+
+ @param rect Rect that the callout is presented from. This should be the same as the one passed in
+ `-[MGLCalloutView presentCalloutFromRect:inView:constrainedToRect:animated:]`
+ @return `UIEdgeInsets` representing the margins. Values should be negative.
  */
-- (UIEdgeInsets)marginInsetsHintForPresentationFromRect:(CGRect)rect;
+- (UIEdgeInsets)marginInsetsHintForPresentationFromRect:(CGRect)rect NS_SWIFT_NAME(marginInsetsHintForPresentation(from:));
 
 /**
  A Boolean value indicating whether the callout view should be anchored to
diff --git a/platform/ios/src/MGLMapView.h b/platform/ios/src/MGLMapView.h
index 22fa58643d..eb6cf85e39 100644
--- a/platform/ios/src/MGLMapView.h
+++ b/platform/ios/src/MGLMapView.h
@@ -1200,14 +1200,26 @@ MGL_EXPORT IB_DESIGNABLE
 
  Assigning a new array to this property selects only the first annotation in
  the array.
+
+ @note In versions prior to `4.0.0` if the annotation was offscreen it was not selected.
  */
 @property (nonatomic, copy) NS_ARRAY_OF(id <MGLAnnotation>) *selectedAnnotations;
 
 /**
- Selects an annotation and displays a callout view for it.
+ Selects an annotation and displays its callout view.
+
+ The `animated` parameter determines whether the map is panned to bring the annotation on-screen,
+ specifically:
+
+ | `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. The presentation of the callout is animated. |
+ | `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. |
 
  @param annotation The annotation object to select.
- @param animated If `YES`, the callout view is animated into position.
+ @param animated If `YES`, the annotation and callout view are animated on-screen.
+
+ @note In versions prior to `4.0.0` selecting an offscreen annotation did not change the camera.
  */
 - (void)selectAnnotation:(id <MGLAnnotation>)annotation animated:(BOOL)animated;
 
diff --git a/platform/ios/src/MGLMapView.mm b/platform/ios/src/MGLMapView.mm
index 82f78ba169..3daea33367 100644
--- a/platform/ios/src/MGLMapView.mm
+++ b/platform/ios/src/MGLMapView.mm
@@ -1628,7 +1628,7 @@ public:
     {
         CGPoint calloutPoint = [singleTap locationInView:self];
         CGRect positionRect = [self positioningRectForAnnotation:annotation defaultCalloutPoint:calloutPoint];
-        [self selectAnnotation:annotation animated:YES animateSelection:YES calloutPositioningRect:positionRect];
+        [self selectAnnotation:annotation moveOnscreen:YES animateSelection:YES calloutPositioningRect:positionRect];
     }
     else if (self.selectedAnnotation)
     {
@@ -4289,10 +4289,10 @@ public:
 - (void)selectAnnotation:(id <MGLAnnotation>)annotation animated:(BOOL)animated
 {
     CGRect positioningRect = [self positioningRectForAnnotation:annotation defaultCalloutPoint:CGPointZero];
-    [self selectAnnotation:annotation animated:animated animateSelection:YES calloutPositioningRect:positioningRect];
+    [self selectAnnotation:annotation moveOnscreen:animated animateSelection:YES calloutPositioningRect:positioningRect];
 }
 
-- (void)selectAnnotation:(id <MGLAnnotation>)annotation animated:(BOOL)animated animateSelection:(BOOL)animateSelection calloutPositioningRect:(CGRect)calloutPositioningRect
+- (void)selectAnnotation:(id <MGLAnnotation>)annotation moveOnscreen:(BOOL)moveOnscreen animateSelection:(BOOL)animateSelection calloutPositioningRect:(CGRect)calloutPositioningRect
 {
     if ( ! annotation) return;
 
@@ -4326,8 +4326,11 @@ public:
 
     self.selectedAnnotation = annotation;
 
-    // Determine if we need to move offscreen annotations on screen
-    BOOL moveOffscreenAnnotation = [self isBringingAnnotationOnscreenSupportedForAnnotation:annotation animated:animated];
+    // Determine if we're allowed to move this offscreen annotation on screen, even though we've asked it to
+    if (moveOnscreen) {
+        moveOnscreen = [self isBringingAnnotationOnscreenSupportedForAnnotation:annotation animated:animateSelection];
+    }
+
     CGRect expandedPositioningRect = UIEdgeInsetsInsetRect(calloutPositioningRect, MGLMapViewOffscreenAnnotationPadding);
 
     // Used for callout positioning, and moving offscreen annotations onscreen.
@@ -4400,15 +4403,15 @@ public:
 
         // If the callout view provides inset (outset) information, we can use it to expand our positioning
         // rect, which we then use to help move the annotation on-screen if want need to.
-        if (moveOffscreenAnnotation && [calloutView respondsToSelector:@selector(marginInsetsHintForPresentationFromRect:)]) {
+        if (moveOnscreen && [calloutView respondsToSelector:@selector(marginInsetsHintForPresentationFromRect:)]) {
             UIEdgeInsets margins = [calloutView marginInsetsHintForPresentationFromRect:calloutPositioningRect];
             expandedPositioningRect = UIEdgeInsetsInsetRect(expandedPositioningRect, margins);
         }
     }
 
-    if (moveOffscreenAnnotation)
+    if (moveOnscreen)
     {
-        moveOffscreenAnnotation = NO;
+        moveOnscreen = NO;
 
         // Need to consider the content insets.
         CGRect bounds = UIEdgeInsetsInsetRect(self.bounds, self.contentInset);
@@ -4417,23 +4420,23 @@ public:
         if (CGRectGetMinX(calloutPositioningRect) < CGRectGetMinX(bounds))
         {
             constrainedRect.origin.x = expandedPositioningRect.origin.x;
-            moveOffscreenAnnotation = YES;
+            moveOnscreen = YES;
         }
         else if (CGRectGetMaxX(calloutPositioningRect) > CGRectGetMaxX(bounds))
         {
             constrainedRect.origin.x = CGRectGetMaxX(expandedPositioningRect) - constrainedRect.size.width;
-            moveOffscreenAnnotation = YES;
+            moveOnscreen = YES;
         }
 
         if (CGRectGetMinY(calloutPositioningRect) < CGRectGetMinY(bounds))
         {
             constrainedRect.origin.y = expandedPositioningRect.origin.y;
-            moveOffscreenAnnotation = YES;
+            moveOnscreen = YES;
         }
         else if (CGRectGetMaxY(calloutPositioningRect) > CGRectGetMaxY(bounds))
         {
             constrainedRect.origin.y = CGRectGetMaxY(expandedPositioningRect) - constrainedRect.size.height;
-            moveOffscreenAnnotation = YES;
+            moveOnscreen = YES;
         }
     }
 
@@ -4441,7 +4444,7 @@ public:
     [calloutView presentCalloutFromRect:calloutPositioningRect
                                  inView:self.glView
                       constrainedToRect:constrainedRect
-                               animated:animated];
+                               animated:animateSelection];
 
     // notify delegate
     if ([self.delegate respondsToSelector:@selector(mapView:didSelectAnnotation:)])
@@ -4454,11 +4457,11 @@ public:
         [self.delegate mapView:self didSelectAnnotationView:annotationView];
     }
 
-    if (moveOffscreenAnnotation)
+    if (moveOnscreen)
     {
         CGPoint center = CGPointMake(CGRectGetMidX(constrainedRect), CGRectGetMidY(constrainedRect));
         CLLocationCoordinate2D centerCoord = [self convertPoint:center toCoordinateFromView:self];
-        [self setCenterCoordinate:centerCoord animated:animated];
+        [self setCenterCoordinate:centerCoord animated:animateSelection];
     }
 }
 
diff --git a/platform/macos/app/Base.lproj/MainMenu.xib b/platform/macos/app/Base.lproj/MainMenu.xib
index c90a4a6016..8f0aeaf69c 100644
--- a/platform/macos/app/Base.lproj/MainMenu.xib
+++ b/platform/macos/app/Base.lproj/MainMenu.xib
@@ -545,10 +545,10 @@
                                     <action selector="drawAnimatedAnnotation:" target="-1" id="CYM-WB-s97"/>
                                 </connections>
                             </menuItem>
-                            <menuItem title="Select an Offscreen Annotation" id="Xy2-Cc-RUB">
+                            <menuItem title="Select an Offscreen Point Annotation" id="Xy2-Cc-RUB">
                                 <modifierMask key="keyEquivalentModifierMask"/>
                                 <connections>
-                                    <action selector="selectOffscreenAnnotation:" target="-1" id="AHm-rf-mG4"/>
+                                    <action selector="selectOffscreenPointAnnotation:" target="-1" id="Fhm-l3-G6h"/>
                                 </connections>
                             </menuItem>
                             <menuItem title="Show All Annotations" keyEquivalent="A" id="yMj-uM-8SN">
diff --git a/platform/macos/app/MapDocument.m b/platform/macos/app/MapDocument.m
index 14d765d5c9..d315bcf7d0 100644
--- a/platform/macos/app/MapDocument.m
+++ b/platform/macos/app/MapDocument.m
@@ -642,17 +642,23 @@ NS_ARRAY_OF(id <MGLAnnotation>) *MBXFlattenedShapes(NS_ARRAY_OF(id <MGLAnnotatio
 }
 
 
-- (id<MGLAnnotation>)randomOffscreenAnnotation {
-    NSArray *annotations = self.mapView.annotations;
+- (id<MGLAnnotation>)randomOffscreenPointAnnotation {
+
+    NSPredicate *pointAnnotationPredicate = [NSPredicate predicateWithBlock:^BOOL(id  _Nullable evaluatedObject, NSDictionary<NSString *,id> * _Nullable bindings) {
+        return [evaluatedObject isKindOfClass:[MGLPointAnnotation class]];
+    }];
+
+    NSArray *annotations = [self.mapView.annotations filteredArrayUsingPredicate:pointAnnotationPredicate];
+
 
     if (annotations.count == 0)
         return nil;
 
-    // NOTE: This occasionally returns nil - see
+    // NOTE: self.mapView.visibleAnnotations occasionally returns nil - see
     // https://github.com/mapbox/mapbox-gl-native/issues/11296
-    NSArray *visibleAnnotations = self.mapView.visibleAnnotations;
+    NSArray *visibleAnnotations = [self.mapView.visibleAnnotations filteredArrayUsingPredicate:pointAnnotationPredicate];
 
-    NSLog(@"Number of visible annotations = %ld", visibleAnnotations.count);
+    NSLog(@"Number of visible point annotations = %ld", visibleAnnotations.count);
 
     if (visibleAnnotations.count == annotations.count)
         return nil;
@@ -668,8 +674,8 @@ NS_ARRAY_OF(id <MGLAnnotation>) *MBXFlattenedShapes(NS_ARRAY_OF(id <MGLAnnotatio
     return invisibleAnnotations[index];
 }
 
-- (IBAction)selectOffscreenAnnotation:(id)sender {
-    id<MGLAnnotation> annotation = [self randomOffscreenAnnotation];
+- (IBAction)selectOffscreenPointAnnotation:(id)sender {
+    id<MGLAnnotation> annotation = [self randomOffscreenPointAnnotation];
     if (annotation) {
         [self.mapView selectAnnotation:annotation];
 
@@ -1149,7 +1155,7 @@ NS_ARRAY_OF(id <MGLAnnotation>) *MBXFlattenedShapes(NS_ARRAY_OF(id <MGLAnnotatio
     if (menuItem.action == @selector(insertGraticuleLayer:)) {
         return ![self.mapView.style sourceWithIdentifier:@"graticule"];
     }
-    if (menuItem.action == @selector(selectOffscreenAnnotation:)) {
+    if (menuItem.action == @selector(selectOffscreenPointAnnotation:)) {
         return YES;
     }
     if (menuItem.action == @selector(showAllAnnotations:) || menuItem.action == @selector(removeAllAnnotations:)) {
diff --git a/platform/macos/src/MGLMapView.h b/platform/macos/src/MGLMapView.h
index 344052c310..786f1cf3a1 100644
--- a/platform/macos/src/MGLMapView.h
+++ b/platform/macos/src/MGLMapView.h
@@ -721,13 +721,20 @@ MGL_EXPORT IB_DESIGNABLE
 
  Assigning a new array to this property selects only the first annotation in the
  array.
+
+ @note In versions prior to `4.0.0` if the annotation was offscreen it was not selected.
  */
 @property (nonatomic, copy) NS_ARRAY_OF(id <MGLAnnotation>) *selectedAnnotations;
 
 /**
  Selects an annotation and displays a callout popover for it.
 
+ 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.
+
  @param annotation The annotation object to select.
+
+ @note In versions prior to `4.0.0` selecting an offscreen annotation did not change the camera.
  */
 - (void)selectAnnotation:(id <MGLAnnotation>)annotation;
 
diff --git a/platform/macos/src/MGLMapView.mm b/platform/macos/src/MGLMapView.mm
index d4ddf69a5e..9cab9a76da 100644
--- a/platform/macos/src/MGLMapView.mm
+++ b/platform/macos/src/MGLMapView.mm
@@ -2223,10 +2223,10 @@ public:
 
 - (void)selectAnnotation:(id <MGLAnnotation>)annotation atPoint:(NSPoint)gesturePoint
 {
-    [self selectAnnotation:annotation atPoint:gesturePoint animated:YES];
+    [self selectAnnotation:annotation atPoint:gesturePoint moveOnscreen:YES animateSelection:YES];
 }
 
-- (void)selectAnnotation:(id <MGLAnnotation>)annotation atPoint:(NSPoint)gesturePoint animated:(BOOL)animated
+- (void)selectAnnotation:(id <MGLAnnotation>)annotation atPoint:(NSPoint)gesturePoint moveOnscreen:(BOOL)moveOnscreen animateSelection:(BOOL)animateSelection
 {
     id <MGLAnnotation> selectedAnnotation = self.selectedAnnotation;
     if (annotation == selectedAnnotation) {
@@ -2242,12 +2242,14 @@ public:
         [self addAnnotation:annotation];
     }
 
-    BOOL checkOffscreenAnnotation = [self isBringingAnnotationOnscreenSupportedForAnnotation:annotation animated:animated];
+    if (moveOnscreen) {
+        moveOnscreen = [self isBringingAnnotationOnscreenSupportedForAnnotation:annotation animated:animateSelection];
+    }
 
     // The annotation's anchor will bounce to the current click.
     NSRect positioningRect = [self positioningRectForCalloutForAnnotationWithTag:annotationTag];
 
-    if (!checkOffscreenAnnotation && NSIsEmptyRect(NSIntersectionRect(positioningRect, self.bounds))) {
+    if (!moveOnscreen && NSIsEmptyRect(NSIntersectionRect(positioningRect, self.bounds))) {
         positioningRect = CGRectMake(gesturePoint.x, gesturePoint.y, positioningRect.size.width, positioningRect.size.height);
     }
 
@@ -2278,8 +2280,10 @@ public:
         [callout showRelativeToRect:positioningRect ofView:self preferredEdge:edge];
     }
 
-    if (checkOffscreenAnnotation)
+    if (moveOnscreen)
     {
+        moveOnscreen = NO;
+
         NSRect (^edgeInsetsInsetRect)(NSRect, NSEdgeInsets) = ^(NSRect rect, NSEdgeInsets insets) {
             return NSMakeRect(rect.origin.x + insets.left,
                               rect.origin.y + insets.top,
@@ -2294,36 +2298,34 @@ public:
         CGRect constrainedRect = edgeInsetsInsetRect(self.bounds, self.contentInsets);
         CGRect bounds          = constrainedRect;
 
-        BOOL moveOffscreenAnnotation = NO;
-
         // Any one of these cases should trigger a move onscreen
         if (CGRectGetMinX(positioningRect) < CGRectGetMinX(bounds))
         {
             constrainedRect.origin.x = expandedPositioningRect.origin.x;
-            moveOffscreenAnnotation = YES;
+            moveOnscreen = YES;
         }
         else if (CGRectGetMaxX(positioningRect) > CGRectGetMaxX(bounds))
         {
             constrainedRect.origin.x = CGRectGetMaxX(expandedPositioningRect) - constrainedRect.size.width;
-            moveOffscreenAnnotation = YES;
+            moveOnscreen = YES;
         }
 
         if (CGRectGetMinY(positioningRect) < CGRectGetMinY(bounds))
         {
             constrainedRect.origin.y = expandedPositioningRect.origin.y;
-            moveOffscreenAnnotation = YES;
+            moveOnscreen = YES;
         }
         else if (CGRectGetMaxY(positioningRect) > CGRectGetMaxY(bounds))
         {
             constrainedRect.origin.y = CGRectGetMaxY(expandedPositioningRect) - constrainedRect.size.height;
-            moveOffscreenAnnotation = YES;
+            moveOnscreen = YES;
         }
 
-        if (moveOffscreenAnnotation)
+        if (moveOnscreen)
         {
             CGPoint center = CGPointMake(CGRectGetMidX(constrainedRect), CGRectGetMidY(constrainedRect));
             CLLocationCoordinate2D centerCoord = [self convertPoint:center toCoordinateFromView:self];
-            [self setCenterCoordinate:centerCoord animated:animated];
+            [self setCenterCoordinate:centerCoord animated:animateSelection];
         }
     }
 }