lib/goog/events/browserevent.js

1// Copyright 2005 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 A patched, standardized event object for browser events.
17 *
18 * <pre>
19 * The patched event object contains the following members:
20 * - type {string} Event type, e.g. 'click'
21 * - target {Object} The element that actually triggered the event
22 * - currentTarget {Object} The element the listener is attached to
23 * - relatedTarget {Object} For mouseover and mouseout, the previous object
24 * - offsetX {number} X-coordinate relative to target
25 * - offsetY {number} Y-coordinate relative to target
26 * - clientX {number} X-coordinate relative to viewport
27 * - clientY {number} Y-coordinate relative to viewport
28 * - screenX {number} X-coordinate relative to the edge of the screen
29 * - screenY {number} Y-coordinate relative to the edge of the screen
30 * - button {number} Mouse button. Use isButton() to test.
31 * - keyCode {number} Key-code
32 * - ctrlKey {boolean} Was ctrl key depressed
33 * - altKey {boolean} Was alt key depressed
34 * - shiftKey {boolean} Was shift key depressed
35 * - metaKey {boolean} Was meta key depressed
36 * - defaultPrevented {boolean} Whether the default action has been prevented
37 * - state {Object} History state object
38 *
39 * NOTE: The keyCode member contains the raw browser keyCode. For normalized
40 * key and character code use {@link goog.events.KeyHandler}.
41 * </pre>
42 *
43 * @author arv@google.com (Erik Arvidsson)
44 */
45
46goog.provide('goog.events.BrowserEvent');
47goog.provide('goog.events.BrowserEvent.MouseButton');
48
49goog.require('goog.events.BrowserFeature');
50goog.require('goog.events.Event');
51goog.require('goog.events.EventType');
52goog.require('goog.reflect');
53goog.require('goog.userAgent');
54
55
56
57/**
58 * Accepts a browser event object and creates a patched, cross browser event
59 * object.
60 * The content of this object will not be initialized if no event object is
61 * provided. If this is the case, init() needs to be invoked separately.
62 * @param {Event=} opt_e Browser event object.
63 * @param {EventTarget=} opt_currentTarget Current target for event.
64 * @constructor
65 * @extends {goog.events.Event}
66 */
67goog.events.BrowserEvent = function(opt_e, opt_currentTarget) {
68 goog.events.BrowserEvent.base(this, 'constructor', opt_e ? opt_e.type : '');
69
70 /**
71 * Target that fired the event.
72 * @override
73 * @type {Node}
74 */
75 this.target = null;
76
77 /**
78 * Node that had the listener attached.
79 * @override
80 * @type {Node|undefined}
81 */
82 this.currentTarget = null;
83
84 /**
85 * For mouseover and mouseout events, the related object for the event.
86 * @type {Node}
87 */
88 this.relatedTarget = null;
89
90 /**
91 * X-coordinate relative to target.
92 * @type {number}
93 */
94 this.offsetX = 0;
95
96 /**
97 * Y-coordinate relative to target.
98 * @type {number}
99 */
100 this.offsetY = 0;
101
102 /**
103 * X-coordinate relative to the window.
104 * @type {number}
105 */
106 this.clientX = 0;
107
108 /**
109 * Y-coordinate relative to the window.
110 * @type {number}
111 */
112 this.clientY = 0;
113
114 /**
115 * X-coordinate relative to the monitor.
116 * @type {number}
117 */
118 this.screenX = 0;
119
120 /**
121 * Y-coordinate relative to the monitor.
122 * @type {number}
123 */
124 this.screenY = 0;
125
126 /**
127 * Which mouse button was pressed.
128 * @type {number}
129 */
130 this.button = 0;
131
132 /**
133 * Keycode of key press.
134 * @type {number}
135 */
136 this.keyCode = 0;
137
138 /**
139 * Keycode of key press.
140 * @type {number}
141 */
142 this.charCode = 0;
143
144 /**
145 * Whether control was pressed at time of event.
146 * @type {boolean}
147 */
148 this.ctrlKey = false;
149
150 /**
151 * Whether alt was pressed at time of event.
152 * @type {boolean}
153 */
154 this.altKey = false;
155
156 /**
157 * Whether shift was pressed at time of event.
158 * @type {boolean}
159 */
160 this.shiftKey = false;
161
162 /**
163 * Whether the meta key was pressed at time of event.
164 * @type {boolean}
165 */
166 this.metaKey = false;
167
168 /**
169 * History state object, only set for PopState events where it's a copy of the
170 * state object provided to pushState or replaceState.
171 * @type {Object}
172 */
173 this.state = null;
174
175 /**
176 * Whether the default platform modifier key was pressed at time of event.
177 * (This is control for all platforms except Mac, where it's Meta.)
178 * @type {boolean}
179 */
180 this.platformModifierKey = false;
181
182 /**
183 * The browser event object.
184 * @private {Event}
185 */
186 this.event_ = null;
187
188 if (opt_e) {
189 this.init(opt_e, opt_currentTarget);
190 }
191};
192goog.inherits(goog.events.BrowserEvent, goog.events.Event);
193
194
195/**
196 * Normalized button constants for the mouse.
197 * @enum {number}
198 */
199goog.events.BrowserEvent.MouseButton = {
200 LEFT: 0,
201 MIDDLE: 1,
202 RIGHT: 2
203};
204
205
206/**
207 * Static data for mapping mouse buttons.
208 * @type {!Array<number>}
209 */
210goog.events.BrowserEvent.IEButtonMap = [
211 1, // LEFT
212 4, // MIDDLE
213 2 // RIGHT
214];
215
216
217/**
218 * Accepts a browser event object and creates a patched, cross browser event
219 * object.
220 * @param {Event} e Browser event object.
221 * @param {EventTarget=} opt_currentTarget Current target for event.
222 */
223goog.events.BrowserEvent.prototype.init = function(e, opt_currentTarget) {
224 var type = this.type = e.type;
225
226 /**
227 * On touch devices use the first "changed touch" as the relevant touch.
228 * @type {Touch}
229 */
230 var relevantTouch = e.changedTouches ? e.changedTouches[0] : null;
231
232 // TODO(nicksantos): Change this.target to type EventTarget.
233 this.target = /** @type {Node} */ (e.target) || e.srcElement;
234
235 // TODO(nicksantos): Change this.currentTarget to type EventTarget.
236 this.currentTarget = /** @type {Node} */ (opt_currentTarget);
237
238 var relatedTarget = /** @type {Node} */ (e.relatedTarget);
239 if (relatedTarget) {
240 // There's a bug in FireFox where sometimes, relatedTarget will be a
241 // chrome element, and accessing any property of it will get a permission
242 // denied exception. See:
243 // https://bugzilla.mozilla.org/show_bug.cgi?id=497780
244 if (goog.userAgent.GECKO) {
245 if (!goog.reflect.canAccessProperty(relatedTarget, 'nodeName')) {
246 relatedTarget = null;
247 }
248 }
249 // TODO(arv): Use goog.events.EventType when it has been refactored into its
250 // own file.
251 } else if (type == goog.events.EventType.MOUSEOVER) {
252 relatedTarget = e.fromElement;
253 } else if (type == goog.events.EventType.MOUSEOUT) {
254 relatedTarget = e.toElement;
255 }
256
257 this.relatedTarget = relatedTarget;
258
259 if (!goog.isNull(relevantTouch)) {
260 this.clientX = relevantTouch.clientX !== undefined ?
261 relevantTouch.clientX : relevantTouch.pageX;
262 this.clientY = relevantTouch.clientY !== undefined ?
263 relevantTouch.clientY : relevantTouch.pageY;
264 this.screenX = relevantTouch.screenX || 0;
265 this.screenY = relevantTouch.screenY || 0;
266 } else {
267 // Webkit emits a lame warning whenever layerX/layerY is accessed.
268 // http://code.google.com/p/chromium/issues/detail?id=101733
269 this.offsetX = (goog.userAgent.WEBKIT || e.offsetX !== undefined) ?
270 e.offsetX : e.layerX;
271 this.offsetY = (goog.userAgent.WEBKIT || e.offsetY !== undefined) ?
272 e.offsetY : e.layerY;
273 this.clientX = e.clientX !== undefined ? e.clientX : e.pageX;
274 this.clientY = e.clientY !== undefined ? e.clientY : e.pageY;
275 this.screenX = e.screenX || 0;
276 this.screenY = e.screenY || 0;
277 }
278
279 this.button = e.button;
280
281 this.keyCode = e.keyCode || 0;
282 this.charCode = e.charCode || (type == 'keypress' ? e.keyCode : 0);
283 this.ctrlKey = e.ctrlKey;
284 this.altKey = e.altKey;
285 this.shiftKey = e.shiftKey;
286 this.metaKey = e.metaKey;
287 this.platformModifierKey = goog.userAgent.MAC ? e.metaKey : e.ctrlKey;
288 this.state = e.state;
289 this.event_ = e;
290 if (e.defaultPrevented) {
291 this.preventDefault();
292 }
293};
294
295
296/**
297 * Tests to see which button was pressed during the event. This is really only
298 * useful in IE and Gecko browsers. And in IE, it's only useful for
299 * mousedown/mouseup events, because click only fires for the left mouse button.
300 *
301 * Safari 2 only reports the left button being clicked, and uses the value '1'
302 * instead of 0. Opera only reports a mousedown event for the middle button, and
303 * no mouse events for the right button. Opera has default behavior for left and
304 * middle click that can only be overridden via a configuration setting.
305 *
306 * There's a nice table of this mess at http://www.unixpapa.com/js/mouse.html.
307 *
308 * @param {goog.events.BrowserEvent.MouseButton} button The button
309 * to test for.
310 * @return {boolean} True if button was pressed.
311 */
312goog.events.BrowserEvent.prototype.isButton = function(button) {
313 if (!goog.events.BrowserFeature.HAS_W3C_BUTTON) {
314 if (this.type == 'click') {
315 return button == goog.events.BrowserEvent.MouseButton.LEFT;
316 } else {
317 return !!(this.event_.button &
318 goog.events.BrowserEvent.IEButtonMap[button]);
319 }
320 } else {
321 return this.event_.button == button;
322 }
323};
324
325
326/**
327 * Whether this has an "action"-producing mouse button.
328 *
329 * By definition, this includes left-click on windows/linux, and left-click
330 * without the ctrl key on Macs.
331 *
332 * @return {boolean} The result.
333 */
334goog.events.BrowserEvent.prototype.isMouseActionButton = function() {
335 // Webkit does not ctrl+click to be a right-click, so we
336 // normalize it to behave like Gecko and Opera.
337 return this.isButton(goog.events.BrowserEvent.MouseButton.LEFT) &&
338 !(goog.userAgent.WEBKIT && goog.userAgent.MAC && this.ctrlKey);
339};
340
341
342/**
343 * @override
344 */
345goog.events.BrowserEvent.prototype.stopPropagation = function() {
346 goog.events.BrowserEvent.superClass_.stopPropagation.call(this);
347 if (this.event_.stopPropagation) {
348 this.event_.stopPropagation();
349 } else {
350 this.event_.cancelBubble = true;
351 }
352};
353
354
355/**
356 * @override
357 */
358goog.events.BrowserEvent.prototype.preventDefault = function() {
359 goog.events.BrowserEvent.superClass_.preventDefault.call(this);
360 var be = this.event_;
361 if (!be.preventDefault) {
362 be.returnValue = false;
363 if (goog.events.BrowserFeature.SET_KEY_CODE_TO_PREVENT_DEFAULT) {
364 /** @preserveTry */
365 try {
366 // Most keys can be prevented using returnValue. Some special keys
367 // require setting the keyCode to -1 as well:
368 //
369 // In IE7:
370 // F3, F5, F10, F11, Ctrl+P, Crtl+O, Ctrl+F (these are taken from IE6)
371 //
372 // In IE8:
373 // Ctrl+P, Crtl+O, Ctrl+F (F1-F12 cannot be stopped through the event)
374 //
375 // We therefore do this for all function keys as well as when Ctrl key
376 // is pressed.
377 var VK_F1 = 112;
378 var VK_F12 = 123;
379 if (be.ctrlKey || be.keyCode >= VK_F1 && be.keyCode <= VK_F12) {
380 be.keyCode = -1;
381 }
382 } catch (ex) {
383 // IE throws an 'access denied' exception when trying to change
384 // keyCode in some situations (e.g. srcElement is input[type=file],
385 // or srcElement is an anchor tag rewritten by parent's innerHTML).
386 // Do nothing in this case.
387 }
388 }
389 } else {
390 be.preventDefault();
391 }
392};
393
394
395/**
396 * @return {Event} The underlying browser event object.
397 */
398goog.events.BrowserEvent.prototype.getBrowserEvent = function() {
399 return this.event_;
400};