From 0c95fcfd0606df7c34abcb5770c77bfe4e086e80 Mon Sep 17 00:00:00 2001
From: nitrag <nitrag@users.noreply.github.com>
Date: Mon, 23 Jan 2017 16:17:15 -0500
Subject: [PATCH] [ios, macos] Document how to avoid gesture recognizer
 conflicts (#7816)

* Expand on Gesture Implementation

Adding Gesture info as discussed: https://github.com/mapbox/mapbox-gl-native/issues/2278#issuecomment-273685832

Not sure if using codeblocks is kosher.

* Update styling and verbiage

* More updates

* [ios] -requireGestureRecognizerToFail: seems to be enough

* [macos] Added corresponding macOS documentation
---
 platform/ios/src/MGLMapView.h   | 14 ++++++++++++++
 platform/macos/src/MGLMapView.h | 15 +++++++++++++++
 2 files changed, 29 insertions(+)

diff --git a/platform/ios/src/MGLMapView.h b/platform/ios/src/MGLMapView.h
index 715f3338c..0d65ea2fb 100644
--- a/platform/ios/src/MGLMapView.h
+++ b/platform/ios/src/MGLMapView.h
@@ -73,8 +73,22 @@ typedef NS_ENUM(NSUInteger, MGLAnnotationVerticalAlignment) {
  your Mapbox account. They also deter other developers from using your styles
  without your permission.
  
+ Adding your own gesture recognizer to `MGLMapView` will block the corresponding
+ gesture recognizer built into `MGLMapView`. To avoid conflicts, define which
+ gesture takes precedence. For example, you can create your own
+ `UITapGestureRecognizer` that will be invoked only if the default `MGLMapView`
+ tap gesture fails:
+ 
+ ```swift
+ let mapTapGestureRecognizer = UITapGestureRecognizer(target: self, action: #selector(myCustomFunction))
+ for recognizer in mapView.gestureRecognizers! where recognizer is UITapGestureRecognizer {
+     mapTapGestureRecognizer.require(toFail: recognizer)
+ }
+ ```
+ 
  @note You are responsible for getting permission to use the map data and for
  ensuring that your use adheres to the relevant terms of use.
+
  */
 IB_DESIGNABLE
 @interface MGLMapView : UIView
diff --git a/platform/macos/src/MGLMapView.h b/platform/macos/src/MGLMapView.h
index 954e5a2c7..5f34976ca 100644
--- a/platform/macos/src/MGLMapView.h
+++ b/platform/macos/src/MGLMapView.h
@@ -44,6 +44,21 @@ NS_ASSUME_NONNULL_BEGIN
  your Mapbox account. They also deter other developers from using your styles
  without your permission.
  
+ Adding your own gesture recognizer to `MGLMapView` will block the corresponding
+ gesture recognizer built into `MGLMapView`. To avoid conflicts, define which
+ gesture recognizer takes precedence. For example, you can subclass
+ `NSClickGestureRecognizer` and override `-[NSGestureRecognizer shouldRequireFailureOfGestureRecognizer:]`,
+ so that your subclass will be invoked only if the default `MGLMapView` click
+ gesture recognizer fails:
+ 
+ ```swift
+ class MapClickGestureRecognizer: NSClickGestureRecognizer {
+     override func shouldRequireFailure(of otherGestureRecognizer: NSGestureRecognizer) -> Bool {
+         return otherGestureRecognizer is NSClickGestureRecognizer
+     }
+ }
+ ```
+ 
  @note You are responsible for getting permission to use the map data and for
     ensuring that your use adheres to the relevant terms of use.
  */