1
// Copyright 2007 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 file contains a class for working with keyboard events
17
 * that repeat consistently across browsers and platforms. It also unifies the
18
 * key code so that it is the same in all browsers and platforms.
19
 *
20
 * Different web browsers have very different keyboard event handling. Most
21
 * importantly is that only certain browsers repeat keydown events:
22
 * IE, Opera, FF/Win32, and Safari 3 repeat keydown events.
23
 * FF/Mac and Safari 2 do not.
24
 *
25
 * For the purposes of this code, "Safari 3" means WebKit 525+, when WebKit
26
 * decided that they should try to match IE's key handling behavior.
27
 * Safari 3.0.4, which shipped with Leopard (WebKit 523), has the
28
 * Safari 2 behavior.
29
 *
30
 * Firefox, Safari, Opera prevent on keypress
31
 *
32
 * IE prevents on keydown
33
 *
34
 * Firefox does not fire keypress for shift, ctrl, alt
35
 * Firefox does fire keydown for shift, ctrl, alt, meta
36
 * Firefox does not repeat keydown for shift, ctrl, alt, meta
37
 *
38
 * Firefox does not fire keypress for up and down in an input
39
 *
40
 * Opera fires keypress for shift, ctrl, alt, meta
41
 * Opera does not repeat keypress for shift, ctrl, alt, meta
42
 *
43
 * Safari 2 and 3 do not fire keypress for shift, ctrl, alt
44
 * Safari 2 does not fire keydown for shift, ctrl, alt
45
 * Safari 3 *does* fire keydown for shift, ctrl, alt
46
 *
47
 * IE provides the keycode for keyup/down events and the charcode (in the
48
 * keycode field) for keypress.
49
 *
50
 * Mozilla provides the keycode for keyup/down and the charcode for keypress
51
 * unless it's a non text modifying key in which case the keycode is provided.
52
 *
53
 * Safari 3 provides the keycode and charcode for all events.
54
 *
55
 * Opera provides the keycode for keyup/down event and either the charcode or
56
 * the keycode (in the keycode field) for keypress events.
57
 *
58
 * Firefox x11 doesn't fire keydown events if a another key is already held down
59
 * until the first key is released. This can cause a key event to be fired with
60
 * a keyCode for the first key and a charCode for the second key.
61
 *
62
 * Safari in keypress
63
 *
64
 *        charCode keyCode which
65
 * ENTER:       13      13    13
66
 * F1:       63236   63236 63236
67
 * F8:       63243   63243 63243
68
 * ...
69
 * p:          112     112   112
70
 * P:           80      80    80
71
 *
72
 * Firefox, keypress:
73
 *
74
 *        charCode keyCode which
75
 * ENTER:        0      13    13
76
 * F1:           0     112     0
77
 * F8:           0     119     0
78
 * ...
79
 * p:          112       0   112
80
 * P:           80       0    80
81
 *
82
 * Opera, Mac+Win32, keypress:
83
 *
84
 *         charCode keyCode which
85
 * ENTER: undefined      13    13
86
 * F1:    undefined     112     0
87
 * F8:    undefined     119     0
88
 * ...
89
 * p:     undefined     112   112
90
 * P:     undefined      80    80
91
 *
92
 * IE7, keydown
93
 *
94
 *         charCode keyCode     which
95
 * ENTER: undefined      13 undefined
96
 * F1:    undefined     112 undefined
97
 * F8:    undefined     119 undefined
98
 * ...
99
 * p:     undefined      80 undefined
100
 * P:     undefined      80 undefined
101
 *
102
 * @author [email protected] (Erik Arvidsson)
103
 * @author [email protected] (Emil A Eklund)
104
 * @see ../demos/keyhandler.html
105
 */
106

107
goog.provide('goog.events.KeyEvent');
108
goog.provide('goog.events.KeyHandler');
109
goog.provide('goog.events.KeyHandler.EventType');
110

111
goog.require('goog.events');
112
goog.require('goog.events.BrowserEvent');
113
goog.require('goog.events.EventTarget');
114
goog.require('goog.events.EventType');
115
goog.require('goog.events.KeyCodes');
116
goog.require('goog.userAgent');
117

118

119

120
/**
121
 * A wrapper around an element that you want to listen to keyboard events on.
122
 * @param {Element|Document=} opt_element The element or document to listen on.
123
 * @param {boolean=} opt_capture Whether to listen for browser events in
124
 *     capture phase (defaults to false).
125
 * @constructor
126
 * @extends {goog.events.EventTarget}
127
 * @final
128
 */
129
goog.events.KeyHandler = function(opt_element, opt_capture) {
130
  goog.events.EventTarget.call(this);
131

132
  if (opt_element) {
133
    this.attach(opt_element, opt_capture);
134
  }
135
};
136
goog.inherits(goog.events.KeyHandler, goog.events.EventTarget);
137

138

139
/**
140
 * This is the element that we will listen to the real keyboard events on.
141
 * @type {Element|Document|null}
142
 * @private
143
 */
144
goog.events.KeyHandler.prototype.element_ = null;
145

146

147
/**
148
 * The key for the key press listener.
149
 * @type {goog.events.Key}
150
 * @private
151
 */
152
goog.events.KeyHandler.prototype.keyPressKey_ = null;
153

154

155
/**
156
 * The key for the key down listener.
157
 * @type {goog.events.Key}
158
 * @private
159
 */
160
goog.events.KeyHandler.prototype.keyDownKey_ = null;
161

162

163
/**
164
 * The key for the key up listener.
165
 * @type {goog.events.Key}
166
 * @private
167
 */
168
goog.events.KeyHandler.prototype.keyUpKey_ = null;
169

170

171
/**
172
 * Used to detect keyboard repeat events.
173
 * @private
174
 * @type {number}
175
 */
176
goog.events.KeyHandler.prototype.lastKey_ = -1;
177

178

179
/**
180
 * Keycode recorded for key down events. As most browsers don't report the
181
 * keycode in the key press event we need to record it in the key down phase.
182
 * @private
183
 * @type {number}
184
 */
185
goog.events.KeyHandler.prototype.keyCode_ = -1;
186

187

188
/**
189
 * Alt key recorded for key down events. FF on Mac does not report the alt key
190
 * flag in the key press event, we need to record it in the key down phase.
191
 * @type {boolean}
192
 * @private
193
 */
194
goog.events.KeyHandler.prototype.altKey_ = false;
195

196

197
/**
198
 * Enum type for the events fired by the key handler
199
 * @enum {string}
200
 */
201
goog.events.KeyHandler.EventType = {
202
  KEY: 'key'
203
};
204

205

206
/**
207
 * An enumeration of key codes that Safari 2 does incorrectly
208
 * @type {Object}
209
 * @private
210
 */
211
goog.events.KeyHandler.safariKey_ = {
212
  '3': goog.events.KeyCodes.ENTER,             // 13
213
  '12': goog.events.KeyCodes.NUMLOCK,          // 144
214
  '63232': goog.events.KeyCodes.UP,            // 38
215
  '63233': goog.events.KeyCodes.DOWN,          // 40
216
  '63234': goog.events.KeyCodes.LEFT,          // 37
217
  '63235': goog.events.KeyCodes.RIGHT,         // 39
218
  '63236': goog.events.KeyCodes.F1,            // 112
219
  '63237': goog.events.KeyCodes.F2,            // 113
220
  '63238': goog.events.KeyCodes.F3,            // 114
221
  '63239': goog.events.KeyCodes.F4,            // 115
222
  '63240': goog.events.KeyCodes.F5,            // 116
223
  '63241': goog.events.KeyCodes.F6,            // 117
224
  '63242': goog.events.KeyCodes.F7,            // 118
225
  '63243': goog.events.KeyCodes.F8,            // 119
226
  '63244': goog.events.KeyCodes.F9,            // 120
227
  '63245': goog.events.KeyCodes.F10,           // 121
228
  '63246': goog.events.KeyCodes.F11,           // 122
229
  '63247': goog.events.KeyCodes.F12,           // 123
230
  '63248': goog.events.KeyCodes.PRINT_SCREEN,  // 44
231
  '63272': goog.events.KeyCodes.DELETE,        // 46
232
  '63273': goog.events.KeyCodes.HOME,          // 36
233
  '63275': goog.events.KeyCodes.END,           // 35
234
  '63276': goog.events.KeyCodes.PAGE_UP,       // 33
235
  '63277': goog.events.KeyCodes.PAGE_DOWN,     // 34
236
  '63289': goog.events.KeyCodes.NUMLOCK,       // 144
237
  '63302': goog.events.KeyCodes.INSERT         // 45
238
};
239

240

241
/**
242
 * An enumeration of key identifiers currently part of the W3C draft for DOM3
243
 * and their mappings to keyCodes.
244
 * http://www.w3.org/TR/DOM-Level-3-Events/keyset.html#KeySet-Set
245
 * This is currently supported in Safari and should be platform independent.
246
 * @type {Object}
247
 * @private
248
 */
249
goog.events.KeyHandler.keyIdentifier_ = {
250
  'Up': goog.events.KeyCodes.UP,               // 38
251
  'Down': goog.events.KeyCodes.DOWN,           // 40
252
  'Left': goog.events.KeyCodes.LEFT,           // 37
253
  'Right': goog.events.KeyCodes.RIGHT,         // 39
254
  'Enter': goog.events.KeyCodes.ENTER,         // 13
255
  'F1': goog.events.KeyCodes.F1,               // 112
256
  'F2': goog.events.KeyCodes.F2,               // 113
257
  'F3': goog.events.KeyCodes.F3,               // 114
258
  'F4': goog.events.KeyCodes.F4,               // 115
259
  'F5': goog.events.KeyCodes.F5,               // 116
260
  'F6': goog.events.KeyCodes.F6,               // 117
261
  'F7': goog.events.KeyCodes.F7,               // 118
262
  'F8': goog.events.KeyCodes.F8,               // 119
263
  'F9': goog.events.KeyCodes.F9,               // 120
264
  'F10': goog.events.KeyCodes.F10,             // 121
265
  'F11': goog.events.KeyCodes.F11,             // 122
266
  'F12': goog.events.KeyCodes.F12,             // 123
267
  'U+007F': goog.events.KeyCodes.DELETE,       // 46
268
  'Home': goog.events.KeyCodes.HOME,           // 36
269
  'End': goog.events.KeyCodes.END,             // 35
270
  'PageUp': goog.events.KeyCodes.PAGE_UP,      // 33
271
  'PageDown': goog.events.KeyCodes.PAGE_DOWN,  // 34
272
  'Insert': goog.events.KeyCodes.INSERT        // 45
273
};
274

275

276
/**
277
 * If true, the KeyEvent fires on keydown. Otherwise, it fires on keypress.
278
 *
279
 * @type {boolean}
280
 * @private
281
 */
282
goog.events.KeyHandler.USES_KEYDOWN_ = goog.userAgent.IE ||
283
    goog.userAgent.EDGE ||
284
    goog.userAgent.WEBKIT && goog.userAgent.isVersionOrHigher('525');
285

286

287
/**
288
 * If true, the alt key flag is saved during the key down and reused when
289
 * handling the key press. FF on Mac does not set the alt flag in the key press
290
 * event.
291
 * @type {boolean}
292
 * @private
293
 */
294
goog.events.KeyHandler.SAVE_ALT_FOR_KEYPRESS_ =
295
    goog.userAgent.MAC && goog.userAgent.GECKO;
296

297

298
/**
299
 * Records the keycode for browsers that only returns the keycode for key up/
300
 * down events. For browser/key combinations that doesn't trigger a key pressed
301
 * event it also fires the patched key event.
302
 * @param {goog.events.BrowserEvent} e The key down event.
303
 * @private
304
 */
305
goog.events.KeyHandler.prototype.handleKeyDown_ = function(e) {
306
  // Ctrl-Tab and Alt-Tab can cause the focus to be moved to another window
307
  // before we've caught a key-up event.  If the last-key was one of these we
308
  // reset the state.
309
  if (goog.userAgent.WEBKIT || goog.userAgent.EDGE) {
310
    if (this.lastKey_ == goog.events.KeyCodes.CTRL && !e.ctrlKey ||
311
        this.lastKey_ == goog.events.KeyCodes.ALT && !e.altKey ||
312
        goog.userAgent.MAC && this.lastKey_ == goog.events.KeyCodes.META &&
313
            !e.metaKey) {
314
      this.resetState();
315
    }
316
  }
317

318
  if (this.lastKey_ == -1) {
319
    if (e.ctrlKey && e.keyCode != goog.events.KeyCodes.CTRL) {
320
      this.lastKey_ = goog.events.KeyCodes.CTRL;
321
    } else if (e.altKey && e.keyCode != goog.events.KeyCodes.ALT) {
322
      this.lastKey_ = goog.events.KeyCodes.ALT;
323
    } else if (e.metaKey && e.keyCode != goog.events.KeyCodes.META) {
324
      this.lastKey_ = goog.events.KeyCodes.META;
325
    }
326
  }
327

328
  if (goog.events.KeyHandler.USES_KEYDOWN_ &&
329
      !goog.events.KeyCodes.firesKeyPressEvent(
330
          e.keyCode, this.lastKey_, e.shiftKey, e.ctrlKey, e.altKey,
331
          e.metaKey)) {
332
    this.handleEvent(e);
333
  } else {
334
    this.keyCode_ = goog.events.KeyCodes.normalizeKeyCode(e.keyCode);
335
    if (goog.events.KeyHandler.SAVE_ALT_FOR_KEYPRESS_) {
336
      this.altKey_ = e.altKey;
337
    }
338
  }
339
};
340

341

342
/**
343
 * Resets the stored previous values. Needed to be called for webkit which will
344
 * not generate a key up for meta key operations. This should only be called
345
 * when having finished with repeat key possibilities.
346
 */
347
goog.events.KeyHandler.prototype.resetState = function() {
348
  this.lastKey_ = -1;
349
  this.keyCode_ = -1;
350
};
351

352

353
/**
354
 * Clears the stored previous key value, resetting the key repeat status. Uses
355
 * -1 because the Safari 3 Windows beta reports 0 for certain keys (like Home
356
 * and End.)
357
 * @param {goog.events.BrowserEvent} e The keyup event.
358
 * @private
359
 */
360
goog.events.KeyHandler.prototype.handleKeyup_ = function(e) {
361
  this.resetState();
362
  this.altKey_ = e.altKey;
363
};
364

365

366
/**
367
 * Handles the events on the element.
368
 * @param {goog.events.BrowserEvent} e  The keyboard event sent from the
369
 *     browser.
370
 */
371
goog.events.KeyHandler.prototype.handleEvent = function(e) {
372
  var be = e.getBrowserEvent();
373
  var keyCode, charCode;
374
  var altKey = be.altKey;
375

376
  // IE reports the character code in the keyCode field for keypress events.
377
  // There are two exceptions however, Enter and Escape.
378
  if (goog.userAgent.IE && e.type == goog.events.EventType.KEYPRESS) {
379
    keyCode = this.keyCode_;
380
    charCode = keyCode != goog.events.KeyCodes.ENTER &&
381
            keyCode != goog.events.KeyCodes.ESC ?
382
        be.keyCode :
383
        0;
384

385
    // Safari reports the character code in the keyCode field for keypress
386
    // events but also has a charCode field.
387
  } else if (
388
      (goog.userAgent.WEBKIT || goog.userAgent.EDGE) &&
389
      e.type == goog.events.EventType.KEYPRESS) {
390
    keyCode = this.keyCode_;
391
    charCode = be.charCode >= 0 && be.charCode < 63232 &&
392
            goog.events.KeyCodes.isCharacterKey(keyCode) ?
393
        be.charCode :
394
        0;
395

396
    // Opera reports the keycode or the character code in the keyCode field.
397
  } else if (goog.userAgent.OPERA && !goog.userAgent.WEBKIT) {
398
    keyCode = this.keyCode_;
399
    charCode = goog.events.KeyCodes.isCharacterKey(keyCode) ? be.keyCode : 0;
400

401
    // Mozilla reports the character code in the charCode field.
402
  } else {
403
    keyCode = be.keyCode || this.keyCode_;
404
    charCode = be.charCode || 0;
405
    if (goog.events.KeyHandler.SAVE_ALT_FOR_KEYPRESS_) {
406
      altKey = this.altKey_;
407
    }
408
    // On the Mac, shift-/ triggers a question mark char code and no key code
409
    // (normalized to WIN_KEY), so we synthesize the latter.
410
    if (goog.userAgent.MAC && charCode == goog.events.KeyCodes.QUESTION_MARK &&
411
        keyCode == goog.events.KeyCodes.WIN_KEY) {
412
      keyCode = goog.events.KeyCodes.SLASH;
413
    }
414
  }
415

416
  keyCode = goog.events.KeyCodes.normalizeKeyCode(keyCode);
417
  var key = keyCode;
418

419
  // Correct the key value for certain browser-specific quirks.
420
  if (keyCode) {
421
    if (keyCode >= 63232 && keyCode in goog.events.KeyHandler.safariKey_) {
422
      // NOTE(nicksantos): Safari 3 has fixed this problem,
423
      // this is only needed for Safari 2.
424
      key = goog.events.KeyHandler.safariKey_[keyCode];
425
    } else {
426
      // Safari returns 25 for Shift+Tab instead of 9.
427
      if (keyCode == 25 && e.shiftKey) {
428
        key = 9;
429
      }
430
    }
431
  } else if (
432
      be.keyIdentifier &&
433
      be.keyIdentifier in goog.events.KeyHandler.keyIdentifier_) {
434
    // This is needed for Safari Windows because it currently doesn't give a
435
    // keyCode/which for non printable keys.
436
    key = goog.events.KeyHandler.keyIdentifier_[be.keyIdentifier];
437
  }
438

439
  // If we get the same keycode as a keydown/keypress without having seen a
440
  // keyup event, then this event was caused by key repeat.
441
  var repeat = key == this.lastKey_;
442
  this.lastKey_ = key;
443

444
  var event = new goog.events.KeyEvent(key, charCode, repeat, be);
445
  event.altKey = altKey;
446
  this.dispatchEvent(event);
447
};
448

449

450
/**
451
 * Returns the element listened on for the real keyboard events.
452
 * @return {Element|Document|null} The element listened on for the real
453
 *     keyboard events.
454
 */
455
goog.events.KeyHandler.prototype.getElement = function() {
456
  return this.element_;
457
};
458

459

460
/**
461
 * Adds the proper key event listeners to the element.
462
 * @param {Element|Document} element The element to listen on.
463
 * @param {boolean=} opt_capture Whether to listen for browser events in
464
 *     capture phase (defaults to false).
465
 */
466
goog.events.KeyHandler.prototype.attach = function(element, opt_capture) {
467
  if (this.keyUpKey_) {
468
    this.detach();
469
  }
470

471
  this.element_ = element;
472

473
  this.keyPressKey_ = goog.events.listen(
474
      this.element_, goog.events.EventType.KEYPRESS, this, opt_capture);
475

476
  // Most browsers (Safari 2 being the notable exception) doesn't include the
477
  // keyCode in keypress events (IE has the char code in the keyCode field and
478
  // Mozilla only included the keyCode if there's no charCode). Thus we have to
479
  // listen for keydown to capture the keycode.
480
  this.keyDownKey_ = goog.events.listen(
481
      this.element_, goog.events.EventType.KEYDOWN, this.handleKeyDown_,
482
      opt_capture, this);
483

484

485
  this.keyUpKey_ = goog.events.listen(
486
      this.element_, goog.events.EventType.KEYUP, this.handleKeyup_,
487
      opt_capture, this);
488
};
489

490

491
/**
492
 * Removes the listeners that may exist.
493
 */
494
goog.events.KeyHandler.prototype.detach = function() {
495
  if (this.keyPressKey_) {
496
    goog.events.unlistenByKey(this.keyPressKey_);
497
    goog.events.unlistenByKey(this.keyDownKey_);
498
    goog.events.unlistenByKey(this.keyUpKey_);
499
    this.keyPressKey_ = null;
500
    this.keyDownKey_ = null;
501
    this.keyUpKey_ = null;
502
  }
503
  this.element_ = null;
504
  this.lastKey_ = -1;
505
  this.keyCode_ = -1;
506
};
507

508

509
/** @override */
510
goog.events.KeyHandler.prototype.disposeInternal = function() {
511
  goog.events.KeyHandler.superClass_.disposeInternal.call(this);
512
  this.detach();
513
};
514

515

516

517
/**
518
 * This class is used for the goog.events.KeyHandler.EventType.KEY event and
519
 * it overrides the key code with the fixed key code.
520
 * @param {number} keyCode The adjusted key code.
521
 * @param {number} charCode The unicode character code.
522
 * @param {boolean} repeat Whether this event was generated by keyboard repeat.
523
 * @param {Event} browserEvent Browser event object.
524
 * @constructor
525
 * @extends {goog.events.BrowserEvent}
526
 * @final
527
 */
528
goog.events.KeyEvent = function(keyCode, charCode, repeat, browserEvent) {
529
  goog.events.BrowserEvent.call(this, browserEvent);
530
  this.type = goog.events.KeyHandler.EventType.KEY;
531

532
  /**
533
   * Keycode of key press.
534
   * @type {number}
535
   */
536
  this.keyCode = keyCode;
537

538
  /**
539
   * Unicode character code.
540
   * @type {number}
541
   */
542
  this.charCode = charCode;
543

544
  /**
545
   * True if this event was generated by keyboard auto-repeat (i.e., the user is
546
   * holding the key down.)
547
   * @type {boolean}
548
   */
549
  this.repeat = repeat;
550
};
551
goog.inherits(goog.events.KeyEvent, goog.events.BrowserEvent);
552

553