From 7c5e1b808d44c18465f328d159946a7d06f9062a Mon Sep 17 00:00:00 2001 From: Andreas Hocevar Date: Thu, 10 Mar 2016 17:35:55 +0100 Subject: [PATCH] Add and fix API docs for ol.events.Event stack --- externs/oli.js | 37 +++++++++++++++++++++++++++---------- src/ol/events.js | 34 ++++++++++++++-------------------- src/ol/events/event.js | 19 ++++++++++++++++--- 3 files changed, 57 insertions(+), 33 deletions(-) diff --git a/externs/oli.js b/externs/oli.js index 25a729ba34..1c9b4834be 100644 --- a/externs/oli.js +++ b/externs/oli.js @@ -9,6 +9,33 @@ var oli; +/** + * @interface + */ +oli.events.Event = function() {}; + + +/** + * @type {Object} + */ +oli.events.Event.prototype.target; + + +/** + * @type {string} + */ +oli.events.Event.prototype.type; + + +/** + */ +oli.events.Event.prototype.preventDefault = function() {}; + + +/** + */ +oli.events.Event.prototype.stopPropagation = function() {}; + /** * @interface @@ -22,7 +49,6 @@ oli.CollectionEvent = function() {}; oli.CollectionEvent.prototype.element; - /** * @interface */ @@ -41,7 +67,6 @@ oli.DragBoxEvent.prototype.coordinate; oli.DragBoxEvent.prototype.mapBrowserEvent; - /** * @interface */ @@ -54,7 +79,6 @@ oli.DrawEvent = function() {}; oli.DrawEvent.prototype.feature; - /** * @interface */ @@ -73,7 +97,6 @@ oli.ModifyEvent.prototype.features; oli.ModifyEvent.prototype.mapBrowserPointerEvent; - /** * @interface */ @@ -92,7 +115,6 @@ oli.ObjectEvent.prototype.key; oli.ObjectEvent.prototype.oldValue; - /** * @interface */ @@ -123,7 +145,6 @@ oli.MapBrowserEvent.prototype.pixel; oli.MapBrowserEvent.prototype.dragging; - /** * @interface */ @@ -166,7 +187,6 @@ oli.SelectEvent.prototype.selected; oli.SelectEvent.prototype.mapBrowserEvent; - /** * @type {Object} */ @@ -186,7 +206,6 @@ oli.control.Control = function() {}; oli.control.Control.prototype.setMap = function(map) {}; - /** * @type {Object} */ @@ -217,7 +236,6 @@ oli.interaction.DragAndDropEvent.prototype.projection; oli.interaction.DragAndDropEvent.prototype.file; - /** * @interface */ @@ -242,7 +260,6 @@ oli.interaction.TranslateEvent.prototype.coordinate; oli.render; - /** * @interface */ diff --git a/src/ol/events.js b/src/ol/events.js index 2035441864..6bd280a1ea 100644 --- a/src/ol/events.js +++ b/src/ol/events.js @@ -73,7 +73,13 @@ ol.events.EventTargetLike; /** * Key to use with {@link ol.Observable#unByKey}. * - * @typedef {ol.events.ListenerObjType} + * @typedef {{bindTo: (Object|undefined), + * boundListener: (ol.events.ListenerFunctionType|undefined), + * callOnce: boolean, + * deleteIndex: (number|undefined), + * listener: ol.events.ListenerFunctionType, + * target: (EventTarget|ol.events.EventTarget), + * type: string}} * @api */ ol.events.Key; @@ -90,19 +96,7 @@ ol.events.ListenerFunctionType; /** - * @typedef {{bindTo: (Object|undefined), - * boundListener: (ol.events.ListenerFunctionType|undefined), - * callOnce: boolean, - * deleteIndex: (number|undefined), - * listener: ol.events.ListenerFunctionType, - * target: (EventTarget|ol.events.EventTarget), - * type: string}} - */ -ol.events.ListenerObjType; - - -/** - * @param {ol.events.ListenerObjType} listenerObj Listener object. + * @param {ol.events.Key} listenerObj Listener object. * @return {ol.events.ListenerFunctionType} Bound listener. */ ol.events.bindListener_ = function(listenerObj) { @@ -120,15 +114,15 @@ ol.events.bindListener_ = function(listenerObj) { /** - * Finds the matching {@link ol.events.ListenerObjType} in the given listener + * Finds the matching {@link ol.events.Key} in the given listener * array. * - * @param {!Array} listeners Array of listeners. + * @param {!Array} listeners Array of listeners. * @param {!Function} listener The listener function. * @param {Object=} opt_this The `this` value inside the listener. * @param {boolean=} opt_setDeleteIndex Set the deleteIndex on the matching * listener, for {@link ol.events.unlistenByKey}. - * @return {ol.events.ListenerObjType|undefined} The matching listener object. + * @return {ol.events.Key|undefined} The matching listener object. * @private */ ol.events.findListener_ = function(listeners, listener, opt_this, @@ -151,7 +145,7 @@ ol.events.findListener_ = function(listeners, listener, opt_this, /** * @param {ol.events.EventTargetLike} target Target. * @param {string} type Type. - * @return {Array.|undefined} Listeners. + * @return {Array.|undefined} Listeners. */ ol.events.getListeners = function(target, type) { var listenerMap = target[ol.events.LISTENER_MAP_PROP_]; @@ -163,7 +157,7 @@ ol.events.getListeners = function(target, type) { * Get the lookup of listeners. If one does not exist on the target, it is * created. * @param {ol.events.EventTargetLike} target Target. - * @return {!Object.>} Map of + * @return {!Object.>} Map of * listeners by event type. * @private */ @@ -232,7 +226,7 @@ ol.events.listen = function(target, type, listener, opt_this, opt_once) { listenerObj.callOnce = false; } } else { - listenerObj = /** @type {ol.events.ListenerObjType} */ ({ + listenerObj = /** @type {ol.events.Key} */ ({ bindTo: opt_this, callOnce: !!opt_once, listener: listener, diff --git a/src/ol/events/event.js b/src/ol/events/event.js index 84cf18c82c..31b60c7136 100644 --- a/src/ol/events/event.js +++ b/src/ol/events/event.js @@ -12,6 +12,7 @@ goog.provide('ol.events.Event'); * {@link ol.events.EventTarget}. * * @constructor + * @implements {oli.events.Event} * @param {string} type Type. * @param {Object=} opt_target Target. */ @@ -23,22 +24,34 @@ ol.events.Event = function(type, opt_target) { this.propagationStopped; /** + * The event type. * @type {string} + * @api stable */ this.type = type; /** - * @type {Object|undefined} + * The event target. + * @type {Object} + * @api stable */ - this.target = opt_target; + this.target = opt_target || null; }; /** - * Stop event propagation + * Stop event propagation. + * @function + * @api stable */ ol.events.Event.prototype.preventDefault = + +/** + * Stop event propagation. + * @function + * @api stable + */ ol.events.Event.prototype.stopPropagation = function() { this.propagationStopped = true; };