[ios] Made user dot position configurable

The user dot or user puck’s position is now configurable via a new alignment property in any user tracking mode. Also, -setUserTrackingMode:animated: is now exposed publicly, and setting its animated parameter to NO skips the initial animation.

4 files changed, 50 insertions, 6 deletions

diff --git a/.jazzy.yaml b/.jazzy.yaml
index e0c7b721bf..99224d9626 100644
--- a/.jazzy.yaml
+++ b/.jazzy.yaml
@@ -27,6 +27,7 @@ custom_categories:
     children:
       - MGLAnnotation
       - MGLAnnotationImage
+      - MGLAnnotationVerticalAlignment
       - MGLCalloutView
       - MGLCalloutViewDelegate
       - MGLMultiPoint
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9653d34886..444e0a74f0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -47,7 +47,7 @@ Known issues:
 - A new method on MGLMapView, `-flyToCamera:withDuration:completionHandler:`, lets you transition between viewpoints along an arc as if by aircraft. ([#3171](https://github.com/mapbox/mapbox-gl-native/pull/3171), [#3301](https://github.com/mapbox/mapbox-gl-native/pull/3301))
 - MGLMapCamera’s `altitude` values now match those of MKMapCamera. ([#3362](https://github.com/mapbox/mapbox-gl-native/pull/3362))
 - MGLMapView properties like `centerCoordinate` and `camera` now offset the center to account for any translucent top or bottom bar. As a result, when user tracking is enabled and the map view is an immediate child of a view controller, the user dot is centered in the unobscured portion of the map view. To override this offset, modify the `contentInset` property; you may also need to set the containing view controller’s `automaticallyAdjustsScrollViewInsets` property to `NO`. ([#3583](https://github.com/mapbox/mapbox-gl-native/pull/3583))
-- In user tracking mode, the user dot stays in a fixed position within MGLMapView while the map pans smoothly. In course tracking mode, the user puck is shifted towards the bottom of the view. ([#3589](https://github.com/mapbox/mapbox-gl-native/pull/3589))
+- In user tracking mode, the user dot stays in a fixed position within MGLMapView while the map pans smoothly. A new property, `userLocationVerticalAlignment`, determines the user dot’s fixed position. ([#3589](https://github.com/mapbox/mapbox-gl-native/pull/3589))
 - The user dot’s callout view is now centered above the user dot. It was previously offset slightly to the left. ([#3261](https://github.com/mapbox/mapbox-gl-native/pull/3261))
 - Fixed an issue with small map views not properly fitting annotations within bounds. (#[3407](https://github.com/mapbox/mapbox-gl-native/pull/3407))
 - When the user rotates the map to within 7° of true north, the map view now snaps to true north. ([#3403](https://github.com/mapbox/mapbox-gl-native/pull/3403))
diff --git a/include/mbgl/ios/MGLMapView.h b/include/mbgl/ios/MGLMapView.h
index d2bd849176..847864e29a 100644
--- a/include/mbgl/ios/MGLMapView.h
+++ b/include/mbgl/ios/MGLMapView.h
@@ -19,6 +19,16 @@ NS_ASSUME_NONNULL_BEGIN
 @protocol MGLOverlay;
 @protocol MGLCalloutView;
 
+/** The vertical alignment of an annotation within a map view. */
+typedef NS_ENUM(NSUInteger, MGLAnnotationVerticalAlignment) {
+    /** Aligns the annotation vertically in the center of the map view. */
+    MGLAnnotationVerticalAlignmentCenter = 0,
+    /** Aligns the annotation vertically at the top of the map view. */
+    MGLAnnotationVerticalAlignmentTop,
+    /** Aligns the annotation vertically at the bottom of the map view. */
+    MGLAnnotationVerticalAlignmentBottom,
+};
+
 /**
  An interactive, customizable map view with an interface similar to the one
  provided by Apple's MapKit.
@@ -219,6 +229,24 @@ IB_DESIGNABLE
 @property (nonatomic, assign) MGLUserTrackingMode userTrackingMode;
 
 /**
+ Sets the mode used to track the user location, with an optional transition.
+ 
+ @param mode The mode used to track the user location.
+ @param animated If `YES`, there is an animated transition from the current
+    viewport to a viewport that results from the change to `mode`. If `NO`, the
+    map view instantaneously changes to the new viewport. This parameter only
+    affects the initial transition; subsequent changes to the user location or
+    heading are always animated.
+ */
+- (void)setUserTrackingMode:(MGLUserTrackingMode)mode animated:(BOOL)animated;
+
+/**
+ The vertical alignment of the user location annotation within the receiver. The
+ default value is `MGLAnnotationVerticalAlignmentCenter`.
+ */
+@property (nonatomic, assign) MGLAnnotationVerticalAlignment userLocationVerticalAlignment;
+
+/**
  Whether the map view should display a heading calibration alert when necessary.
  The default value is `YES`.
  */
diff --git a/platform/ios/src/MGLMapView.mm b/platform/ios/src/MGLMapView.mm
index 079e5a8432..93b30cb177 100644
--- a/platform/ios/src/MGLMapView.mm
+++ b/platform/ios/src/MGLMapView.mm
@@ -53,9 +53,9 @@ typedef NS_ENUM(NSUInteger, MGLUserTrackingState) {
     /// The map view is not yet tracking the user location.
     MGLUserTrackingStatePossible = 0,
     /// The map view has begun to move to the first reported user location.
-    MGLUserTrackingStateBegan = 1,
+    MGLUserTrackingStateBegan,
     /// The map view has finished moving to the first reported user location.
-    MGLUserTrackingStateChanged = 2,
+    MGLUserTrackingStateChanged,
 };
 
 NSString *const MGLMapboxSetupDocumentationURLDisplayString = @"mapbox.com/help/first-steps-ios-sdk";
@@ -3030,6 +3030,15 @@ std::chrono::steady_clock::duration MGLDurationInSeconds(float duration)
     }
 }
 
+- (void)setUserLocationVerticalAlignment:(MGLAnnotationVerticalAlignment)alignment
+{
+    _userLocationVerticalAlignment = alignment;
+    if (self.userTrackingMode != MGLUserTrackingModeNone)
+    {
+        [self locationManager:self.locationManager didUpdateLocations:@[self.userLocation.location] animated:YES];
+    }
+}
+
 - (void)locationManager:(CLLocationManager *)manager didUpdateLocations:(NSArray *)locations
 {
     [self locationManager:manager didUpdateLocations:locations animated:YES];
@@ -3449,9 +3458,15 @@ std::chrono::steady_clock::duration MGLDurationInSeconds(float duration)
     
     // When tracking course, it’s more important to see the road ahead, so
     // weight the user dot down towards the bottom.
-    if (self.userTrackingMode == MGLUserTrackingModeFollowWithCourse)
-    {
-        center.y = CGRectGetHeight(contentFrame) - CGRectGetHeight(self.userLocationAnnotationView.frame);
+    switch (self.userLocationVerticalAlignment) {
+        case MGLAnnotationVerticalAlignmentCenter:
+            break;
+        case MGLAnnotationVerticalAlignmentTop:
+            center.y = CGRectGetHeight(self.userLocationAnnotationView.frame);
+            break;
+        case MGLAnnotationVerticalAlignmentBottom:
+            center.y = CGRectGetHeight(contentFrame) - CGRectGetHeight(self.userLocationAnnotationView.frame);
+            break;
     }
     
     return center;