add pitchstart and pitchend events (#4473)

* add pitchstart and pitchend events

* docs docs docs 📝

* testing ☢️

* ensure pitch events fire with interaction handlers

src/ui/camera.js

@@ -295,6 +295,7 @@ class Camera extends Evented {
      * @memberof Map#
      * @param {number} pitch The pitch to set, measured in degrees away from the plane of the screen (0-60).
      * @param {Object} [eventData] Additional properties to be added to event objects of events triggered by this method.
+     * @fires pitchstart
      * @fires movestart
      * @fires moveend
      * @returns {Map} `this`
@@ -405,12 +406,14 @@ class Camera extends Evented {
      * @param {Object} [eventData] Additional properties to be added to event objects of events triggered by this method.
      * @fires movestart
      * @fires zoomstart
+     * @fires pitchstart
+     * @fires rotate
      * @fires move
      * @fires zoom
-     * @fires rotate
      * @fires pitch
-     * @fires zoomend
      * @fires moveend
+     * @fires zoomend
+     * @fires pitchend
      * @returns {Map} `this`
      */
     jumpTo(options, eventData) {
@@ -454,7 +457,9 @@ class Camera extends Evented {
         }
 
         if (pitchChanged) {
-            this.fire('pitch', eventData);
+            this.fire('pitchstart', eventData)
+                .fire('pitch', eventData)
+                .fire('pitchend', eventData);
         }
 
         return this.fire('moveend', eventData);
@@ -471,12 +476,14 @@ class Camera extends Evented {
      * @param {Object} [eventData] Additional properties to be added to event objects of events triggered by this method.
      * @fires movestart
      * @fires zoomstart
+     * @fires pitchstart
+     * @fires rotate
      * @fires move
      * @fires zoom
-     * @fires rotate
      * @fires pitch
-     * @fires zoomend
      * @fires moveend
+     * @fires zoomend
+     * @fires pitchend
      * @returns {Map} `this`
      * @see [Navigate the map with game-like controls](https://www.mapbox.com/mapbox-gl-js/example/game-controls/)
      */
@@ -532,6 +539,9 @@ class Camera extends Evented {
         if (this.zooming) {
             this.fire('zoomstart', eventData);
         }
+        if (this.pitching) {
+            this.fire('pitchstart', eventData);
+        }
 
         clearTimeout(this._onEaseEnd);
 
@@ -573,6 +583,7 @@ class Camera extends Evented {
 
     _easeToEnd(eventData) {
         const wasZooming = this.zooming;
+        const wasPitching = this.pitching;
         this.moving = false;
         this.zooming = false;
         this.rotating = false;
@@ -581,6 +592,9 @@ class Camera extends Evented {
         if (wasZooming) {
             this.fire('zoomend', eventData);
         }
+        if (wasPitching) {
+            this.fire('pitchend', eventData);
+        }
         this.fire('moveend', eventData);
 
     }
@@ -612,12 +626,14 @@ class Camera extends Evented {
      * @param {Object} [eventData] Additional properties to be added to event objects of events triggered by this method.
      * @fires movestart
      * @fires zoomstart
+     * @fires pitchstart
      * @fires move
      * @fires zoom
      * @fires rotate
      * @fires pitch
-     * @fires zoomend
      * @fires moveend
+     * @fires zoomend
+     * @fires pitchend
      * @returns {Map} `this`
      * @example
      * // fly with default options to null island
@@ -760,6 +776,7 @@ class Camera extends Evented {
 
         this.fire('movestart', eventData);
         this.fire('zoomstart', eventData);
+        if (this.pitching) this.fire('pitchstart', eventData);
 
         this._ease(function (k) {
             // s: The distance traveled along the flight path, measured in ρ-screenfuls.
@@ -789,11 +806,13 @@ class Camera extends Evented {
                 this.fire('pitch', eventData);
             }
         }, function() {
+            const wasPitching = this.pitching;
             this.moving = false;
             this.zooming = false;
             this.rotating = false;
             this.pitching = false;
 
+            if (wasPitching) this.fire('pitchend', eventData);
             this.fire('zoomend', eventData);
             this.fire('moveend', eventData);
         }, options);
@@ -884,12 +903,32 @@ class Camera extends Evented {
 }
 
 /**
- * Fired whenever the map's pitch (tilt) changes.
+ * Fired whenever the map's pitch (tilt) begins a change as
+ * the result of either user interaction or methods such as [Map#flyTo](#Map#flyTo).
+ *
+ * @event pitchstart
+ * @memberof Map
+ * @instance
+ * @property {MapEventData} data
+ */
+
+/**
+ * Fired whenever the map's pitch (tilt) changes as.
+ * the result of either user interaction or methods such as [Map#flyTo](#Map#flyTo).
  *
  * @event pitch
  * @memberof Map
  * @instance
  * @property {MapEventData} data
  */
 
+/**
+ * Fired immediately after the map's pitch (tilt) finishes changing as
+ * the result of either user interaction or methods such as [Map#flyTo](#Map#flyTo).
+ *
+ * @event pitchend
+ * @memberof Map
+ * @instance
+ * @property {MapEventData} data
+ */
 module.exports = Camera;

src/ui/handler/drag_rotate.js

@@ -101,6 +101,9 @@ class DragRotateHandler {
             this._map.moving = true;
             this._fireEvent('rotatestart', e);
             this._fireEvent('movestart', e);
+            if (this._pitchWithRotate) {
+                this._fireEvent('pitchstart', e);
+            }
         }
 
         const map = this._map;
@@ -119,7 +122,10 @@ class DragRotateHandler {
         inertia.push([Date.now(), map._normalizeBearing(bearing, last[1])]);
 
         map.transform.bearing = bearing;
-        if (this._pitchWithRotate) map.transform.pitch = pitch;
+        if (this._pitchWithRotate) {
+            this._fireEvent('pitch', e);
+            map.transform.pitch = pitch;
+        }
 
         this._fireEvent('rotate', e);
         this._fireEvent('move', e);
@@ -150,6 +156,7 @@ class DragRotateHandler {
                 this._map.moving = false;
                 this._fireEvent('moveend', e);
             }
+            if (this._pitchWithRotate) this._fireEvent('pitchend', e);
         };
 
         if (inertia.length < 2) {

test/unit/ui/camera.test.js

@@ -124,6 +124,22 @@ test('camera', (t) => {
             t.end();
         });
 
+        t.test('emits pitch events, preserving eventData', (t)=>{
+            let started, pitched, ended;
+            const eventData = { data: 'ok'};
+
+            camera
+                .on('pitchstart', (d) => { started = d.data; })
+                .on('pitch', (d) => { pitched = d.data; })
+                .on('pitchend', (d) => { ended = d.data; });
+
+            camera.jumpTo({pitch: 10}, eventData);
+            t.equal(started, 'ok');
+            t.equal(pitched, 'ok');
+            t.equal(ended, 'ok');
+            t.end();
+        });
+
         t.test('cancels in-progress easing', (t) => {
             camera.panTo([3, 4]);
             t.ok(camera.isEasing());
@@ -861,14 +877,16 @@ test('camera', (t) => {
             //As such; it deserves a separate test case. This test case flies the map from A to A.
             const fromTo = { center: [100, 0] };
             const camera = createCamera(fromTo);
-            let movestarted, moved, rotated, pitched, zoomstarted, zoomed, zoomended;
+            let movestarted, moved, rotated, pitched, pitchstarted, pitchended, zoomstarted, zoomed, zoomended;
             const eventData = { data: 'ok' };
 
             camera
                 .on('movestart', (d) => { movestarted = d.data; })
                 .on('move', (d) => { moved = d.data; })
                 .on('rotate', (d) => { rotated = d.data; })
                 .on('pitch', (d) => { pitched = d.data; })
+                .on('pitchstart', (d) => { pitchstarted = d.data; })
+                .on('pitchend', (d) => { pitchended = d.data; })
                 .on('zoomstart', (d) => { zoomstarted = d.data; })
                 .on('zoom', (d) => { zoomed = d.data; })
                 .on('zoomend', (d) => { zoomended = d.data; })
@@ -884,6 +902,8 @@ test('camera', (t) => {
                     t.equal(zoomended, undefined);
                     t.equal(rotated, undefined);
                     t.equal(pitched, undefined);
+                    t.equal(pitchstarted, undefined);
+                    t.equal(pitchended, undefined);
                     t.equal(d.data, 'ok');
                     t.end();
                 });