Event improvements

CHANGELOG.md

@@ -1,3 +1,9 @@
+## master
+
+### ⚠️ Breaking changes
+
+* `Evented` is no longer publicly exported, and `Evented#fire` and `Evented#listens` are now private. If you are writing a class that needs event emitting functionality, consider using [`EventEmitter`](https://nodejs.org/api/events.html#events_class_eventemitter) or similar libraries instead.
+
 ## 0.44.1
 
 ### 🐛 Bug fixes

bench/lib/create_style.js

@@ -1,7 +1,7 @@
 // @flow
 
 const Style = require('../../src/style/style');
-const Evented = require('../../src/util/evented');
+const {Evented} = require('../../src/util/evented');
 
 class StubMap extends Evented {
     _transformRequest(url) {

docs/documentation.yml

@@ -51,8 +51,8 @@ toc:
   - CanvasSource
   - name: Events
     description: |
-      `Evented` is Mapbox GL JS's event system. It is sometimes extended when
-      implementing [IControls](#IControl) and other extensions.
+      `Map` (and some other classes) emit events in response to user interactions or changes in state. `Evented`
+      is the interface used to bind and unbind listeners for these events.
   - Evented
   - MapMouseEvent
   - MapTouchEvent

docs/pages/example/drag-a-point.html

@@ -19,14 +19,6 @@
 <pre id='coordinates' class='coordinates'></pre>
 
 <script>
-// Holds mousedown state for events. if this
-// flag is active, we move the point on `mousemove`.
-var isDragging;
-
-// Is the cursor over a point? if this
-// flag is active, we listen for a mousedown event.
-var isCursorOverPoint;
-
 var coordinates = document.getElementById('coordinates');
 var map = new mapboxgl.Map({
     container: 'map',
@@ -48,21 +40,7 @@
     }]
 };
 
-function mouseDown() {
-    if (!isCursorOverPoint) return;
-
-    isDragging = true;
-
-    // Set a cursor indicator
-    canvas.style.cursor = 'grab';
-
-    // Mouse events
-    map.on('mousemove', onMove);
-    map.once('mouseup', onUp);
-}
-
 function onMove(e) {
-    if (!isDragging) return;
     var coords = e.lngLat;
 
     // Set a UI indicator for dragging.
@@ -75,15 +53,13 @@
 }
 
 function onUp(e) {
-    if (!isDragging) return;
     var coords = e.lngLat;
 
     // Print the coordinates of where the point had
     // finished being dragged to on the map.
     coordinates.style.display = 'block';
     coordinates.innerHTML = 'Longitude: ' + coords.lng + '<br />Latitude: ' + coords.lat;
     canvas.style.cursor = '';
-    isDragging = false;
 
     // Unbind mouse events
     map.off('mousemove', onMove);
@@ -111,17 +87,21 @@
     map.on('mouseenter', 'point', function() {
         map.setPaintProperty('point', 'circle-color', '#3bb2d0');
         canvas.style.cursor = 'move';
-        isCursorOverPoint = true;
-        map.dragPan.disable();
     });
 
     map.on('mouseleave', 'point', function() {
         map.setPaintProperty('point', 'circle-color', '#3887be');
         canvas.style.cursor = '';
-        isCursorOverPoint = false;
-        map.dragPan.enable();
     });
 
-    map.on('mousedown', mouseDown);
+    map.on('mousedown', 'point', function(e) {
+        // Prevent the default map drag behavior.
+        e.preventDefault();
+
+        canvas.style.cursor = 'grab';
+
+        map.on('mousemove', onMove);
+        map.once('mouseup', onUp);
+    });
 });
 </script>

src/index.js

@@ -15,7 +15,6 @@ const Style = require('./style/style');
 const LngLat = require('./geo/lng_lat');
 const LngLatBounds = require('./geo/lng_lat_bounds');
 const Point = require('@mapbox/point-geometry');
-const Evented = require('./util/evented');
 const config = require('./util/config');
 const rtlTextPlugin = require('./source/rtl_text_plugin');
 
@@ -38,7 +37,6 @@ module.exports = {
     LngLat,
     LngLatBounds,
     Point,
-    Evented,
     config,
 
     /**

src/source/canvas_source.js

@@ -5,10 +5,11 @@ const window = require('../util/window');
 const rasterBoundsAttributes = require('../data/raster_bounds_attributes');
 const VertexArrayObject = require('../render/vertex_array_object');
 const Texture = require('../render/texture');
+const {ErrorEvent} = require('../util/evented');
 
 import type Map from '../ui/map';
 import type Dispatcher from '../util/dispatcher';
-import type Evented from '../util/evented';
+import type {Evented} from '../util/evented';
 
 /**
  * A data source containing the contents of an HTML canvas.
@@ -78,7 +79,7 @@ class CanvasSource extends ImageSource {
         this.height = this.canvas.height;
 
         if (this._hasInvalidDimensions()) {
-            this.fire('error', new Error('Canvas dimensions cannot be less than or equal to zero.'));
+            this.fire(new ErrorEvent(new Error('Canvas dimensions cannot be less than or equal to zero.')));
             return;
         }
 

src/source/geojson_source.js

@@ -1,6 +1,6 @@
 // @flow
 
-const Evented = require('../util/evented');
+const {Event, ErrorEvent, Evented} = require('../util/evented');
 const util = require('../util/util');
 const window = require('../util/window');
 const EXTENT = require('../data/extent');
@@ -137,10 +137,10 @@ class GeoJSONSource extends Evented implements Source {
     }
 
     load() {
-        this.fire('dataloading', {dataType: 'source'});
+        this.fire(new Event('dataloading', {dataType: 'source'}));
         this._updateWorkerData((err) => {
             if (err) {
-                this.fire('error', {error: err});
+                this.fire(new ErrorEvent(err));
                 return;
             }
 
@@ -152,7 +152,7 @@ class GeoJSONSource extends Evented implements Source {
 
             // although GeoJSON sources contain no metadata, we fire this event to let the SourceCache
             // know its ok to start requesting tiles.
-            this.fire('data', data);
+            this.fire(new Event('data', data));
         });
     }
 
@@ -169,18 +169,18 @@ class GeoJSONSource extends Evented implements Source {
      */
     setData(data: GeoJSON | string) {
         this._data = data;
-        this.fire('dataloading', {dataType: 'source'});
+        this.fire(new Event('dataloading', {dataType: 'source'}));
         this._updateWorkerData((err) => {
             if (err) {
-                return this.fire('error', { error: err });
+                return this.fire(new ErrorEvent(err));
             }
 
             const data: Object = { dataType: 'source', sourceDataType: 'content' };
             if (this._collectResourceTiming && this._resourceTiming && (this._resourceTiming.length > 0)) {
                 data.resourceTiming = this._resourceTiming;
                 this._resourceTiming = [];
             }
-            this.fire('data', data);
+            this.fire(new Event('data', data));
         });
 
         return this;

src/source/image_source.js

@@ -4,7 +4,7 @@ const util = require('../util/util');
 const {CanonicalTileID} = require('./tile_id');
 const LngLat = require('../geo/lng_lat');
 const Point = require('@mapbox/point-geometry');
-const Evented = require('../util/evented');
+const {Event, ErrorEvent, Evented} = require('../util/evented');
 const ajax = require('../util/ajax');
 const browser = require('../util/browser');
 const EXTENT = require('../data/extent');
@@ -92,13 +92,13 @@ class ImageSource extends Evented implements Source {
     }
 
     load() {
-        this.fire('dataloading', {dataType: 'source'});
+        this.fire(new Event('dataloading', {dataType: 'source'}));
 
         this.url = this.options.url;
 
         ajax.getImage(this.map._transformRequest(this.url, ajax.ResourceType.Image), (err, image) => {
             if (err) {
-                this.fire('error', {error: err});
+                this.fire(new ErrorEvent(err));
             } else if (image) {
                 this.image = browser.getImageData(image);
                 this._finishLoading();
@@ -109,7 +109,7 @@ class ImageSource extends Evented implements Source {
     _finishLoading() {
         if (this.map) {
             this.setCoordinates(this.coordinates);
-            this.fire('data', {dataType: 'source', sourceDataType: 'metadata'});
+            this.fire(new Event('data', {dataType: 'source', sourceDataType: 'metadata'}));
         }
     }
 
@@ -175,7 +175,7 @@ class ImageSource extends Evented implements Source {
             delete this.boundsBuffer;
         }
 
-        this.fire('data', {dataType:'source', sourceDataType: 'content'});
+        this.fire(new Event('data', {dataType:'source', sourceDataType: 'content'}));
         return this;
     }
 

src/source/raster_dem_tile_source.js

@@ -2,7 +2,7 @@
 
 const ajax = require('../util/ajax');
 const util = require('../util/util');
-const Evented = require('../util/evented');
+const {Evented} = require('../util/evented');
 const normalizeURL = require('../util/mapbox').normalizeTileURL;
 const browser = require('../util/browser');
 const {OverscaledTileID} = require('./tile_id');

src/source/raster_tile_source.js

@@ -2,7 +2,7 @@
 
 const util = require('../util/util');
 const ajax = require('../util/ajax');
-const Evented = require('../util/evented');
+const {Event, ErrorEvent, Evented} = require('../util/evented');
 const loadTileJSON = require('./load_tilejson');
 const normalizeURL = require('../util/mapbox').normalizeTileURL;
 const TileBounds = require('./tile_bounds');
@@ -53,19 +53,19 @@ class RasterTileSource extends Evented implements Source {
     }
 
     load() {
-        this.fire('dataloading', {dataType: 'source'});
+        this.fire(new Event('dataloading', {dataType: 'source'}));
         loadTileJSON(this._options, this.map._transformRequest, (err, tileJSON) => {
             if (err) {
-                this.fire('error', err);
+                this.fire(new ErrorEvent(err));
             } else if (tileJSON) {
                 util.extend(this, tileJSON);
                 if (tileJSON.bounds) this.tileBounds = new TileBounds(tileJSON.bounds, this.minzoom, this.maxzoom);
 
                 // `content` is included here to prevent a race condition where `Style#_updateSources` is called
                 // before the TileJSON arrives. this makes sure the tiles needed are loaded once TileJSON arrives
                 // ref: https://github.com/mapbox/mapbox-gl-js/pull/4347#discussion_r104418088
-                this.fire('data', {dataType: 'source', sourceDataType: 'metadata'});
-                this.fire('data', {dataType: 'source', sourceDataType: 'content'});
+                this.fire(new Event('data', {dataType: 'source', sourceDataType: 'metadata'}));
+                this.fire(new Event('data', {dataType: 'source', sourceDataType: 'content'}));
             }
         });
     }

src/source/rtl_text_plugin.js

@@ -1,5 +1,6 @@
 // @flow
-const Evented = require('../util/evented');
+
+const {Event, Evented} = require('../util/evented');
 
 let pluginRequested = false;
 let pluginURL = null;
@@ -32,7 +33,7 @@ module.exports.setRTLTextPlugin = function(url: string, callback: ErrorCallback)
     pluginRequested = true;
     pluginURL = url;
     module.exports.errorCallback = callback;
-    module.exports.evented.fire('pluginAvailable', { pluginURL: pluginURL, errorCallback: callback });
+    module.exports.evented.fire(new Event('pluginAvailable', { pluginURL: pluginURL, errorCallback: callback }));
 };
 
 module.exports.applyArabicShaping = (null: ?Function);

src/source/source.js

@@ -3,7 +3,7 @@
 const util = require('../util/util');
 
 import type Dispatcher from '../util/dispatcher';
-import type Evented from '../util/evented';
+import type {Event, Evented} from '../util/evented';
 import type Map from '../ui/map';
 import type Tile from './tile';
 import type {OverscaledTileID} from './tile_id';
@@ -56,7 +56,7 @@ export interface Source {
 
     hasTransition(): boolean;
 
-    fire(type: string, data: Object): mixed;
+    fire(event: Event): mixed;
 
     +onAdd?: (map: Map) => void;
     +onRemove?: (map: Map) => void;

src/source/source_cache.js

@@ -2,7 +2,7 @@
 
 const createSource = require('./source').create;
 const Tile = require('./tile');
-const Evented = require('../util/evented');
+const {Event, ErrorEvent, Evented} = require('../util/evented');
 const Cache = require('../util/lru_cache');
 const Coordinate = require('../geo/coordinate');
 const util = require('../util/util');
@@ -235,7 +235,7 @@ class SourceCache extends Evented {
     _tileLoaded(tile: Tile, id: string | number, previousState: TileState, err: ?Error) {
         if (err) {
             tile.state = 'errored';
-            if (err.status !== 404) this._source.fire('error', {tile: tile, error: err});
+            if (err.status !== 404) this._source.fire(new ErrorEvent(err, {tile}));
             // continue to try loading parent/children tiles if a tile doesn't exist (404)
             else this.update(this.transform);
             return;
@@ -245,7 +245,7 @@ class SourceCache extends Evented {
         if (previousState === 'expired') tile.refreshedUponExpiration = true;
         this._setTileReloadTimer(id, tile);
         if (this.getSource().type === 'raster-dem' && tile.dem) this._backfillDEM(tile);
-        this._source.fire('data', {dataType: 'source', tile: tile, coord: tile.tileID});
+        this._source.fire(new Event('data', {dataType: 'source', tile: tile, coord: tile.tileID}));
 
         // HACK this is necessary to fix https://github.com/mapbox/mapbox-gl-js/issues/2986
         if (this.map) this.map.painter.tileExtentVAO.vao = null;
@@ -589,7 +589,7 @@ class SourceCache extends Evented {
 
         tile.uses++;
         this._tiles[tileID.key] = tile;
-        if (!cached) this._source.fire('dataloading', {tile: tile, coord: tile.tileID, dataType: 'source'});
+        if (!cached) this._source.fire(new Event('dataloading', {tile: tile, coord: tile.tileID, dataType: 'source'}));
 
         return tile;
     }

src/source/vector_tile_source.js

@@ -1,6 +1,6 @@
 // @flow
 
-const Evented = require('../util/evented');
+const {Event, ErrorEvent, Evented} = require('../util/evented');
 const util = require('../util/util');
 const loadTileJSON = require('./load_tilejson');
 const normalizeURL = require('../util/mapbox').normalizeTileURL;
@@ -60,20 +60,20 @@ class VectorTileSource extends Evented implements Source {
     }
 
     load() {
-        this.fire('dataloading', {dataType: 'source'});
+        this.fire(new Event('dataloading', {dataType: 'source'}));
 
         loadTileJSON(this._options, this.map._transformRequest, (err, tileJSON) => {
             if (err) {
-                this.fire('error', err);
+                this.fire(new ErrorEvent(err));
             } else if (tileJSON) {
                 util.extend(this, tileJSON);
                 if (tileJSON.bounds) this.tileBounds = new TileBounds(tileJSON.bounds, this.minzoom, this.maxzoom);
 
                 // `content` is included here to prevent a race condition where `Style#_updateSources` is called
                 // before the TileJSON arrives. this makes sure the tiles needed are loaded once TileJSON arrives
                 // ref: https://github.com/mapbox/mapbox-gl-js/pull/4347#discussion_r104418088
-                this.fire('data', {dataType: 'source', sourceDataType: 'metadata'});
-                this.fire('data', {dataType: 'source', sourceDataType: 'content'});
+                this.fire(new Event('data', {dataType: 'source', sourceDataType: 'metadata'}));
+                this.fire(new Event('data', {dataType: 'source', sourceDataType: 'content'}));
             }
         });
     }