Merge pull request #1088 from mapbox/ios-callouts-final

refs #894, fixes #1074: callout views for iOS

.gitmodules

@@ -13,3 +13,7 @@
 [submodule "test/ios/KIF"]
 	path = test/ios/KIF
 	url = https://github.com/mapbox/KIF.git
+
+[submodule "platform/ios/vendor/SMCalloutView"]
+	path = platform/ios/vendor/SMCalloutView
+	url = https://github.com/nfarina/calloutview.git

Makefile

@@ -25,10 +25,13 @@ config/%.gypi: configure
 styles/styles:
 	git submodule update --init styles
 
+SMCalloutView:
+	git submodule update --init platform/ios/vendor/SMCalloutView
+
 #### Library builds ############################################################
 
 .PRECIOUS: Makefile/mbgl
-Makefile/mbgl: config/$(HOST).gypi styles/styles
+Makefile/mbgl: config/$(HOST).gypi styles/styles SMCalloutView
 	deps/run_gyp mbgl.gyp $(CONFIG_$(HOST)) $(LIBS_$(HOST)) --generator-output=./build/$(HOST) -f make
 
 mbgl: Makefile/mbgl
@@ -41,13 +44,13 @@ install: Makefile/mbgl
 	LINK=`pwd`/gyp/link.py $(MAKE) -C build/$(HOST) BUILDTYPE=$(BUILDTYPE) install
 
 .PRECIOUS: Xcode/mbgl
-Xcode/mbgl: config/$(HOST).gypi styles/styles
+Xcode/mbgl: config/$(HOST).gypi styles/styles SMCalloutView
 	deps/run_gyp mbgl.gyp $(CONFIG_$(HOST)) $(LIBS_$(HOST)) --generator-output=./build/$(HOST) -f xcode
 
 ##### Test builds ##############################################################
 
 .PRECIOUS: Makefile/test
-Makefile/test: test/test.gyp config/$(HOST).gypi styles/styles
+Makefile/test: test/test.gyp config/$(HOST).gypi styles/styles SMCalloutView
 	deps/run_gyp test/test.gyp $(CONFIG_$(HOST)) $(LIBS_$(HOST)) --generator-output=./build/$(HOST) -f make
 
 test: Makefile/test
@@ -58,7 +61,7 @@ test-%: test
 
 
 .PRECIOUS: Xcode/test
-Xcode/test: test/test.gyp config/osx.gypi styles/styles
+Xcode/test: test/test.gyp config/osx.gypi styles/styles SMCalloutView
 	deps/run_gyp test/test.gyp $(CONFIG_osx) $(LIBS_osx) --generator-output=./build/osx -f xcode
 
 .PHONY: lproj lbuild run-xlinux
@@ -108,7 +111,7 @@ xproj: xosx-proj
 #### iOS application builds ####################################################
 
 .PRECIOUS: Xcode/ios
-Xcode/ios: ios/app/mapboxgl-app.gyp config/ios.gypi styles/styles
+Xcode/ios: ios/app/mapboxgl-app.gyp config/ios.gypi styles/styles SMCalloutView
 	deps/run_gyp ios/app/mapboxgl-app.gyp $(CONFIG_ios) $(LIBS_ios) --generator-output=./build/ios -f xcode
 
 .PHONY: ios-proj ios run-ios

gyp/platform-ios.gypi

@@ -34,6 +34,8 @@
         '../platform/ios/NSDictionary+MGLAdditions.m',
         '../include/mbgl/ios/UIColor+MGLAdditions.h',
         '../platform/ios/UIColor+MGLAdditions.m',
+        '../platform/ios/vendor/SMCalloutView/SMCalloutView.h',
+        '../platform/ios/vendor/SMCalloutView/SMCalloutView.m',
       ],
 
       'variables': {
@@ -52,6 +54,7 @@
           '-framework GLKit',
           '-framework MobileCoreServices',
           '-framework OpenGLES',
+          '-framework QuartzCore',
           '-framework SystemConfiguration',
           '-framework UIKit',
         ],

include/mbgl/ios/MGLMapView.h

@@ -251,11 +251,15 @@
 
 @end
 
+#pragma mark - MGLMapViewDelegate
+
 /** The MGLMapViewDelegate protocol defines a set of optional methods that you can use to receive map-related update messages. Because many map operations require the MGLMapView class to load data asynchronously, the map view calls these methods to notify your application when specific operations complete. The map view also uses these methods to request annotation marker symbology and to manage interactions with those markers. */
 @protocol MGLMapViewDelegate <NSObject>
 
 @optional
 
+#pragma mark - Managing the Display of Annotations
+
 /** @name Managing the Display of Annotations */
 
 /** Returns the style's symbol name to use for the marker for the specified point annotation object.
@@ -264,14 +268,54 @@
 *   @return The marker symbol to display for the specified annotation or `nil` if you want to display the default symbol. */
 - (NSString *)mapView:(MGLMapView *)mapView symbolNameForAnnotation:(id <MGLAnnotation>)annotation;
 
+/** Returns a Boolean value indicating whether the annotation is able to display extra information in a callout bubble.
+*
+*   If the value returned is `YES`, a standard callout bubble is shown when the user taps a selected annotation. The callout uses the title and subtitle text from the associated annotation object. If there is no title text, though, the annotation will not show a callout. The callout also displays any custom callout views returned by the delegate for the left and right callout accessory views.
+*
+*   If the value returned is `NO`, the value of the title and subtitle strings are ignored.
+*
+*   @param mapView The map view that requested the annotation callout ability.
+*   @param annotation The object representing the annotation.
+*   @return A Boolean indicating whether the annotation should show a callout. */
+- (BOOL)mapView:(MGLMapView *)mapView annotationCanShowCallout:(id <MGLAnnotation>)annotation;
+
+/** Return the view to display on the left side of the standard callout bubble.
+*
+*   The default value is treated as if `nil`. The left callout view is typically used to display information about the annotation or to link to custom information provided by your application.
+*
+*   If the view you specify is also a descendant of the `UIControl` class, you can use the map view’s delegate to receive notifications when your control is tapped. If it does not descend from `UIControl`, your view is responsible for handling any touch events within its bounds.
+*
+*   @param mapView The map view presenting the annotation callout.
+*   @param annotation The object representing the annotation with the callout.
+*   @return The accessory view to display. */
+- (UIView *)mapView:(MGLMapView *)mapView leftCalloutAccessoryViewForAnnotation:(id <MGLAnnotation>)annotation;
+
+/** Return the view to display on the right side of the standard callout bubble.
+*
+*   The default value is treated is if `nil`. The right callout view is typically used to link to more detailed information about the annotation. A common view to specify for this property is `UIButton` object whose type is set to `UIButtonTypeDetailDisclosure`.
+*
+*   If the view you specify is also a descendant of the `UIControl` class, you can use the map view’s delegate to receive notifications when your control is tapped. If it does not descend from `UIControl`, your view is responsible for handling any touch events within its bounds.
+*
+*   @param mapView The map view presenting the annotation callout.
+*   @param annotation The object representing the annotation with the callout.
+*   @return The accessory view to display. */
+- (UIView *)mapView:(MGLMapView *)mapView rightCalloutAccessoryViewForAnnotation:(id <MGLAnnotation>)annotation;
+
+#pragma mark - Responding to Map Position Changes
+
 // Responding to Map Position Changes
 
 // TODO
 - (void)mapView:(MGLMapView *)mapView regionWillChangeAnimated:(BOOL)animated;
 
+// TODO
+- (void)mapViewRegionIsChanging:(MGLMapView *)mapView;
+
 // TODO
 - (void)mapView:(MGLMapView *)mapView regionDidChangeAnimated:(BOOL)animated;
 
+#pragma mark - Loading the Map Data
+
 // Loading the Map Data
 
 // TODO
@@ -289,4 +333,39 @@
 // TODO
 - (void)mapViewDidFinishRenderingMap:(MGLMapView *)mapView fullyRendered:(BOOL)fullyRendered;
 
+#pragma mark - Managing Annotations
+
+/** @name Managing Annotations */
+
+/* Tells the delegate that the user tapped one of the annotation's accessory buttons.
+*
+*  Accessory views contain custom content and are positioned on either side of the annotation title text. If a view you specify is a descendant of the `UIControl` class, the map view calls this method as a convenience whenever the user taps your view. You can use this method to respond to taps and perform any actions associated with that control. For example, if your control displayed additional information about the annotation, you could use this method to present a modal panel with that information.
+*
+*  If your custom accessory views are not descendants of the `UIControl` class, the map view does not call this method.
+*
+*  @param mapView The map view containing the specified annotation.
+*  @param annotation The annotation whose button was tapped.
+*  @param control The control that was tapped. */
+- (void)mapView:(MGLMapView *)mapView annotation:(id <MGLAnnotation>)annotation calloutAccessoryControlTapped:(UIControl *)control;
+
+#pragma mark - Selecting Annotations
+
+/** @name Selecting Annotations */
+
+/* Tells the delegate that one of its annotations was selected.
+*
+*  You can use this method to track changes in the selection state of annotations.
+*
+*  @param mapView The map view containing the annotation.
+*  @param annotation The annotation that was selected. */
+- (void)mapView:(MGLMapView *)mapView didSelectAnnotation:(id <MGLAnnotation>)annotation;
+
+/* Tells the delegate that one of its annotations was deselected.
+*
+*  You can use this method to track changes in the selection state of annotations.
+*
+*  @param mapView The map view containing the annotation.
+*  @param annotation The annotation that was deselected. */
+- (void)mapView:(MGLMapView *)mapView didDeselectAnnotation:(id <MGLAnnotation>)annotation;
+
 @end

include/mbgl/map/map.hpp

@@ -153,6 +153,7 @@ class Map : private util::noncopyable {
 
     // Annotations
     void setDefaultPointAnnotationSymbol(const std::string&);
+    double getTopOffsetPixelsForAnnotationSymbol(const std::string&);
     uint32_t addPointAnnotation(const LatLng&, const std::string& symbol);
     std::vector<uint32_t> addPointAnnotations(const std::vector<LatLng>&,
                                               const std::vector<std::string>& symbols);

include/mbgl/map/view.hpp

@@ -10,14 +10,15 @@ class Map;
 enum MapChange : uint8_t {
     MapChangeRegionWillChange = 0,
     MapChangeRegionWillChangeAnimated = 1,
-    MapChangeRegionDidChange = 2,
-    MapChangeRegionDidChangeAnimated = 3,
-    MapChangeWillStartLoadingMap = 4,
-    MapChangeDidFinishLoadingMap = 5,
-    MapChangeDidFailLoadingMap = 6,
-    MapChangeWillStartRenderingMap = 7,
-    MapChangeDidFinishRenderingMap = 8,
-    MapChangeDidFinishRenderingMapFullyRendered = 9
+    MapChangeRegionIsChanging = 2,
+    MapChangeRegionDidChange = 3,
+    MapChangeRegionDidChangeAnimated = 4,
+    MapChangeWillStartLoadingMap = 5,
+    MapChangeDidFinishLoadingMap = 6,
+    MapChangeDidFailLoadingMap = 7,
+    MapChangeWillStartRenderingMap = 8,
+    MapChangeDidFinishRenderingMap = 9,
+    MapChangeDidFinishRenderingMapFullyRendered = 10
 };
 
 class View {

ios/app/MBXViewController.mm

@@ -21,7 +21,7 @@
 
 static NSString *const kStyleVersion = @"v7";
 
-@interface MBXViewController () <UIActionSheetDelegate, CLLocationManagerDelegate>
+@interface MBXViewController () <UIActionSheetDelegate, CLLocationManagerDelegate, MGLMapViewDelegate>
 
 @property (nonatomic) MGLMapView *mapView;
 @property (nonatomic) CLLocationManager *locationManager;
@@ -70,6 +70,8 @@ - (void)viewDidLoad
 
     self.mapView.viewControllerForLayoutGuides = self;
 
+    self.mapView.delegate = self;
+
     self.view.tintColor = kTintColor;
     self.navigationController.navigationBar.tintColor = kTintColor;
     self.mapView.tintColor = kTintColor;
@@ -338,6 +340,13 @@ - (void)locationManager:(CLLocationManager *)manager didUpdateLocations:(NSArray
     [self.locationManager stopUpdatingLocation];
 }
 
+#pragma mark - MGLMapViewDelegate
+
+- (BOOL)mapView:(MGLMapView *)mapView annotationCanShowCallout:(id <MGLAnnotation>)annotation
+{
+    return YES;
+}
+
 #pragma clang diagnostic pop
 
 @end