closes #1082, refs #756: user dot on map in iOS

5 files changed, 89 insertions, 0 deletions

diff --git a/include/mbgl/ios/MGLMapView.h b/include/mbgl/ios/MGLMapView.h
index 0fbd498fc3..b41e2f5d72 100644
--- a/include/mbgl/ios/MGLMapView.h
+++ b/include/mbgl/ios/MGLMapView.h
@@ -1,6 +1,10 @@
 #import <UIKit/UIKit.h>
 #import <CoreLocation/CoreLocation.h>
 
+#import "MGLTypes.h"
+
+@class MGLUserLocation;
+
 @protocol MGLMapViewDelegate;
 @protocol MGLAnnotation;
 
@@ -234,6 +238,30 @@
 *   @param animated If `YES`, the callout view is animated offscreen. */
 - (void)deselectAnnotation:(id <MGLAnnotation>)annotation animated:(BOOL)animated;
 
+#pragma mark - Displaying the User's Location
+
+/** A Boolean value indicating whether the map may display the user location.
+ 
+    This property does not indicate whether the user’s position is actually visible on the map, only whether the map view is allowed to display it. To determine whether the user’s position is visible, use the userLocationVisible property. The default value of this property is `NO`.
+
+    Setting this property to `YES` causes the map view to use the Core Location framework to find the current location. As long as this property is `YES`, the map view continues to track the user’s location and update it periodically.
+
+    On iOS 8 and above, your app must specify a value for `NSLocationWhenInUseUsageDescription` in its `Info.plist` to satisfy the requirements of the underlying Core Location framework when enabling this property.
+ */
+@property (nonatomic, assign) BOOL showsUserLocation;
+
+/// Returns a Boolean value indicating whether the user currently sees the user location annotation.
+@property (nonatomic, assign, readonly, getter=isUserLocationVisible) BOOL userLocationVisible;
+
+/// Returns the annotation object indicating the user’s current location.
+@property (nonatomic, readonly) MGLUserLocation *userLocation;
+
+/** The mode used to track the user location. */
+@property (nonatomic, assign) MGLUserTrackingMode userTrackingMode;
+
+/** Whether the map view should display a heading calibration alert when necessary. The default value is `YES`. */
+@property (nonatomic, assign) BOOL displayHeadingCalibration;
+
 #pragma mark - Debugging
 
 /** @name Debugging */
@@ -333,6 +361,27 @@
 // TODO
 - (void)mapViewDidFinishRenderingMap:(MGLMapView *)mapView fullyRendered:(BOOL)fullyRendered;
 
+#pragma mark - Tracking the User Location
+
+/// Tells the delegate that the map view will begin tracking the user’s location.
+- (void)mapViewWillStartLocatingUser:(MGLMapView *)mapView;
+
+/// Tells the delegate that the map view has stopped tracking the user’s location.
+- (void)mapViewDidStopLocatingUser:(MGLMapView *)mapView;
+
+/// Tells the delegate that the map view has updated the user’s location to the given location.
+- (void)mapView:(MGLMapView *)mapView didUpdateUserLocation:(MGLUserLocation *)userLocation;
+
+/// Tells the delegate that the map view has failed to locate the user.
+- (void)mapView:(MGLMapView *)mapView didFailToLocateUserWithError:(NSError *)error;
+
+/**
+    Tells the delegate that the map view’s user tracking mode has changed.
+ 
+    This method is called after the map view asynchronously changes to reflect the new user tracking mode, for example by beginning to zoom or rotate.
+ */
+- (void)mapView:(MGLMapView *)mapView didChangeUserTrackingMode:(MGLUserTrackingMode)mode animated:(BOOL)animated;
+
 #pragma mark - Managing Annotations
 
 /** @name Managing Annotations */
diff --git a/include/mbgl/ios/MGLTypes.h b/include/mbgl/ios/MGLTypes.h
index 7a17445770..0d7ae5f6d1 100644
--- a/include/mbgl/ios/MGLTypes.h
+++ b/include/mbgl/ios/MGLTypes.h
@@ -15,3 +15,11 @@ extern NSString *const MGLStyleValueTypeFunctionMaximumZoom;
 extern NSString *const MGLStyleValueTypeFunctionLinear;
 extern NSString *const MGLStyleValueTypeFunctionExponential;
 extern NSString *const MGLStyleValueTypeFunctionStops;
+
+/// The degree to which the map view tracks the user’s location.
+typedef NS_ENUM(NSUInteger, MGLUserTrackingMode)
+{
+    MGLUserTrackingModeNone              = 0,   ///< does not track the user’s location or heading
+    MGLUserTrackingModeFollow            = 1,   ///< tracks the user’s location
+    MGLUserTrackingModeFollowWithHeading = 2,   ///< tracks the user’s location and heading
+};
diff --git a/include/mbgl/ios/MGLUserLocation.h b/include/mbgl/ios/MGLUserLocation.h
new file mode 100644
index 0000000000..fee3368889
--- /dev/null
+++ b/include/mbgl/ios/MGLUserLocation.h
@@ -0,0 +1,26 @@
+#import "MGLAnnotation.h"
+
+@interface MGLUserLocation : NSObject <MGLAnnotation>
+
+@property (nonatomic, readonly) CLLocationCoordinate2D coordinate;
+
+/** @name Determining the User’s Position */
+
+/** The current location of the device. (read-only)
+*
+*   This property contains `nil` if the map view is not currently showing the user location or if the user’s location has not yet been determined. */
+@property (nonatomic, readonly) CLLocation *location;
+
+/** A Boolean value indicating whether the user’s location is currently being updated. (read-only) */
+@property (nonatomic, readonly, getter=isUpdating) BOOL updating; // FIXME
+
+/** The heading of the user location. (read-only)
+*
+* This property is `nil` if the user location tracking mode is not `RMUserTrackingModeFollowWithHeading`. */
+@property (nonatomic, readonly) CLHeading *heading;
+
+@property (nonatomic, copy) NSString *title;
+
+@property (nonatomic, copy) NSString *subtitle;
+
+@end
diff --git a/include/mbgl/ios/MapboxGL.h b/include/mbgl/ios/MapboxGL.h
index 237d493f31..48ea908bba 100644
--- a/include/mbgl/ios/MapboxGL.h
+++ b/include/mbgl/ios/MapboxGL.h
@@ -2,6 +2,7 @@
 #import "MGLMapView.h"
 #import "MGLStyleFunctionValue.h"
 #import "MGLTypes.h"
+#import "MGLUserLocation.h"
 #import "NSArray+MGLAdditions.h"
 #import "NSDictionary+MGLAdditions.h"
 #import "UIColor+MGLAdditions.h"
diff --git a/include/mbgl/platform/darwin/settings_nsuserdefaults.hpp b/include/mbgl/platform/darwin/settings_nsuserdefaults.hpp
index 3533e3da35..6c91fd3029 100644
--- a/include/mbgl/platform/darwin/settings_nsuserdefaults.hpp
+++ b/include/mbgl/platform/darwin/settings_nsuserdefaults.hpp
@@ -1,6 +1,8 @@
 #ifndef MBGL_COMMON_SETTINGS_NSUSERDEFAULTS
 #define MBGL_COMMON_SETTINGS_NSUSERDEFAULTS
 
+#import <mbgl/ios/MGLTypes.h>
+
 namespace mbgl {
 
 class Settings_NSUserDefaults {
@@ -16,6 +18,9 @@ public:
     double zoom = 0;
     double bearing = 0;
 
+    MGLUserTrackingMode userTrackingMode = MGLUserTrackingModeNone;
+    bool showsUserLocation = false;
+
     bool debug = false;
 };