NavigationScaleGestureHandler

Provides support in reacting to map gesture interaction and other animations scheduled outside of the NavigationCamera context.

Gestures recognition

When enabled, the handler listens for all map gestures interactions, and if that interaction is changing the zoom level of the camera, it can be freely continued. This allows users to change the zoom level of the camera by executing well-known gestures like:

• double-tapping to zoom in

• two-finger-tapping to zoom out

• quick-scaling by double-tapping and holding the finger down while moving it up and down

• pinching to zoom in and out (depends on NavigationScaleGestureHandlerOptions)

without the camera stopping to track the current user's puck and upcoming maneuver context.

You can configure which gestures should be recognized with GesturesSettings.

Interruptions

Any other camera change request outside of the NAVIGATION_CAMERA_OWNER and scale gestures (MapAnimationOwnerRegistry.GESTURES) will immediately make NavigationCamera fallback to NavigationCameraState.IDLE state to avoid running competing animations.

Interop with the ViewportDataSource

Allowing to execute scale gestures means allowing the Maps gesture recognizer to change the camera's zoom level. Those zoom level updates, can interfere with camera updates that the ViewportDataSource produces and passes to NavigationCamera. It's a good practice to stop the data source from producing zoom level updates during and after scale gesture interaction.

This handler exposes an NavigationScaleGestureActionListener which is triggered whenever zoom level changes due to the gesture interaction that was allowed. This callback can be used to notify the ViewportDataSource implementation to stop producing zoom level for a certain period of time.

For example, when using the MapboxNavigationViewportDataSource, you can call FollowingFrameOptions.zoomUpdatesAllowed with false to stop producing zoom level updates. You can later reset the value to true (after a button click, or after a certain period of time). Use MapboxNavigationViewportDataSource.options to mutate this state.

Integration

To enable the handler, register it via CameraAnimationsPlugin.addCameraAnimationsLifecycleListener and call initialize. To deinitialize, call CameraAnimationsPlugin.removeCameraAnimationsLifecycleListener and cleanup.

When the handler is initialized, it sets a custom AndroidGesturesManager to the Maps SDK and starts manipulating the gesture thresholds to make the execution of scale gestures possible without impacting other camera transitions. It's important to clean up afterwards to go back to the initial behavior if navigation gesture handling features are not required anymore.