From 018ad97f25647e49e6d70e8f6c48b29c6ecd4b01 Mon Sep 17 00:00:00 2001 From: Andreas Hocevar Date: Sun, 20 Jun 2021 20:22:53 +0200 Subject: [PATCH] Use generics to limit event types in on(), once() and un() --- src/ol/Collection.js | 2 +- src/ol/Feature.js | 1 + src/ol/Geolocation.js | 1 + src/ol/Object.js | 2 ++ src/ol/Observable.js | 12 +++++++++--- src/ol/Overlay.js | 1 + src/ol/PluggableMap.js | 1 + src/ol/View.js | 1 + src/ol/control/Control.js | 2 ++ src/ol/control/FullScreen.js | 1 + src/ol/control/MousePosition.js | 1 + src/ol/control/ScaleLine.js | 1 + src/ol/interaction/DragAndDrop.js | 1 + src/ol/interaction/DragBox.js | 1 + src/ol/interaction/Draw.js | 1 + src/ol/interaction/Extent.js | 1 + src/ol/interaction/Interaction.js | 3 +++ src/ol/interaction/Modify.js | 1 + src/ol/interaction/Pointer.js | 3 +++ src/ol/interaction/Select.js | 1 + src/ol/interaction/Translate.js | 1 + src/ol/layer/Base.js | 2 ++ src/ol/layer/BaseTile.js | 2 +- src/ol/layer/BaseVector.js | 3 ++- src/ol/layer/Layer.js | 2 ++ src/ol/layer/VectorTile.js | 2 +- src/ol/source/Image.js | 1 + src/ol/source/Source.js | 2 ++ src/ol/source/Tile.js | 2 ++ src/ol/source/UrlTile.js | 1 + 30 files changed, 49 insertions(+), 7 deletions(-) diff --git a/src/ol/Collection.js b/src/ol/Collection.js index 401e19d256..30f9498d3a 100644 --- a/src/ol/Collection.js +++ b/src/ol/Collection.js @@ -59,7 +59,7 @@ export class CollectionEvent extends Event { * Collection as a whole. * * @fires CollectionEvent - * + * @extends BaseObject<'add'|'remove'|'change:length'> * @template T * @api */ diff --git a/src/ol/Feature.js b/src/ol/Feature.js index 502c623e20..fb174f8d74 100644 --- a/src/ol/Feature.js +++ b/src/ol/Feature.js @@ -58,6 +58,7 @@ import {listen, unlistenByKey} from './events.js'; * * @api * @template {import("./geom/Geometry.js").default} Geometry + * @extends BaseObject<'change:geometry'> */ class Feature extends BaseObject { /** diff --git a/src/ol/Geolocation.js b/src/ol/Geolocation.js index 62d2621652..b63adda9f2 100644 --- a/src/ol/Geolocation.js +++ b/src/ol/Geolocation.js @@ -82,6 +82,7 @@ class GeolocationError extends BaseEvent { * }); * * @fires module:ol/events/Event~BaseEvent#event:error + * @extends BaseObject<'change:accuracy'|'change:accuracyGeometry'|'change:altitude'|'change:altitudeAccuracy'|'change:heading'|'change:position'|'change:projection'|'change:speed'|'change:tracking'|'change:trackingOptions'> * @api */ class Geolocation extends BaseObject { diff --git a/src/ol/Object.js b/src/ol/Object.js index 3343b6521f..5dbcd9d357 100644 --- a/src/ol/Object.js +++ b/src/ol/Object.js @@ -78,6 +78,8 @@ export class ObjectEvent extends Event { * object.unset('foo'). * * @fires ObjectEvent + * @template {string} EventTypes + * @extends Observable<'propertychange'|EventTypes> * @api */ class BaseObject extends Observable { diff --git a/src/ol/Observable.js b/src/ol/Observable.js index 5962fd5dc7..be5a9412c3 100644 --- a/src/ol/Observable.js +++ b/src/ol/Observable.js @@ -5,6 +5,11 @@ import EventTarget from './events/Target.js'; import EventType from './events/EventType.js'; import {listen, listenOnce, unlistenByKey} from './events.js'; +/** + * @template ChildTypes + * @typedef {ChildTypes|'change'|'error'|Array} EventTypes + */ + /** * @classdesc * Abstract base class; normally only used for creating subclasses and not @@ -14,6 +19,7 @@ import {listen, listenOnce, unlistenByKey} from './events.js'; * {@link module:ol/Observable~Observable#changed}. * * @fires import("./events/Event.js").default + * @template {string} ChildTypes * @api */ class Observable extends EventTarget { @@ -48,7 +54,7 @@ class Observable extends EventTarget { /** * Listen for a certain type of event. - * @param {string|Array} type The event type or array of event types. + * @param {EventTypes} type The event type or array of event types. * @param {function(?): ?} listener The listener function. * @return {import("./events.js").EventsKey|Array} Unique key for the listener. If * called with an array of event types as the first argument, the return @@ -70,7 +76,7 @@ class Observable extends EventTarget { /** * Listen once for a certain type of event. - * @param {string|Array} type The event type or array of event types. + * @param {EventTypes} type The event type or array of event types. * @param {function(?): ?} listener The listener function. * @return {import("./events.js").EventsKey|Array} Unique key for the listener. If * called with an array of event types as the first argument, the return @@ -94,7 +100,7 @@ class Observable extends EventTarget { /** * Unlisten for a certain type of event. - * @param {string|Array} type The event type or array of event types. + * @param {EventTypes} type The event type or array of event types. * @param {function(?): ?} listener The listener function. * @api */ diff --git a/src/ol/Overlay.js b/src/ol/Overlay.js index 869eac4614..80dd9bceb2 100644 --- a/src/ol/Overlay.js +++ b/src/ol/Overlay.js @@ -101,6 +101,7 @@ const Property = { * popup.setPosition(coordinate); * map.addOverlay(popup); * + * @extends BaseObject<'change:element'|'change:map'|'change:offset'|'change:position'|'change:positioning'> * @api */ class Overlay extends BaseObject { diff --git a/src/ol/PluggableMap.js b/src/ol/PluggableMap.js index f21179a16a..6d6004a1d8 100644 --- a/src/ol/PluggableMap.js +++ b/src/ol/PluggableMap.js @@ -132,6 +132,7 @@ import {removeNode} from './dom.js'; * @fires import("./render/Event.js").default#precompose * @fires import("./render/Event.js").default#postcompose * @fires import("./render/Event.js").default#rendercomplete + * @extends BaseObject<'change:layergroup'|'change:size'|'change:target'|'change:view'|'precompose'|'singleclick'|'click'|'dblclick'|'pointerdrag'|'pointermove'|'postrender'|'movestart'|'moveend'|'postcompose'|'rendercomplete'> * @api */ class PluggableMap extends BaseObject { diff --git a/src/ol/View.js b/src/ol/View.js index 7dab1d6f90..de1514c8f2 100644 --- a/src/ol/View.js +++ b/src/ol/View.js @@ -288,6 +288,7 @@ const DEFAULT_MIN_ZOOM = 0; * the snap angle is 0), an animation will be triggered at the interaction end to * put back the view to a stable state; * + * @extends BaseObject<'change:center'|'change:resolution'|'change:rotation'> * @api */ class View extends BaseObject { diff --git a/src/ol/control/Control.js b/src/ol/control/Control.js index 81cef9b6d8..7295b973b0 100644 --- a/src/ol/control/Control.js +++ b/src/ol/control/Control.js @@ -41,6 +41,8 @@ import {removeNode} from '../dom.js'; * You can also extend this base for your own control class. See * examples/custom-controls for an example of how to do this. * + * @template {string} EventTypes + * @extends BaseObject * @api */ class Control extends BaseObject { diff --git a/src/ol/control/FullScreen.js b/src/ol/control/FullScreen.js index b29a827cf0..4362066be4 100644 --- a/src/ol/control/FullScreen.js +++ b/src/ol/control/FullScreen.js @@ -66,6 +66,7 @@ const FullScreenEventType = { * * @fires FullScreenEventType#enterfullscreen * @fires FullScreenEventType#leavefullscreen + * @extends Control<'enterfullscreen'|'leavefullscreen'> * @api */ class FullScreen extends Control { diff --git a/src/ol/control/MousePosition.js b/src/ol/control/MousePosition.js index be69cad9cb..223019827c 100644 --- a/src/ol/control/MousePosition.js +++ b/src/ol/control/MousePosition.js @@ -50,6 +50,7 @@ const COORDINATE_FORMAT = 'coordinateFormat'; * On touch devices, which usually do not have a mouse cursor, the coordinates * of the currently touched position are shown. * + * @extends Control<'change:coordinaetFormat'|'change:projection'> * @api */ class MousePosition extends Control { diff --git a/src/ol/control/ScaleLine.js b/src/ol/control/ScaleLine.js index 10af5361ab..5938f7a30b 100644 --- a/src/ol/control/ScaleLine.js +++ b/src/ol/control/ScaleLine.js @@ -69,6 +69,7 @@ const DEFAULT_DPI = 25.4 / 0.28; * When specifying `bar` as `true`, a scalebar will be rendered instead * of a scaleline. * + * @extends Control<'change:units'> * @api */ class ScaleLine extends Control { diff --git a/src/ol/interaction/DragAndDrop.js b/src/ol/interaction/DragAndDrop.js index 44bb6aaac4..2065418197 100644 --- a/src/ol/interaction/DragAndDrop.js +++ b/src/ol/interaction/DragAndDrop.js @@ -82,6 +82,7 @@ export class DragAndDropEvent extends Event { * combinnation of formats read both text string and ArrayBuffer sources. Older browsers such * as IE which do not support this will need a TextDecoder polyfill to be loaded before use. * + * @extends Interaction<'addfeatures'> * @api * * @fires DragAndDropEvent diff --git a/src/ol/interaction/DragBox.js b/src/ol/interaction/DragBox.js index 804777da95..c0bfdc66d3 100644 --- a/src/ol/interaction/DragBox.js +++ b/src/ol/interaction/DragBox.js @@ -103,6 +103,7 @@ export class DragBoxEvent extends Event { * {@link module:ol/interaction/DragRotateAndZoom}). * * @fires DragBoxEvent + * @extends PointerInteraction<'boxcancel'|'boxdrag'|'boxend'> * @api */ class DragBox extends PointerInteraction { diff --git a/src/ol/interaction/Draw.js b/src/ol/interaction/Draw.js index 960945320f..b4cb83a9ae 100644 --- a/src/ol/interaction/Draw.js +++ b/src/ol/interaction/Draw.js @@ -178,6 +178,7 @@ export class DrawEvent extends Event { * Interaction for drawing feature geometries. * * @fires DrawEvent + * @extends PointerInteraction<'drawabort'|'drawend'|'drawstart'> * @api */ class Draw extends PointerInteraction { diff --git a/src/ol/interaction/Extent.js b/src/ol/interaction/Extent.js index 9dc85b21c4..3c7960da99 100644 --- a/src/ol/interaction/Extent.js +++ b/src/ol/interaction/Extent.js @@ -81,6 +81,7 @@ export class ExtentEvent extends Event { * This interaction is only supported for mouse devices. * * @fires ExtentEvent + * @extends PointerInteraction<'extentchanged'> * @api */ class Extent extends PointerInteraction { diff --git a/src/ol/interaction/Interaction.js b/src/ol/interaction/Interaction.js index 284b90aed6..03cd91fbfa 100644 --- a/src/ol/interaction/Interaction.js +++ b/src/ol/interaction/Interaction.js @@ -27,6 +27,9 @@ import {easeOut, linear} from '../easing.js'; * by a keyboard event not a button element event. * Although interactions do not have a DOM element, some of them do render * vectors and so are visible on the screen. + * + * @template {string} EventTypes + * @extends BaseObject * @api */ class Interaction extends BaseObject { diff --git a/src/ol/interaction/Modify.js b/src/ol/interaction/Modify.js index 82df1c7604..5027a431b9 100644 --- a/src/ol/interaction/Modify.js +++ b/src/ol/interaction/Modify.js @@ -183,6 +183,7 @@ export class ModifyEvent extends Event { * key is pressed. To configure the interaction with a different condition * for deletion, use the `deleteCondition` option. * @fires ModifyEvent + * @extends PointerInteraction<'modifyend'|'modifystart'> * @api */ class Modify extends PointerInteraction { diff --git a/src/ol/interaction/Pointer.js b/src/ol/interaction/Pointer.js index a4919e15c1..4c43375afd 100644 --- a/src/ol/interaction/Pointer.js +++ b/src/ol/interaction/Pointer.js @@ -41,6 +41,9 @@ import {getValues} from '../obj.js'; * started. During a drag sequence the `handleDragEvent` user function is * called on `move` events. The drag sequence ends when the `handleUpEvent` * user function is called and returns `false`. + * + * @template {string} EventTypes + * @extends Interaction * @api */ class PointerInteraction extends Interaction { diff --git a/src/ol/interaction/Select.js b/src/ol/interaction/Select.js index 14fc85e485..42f935bb2f 100644 --- a/src/ol/interaction/Select.js +++ b/src/ol/interaction/Select.js @@ -147,6 +147,7 @@ const originalFeatureStyles = {}; * Selected features are added to an internal unmanaged layer. * * @fires SelectEvent + * @extends Interaction<'select'> * @api */ class Select extends Interaction { diff --git a/src/ol/interaction/Translate.js b/src/ol/interaction/Translate.js index b40de7ff89..6fbd89cf08 100644 --- a/src/ol/interaction/Translate.js +++ b/src/ol/interaction/Translate.js @@ -116,6 +116,7 @@ export class TranslateEvent extends Event { * Interaction for translating (moving) features. * * @fires TranslateEvent + * @extends PointerInteraction<'translateend'|'translatestart'|'translating'> * @api */ class Translate extends PointerInteraction { diff --git a/src/ol/layer/Base.js b/src/ol/layer/Base.js index ef18a520e1..9363040a88 100644 --- a/src/ol/layer/Base.js +++ b/src/ol/layer/Base.js @@ -38,6 +38,8 @@ import {clamp} from '../math.js'; * the options is set as a {@link module:ol/Object} property on the layer object, so * is observable, and has get/set accessors. * + * @template {string} EventTypes + * @extends BaseObject * @api */ class BaseLayer extends BaseObject { diff --git a/src/ol/layer/BaseTile.js b/src/ol/layer/BaseTile.js index 4207a737df..a2773c6421 100644 --- a/src/ol/layer/BaseTile.js +++ b/src/ol/layer/BaseTile.js @@ -45,7 +45,7 @@ import {assign} from '../obj.js'; * options means that `title` is observable, and has get/set accessors. * * @template {import("../source/Tile.js").default} TileSourceType - * @extends {Layer} + * @extends Layer * @api */ class BaseTileLayer extends Layer { diff --git a/src/ol/layer/BaseVector.js b/src/ol/layer/BaseVector.js index 8c8ad65f16..3c0d0a367c 100644 --- a/src/ol/layer/BaseVector.js +++ b/src/ol/layer/BaseVector.js @@ -73,7 +73,8 @@ const Property = { * options means that `title` is observable, and has get/set accessors. * * @template {import("../source/Vector.js").default|import("../source/VectorTile.js").default} VectorSourceType - * @extends {Layer} + * @template {string} EventTypes + * @extends Layer * @api */ class BaseVectorLayer extends Layer { diff --git a/src/ol/layer/Layer.js b/src/ol/layer/Layer.js index 1dc67905d2..a09e95e07c 100644 --- a/src/ol/layer/Layer.js +++ b/src/ol/layer/Layer.js @@ -85,6 +85,8 @@ import {listen, unlistenByKey} from '../events.js'; * @fires import("../render/Event.js").RenderEvent#postrender * * @template {import("../source/Source.js").default} SourceType + * @template {string} EventTypes + * @extends BaseLayer * @api */ class Layer extends BaseLayer { diff --git a/src/ol/layer/VectorTile.js b/src/ol/layer/VectorTile.js index ca11b7f2d6..3a8aab2349 100644 --- a/src/ol/layer/VectorTile.js +++ b/src/ol/layer/VectorTile.js @@ -74,7 +74,7 @@ import {assign} from '../obj.js'; * options means that `title` is observable, and has get/set accessors. * * @param {Options} [opt_options] Options. - * @extends {BaseVectorLayer} + * @extends BaseVectorLayer * @api */ class VectorTileLayer extends BaseVectorLayer { diff --git a/src/ol/source/Image.js b/src/ol/source/Image.js index 6ab9754ec6..1372b3978b 100644 --- a/src/ol/source/Image.js +++ b/src/ol/source/Image.js @@ -76,6 +76,7 @@ export class ImageSourceEvent extends Event { * Base class for sources providing a single image. * @abstract * @fires module:ol/source/Image.ImageSourceEvent + * @extends Source<'imageloadend'|'imageloaderror'|'imageloadstart'> * @api */ class ImageSource extends Source { diff --git a/src/ol/source/Source.js b/src/ol/source/Source.js index e2b50a8f6d..e05c7cc0fc 100644 --- a/src/ol/source/Source.js +++ b/src/ol/source/Source.js @@ -40,6 +40,8 @@ import {get as getProjection} from '../proj.js'; * Base class for {@link module:ol/layer/Layer~Layer} sources. * * A generic `change` event is triggered when the state of the source changes. + * @template {string} EventTypes + * @extends BaseObject * @abstract * @api */ diff --git a/src/ol/source/Tile.js b/src/ol/source/Tile.js index 7e9036fe83..cb8e7de7e3 100644 --- a/src/ol/source/Tile.js +++ b/src/ol/source/Tile.js @@ -36,6 +36,8 @@ import {scale as scaleSize, toSize} from '../size.js'; * Abstract base class; normally only used for creating subclasses and not * instantiated in apps. * Base class for sources providing images divided into a tile grid. + * @template {string} EventTypes + * @extends Source * @abstract * @api */ diff --git a/src/ol/source/UrlTile.js b/src/ol/source/UrlTile.js index d049731fdd..7267a5407b 100644 --- a/src/ol/source/UrlTile.js +++ b/src/ol/source/UrlTile.js @@ -33,6 +33,7 @@ import {getUid} from '../util.js'; * Base class for sources providing tiles divided into a tile grid over http. * * @fires import("./Tile.js").TileSourceEvent + * @extends TileSource<'tileloadend'|'tileloaderror'|'tileloadstart'> */ class UrlTile extends TileSource { /**