[ios] add user interaction guide #7937
Conversation
There was a problem hiding this comment.
This is great! One comment/question:
If you would like to disable a specific set of gesture recognizers, such as zoom, you can set the Boolean value for the appropriate property to
false. You can then add your own gesture recognizers to perform those actions.
Is this true? I'm not sure but I think we would still need to implement something to disable our relevant gesture recognizers since our currently implementation short circuits the handler but does not actually disable the gesture recognizer itself. I think the workaround for devs now is to loop through the map's recognizers and manually disable ones they don't want running that correspond to the booleans they set to false.
|
@boundsj Thank you, good point! If you set the Boolean value to |
|
We have an example of adding a gesture recognizer that doesn’t conflict with the built-in ones: https://www.mapbox.com/ios-sdk/api/3.4.1/Classes/MGLMapView.html |
|
Pulled in a change to Bitrise.yml to fix failing build. |
| @@ -0,0 +1,47 @@ | |||
| # User Interactions in the Mapbox iOS SDK | |||
There was a problem hiding this comment.
Titles of guides don’t need to say “Mapbox iOS SDK”, since the guides are part of the iOS SDK docset.
| @@ -0,0 +1,47 @@ | |||
| # User Interactions in the Mapbox iOS SDK | |||
|
|
|||
| The Mapbox iOS SDK provides a set of built-in gesture recognizers to developers. These interactions can be customized to fit your use case. You see what gesture recognizers are on your `MGLMapView` by accessing the `gestureRecognizers` property on your map. | |||
There was a problem hiding this comment.
Remove “to developers”: the built-in gesture recognizers are primarily provided for the benefit of end users, not developers.
| @@ -0,0 +1,47 @@ | |||
| # User Interactions in the Mapbox iOS SDK | |||
|
|
|||
| The Mapbox iOS SDK provides a set of built-in gesture recognizers to developers. These interactions can be customized to fit your use case. You see what gesture recognizers are on your `MGLMapView` by accessing the `gestureRecognizers` property on your map. | |||
There was a problem hiding this comment.
Avoid passive voice:
You can customize or supplement these gesture recognizers according to your use case.
|
|
||
| ## Configuring user interaction | ||
|
|
||
| There are several properties on a `MGLMapView` that are built-in ways to enable or disable a set of gesture recognizers. Boolean values are set to `true` by default. |
There was a problem hiding this comment.
Replace true with YES or say “are enabled by default”. In the absence of #3956, we use Objective-C syntax rather than Swift syntax in prose.
|
|
||
| There are several properties on a `MGLMapView` that are built-in ways to enable or disable a set of gesture recognizers. Boolean values are set to `true` by default. | ||
|
|
||
| - `zoomEnabled` - Allows the user to zoom in and out by pinching two fingers, double tapping, or using "quick zoom". Accepts Boolean values. |
There was a problem hiding this comment.
Nit: s/double tapping/double-tapping/
| |Single Tap |`handleSingleTapGesture:` | Selects/Deselects the annotation that you tap. | | | ||
| |Double Tap |`handleDoubleTapGesture:` | Zooms in on the map's anchor point | `zoomEnabled` | | ||
| |Two Finger Tap:| `handleTwoFingerTapGesture:` | Zooms out with the map's anchor point centered | `zoomEnabled` | | ||
| |Pan Gesture| `handlePanGesture:`| Scrolls across mapView (_Note: If_ `MGLUserTrackingModeFollow` _is being used, it will be disabled once the user pans_)| `scrollEnabled` | |
| |Two Finger Tap:| `handleTwoFingerTapGesture:` | Zooms out with the map's anchor point centered | `zoomEnabled` | | ||
| |Pan Gesture| `handlePanGesture:`| Scrolls across mapView (_Note: If_ `MGLUserTrackingModeFollow` _is being used, it will be disabled once the user pans_)| `scrollEnabled` | | ||
| |Two Finger Drag | `handleTwoFingerDragGesture:` | Adjusts the pitch of the `MGLMapView` | `pitchEnabled` | | ||
| |"Quick Zoom" |`handleQuickZoomGesture:` |Tap twice. On second tap, hold your finger on the map and pan up to zoom in, or down to zoom out | `zoomEnabled`| |
There was a problem hiding this comment.
As above, we shouldn’t use the term “quick zoom” in documentation, especially since it isn’t any quicker than pinching. (If we want to coin a term for this gesture, “one-finger zoom” would be more apt.)
| for recognizer in gestureRecognizers where recognizer is UITapGestureRecognizer { | ||
| singleTapGestureRecognizer.require(toFail: recognizer) | ||
| } | ||
| mapView.addGestureRecognizer(singleTapGestureRecognizer)` |
There was a problem hiding this comment.
Delimit code blocks with three backticks, not one. Additionally, this code block duplicates the example code in MGLMapView. Unlike this guide, that example code is subject to unit tests. Remove this duplication and refer the developer to the MGLMapView documentation.
|
|
||
| If you would like to disable a specific set of gesture recognizers, such as zoom, you can set the Boolean value for the appropriate property to `false`. You can then add your own gesture recognizers to perform those actions. | ||
|
|
||
| With [runtime styling](runtime-styling.html), you can also use user interactions to style the map! |
There was a problem hiding this comment.
This is an unusual sentence to end the guide with. Runtime styling isn’t closely related to gestures, so let’s leave it out.
platform/ios/jazzy.yml
Outdated
| @@ -23,6 +23,7 @@ custom_categories: | |||
| - Working with GeoJSON Data | |||
| - For Style Authors | |||
| - Info.plist Keys | |||
| - Using Gesture Recognizers | |||
There was a problem hiding this comment.
The name of the .md file must match the entry in this list verbatim. Rename the file “Gesture Recognizers.md” and update this line.
| |Rotation | Changes the MGLMapView direction based on the user rotating two fingers in a circular motion | `rotateEnabled` | | ||
| |Single tap | Selects/deselects the annotation that you tap. | | | ||
| |Double tap | Zooms in on the map's anchor point | `zoomEnabled` | | ||
| |Two-finger tap:| Zooms out with the map's anchor point centered | `zoomEnabled` | |
| |Two-finger tap:| Zooms out with the map's anchor point centered | `zoomEnabled` | | ||
| |Pan | Scrolls across mapView (_note: if_ `MGLUserTrackingModeFollow` _is being used, it will be disabled once the user pans_)| `scrollEnabled` | | ||
| |Two-finger drag | Adjusts the pitch of the `MGLMapView` | `pitchEnabled` | | ||
| |One-finger zoom | Tap twice. On second tap, hold your finger on the map and pan up to zoom in, or down to zoom out | `zoomEnabled`| |
There was a problem hiding this comment.
Replace the period with a semicolon so that the text afterwards doesn't look like a sentence fragment.
|
|
||
| You can also add gesture recognizers that are only called when the default gesture recognizer fails (and vice versa), such as when a user taps on a part of the map that is not an annotation. The documentation for [MGLMapView](Classes/MGLMapView.html) includes an example of how to create a fallback gesture recognizer. | ||
|
|
||
| If you would like to disable a specific set of gesture recognizers, such as zoom, you can set the Boolean value for the appropriate property to `false`. You can then add your own gesture recognizers to perform those actions. |
Added an overview of built-in gesture recognizers in iOS SDK.
Addresses #7635
cc @1ec5 @friedbunny