[ios] Mapbox's Location Manager new API. (#12013)

* [ios] The new location manager API provides two new protocols MGLLocationManager and MGLLocationManagerDelegate to handle the location cycle and updates respectively. This enables developers to chose the appropriate location provider according to their needs, or transition between outdoors/indoors location updates.

It does provide a default implementation based on CLLocationManager.

platform/darwin/src/MGLLocationManager.h

@@ -0,0 +1,181 @@
+#import <Foundation/Foundation.h>
+#import <CoreLocation/CoreLocation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+@protocol MGLLocationManagerDelegate;
+
+/**
+ The `MGLLocationManager` protocol defines a set of methods that a class must
+ implement in order to serve as the location manager of an `MGLMapView`. A location
+ manager is responsible for notifying the map view about location-related events,
+ such as a change in the user’s location. This protocol is similar to the
+ Core Location framework’s `CLLocationManager` class, but your implementation
+ does not need to be based on `CLLocationManager`.
+ 
+ */
+@protocol MGLLocationManager <NSObject>
+
+@optional
+
+#pragma mark Configuring Location Update Precision
+
+/**
+ Specifies the minimum distance (measured in meters) a device must move horizontally
+ before a location update is generated.
+ 
+ The default value of this property is `kCLDistanceFilterNone` when `MGLMapView` uses its
+ default location manager.
+ 
+ @see `CLLocationManager.distanceFilter`
+ */
+@property(nonatomic, assign) CLLocationDistance distanceFilter;
+
+/**
+ Specifies the accuracy of the location data.
+ 
+ The default value is `kCLLocationAccuracyBest` when `MGLMapView` uses its
+ default location manager.
+ 
+ @note Determining a location with greater accuracy requires more time and more power.
+ 
+ @see `CLLocationManager.desiredAccuracy`
+ */
+@property (nonatomic, assign) CLLocationAccuracy desiredAccuracy;
+
+/**
+ Specifies the type of user activity associated with the location updates.
+ 
+ The location manager uses this property as a cue to determine when location updates
+ may be automatically paused.
+ 
+ The default value is `CLActivityTypeOther` when `MGLMapView` uses its
+ default location manager.
+ 
+ @see `CLLocationManager.activityType`
+ */
+@property (nonatomic, assign) CLActivityType activityType;
+
+@required
+
+/**
+ The delegate to receive location updates.
+ 
+ Do not set the location manager’s delegate yourself. `MGLMapView` sets this property
+ after the location manager becomes `MGLMapView`’s location manager.
+ */
+@property (nonatomic, weak) id<MGLLocationManagerDelegate> delegate;
+
+#pragma mark Requesting Authorization for Location Services
+
+/**
+ Returns the current localization authorization status.
+ 
+ @see `+[CLLocationManger authorizationStatus]`
+ */
+@property (nonatomic, readonly) CLAuthorizationStatus authorizationStatus;
+
+/**
+ Requests permission to use the location services whenever the app is running.
+ */
+- (void)requestAlwaysAuthorization;
+
+/**
+ Requests permission to use the location services while the app is in
+ the foreground.
+ */
+- (void)requestWhenInUseAuthorization;
+
+#pragma mark Initiating Location Updates
+
+/**
+ Starts the generation of location updates that reports the user's current location.
+ */
+- (void)startUpdatingLocation;
+
+/**
+ Stops the generation of location updates.
+ */
+- (void)stopUpdatingLocation;
+
+#pragma mark Initiating Heading Updates
+
+/**
+ Specifies a physical device orientation.
+ */
+@property (nonatomic) CLDeviceOrientation headingOrientation;
+
+/**
+ Starts the generation of heading updates that reports the user's current hading.
+ */
+- (void)startUpdatingHeading;
+
+/**
+ Stops the generation of heading updates.
+ */
+- (void)stopUpdatingHeading;
+
+/**
+ Dissmisses immediately the heading calibration view from screen.
+ */
+- (void)dismissHeadingCalibrationDisplay;
+
+@end
+
+/**
+ The `MGLLocationManagerDelegate` protocol defines a set of methods that respond
+ to location updates from an `MGLLocationManager` object that is serving as the
+ location manager of an `MGLMapView`.
+ */
+@protocol MGLLocationManagerDelegate <NSObject>
+
+#pragma mark Responding to Location Updates
+
+/**
+ Notifies the delegate with the new location data.
+ 
+ @param manager The location manager reporting the update.
+ @param locations An array of `CLLocation` objects in chronological order,
+ with the last object representing the most recent location. This array
+ contains multiple `CLLocation` objects when `MGLMapView` uses  its
+ default location manager.
+ */
+- (void)locationManager:(id<MGLLocationManager>)manager
+     didUpdateLocations:(NSArray<CLLocation *> *)locations;
+
+#pragma mark Responding to Heading Updates
+
+/**
+ Notifies the delegate with the new heading data.
+ 
+ @param manager The location manager reporting the update.
+ @param newHeading The new heading update.
+ */
+- (void)locationManager:(id<MGLLocationManager>)manager
+       didUpdateHeading:(CLHeading *)newHeading;
+
+/**
+ Asks the delegate if the calibration alert should be displayed.
+ 
+ @param manager The location manager reporting the calibration.
+ */
+- (BOOL)locationManagerShouldDisplayHeadingCalibration:(id<MGLLocationManager>)manager;
+
+#pragma mark Responding to Location Updates Errors
+
+/**
+ Notifies the delegate that the location manager was unable to retrieve
+ location updates.
+ 
+ @param manager The location manager reporting the error.
+ @param error An error object containing the error code that indicates
+ why the location manager failed.
+ */
+- (void)locationManager:(id<MGLLocationManager>)manager
+       didFailWithError:(nonnull NSError *)error;
+
+@optional
+
+@end
+
+NS_ASSUME_NONNULL_END

platform/darwin/src/MGLLocationManager.m

@@ -0,0 +1,116 @@
+#import "MGLLocationManager_Private.h"
+
+@interface MGLCLLocationManager()<CLLocationManagerDelegate>
+
+@property (nonatomic) CLLocationManager *locationManager;
+
+@end
+
+@implementation MGLCLLocationManager
+
+- (instancetype)init
+{
+    if (self = [super init]) {
+        _locationManager = [[CLLocationManager alloc] init];
+        _locationManager.delegate = self;
+    }
+    return self;
+}
+
+@synthesize delegate;
+
+- (void)setHeadingOrientation:(CLDeviceOrientation)headingOrientation
+{
+    self.locationManager.headingOrientation = headingOrientation;
+}
+
+- (CLDeviceOrientation)headingOrientation
+{
+    return self.locationManager.headingOrientation;
+}
+
+- (void)setDesiredAccuracy:(CLLocationAccuracy)desiredAccuracy {
+    self.locationManager.desiredAccuracy = desiredAccuracy;
+}
+
+- (CLLocationAccuracy)desiredAccuracy {
+    return self.locationManager.desiredAccuracy;
+}
+
+- (CLAuthorizationStatus)authorizationStatus {
+    return [CLLocationManager authorizationStatus];
+}
+
+- (void)setActivityType:(CLActivityType)activityType {
+    self.locationManager.activityType = activityType;
+}
+
+- (CLActivityType)activityType {
+    return self.locationManager.activityType;
+}
+
+- (void)dismissHeadingCalibrationDisplay {
+    [self.locationManager dismissHeadingCalibrationDisplay];
+}
+
+- (void)requestAlwaysAuthorization {
+    [self.locationManager requestAlwaysAuthorization];
+}
+
+- (void)requestWhenInUseAuthorization {
+    [self.locationManager requestWhenInUseAuthorization];
+}
+
+- (void)startUpdatingHeading {
+    [self.locationManager startUpdatingHeading];
+}
+
+- (void)startUpdatingLocation {
+    [self.locationManager startUpdatingLocation];
+}
+
+- (void)stopUpdatingHeading {
+    [self.locationManager stopUpdatingHeading];
+}
+
+- (void)stopUpdatingLocation {
+    [self.locationManager stopUpdatingLocation];
+}
+
+- (void)dealloc
+{
+    [self.locationManager stopUpdatingLocation];
+    [self.locationManager stopUpdatingHeading];
+    self.locationManager.delegate = nil;
+    self.delegate = nil;
+}
+
+#pragma mark - CLLocationManagerDelegate
+
+- (void)locationManager:(CLLocationManager *)manager didUpdateLocations:(NSArray<CLLocation *> *)locations {
+    if ([self.delegate respondsToSelector:@selector(locationManager:didUpdateLocations:)]) {
+        [self.delegate locationManager:self didUpdateLocations:locations];
+    }
+}
+
+- (void)locationManager:(CLLocationManager *)manager didUpdateHeading:(CLHeading *)newHeading {
+    if ([self.delegate respondsToSelector:@selector(locationManager:didUpdateHeading:)]) {
+        [self.delegate locationManager:self didUpdateHeading:newHeading];
+    }
+}
+
+- (BOOL)locationManagerShouldDisplayHeadingCalibration:(CLLocationManager *)manager {
+    if ([self.delegate respondsToSelector:@selector(locationManagerShouldDisplayHeadingCalibration:)]) {
+        return [self.delegate locationManagerShouldDisplayHeadingCalibration:self];
+    }
+
+    return NO;
+}
+
+- (void)locationManager:(CLLocationManager *)manager didFailWithError:(NSError *)error {
+    if ([self.delegate respondsToSelector:@selector(locationManager:didFailWithError:)]) {
+        [self.delegate locationManager:self didFailWithError:error];
+    }
+}
+
+@end

platform/darwin/src/MGLLocationManager_Private.h

@@ -0,0 +1,5 @@
+#import "MGLLocationManager.h"
+
+@interface MGLCLLocationManager : NSObject<MGLLocationManager>
+
+@end

platform/ios/CHANGELOG.md

@@ -4,8 +4,12 @@ Mapbox welcomes participation and contributions from everyone. Please read [CONT
 
 ## master
 
+### Other changes
+
 * Fixed a crash that occurred when the user started a gesture before the drift animation for a previous gesture was complete. ([#12148](https://github.com/mapbox/mapbox-gl-native/pull/12148))
 * Token string syntax (`"{token}"`) in `MGLSymbolStyleLayer` `text` and `iconImageName` properties is now correctly converted to the appropriate `NSExpression` equivalent. ([#11659](https://github.com/mapbox/mapbox-gl-native/issues/11659))
+* Added an `MGLMapView.locationManager` property and `MGLLocationManager` protocol for tracking user location using a custom alternative to `CLLocationManager`. ([#12013](https://github.com/mapbox/mapbox-gl-native/pull/12013))
+
 
 ## 4.2.0 - July 18, 2018
 

platform/ios/app/MBXCustomLocationViewController.h

@@ -0,0 +1,5 @@
+#import <UIKit/UIKit.h>
+
+@interface MBXCustomLocationViewController : UIViewController
+
+@end