1
// Copyright 2014 The Closure Library Authors. All Rights Reserved.
2
//
3
// Licensed under the Apache License, Version 2.0 (the "License");
4
// you may not use this file except in compliance with the License.
5
// You may obtain a copy of the License at
6
//
7
//      http://www.apache.org/licenses/LICENSE-2.0
8
//
9
// Unless required by applicable law or agreed to in writing, software
10
// distributed under the License is distributed on an "AS-IS" BASIS,
11
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
// See the License for the specific language governing permissions and
13
// limitations under the License.
14

15
/**
16
 * @fileoverview This event wrapper will dispatch an event when the user uses
17
 * the wheel on an element. The event provides details of the unit type (pixel /
18
 * line / page) and deltas in those units in up to 3 dimensions. Additionally,
19
 * simplified pixel deltas are provided for code that doesn't need to handle the
20
 * different units differently. This is not to be confused with the scroll
21
 * event, where an element in the dom can report that it was scrolled.
22
 *
23
 * This class aims to smooth out inconsistencies between browser platforms with
24
 * regards to wheel events, but we do not cover every possible software/hardware
25
 * combination out there, some of which occasionally produce very large deltas
26
 * in wheel events, especially when the device supports acceleration.
27
 *
28
 * Relevant standard:
29
 * http://www.w3.org/TR/2014/WD-DOM-Level-3-Events-20140925/#interface-WheelEvent
30
 *
31
 * Clients of this code should be aware that some input devices only fire a few
32
 * discrete events (such as a mouse wheel without acceleration) whereas some can
33
 * generate a large number of events for a single interaction (such as a
34
 * touchpad with acceleration). There is no signal in the events to reliably
35
 * distinguish between these.
36
 *
37
 * @author [email protected] (Erik Arvidsson)
38
 * @see ../demos/wheelhandler.html
39
 */
40

41
goog.provide('goog.events.WheelHandler');
42

43
goog.require('goog.dom');
44
goog.require('goog.events');
45
goog.require('goog.events.EventTarget');
46
goog.require('goog.events.WheelEvent');
47
goog.require('goog.style');
48
goog.require('goog.userAgent');
49
goog.require('goog.userAgent.product');
50
goog.require('goog.userAgent.product.isVersion');
51

52

53

54
/**
55
 * This event handler allows you to catch wheel events in a consistent manner.
56
 * @param {!Element|!Document} element The element to listen to the wheel event
57
 *     on.
58
 * @param {boolean=} opt_capture Whether to handle the wheel event in capture
59
 *     phase.
60
 * @constructor
61
 * @extends {goog.events.EventTarget}
62
 */
63
goog.events.WheelHandler = function(element, opt_capture) {
64
  goog.events.WheelHandler.base(this, 'constructor');
65

66
  /**
67
   * This is the element that we will listen to the real wheel events on.
68
   * @private {!Element|!Document}
69
   */
70
  this.element_ = element;
71

72
  var rtlElement = goog.dom.isElement(this.element_) ?
73
      /** @type {!Element} */ (this.element_) :
74
                              /** @type {!Document} */ (this.element_).body;
75

76
  /**
77
   * True if the element exists and is RTL, false otherwise.
78
   * @private {boolean}
79
   */
80
  this.isRtl_ = !!rtlElement && goog.style.isRightToLeft(rtlElement);
81

82
  /**
83
   * The key returned from the goog.events.listen.
84
   * @private {goog.events.Key}
85
   */
86
  this.listenKey_ = goog.events.listen(
87
      this.element_, goog.events.WheelHandler.getDomEventType(), this,
88
      opt_capture);
89
};
90
goog.inherits(goog.events.WheelHandler, goog.events.EventTarget);
91

92

93
/**
94
 * Returns the dom event type.
95
 * @return {string} The dom event type.
96
 */
97
goog.events.WheelHandler.getDomEventType = function() {
98
  // Prefer to use wheel events whenever supported.
99
  if (goog.userAgent.GECKO && goog.userAgent.isVersionOrHigher(17) ||
100
      goog.userAgent.IE && goog.userAgent.isVersionOrHigher(9) ||
101
      goog.userAgent.product.CHROME && goog.userAgent.product.isVersion(31)) {
102
    return 'wheel';
103
  }
104

105
  // Legacy events. Still the best we have on Opera and Safari.
106
  return goog.userAgent.GECKO ? 'DOMMouseScroll' : 'mousewheel';
107
};
108

109

110
/**
111
 * Handles the events on the element.
112
 * @param {!goog.events.BrowserEvent} e The underlying browser event.
113
 */
114
goog.events.WheelHandler.prototype.handleEvent = function(e) {
115
  var deltaMode = goog.events.WheelEvent.DeltaMode.PIXEL;
116
  var deltaX = 0;
117
  var deltaY = 0;
118
  var deltaZ = 0;
119
  var be = e.getBrowserEvent();
120
  if (be.type == 'wheel') {
121
    deltaMode = be.deltaMode;
122
    deltaX = be.deltaX;
123
    deltaY = be.deltaY;
124
    deltaZ = be.deltaZ;
125
  } else if (be.type == 'mousewheel') {
126
    // Assume that these are still comparable to pixels. This may not be true
127
    // for all old browsers.
128
    if (goog.isDef(be.wheelDeltaX)) {
129
      deltaX = -be.wheelDeltaX;
130
      deltaY = -be.wheelDeltaY;
131
    } else {
132
      deltaY = -be.wheelDelta;
133
    }
134
  } else {  // Historical Gecko
135
    // Gecko returns multiple of 3 (representing the number of lines)
136
    deltaMode = goog.events.WheelEvent.DeltaMode.LINE;
137
    // Firefox 3.1 adds an axis field to the event to indicate axis.
138
    if (goog.isDef(be.axis) && be.axis === be.HORIZONTAL_AXIS) {
139
      deltaX = be.detail;
140
    } else {
141
      deltaY = be.detail;
142
    }
143
  }
144
  // For horizontal deltas we need to flip the value for RTL grids.
145
  if (this.isRtl_) {
146
    deltaX = -deltaX;
147
  }
148
  var newEvent =
149
      new goog.events.WheelEvent(be, deltaMode, deltaX, deltaY, deltaZ);
150
  this.dispatchEvent(newEvent);
151
};
152

153

154
/** @override */
155
goog.events.WheelHandler.prototype.disposeInternal = function() {
156
  goog.events.WheelHandler.superClass_.disposeInternal.call(this);
157
  goog.events.unlistenByKey(this.listenKey_);
158
  this.listenKey_ = null;
159
};
160

161