New MapHandler base class; better API docs

src/ol/Map.js

@@ -525,7 +525,7 @@ ol.Map.prototype.initHandlers = function() {
     goog.asserts.assert(!goog.isNull(this.viewport_));
 
     var handler,
-        states = {};
+        states = /** @type {ol.handler.states} */ ({});
 
     if (ol.ENABLE_DRAG_HANDLER) {
         handler = new ol.handler.Drag(this, this.viewport_, states);

src/ol/handler/Click.js

@@ -2,52 +2,36 @@
  * @fileoverview Click Handler.
  *
  * Provides a class for listening to click events on a DOM element
- * and re-dispatching to a map instance.
+ * and dispatching click events to a map instance.
  *
  * This handler has no default behaviour.
  */
 
 goog.provide('ol.handler.Click');
 
-goog.require('ol.handler.states');
+goog.require('ol.handler.MapHandler');
 goog.require('ol.events.MapEvent');
 goog.require('ol.events.MapEventType');
 
-goog.require('goog.asserts');
 goog.require('goog.events');
 goog.require('goog.events.EventType');
-goog.require('goog.Disposable');
 
 
 /**
  * @constructor
- * @extends {goog.Disposable}
+ * @extends {ol.handler.MapHandler}
  * @param {ol.Map} map The map instance.
  * @param {Element} element The element we listen for click on.
- * @param {Object} states An object for the handlers to share states.
+ * @param {ol.handler.states} states An object for the handlers to share
+ *     states.
  */
 ol.handler.Click = function(map, element, states) {
-    goog.base(this);
+    goog.base(this, map, element, states);
-
-    /**
-     * @type {ol.Map}
-     */
-    this.map_ = map;
-
-    /**
-     * @type {Element}
-     */
-    this.element_ = element;
-
-    /**
-     * @type {Object}
-     */
-    this.states_ = states;
 
     goog.events.listen(this.element_, goog.events.EventType.CLICK,
                        this.handleClick, undefined, this);
 };
-goog.inherits(ol.handler.Click, goog.Disposable);
+goog.inherits(ol.handler.Click, ol.handler.MapHandler);
 
 /**
  * @inheritDoc

src/ol/handler/Drag.js

@@ -1,49 +1,33 @@
 /**
  * @fileoverview Drag Handler.
  *
- * Provides a class for listening to drag events on a DOM element and
+ * Provides a class for listening to drag sequences on a DOM element and
- * re-dispatching to a map object.
+ * dispatching dragstart, drag and dragend events to a map object.
  *
- * The default behavior is moving the map.
+ * The default behavior for the drag event is moving the map.
  */
 
 goog.provide('ol.handler.Drag');
 
-goog.require('ol.handler.states');
+goog.require('ol.handler.MapHandler');
 goog.require('ol.events.MapEvent');
 goog.require('ol.events.MapEventType');
 
-goog.require('goog.asserts');
 goog.require('goog.events');
 goog.require('goog.events.Event');
 goog.require('goog.events.EventType');
-goog.require('goog.Disposable');
 goog.require('goog.fx.Dragger');
 
 /**
  * @constructor
- * @extends {goog.Disposable}
+ * @extends {ol.handler.MapHandler}
  * @param {ol.Map} map The map instance.
- * @param {Element} element The element that will be dragged.
+ * @param {Element} element The element we listen for click on.
- * @param {Object} states An object for the handlers to share states.
+ * @param {ol.handler.states} states An object for the handlers to share
+ *     states.
  */
 ol.handler.Drag = function(map, element, states) {
-    goog.base(this);
+    goog.base(this, map, element, states);
-
-    /**
-     * @type {ol.Map}
-     */
-    this.map_ = map;
-
-    /**
-     * @type {Element}
-     */
-    this.element_ = element;
-
-    /**
-     * @type {Object}
-     */
-    this.states_ = states;
 
     /**
      * @type {goog.fx.Dragger}
@@ -73,7 +57,7 @@ ol.handler.Drag = function(map, element, states) {
                        this.handleDragEarlyCancel, false, this);
 
 };
-goog.inherits(ol.handler.Drag, goog.Disposable);
+goog.inherits(ol.handler.Drag, ol.handler.MapHandler);
 
 /**
  * @inheritDoc
@@ -118,14 +102,14 @@ ol.handler.Drag.prototype.handleDrag = function(e) {
     this.prevY_ = e.clientY;
     var rt = goog.events.dispatchEvent(this.map_, newE);
     if (rt) {
-        this.defaultBehavior(newE);
+        this.defaultDrag(newE);
     }
 };
 
 /**
  * @param {ol.events.MapEvent} e
  */
-ol.handler.Drag.prototype.defaultBehavior = function(e) {
+ol.handler.Drag.prototype.defaultDrag = function(e) {
     var delementaX = /** @type {number} */ e.delementaX;
     var delementaY = /** @type {number} */ e.delementaY;
     this.map_.moveByViewportPx(delementaX, delementaY);

src/ol/handler/MapHandler.js

@@ -0,0 +1,54 @@
+/**
+ * @fileoverview Map Handler.
+ *
+ * Type definitions and base class for map event handlers that share states,
+ * listen for events on a map related dom element (usually the map's viewport),
+ * dispatch events to an ol.Map instance, and optionally perform default
+ * actions on an ol.Map instance.
+ */
+
+goog.provide('ol.handler.states');
+goog.provide('ol.handler.MapHandler');
+
+goog.require('goog.Disposable');
+
+/**
+ * Type definition for shared states between handlers. The following states
+ * are defined:
+ *
+ * * dragged (boolean) - Set by the Drag handler when we are dragging. Read by
+ *   the click handler to determine if a click is a real click or the result
+ *   of a mouseup/touchend at the end of a drag sequence.
+ *
+ * @typedef {{dragged: boolean}}
+ */
+ol.handler.states;
+
+/**
+ * @constructor
+ * @extends {goog.Disposable}
+ * @param {ol.Map} map The map instance.
+ * @param {Element} element The element we listen for browser events on.
+ * @param {ol.handler.states} states An object for the handlers to share
+ *     states.
+ */
+ol.handler.MapHandler = function(map, element, states) {
+    goog.base(this);
+
+    /**
+     * @type {ol.Map}
+     */
+    this.map_ = map;
+
+    /**
+     * @type {Element}
+     */
+    this.element_ = element;
+
+    /**
+     * @type {ol.handler.states}
+     */
+    this.states_ = states;
+
+};
+goog.inherits(ol.handler.MapHandler, goog.Disposable);

src/ol/handler/MouseWheel.js

@@ -2,44 +2,33 @@
  * @fileoverview Mouse Wheel Handler.
  *
  * Provides a class for listening to mousewheel events on a DOM element
- * and re-dispatching to a map instance.
+ * and dispatching mousewheel events to a map instance.
  *
- * The default behabior is zooming the map.
+ * The default behavior for the mousewheel event is zooming the map.
  */
 
 goog.provide('ol.handler.MouseWheel');
 
-goog.require('ol.handler.states');
+goog.require('ol.handler.MapHandler');
 goog.require('ol.events.MapEvent');
 goog.require('ol.events.MapEventType');
 
-goog.require('goog.asserts');
 goog.require('goog.events');
 goog.require('goog.style');
-goog.require('goog.Disposable');
 goog.require('goog.events.MouseWheelHandler');
 goog.require('goog.events.MouseWheelHandler.EventType');
 
 
 /**
  * @constructor
- * @extends {goog.Disposable}
+ * @extends {ol.handler.MapHandler}
  * @param {ol.Map} map The map instance.
- * @param {Element} element The element we listen to mousewheel on.
+ * @param {Element} element The element we listen for click on.
- * @param {Object} states An object for the handlers to share states.
+ * @param {ol.handler.states} states An object for the handlers to share
+ *     states.
  */
 ol.handler.MouseWheel = function(map, element, states) {
-    goog.base(this);
+    goog.base(this, map, element, states);
-
-    /**
-     * @type {ol.Map}
-     */
-    this.map_ = map;
-
-    /**
-     * @type {Element}
-     */
-    this.element_ = element;
 
     var handler = new goog.events.MouseWheelHandler(element);
     this.registerDisposable(handler);
@@ -49,7 +38,7 @@ ol.handler.MouseWheel = function(map, element, states) {
                        this.handleMouseWheel, false, this);
 
 };
-goog.inherits(ol.handler.MouseWheel, goog.Disposable);
+goog.inherits(ol.handler.MouseWheel, ol.handler.MapHandler);
 
 /**
  * @param {goog.events.MouseWheelEvent} e
@@ -58,14 +47,14 @@ ol.handler.MouseWheel.prototype.handleMouseWheel = function(e) {
     var newE = new ol.events.MapEvent(ol.events.MapEventType.MOUSEWHEEL, e);
     var rt = goog.events.dispatchEvent(this.map_, newE);
     if (rt) {
-        this.defaultBehavior(e);
+        this.defaultMouseWheel(e);
     }
 };
 
 /**
  * @param {goog.events.MouseWheelEvent} e
  */
-ol.handler.MouseWheel.prototype.defaultBehavior = function(e) {
+ol.handler.MouseWheel.prototype.defaultMouseWheel = function(e) {
     var me = this;
     if (e.deltaY === 0 || me.zoomBlocked_) {
         return;

src/ol/handler/handler.js

@@ -1,13 +0,0 @@
-goog.provide('ol.handler.states');
-
-/**
- * Type definition for shared states between handlers. The following states
- * are defined:
- *
- * * dragged {boolean} - Set by the Drag handler when we are dragging. Read by
- *   the click handler to determine if a click is a real click or the result
- *   of a mouseup/touchend at the end of a drag sequence.
- *
- * @typedef {{dragged: boolean}}
- */
-ol.handler.states;