[ios] Introduce MGLAnnotationView and support for view annotations

Add an UIView subclass that can be used as the base class for all
client provided UIViews for annotations.

Teach MGLMapView to be able to display annotation views over the map if provided by the client delegate. For now, if the delegate provides a UIView then it will be used. If not, the map view will fall back to the old strategy of using GL annotations with an image provided by the delegate or a default image if not.
The map keeps a reuse queue and will store annotation views that are panned
offscreen in the queue if the application developer supplied a reuse queue identifer. The views in the queue are reused when more annotation
views are required. This view reuse provides a performance gain when many
annotations are shown and most of them are offscreen.

iosapp now implements the new delegate method to supply
a native view.

Add a playground to the workspace to facilitate experimentation
with new features. A playground is capable of importing frameworks if it
exists in the same workspace that builds the imported framework. The
initial playground demonstrates annotation views.

This also fixes a crash due to nullptr in annotations array If the `annotations` method is called while the user dot's callout view was showing, the userdot annotation is represented as null in the annotation context map. This
caused a crash when the null pointer was attempted to be converted
into an NSArray via C array. This protects against this bug by filtering out such a null annotation.

.gitignore

@@ -23,3 +23,4 @@ xcuserdata
 /node_modules
 /platform/ios/benchmark/assets/glyphs/DIN*
 /platform/ios/benchmark/assets/tiles/mapbox.mapbox-terrain-v2,mapbox.mapbox-streets-v6
+**/token

platform/ios/Mapbox.playground/Contents.swift

@@ -0,0 +1,133 @@
+import UIKit
+import XCPlayground
+import Mapbox
+
+let width: CGFloat = 700
+let height: CGFloat = 800
+
+//: A control panel
+let panelWidth: CGFloat = 200
+let panel = UIView(frame: CGRect(x: width - panelWidth, y: 0, width: 200, height: 100))
+panel.alpha = 0.8
+panel.backgroundColor = UIColor.whiteColor()
+let deleteSwitchLabel = UILabel(frame: CGRect(x: 0, y: 0, width: 100, height: 30))
+deleteSwitchLabel.adjustsFontSizeToFitWidth = true
+deleteSwitchLabel.text = "Delete Markers"
+let deleteMarkerSwitchView = UISwitch(frame: CGRect(x: panelWidth - panelWidth / 2.0, y:0, width: 100, height: 50))
+panel.addSubview(deleteSwitchLabel)
+panel.addSubview(deleteMarkerSwitchView)
+let hideSwitchLabel = UILabel(frame: CGRect(x: 0, y: 30, width: 100, height: 30))
+hideSwitchLabel.adjustsFontSizeToFitWidth = true
+hideSwitchLabel.text = "Hide Markers"
+let hideMarkerSwitchView = UISwitch(frame: CGRect(x: panelWidth - panelWidth / 2.0, y: 30, width: 100, height: 50))
+panel.addSubview(hideSwitchLabel)
+panel.addSubview(hideMarkerSwitchView)
+
+//: # Mapbox Maps
+
+/*:
+ Put your access token into a plain text file called `token`. Then select the “token” placeholder below, go to Editor ‣ Insert File Literal, and select the `token` file.
+ */
+var accessToken = try String(contentsOfURL: <#token#>)
+MGLAccountManager.setAccessToken(accessToken)
+
+class PlaygroundAnnotationView: MGLAnnotationView {
+
+    override func prepareForReuse() {
+        hidden = hideMarkerSwitchView.on
+    }
+
+}
+
+//: Define a map delegate
+
+class MapDelegate: NSObject, MGLMapViewDelegate {
+
+    var annotationViewByAnnotation = [MGLPointAnnotation: PlaygroundAnnotationView]()
+
+    func mapView(mapView: MGLMapView, viewForAnnotation annotation: MGLAnnotation) -> MGLAnnotationView? {
+
+        var annotationView = mapView.dequeueReusableAnnotationViewWithIdentifier("annotation") as? PlaygroundAnnotationView
+
+        if (annotationView == nil) {
+            let av = PlaygroundAnnotationView(reuseIdentifier: "annotation")
+            av.frame = CGRect(x: 0, y: 0, width: 30, height: 30)
+            let centerView = UIView(frame: CGRectInset(av.bounds, 3, 3))
+            centerView.backgroundColor = UIColor.whiteColor()
+            av.addSubview(centerView)
+            av.backgroundColor = UIColor.purpleColor()
+            annotationView = av
+        } else {
+            annotationView!.subviews.first?.backgroundColor = UIColor.greenColor()
+        }
+
+        annotationViewByAnnotation[annotation as! MGLPointAnnotation] = annotationView
+
+        return annotationView
+    }
+
+    func mapView(mapView: MGLMapView, didSelectAnnotation annotation: MGLAnnotation) {
+        let pointAnnotation = annotation as! MGLPointAnnotation
+        let annotationView: PlaygroundAnnotationView  = annotationViewByAnnotation[pointAnnotation]!
+
+        for view in annotationViewByAnnotation.values {
+            view.layer.zPosition = -1
+        }
+
+        annotationView.layer.zPosition = 1
+
+        UIView.animateWithDuration(1.25, delay: 0, usingSpringWithDamping: 0.4, initialSpringVelocity: 0.6, options: .CurveEaseOut, animations: {
+            annotationView.transform = CGAffineTransformMakeScale(1.8, 1.8)
+        }) { _ in
+            annotationView.transform = CGAffineTransformMakeScale(1, 1)
+
+            if deleteMarkerSwitchView.on {
+                mapView.removeAnnotation(pointAnnotation)
+                return
+            }
+
+            if hideMarkerSwitchView.on {
+                annotationView.hidden = true
+            }
+        }
+    }
+
+    func handleTap(press: UILongPressGestureRecognizer) {
+        let mapView: MGLMapView = press.view as! MGLMapView
+
+        if (press.state == .Recognized) {
+            let coordiante: CLLocationCoordinate2D = mapView.convertPoint(press.locationInView(mapView), toCoordinateFromView: mapView)
+            let annotation = MGLPointAnnotation()
+            annotation.title = "Dropped Marker"
+            annotation.coordinate = coordiante
+            mapView.addAnnotation(annotation)
+            mapView.showAnnotations([annotation], animated: true)
+        }
+    }
+
+}
+
+//: Create a map and its delegate
+
+let lat: CLLocationDegrees = 37.174057
+let lng: CLLocationDegrees = -104.490984
+let centerCoordinate = CLLocationCoordinate2D(latitude: lat, longitude: lng)
+
+let mapView = MGLMapView(frame: CGRect(x: 0, y: 0, width: width, height: height))
+mapView.frame = CGRect(x: 0, y: 0, width: width, height: height)
+
+XCPlaygroundPage.currentPage.liveView = mapView
+
+let mapDelegate = MapDelegate()
+mapView.delegate = mapDelegate
+
+let tapGesture = UILongPressGestureRecognizer(target: mapDelegate, action: #selector(mapDelegate.handleTap))
+mapView.addGestureRecognizer(tapGesture)
+
+//: Zoom in to a location
+
+mapView.setCenterCoordinate(centerCoordinate, zoomLevel: 12, animated: false)
+
+//: Add control panel
+
+mapView.addSubview(panel)

platform/ios/Mapbox.playground/contents.xcplayground

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<playground version='5.0' target-platform='ios' display-mode='raw'>
+    <timeline fileName='timeline.xctimeline'/>
+</playground>

platform/ios/Mapbox.playground/timeline.xctimeline

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Timeline
+   version = "3.0">
+   <TimelineItems>
+   </TimelineItems>
+</Timeline>

platform/ios/app/MBXAnnotationView.h

@@ -0,0 +1,7 @@
+#import <Mapbox/Mapbox.h>
+
+@interface MBXAnnotationView : MGLAnnotationView
+
+@property (nonatomic) UIColor *centerColor;
+
+@end

platform/ios/app/MBXAnnotationView.m

@@ -0,0 +1,28 @@
+#import "MBXAnnotationView.h"
+
+@interface MBXAnnotationView ()
+
+@property (nonatomic) UIView *centerView;
+
+@end
+
+@implementation MBXAnnotationView
+
+- (void)layoutSubviews {
+    [super layoutSubviews];
+    if (!self.centerView) {
+        self.backgroundColor = [UIColor blueColor];
+        self.centerView = [[UIView alloc] initWithFrame:CGRectInset(self.bounds, 5.0, 5.0)];
+        self.centerView.backgroundColor = self.centerColor;
+        [self addSubview:self.centerView];
+    }
+}
+
+- (void)setCenterColor:(UIColor *)centerColor {
+    if (![_centerColor isEqual:centerColor]) {
+        _centerColor = centerColor;
+        self.centerView.backgroundColor = centerColor;
+    }
+}
+
+@end

platform/ios/app/MBXViewController.m

@@ -3,6 +3,7 @@
 #import "MBXAppDelegate.h"
 #import "MBXCustomCalloutView.h"
 #import "MBXOfflinePacksTableViewController.h"
+#import "MBXAnnotationView.h"
 
 #import <Mapbox/Mapbox.h>
 
@@ -17,6 +18,8 @@
     { .latitude = -13.15589555, .longitude = -74.2178961777998 },
 };
 
+static NSString * const MBXViewControllerAnnotationViewReuseIdentifer = @"MBXViewControllerAnnotationViewReuseIdentifer";
+
 @interface MBXDroppedPinAnnotation : MGLPointAnnotation
 @end
 
@@ -461,7 +464,7 @@ - (IBAction)handleLongPress:(UILongPressGestureRecognizer *)longPress
                                  toCoordinateFromView:self.mapView];
         point.title = @"Dropped Pin";
         point.subtitle = [[[MGLCoordinateFormatter alloc] init] stringFromCoordinate:point.coordinate];
-        [self.mapView addAnnotation:point];
+        // Calling `addAnnotation:` on mapView is not required since `selectAnnotation:animated` has the side effect of adding the annotation if required
         [self.mapView selectAnnotation:point animated:YES];
     }
 }
@@ -608,6 +611,21 @@ - (void)dealloc
 
 #pragma mark - MGLMapViewDelegate
 
+- (MGLAnnotationView *)mapView:(MGLMapView *)mapView viewForAnnotation:(id<MGLAnnotation>)annotation
+{
+    MBXAnnotationView *annotationView = (MBXAnnotationView *)[mapView dequeueReusableAnnotationViewWithIdentifier:MBXViewControllerAnnotationViewReuseIdentifer];
+    if (!annotationView)
+    {
+        annotationView = [[MBXAnnotationView alloc] initWithReuseIdentifier:MBXViewControllerAnnotationViewReuseIdentifer];
+        annotationView.frame = CGRectMake(0, 0, 40, 40);
+        annotationView.centerColor = [UIColor whiteColor];
+    } else {
+        // orange indicates that the annotation view was reused
+        annotationView.centerColor = [UIColor orangeColor];
+    }
+    return annotationView;
+}
+
 - (MGLAnnotationImage *)mapView:(MGLMapView * __nonnull)mapView imageForAnnotation:(id <MGLAnnotation> __nonnull)annotation
 {
     if ([annotation isKindOfClass:[MBXDroppedPinAnnotation class]]

platform/ios/ios.xcodeproj/project.pbxproj

@@ -7,6 +7,12 @@
 	objects = {
 
 /* Begin PBXBuildFile section */
+		4018B1C71CDC287F00F666AF /* MGLAnnotationView.m in Sources */ = {isa = PBXBuildFile; fileRef = 4018B1C41CDC277F00F666AF /* MGLAnnotationView.m */; };
+		4018B1C81CDC287F00F666AF /* MGLAnnotationView.m in Sources */ = {isa = PBXBuildFile; fileRef = 4018B1C41CDC277F00F666AF /* MGLAnnotationView.m */; };
+		4018B1C91CDC288A00F666AF /* MGLAnnotationView_Private.h in Headers */ = {isa = PBXBuildFile; fileRef = 4018B1C31CDC277F00F666AF /* MGLAnnotationView_Private.h */; };
+		4018B1CA1CDC288E00F666AF /* MGLAnnotationView.h in Headers */ = {isa = PBXBuildFile; fileRef = 4018B1C51CDC277F00F666AF /* MGLAnnotationView.h */; settings = {ATTRIBUTES = (Public, ); }; };
+		4018B1CB1CDC288E00F666AF /* MGLAnnotationView.h in Headers */ = {isa = PBXBuildFile; fileRef = 4018B1C51CDC277F00F666AF /* MGLAnnotationView.h */; settings = {ATTRIBUTES = (Public, ); }; };
+		40FDA76B1CCAAA6800442548 /* MBXAnnotationView.m in Sources */ = {isa = PBXBuildFile; fileRef = 40FDA76A1CCAAA6800442548 /* MBXAnnotationView.m */; };
 		DA17BE301CC4BAC300402C41 /* MGLMapView_Internal.h in Headers */ = {isa = PBXBuildFile; fileRef = DA17BE2F1CC4BAC300402C41 /* MGLMapView_Internal.h */; };
 		DA17BE311CC4BDAA00402C41 /* MGLMapView_Internal.h in Headers */ = {isa = PBXBuildFile; fileRef = DA17BE2F1CC4BAC300402C41 /* MGLMapView_Internal.h */; };
 		DA1DC96A1CB6C6B7006E619F /* MBXCustomCalloutView.m in Sources */ = {isa = PBXBuildFile; fileRef = DA1DC9671CB6C6B7006E619F /* MBXCustomCalloutView.m */; };
@@ -304,6 +310,12 @@
 /* End PBXCopyFilesBuildPhase section */
 
 /* Begin PBXFileReference section */
+		4018B1C31CDC277F00F666AF /* MGLAnnotationView_Private.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = MGLAnnotationView_Private.h; sourceTree = "<group>"; };
+		4018B1C41CDC277F00F666AF /* MGLAnnotationView.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = MGLAnnotationView.m; sourceTree = "<group>"; };
+		4018B1C51CDC277F00F666AF /* MGLAnnotationView.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = MGLAnnotationView.h; sourceTree = "<group>"; };
+		402E9DE01CD2C76200FD4519 /* Mapbox.playground */ = {isa = PBXFileReference; lastKnownFileType = file.playground; path = Mapbox.playground; sourceTree = "<group>"; };
+		40FDA7691CCAAA6800442548 /* MBXAnnotationView.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = MBXAnnotationView.h; sourceTree = "<group>"; };
+		40FDA76A1CCAAA6800442548 /* MBXAnnotationView.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = MBXAnnotationView.m; sourceTree = "<group>"; };
 		DA17BE2F1CC4BAC300402C41 /* MGLMapView_Internal.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = MGLMapView_Internal.h; sourceTree = "<group>"; };
 		DA1DC94A1CB6C1C2006E619F /* Mapbox GL.app */ = {isa = PBXFileReference; explicitFileType = wrapper.application; includeInIndex = 0; path = "Mapbox GL.app"; sourceTree = BUILT_PRODUCTS_DIR; };
 		DA1DC9501CB6C1C2006E619F /* MBXAppDelegate.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = MBXAppDelegate.h; sourceTree = "<group>"; };
@@ -511,9 +523,18 @@
 /* End PBXFrameworksBuildPhase section */
 
 /* Begin PBXGroup section */
+		402E9DE21CD3A56500FD4519 /* Playground */ = {
+			isa = PBXGroup;
+			children = (
+				402E9DE01CD2C76200FD4519 /* Mapbox.playground */,
+			);
+			name = Playground;
+			sourceTree = "<group>";
+		};
 		DA1DC9411CB6C1C2006E619F = {
 			isa = PBXGroup;
 			children = (
+				402E9DE21CD3A56500FD4519 /* Playground */,
 				DA1DC94C1CB6C1C2006E619F /* Demo App */,
 				DABCABA91CB80692000A7C39 /* Benchmarking App */,
 				DA8847D31CBAF91600AB86E3 /* SDK */,
@@ -543,6 +564,8 @@
 			children = (
 				DA1DC9501CB6C1C2006E619F /* MBXAppDelegate.h */,
 				DA1DC9981CB6E054006E619F /* MBXAppDelegate.m */,
+				40FDA7691CCAAA6800442548 /* MBXAnnotationView.h */,
+				40FDA76A1CCAAA6800442548 /* MBXAnnotationView.m */,
 				DA1DC9661CB6C6B7006E619F /* MBXCustomCalloutView.h */,
 				DA1DC9671CB6C6B7006E619F /* MBXCustomCalloutView.m */,
 				DA1DC9681CB6C6B7006E619F /* MBXOfflinePacksTableViewController.h */,
@@ -690,6 +713,9 @@
 		DA8848331CBAFB2A00AB86E3 /* Kit */ = {
 			isa = PBXGroup;
 			children = (
+				4018B1C31CDC277F00F666AF /* MGLAnnotationView_Private.h */,
+				4018B1C41CDC277F00F666AF /* MGLAnnotationView.m */,
+				4018B1C51CDC277F00F666AF /* MGLAnnotationView.h */,
 				DA8848341CBAFB8500AB86E3 /* MGLAnnotationImage.h */,
 				DA8848401CBAFB9800AB86E3 /* MGLAnnotationImage_Private.h */,
 				DA8848411CBAFB9800AB86E3 /* MGLAnnotationImage.m */,
@@ -844,6 +870,7 @@
 				DA8848861CBB033F00AB86E3 /* Fabric+FABKits.h in Headers */,
 				DA8848201CBAFA6200AB86E3 /* MGLOfflinePack_Private.h in Headers */,
 				DA8847FA1CBAFA5100AB86E3 /* MGLPolyline.h in Headers */,
+				4018B1C91CDC288A00F666AF /* MGLAnnotationView_Private.h in Headers */,
 				DA88482C1CBAFA6200AB86E3 /* NSBundle+MGLAdditions.h in Headers */,
 				DA88488E1CBB047F00AB86E3 /* reachability.h in Headers */,
 				DA8848231CBAFA6200AB86E3 /* MGLOfflineStorage_Private.h in Headers */,
@@ -855,6 +882,7 @@
 				DA8847FC1CBAFA5100AB86E3 /* MGLStyle.h in Headers */,
 				DA8847F01CBAFA5100AB86E3 /* MGLAnnotation.h in Headers */,
 				DA88483E1CBAFB8500AB86E3 /* MGLMapView+MGLCustomStyleLayerAdditions.h in Headers */,
+				4018B1CA1CDC288E00F666AF /* MGLAnnotationView.h in Headers */,
 				DA8847EF1CBAFA5100AB86E3 /* MGLAccountManager.h in Headers */,
 				DA8848511CBAFB9800AB86E3 /* MGLAPIClient.h in Headers */,
 				DA35A2C91CCAAAD200E826B2 /* NSValue+MGLAdditions.h in Headers */,
@@ -919,6 +947,7 @@
 				DA35A2B21CCA141D00E826B2 /* MGLCompassDirectionFormatter.h in Headers */,
 				DABFB8731CBE9A9900D62B32 /* Mapbox.h in Headers */,
 				DABFB86B1CBE99E500D62B32 /* MGLTilePyramidOfflineRegion.h in Headers */,
+				4018B1CB1CDC288E00F666AF /* MGLAnnotationView.h in Headers */,
 				DABFB85F1CBE99E500D62B32 /* MGLGeometry.h in Headers */,
 				DABFB85D1CBE99E500D62B32 /* MGLAccountManager.h in Headers */,
 				DA35A2BC1CCA9A6900E826B2 /* MGLClockDirectionFormatter.h in Headers */,
@@ -1217,6 +1246,7 @@
 				DA1DC96B1CB6C6B7006E619F /* MBXOfflinePacksTableViewController.m in Sources */,
 				DA1DC96A1CB6C6B7006E619F /* MBXCustomCalloutView.m in Sources */,
 				DA1DC99B1CB6E064006E619F /* MBXViewController.m in Sources */,
+				40FDA76B1CCAAA6800442548 /* MBXAnnotationView.m in Sources */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 		};
@@ -1259,6 +1289,7 @@
 				DA88481C1CBAFA6200AB86E3 /* MGLGeometry.mm in Sources */,
 				DA88481F1CBAFA6200AB86E3 /* MGLMultiPoint.mm in Sources */,
 				DA88482B1CBAFA6200AB86E3 /* MGLTypes.m in Sources */,
+				4018B1C71CDC287F00F666AF /* MGLAnnotationView.m in Sources */,
 				DA88481D1CBAFA6200AB86E3 /* MGLMapCamera.mm in Sources */,
 				DA8848261CBAFA6200AB86E3 /* MGLPolygon.mm in Sources */,
 				DA8848521CBAFB9800AB86E3 /* MGLAPIClient.m in Sources */,
@@ -1296,6 +1327,7 @@
 				DAA4E4301CBB730400178DFB /* MGLLocationManager.m in Sources */,
 				DAA4E4321CBB730400178DFB /* MGLMapView.mm in Sources */,
 				DAA4E41E1CBB730400178DFB /* MGLMapCamera.mm in Sources */,
+				4018B1C81CDC287F00F666AF /* MGLAnnotationView.m in Sources */,
 				DAA4E4341CBB730400178DFB /* MGLUserLocationAnnotationView.m in Sources */,
 				DAA4E42C1CBB730400178DFB /* reachability.m in Sources */,
 				DAA4E4311CBB730400178DFB /* MGLMapboxEvents.m in Sources */,

platform/ios/ios.xcodeproj/xcshareddata/xcschemes/iosapp.xcscheme

@@ -70,15 +70,16 @@
       savedToolIdentifier = ""
       useCustomWorkingDirectory = "NO"
       debugDocumentVersioning = "YES">
-      <MacroExpansion>
+      <BuildableProductRunnable
+         runnableDebuggingMode = "0">
          <BuildableReference
             BuildableIdentifier = "primary"
             BlueprintIdentifier = "DA1DC9491CB6C1C2006E619F"
             BuildableName = "Mapbox GL.app"
             BlueprintName = "iosapp"
             ReferencedContainer = "container:ios.xcodeproj">
          </BuildableReference>
-      </MacroExpansion>
+      </BuildableProductRunnable>
    </ProfileAction>
    <AnalyzeAction
       buildConfiguration = "Debug">

platform/ios/src/MGLAnnotationView.h

@@ -0,0 +1,20 @@
+#import <UIKit/UIKit.h>
+
+#import "MGLTypes.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+@interface MGLAnnotationView : UIView
+
+- (instancetype)initWithReuseIdentifier:(NSString *)reuseIdentifier;
+
+/**
+ The string that identifies that this annotation view is reusable. (read-only)
+ */
+@property (nonatomic, readonly, nullable) NSString *reuseIdentifier;
+
+- (void)prepareForReuse;
+
+@end
+
+NS_ASSUME_NONNULL_END