mapbox · avpeery · Oct 19, 2021 · Oct 4, 2021 · Oct 4, 2021 · Oct 8, 2021
@@ -1,7 +1,7 @@
 <!DOCTYPE html>
 <html>
 <head>
-    <title>Scroll Zoom Blocker Control</title>
+    <title>Cooperative Gestures</title>
     <meta charset='utf-8'>
     <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no">
     <link rel='stylesheet' href='../dist/mapbox-gl.css' />
@@ -12,7 +12,7 @@
 </head>
 
 <body>
-<div id='map' style='width: 250px; height: 250px;'></div>
+<div id='map' style='width: 400px; height: 400px;'></div>
 
 <div style='width: 500px; height: 500px;'></div>
 <script src='../dist/mapbox-gl-dev.js'></script>
@@ -24,7 +24,7 @@
     zoom: 12.5,
     center: [-77.01866, 38.888],
     style: 'mapbox://styles/mapbox/streets-v10',
-    gestureHandling: true
+    cooperativeGestures: true
 });
 
 map.addControl(new mapboxgl.FullscreenControl());

@@ -770,6 +770,7 @@ a.mapboxgl-ctrl-logo.mapboxgl-compact {
     }
 }
 
+.mapboxgl-touch-pan-blocker,
 .mapboxgl-scroll-zoom-blocker {
     color: #fff;
     font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
@@ -789,7 +790,13 @@ a.mapboxgl-ctrl-logo.mapboxgl-compact {
     transition-delay: 1s;
 }
 
+.mapboxgl-touch-pan-blocker-show,
 .mapboxgl-scroll-zoom-blocker-show {
     opacity: 1;
     transition: opacity 0.1s ease-in-out;
 }
+
+.mapboxgl-canvas-container.mapboxgl-touch-pan-blocker-override.mapboxgl-scrollable-page,
+.mapboxgl-canvas-container.mapboxgl-touch-pan-blocker-override.mapboxgl-scrollable-page .mapboxgl-canvas {
+    touch-action: pan-x pan-y;
+}
@@ -17,7 +17,8 @@ const defaultLocale = {
     'ScaleControl.Miles': 'mi',
     'ScaleControl.NauticalMiles': 'nm',
     'ScrollZoomBlocker.CtrlMessage': 'Use ctrl + scroll to zoom the map',
-    'ScrollZoomBlocker.CmdMessage': 'Use ⌘ + scroll to zoom the map'
+    'ScrollZoomBlocker.CmdMessage': 'Use ⌘ + scroll to zoom the map',
+    'TouchPanBlocker.Message': 'Use two fingers to move the map'
 };
 
 export default defaultLocale;
@@ -143,7 +143,7 @@ class ScrollZoomHandler {
         if (this.isEnabled()) return;
         this._enabled = true;
         this._aroundCenter = options && options.around === 'center';
-        if (this._map._gestureHandling) this._addScrollZoomBlocker();
+        if (this._map._cooperativeGestures) this._addScrollZoomBlocker();
     }
 
     /**
@@ -155,13 +155,16 @@ class ScrollZoomHandler {
     disable() {
         if (!this.isEnabled()) return;
         this._enabled = false;
-        if (this._map._gestureHandling) this._alertContainer.remove();
+        if (this._map._cooperativeGestures) {
+            clearTimeout(this._alertTimer);
+            this._alertContainer.remove();
+        }
     }
 
     wheel(e: WheelEvent) {
         if (!this.isEnabled()) return;
 
-        if (this._map._gestureHandling) {
+        if (this._map._cooperativeGestures) {
             if (!e.ctrlKey && !e.metaKey && !this.isZooming() && !this._isFullscreen()) {
                 this._showBlockerAlert();
                 return;

@@ -1,21 +1,31 @@
 // @flow
 
 import Point from '@mapbox/point-geometry';
+import type Map from '../map.js';
 import {indexTouches} from './handler_util.js';
+import {bindAll} from '../../util/util.js';
+import DOM from '../../util/dom.js';
 
 export default class TouchPanHandler {
 
+    _map: Map;
+    _el: HTMLElement;
     _enabled: boolean;
     _active: boolean;
     _touches: { [string | number]: Point };
     _minTouches: number;
     _clickTolerance: number;
     _sum: Point;
+    _alertContainer: HTMLElement;
+    _alertTimer: TimeoutID;
 
-    constructor(options: { clickTolerance: number }) {
+    constructor(map: Map, options: { clickTolerance: number }) {
+        this._map = map;
+        this._el = map.getCanvasContainer();
         this._minTouches = 1;
         this._clickTolerance = options.clickTolerance || 1;
         this.reset();
+        bindAll(['_addTouchPanBlocker', '_showTouchPanBlockerAlert'], this);
     }
 
     reset() {
@@ -30,7 +40,21 @@ export default class TouchPanHandler {
 
     touchmove(e: TouchEvent, points: Array<Point>, mapTouches: Array<Touch>) {
         if (!this._active || mapTouches.length < this._minTouches) return;
+
+        // if cooperative gesture handling is set to true, require two fingers to touch pan
+        if (this._map._cooperativeGestures && !this._map.isMoving()) {
+            if (mapTouches.length === 1) {
+                this._showTouchPanBlockerAlert();
+                return;
+            } else if (this._alertContainer.style.visibility !== 'hidden') {
+                // immediately hide alert if it is visible when two fingers are used to pan.
+                this._alertContainer.style.visibility = 'hidden';
+                clearTimeout(this._alertTimer);
+            }
+        }
+
         e.preventDefault();
+
         return this._calculateTransform(e, points, mapTouches);
     }
 
@@ -84,10 +108,20 @@ export default class TouchPanHandler {
 
     enable() {
         this._enabled = true;
+        if (this._map._cooperativeGestures) {
+            this._addTouchPanBlocker();
+            // override touch-action css property to enable scrolling page over map
+            this._el.classList.add('mapboxgl-touch-pan-blocker-override', 'mapboxgl-scrollable-page');
+        }
     }
 
     disable() {
         this._enabled = false;
+        if (this._map._cooperativeGestures) {
+            clearTimeout(this._alertTimer);
+            this._alertContainer.remove();
+            this._el.classList.remove('mapboxgl-touch-pan-blocker-override', 'mapboxgl-scrollable-page');
+        }
         this.reset();
     }
 
@@ -98,4 +132,28 @@ export default class TouchPanHandler {
     isActive() {
         return this._active;
     }
+
+    _addTouchPanBlocker() {
+        if (this._map && !this._alertContainer) {
+            this._alertContainer = DOM.create('div', 'mapboxgl-touch-pan-blocker', this._map._container);
+
+            this._alertContainer.textContent = this._map._getUIString('TouchPanBlocker.Message');
+
+            // dynamically set the font size of the touch pan blocker alert message
+            this._alertContainer.style.fontSize = `${Math.max(10, Math.min(24, Math.floor(this._el.clientWidth * 0.05)))}px`;
+        }
+    }
+
+    _showTouchPanBlockerAlert() {
+        if (this._alertContainer.style.visibility === 'hidden') this._alertContainer.style.visibility = 'visible';
+
+        this._alertContainer.classList.add('mapboxgl-touch-pan-blocker-show');
+
+        clearTimeout(this._alertTimer);
+
+        this._alertTimer = setTimeout(() => {
+            this._alertContainer.classList.remove('mapboxgl-touch-pan-blocker-show');
+        }, 500);
+    }
+
 }
@@ -2,6 +2,7 @@
 
 import Point from '@mapbox/point-geometry';
 import DOM from '../../util/dom.js';
+import type Map from '../map.js';
 
 class TwoTouchHandler {
 
@@ -205,6 +206,12 @@ export class TouchPitchHandler extends TwoTouchHandler {
     _valid: boolean | void;
     _firstMove: number;
     _lastPoints: [Point, Point];
+    _map: Map;
+
+    constructor(map: Map) {
+        super();
+        this._map = map;
+    }
 
     reset() {
         super.reset();
@@ -220,13 +227,17 @@ export class TouchPitchHandler extends TwoTouchHandler {
             this._valid = false;
 
         }
+
     }
 
     _move(points: [Point, Point], center: Point, e: TouchEvent) {
         const vectorA = points[0].sub(this._lastPoints[0]);
         const vectorB = points[1].sub(this._lastPoints[1]);
 
+        if (this._map._cooperativeGestures && e.touches.length < 3) return;
+
         this._valid = this.gestureBeginsVertically(vectorA, vectorB, e.timeStamp);
+
         if (!this._valid) return;
 
         this._lastPoints = points;

@@ -246,7 +246,7 @@ class HandlerManager {
         const tapDragZoom = new TapDragZoomHandler();
         this._add('tapDragZoom', tapDragZoom);
 
-        const touchPitch = map.touchPitch = new TouchPitchHandler();
+        const touchPitch = map.touchPitch = new TouchPitchHandler(map);
         this._add('touchPitch', touchPitch);
 
         const mouseRotate = new MouseRotateHandler(options);
@@ -256,7 +256,7 @@ class HandlerManager {
         this._add('mousePitch', mousePitch, ['mouseRotate']);
 
         const mousePan = new MousePanHandler(options);
-        const touchPan = new TouchPanHandler(options);
+        const touchPan = new TouchPanHandler(map, options);
         map.dragPan = new DragPanHandler(el, mousePan, touchPan);
         this._add('mousePan', mousePan);
         this._add('touchPan', touchPan, ['touchZoom', 'touchRotate']);
@@ -309,6 +309,7 @@ class HandlerManager {
     isZooming() {
         return !!this._eventsInProgress.zoom || this._map.scrollZoom.isZooming();
     }
+
     isRotating() {
         return !!this._eventsInProgress.rotate;
     }

@@ -106,7 +106,7 @@ type MapOptions = {
     doubleClickZoom?: boolean,
     touchZoomRotate?: boolean,
     touchPitch?: boolean,
-    gestureHandling?: boolean,
+    cooperativeGestures?: boolean,
     trackResize?: boolean,
     center?: LngLatLike,
     zoom?: number,
@@ -149,7 +149,7 @@ const defaultOptions = {
     doubleClickZoom: true,
     touchZoomRotate: true,
     touchPitch: true,
-    gestureHandling: false,
+    cooperativeGestures: false,
 
     bearingSnap: 7,
     clickTolerance: 3,
@@ -236,7 +236,7 @@ const defaultOptions = {
  * @param {boolean} [options.doubleClickZoom=true] If `true`, the "double click to zoom" interaction is enabled (see {@link DoubleClickZoomHandler}).
  * @param {boolean | Object} [options.touchZoomRotate=true] If `true`, the "pinch to rotate and zoom" interaction is enabled. An `Object` value is passed as options to {@link TouchZoomRotateHandler#enable}.
  * @param {boolean | Object} [options.touchPitch=true] If `true`, the "drag to pitch" interaction is enabled. An `Object` value is passed as options to {@link TouchPitchHandler#enable}.
- * @param {boolean} [options.gestureHandling=false] If `true`, scroll zoom will require pressing the ctrl or ⌘ key while scrolling to zoom map.
+ * @param {boolean} [options.cooperativeGestures] If `true`, scroll zoom will require pressing the ctrl or ⌘ key while scrolling to zoom map, and touch pan will require using two fingers while panning to move the map. Touch pitch will require three fingers to activate if enabled.
  * @param {boolean} [options.trackResize=true] If `true`, the map will automatically resize when the browser window resizes.
  * @param {LngLatLike} [options.center=[0, 0]] The inital geographical centerpoint of the map. If `center` is not specified in the constructor options, Mapbox GL JS will look for it in the map's style object. If it is not specified in the style, either, it will default to `[0, 0]` Note: Mapbox GL uses longitude, latitude coordinate order (as opposed to latitude, longitude) to match GeoJSON.
  * @param {number} [options.zoom=0] The initial zoom level of the map. If `zoom` is not specified in the constructor options, Mapbox GL JS will look for it in the map's style object. If it is not specified in the style, either, it will default to `0`.
@@ -345,7 +345,7 @@ class Map extends Camera {
     _removed: boolean;
     _speedIndexTiming: boolean;
     _clickTolerance: number;
-    _gestureHandling: boolean;
+    _cooperativeGestures: boolean;
     _silenceAuthErrors: boolean;
     _averageElevationLastSampledAt: number;
     _averageElevation: EasedVariable;
@@ -446,7 +446,7 @@ class Map extends Camera {
         this._mapId = uniqueId();
         this._locale = extend({}, defaultLocale, options.locale);
         this._clickTolerance = options.clickTolerance;
-        this._gestureHandling = options.gestureHandling;
+        this._cooperativeGestures = options.cooperativeGestures;
 
         this._averageElevationLastSampledAt = -Infinity;
         this._averageElevation = new EasedVariable(0);

@@ -0,0 +1 @@
+../../debug/scroll_zoom_blocker.html
@@ -24,12 +24,12 @@ function createMap(t) {
     });
 }
 
-function createMapWithGestureHandling(t) {
+function createMapWithCooperativeGestures(t) {
     t.stub(Map.prototype, '_detectMissingCSS');
     t.stub(Map.prototype, '_authenticate');
     return new Map({
         container: DOM.create('div', '', window.document.body),
-        gestureHandling: true
+        cooperativeGestures: true
     });
 }
 
@@ -376,15 +376,15 @@ test('ScrollZoomHandler', (t) => {
     t.end();
 });
 
-test('When gestureHandling option is set to true, a .mapboxgl-scroll-zoom-blocker element is added to map', (t) => {
-    const map = createMapWithGestureHandling(t);
+test('When cooperativeGestures option is set to true, a .mapboxgl-scroll-zoom-blocker element is added to map', (t) => {
+    const map = createMapWithCooperativeGestures(t);
 
     t.equal(map.getContainer().querySelectorAll('.mapboxgl-scroll-zoom-blocker').length, 1);
     t.end();
 });
 
-test('When gestureHandling option is set to true, scroll zoom is prevented when the ctrl key or meta key is not pressed during wheel event', (t) => {
-    const map = createMapWithGestureHandling(t);
+test('When cooperativeGestures option is set to true, scroll zoom is prevented when the ctrl key or meta key is not pressed during wheel event', (t) => {
+    const map = createMapWithCooperativeGestures(t);
 
     const zoomSpy = t.spy();
     map.on('zoom', zoomSpy);
@@ -395,8 +395,8 @@ test('When gestureHandling option is set to true, scroll zoom is prevented when
     t.end();
 });
 
-test('When gestureHandling option is set to true, scroll zoom is activated when ctrl key is pressed during wheel event', (t) => {
-    const map = createMapWithGestureHandling(t);
+test('When cooperativeGestures option is set to true, scroll zoom is activated when ctrl key is pressed during wheel event', (t) => {
+    const map = createMapWithCooperativeGestures(t);
 
     const zoomSpy = t.spy();
     map.on('zoom', zoomSpy);
@@ -409,8 +409,8 @@ test('When gestureHandling option is set to true, scroll zoom is activated when
     t.end();
 });
 
-test('When gestureHandling option is set to true, scroll zoom is activated when meta key is pressed during wheel event', (t) => {
-    const map = createMapWithGestureHandling(t);
+test('When cooperativeGestures option is set to true, scroll zoom is activated when meta key is pressed during wheel event', (t) => {
+    const map = createMapWithCooperativeGestures(t);
 
     const zoomSpy = t.spy();
     map.on('zoom', zoomSpy);
@@ -424,7 +424,7 @@ test('When gestureHandling option is set to true, scroll zoom is activated when
 });
 
 test('Disabling scrollZoom removes scroll zoom blocker container', (t) => {
-    const map = createMapWithGestureHandling(t);
+    const map = createMapWithCooperativeGestures(t);
 
     map.scrollZoom.disable();