1
// Copyright 2006 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 Constant declarations for common key codes.
17
 *
18
 * @author [email protected] (Emil A Eklund)
19
 * @see ../demos/keyhandler.html
20
 */
21

22
goog.provide('goog.events.KeyCodes');
23

24
goog.require('goog.userAgent');
25

26
goog.forwardDeclare('goog.events.BrowserEvent');
27

28

29
/**
30
 * Key codes for common characters.
31
 *
32
 * This list is not localized and therefore some of the key codes are not
33
 * correct for non US keyboard layouts. See comments below.
34
 *
35
 * @enum {number}
36
 */
37
goog.events.KeyCodes = {
38
  WIN_KEY_FF_LINUX: 0,
39
  MAC_ENTER: 3,
40
  BACKSPACE: 8,
41
  TAB: 9,
42
  NUM_CENTER: 12,  // NUMLOCK on FF/Safari Mac
43
  ENTER: 13,
44
  SHIFT: 16,
45
  CTRL: 17,
46
  ALT: 18,
47
  PAUSE: 19,
48
  CAPS_LOCK: 20,
49
  ESC: 27,
50
  SPACE: 32,
51
  PAGE_UP: 33,    // also NUM_NORTH_EAST
52
  PAGE_DOWN: 34,  // also NUM_SOUTH_EAST
53
  END: 35,        // also NUM_SOUTH_WEST
54
  HOME: 36,       // also NUM_NORTH_WEST
55
  LEFT: 37,       // also NUM_WEST
56
  UP: 38,         // also NUM_NORTH
57
  RIGHT: 39,      // also NUM_EAST
58
  DOWN: 40,       // also NUM_SOUTH
59
  PLUS_SIGN: 43,  // NOT numpad plus
60
  PRINT_SCREEN: 44,
61
  INSERT: 45,  // also NUM_INSERT
62
  DELETE: 46,  // also NUM_DELETE
63
  ZERO: 48,
64
  ONE: 49,
65
  TWO: 50,
66
  THREE: 51,
67
  FOUR: 52,
68
  FIVE: 53,
69
  SIX: 54,
70
  SEVEN: 55,
71
  EIGHT: 56,
72
  NINE: 57,
73
  FF_SEMICOLON: 59,   // Firefox (Gecko) fires this for semicolon instead of 186
74
  FF_EQUALS: 61,      // Firefox (Gecko) fires this for equals instead of 187
75
  FF_DASH: 173,       // Firefox (Gecko) fires this for dash instead of 189
76
  QUESTION_MARK: 63,  // needs localization
77
  AT_SIGN: 64,
78
  A: 65,
79
  B: 66,
80
  C: 67,
81
  D: 68,
82
  E: 69,
83
  F: 70,
84
  G: 71,
85
  H: 72,
86
  I: 73,
87
  J: 74,
88
  K: 75,
89
  L: 76,
90
  M: 77,
91
  N: 78,
92
  O: 79,
93
  P: 80,
94
  Q: 81,
95
  R: 82,
96
  S: 83,
97
  T: 84,
98
  U: 85,
99
  V: 86,
100
  W: 87,
101
  X: 88,
102
  Y: 89,
103
  Z: 90,
104
  META: 91,  // WIN_KEY_LEFT
105
  WIN_KEY_RIGHT: 92,
106
  CONTEXT_MENU: 93,
107
  NUM_ZERO: 96,
108
  NUM_ONE: 97,
109
  NUM_TWO: 98,
110
  NUM_THREE: 99,
111
  NUM_FOUR: 100,
112
  NUM_FIVE: 101,
113
  NUM_SIX: 102,
114
  NUM_SEVEN: 103,
115
  NUM_EIGHT: 104,
116
  NUM_NINE: 105,
117
  NUM_MULTIPLY: 106,
118
  NUM_PLUS: 107,
119
  NUM_MINUS: 109,
120
  NUM_PERIOD: 110,
121
  NUM_DIVISION: 111,
122
  F1: 112,
123
  F2: 113,
124
  F3: 114,
125
  F4: 115,
126
  F5: 116,
127
  F6: 117,
128
  F7: 118,
129
  F8: 119,
130
  F9: 120,
131
  F10: 121,
132
  F11: 122,
133
  F12: 123,
134
  NUMLOCK: 144,
135
  SCROLL_LOCK: 145,
136

137
  // OS-specific media keys like volume controls and browser controls.
138
  FIRST_MEDIA_KEY: 166,
139
  LAST_MEDIA_KEY: 183,
140

141
  SEMICOLON: 186,             // needs localization
142
  DASH: 189,                  // needs localization
143
  EQUALS: 187,                // needs localization
144
  COMMA: 188,                 // needs localization
145
  PERIOD: 190,                // needs localization
146
  SLASH: 191,                 // needs localization
147
  APOSTROPHE: 192,            // needs localization
148
  TILDE: 192,                 // needs localization
149
  SINGLE_QUOTE: 222,          // needs localization
150
  OPEN_SQUARE_BRACKET: 219,   // needs localization
151
  BACKSLASH: 220,             // needs localization
152
  CLOSE_SQUARE_BRACKET: 221,  // needs localization
153
  WIN_KEY: 224,
154
  MAC_FF_META:
155
      224,  // Firefox (Gecko) fires this for the meta key instead of 91
156
  MAC_WK_CMD_LEFT: 91,   // WebKit Left Command key fired, same as META
157
  MAC_WK_CMD_RIGHT: 93,  // WebKit Right Command key fired, different from META
158
  WIN_IME: 229,
159

160
  // "Reserved for future use". Some programs (e.g. the SlingPlayer 2.4 ActiveX
161
  // control) fire this as a hacky way to disable screensavers.
162
  VK_NONAME: 252,
163

164
  // We've seen users whose machines fire this keycode at regular one
165
  // second intervals. The common thread among these users is that
166
  // they're all using Dell Inspiron laptops, so we suspect that this
167
  // indicates a hardware/bios problem.
168
  // http://en.community.dell.com/support-forums/laptop/f/3518/p/19285957/19523128.aspx
169
  PHANTOM: 255
170
};
171

172

173
/**
174
 * Returns false if the event does not contain a text modifying key.
175
 *
176
 * When it returns true, the event might be text modifying. It is infeasible to
177
 * say for sure because of the many different keyboard layouts, so this method
178
 * errs on the side of assuming a key event is text-modifiable if we cannot be
179
 * certain it is not. As an example, it will return true for ctrl+a, though in
180
 * many standard keyboard layouts that key combination would mean "select all",
181
 * and not actually modify the text.
182
 *
183
 * @param {goog.events.BrowserEvent} e A key event.
184
 * @return {boolean} Whether it's a text modifying key.
185
 */
186
goog.events.KeyCodes.isTextModifyingKeyEvent = function(e) {
187
  if (e.altKey && !e.ctrlKey || e.metaKey ||
188
      // Function keys don't generate text
189
      e.keyCode >= goog.events.KeyCodes.F1 &&
190
          e.keyCode <= goog.events.KeyCodes.F12) {
191
    return false;
192
  }
193

194
  // The following keys are quite harmless, even in combination with
195
  // CTRL, ALT or SHIFT.
196
  switch (e.keyCode) {
197
    case goog.events.KeyCodes.ALT:
198
    case goog.events.KeyCodes.CAPS_LOCK:
199
    case goog.events.KeyCodes.CONTEXT_MENU:
200
    case goog.events.KeyCodes.CTRL:
201
    case goog.events.KeyCodes.DOWN:
202
    case goog.events.KeyCodes.END:
203
    case goog.events.KeyCodes.ESC:
204
    case goog.events.KeyCodes.HOME:
205
    case goog.events.KeyCodes.INSERT:
206
    case goog.events.KeyCodes.LEFT:
207
    case goog.events.KeyCodes.MAC_FF_META:
208
    case goog.events.KeyCodes.META:
209
    case goog.events.KeyCodes.NUMLOCK:
210
    case goog.events.KeyCodes.NUM_CENTER:
211
    case goog.events.KeyCodes.PAGE_DOWN:
212
    case goog.events.KeyCodes.PAGE_UP:
213
    case goog.events.KeyCodes.PAUSE:
214
    case goog.events.KeyCodes.PHANTOM:
215
    case goog.events.KeyCodes.PRINT_SCREEN:
216
    case goog.events.KeyCodes.RIGHT:
217
    case goog.events.KeyCodes.SCROLL_LOCK:
218
    case goog.events.KeyCodes.SHIFT:
219
    case goog.events.KeyCodes.UP:
220
    case goog.events.KeyCodes.VK_NONAME:
221
    case goog.events.KeyCodes.WIN_KEY:
222
    case goog.events.KeyCodes.WIN_KEY_RIGHT:
223
      return false;
224
    case goog.events.KeyCodes.WIN_KEY_FF_LINUX:
225
      return !goog.userAgent.GECKO;
226
    default:
227
      return e.keyCode < goog.events.KeyCodes.FIRST_MEDIA_KEY ||
228
          e.keyCode > goog.events.KeyCodes.LAST_MEDIA_KEY;
229
  }
230
};
231

232

233
/**
234
 * Returns true if the key fires a keypress event in the current browser.
235
 *
236
 * Accoridng to MSDN [1] IE only fires keypress events for the following keys:
237
 * - Letters: A - Z (uppercase and lowercase)
238
 * - Numerals: 0 - 9
239
 * - Symbols: ! @ # $ % ^ & * ( ) _ - + = < [ ] { } , . / ? \ | ' ` " ~
240
 * - System: ESC, SPACEBAR, ENTER
241
 *
242
 * That's not entirely correct though, for instance there's no distinction
243
 * between upper and lower case letters.
244
 *
245
 * [1] http://msdn2.microsoft.com/en-us/library/ms536939(VS.85).aspx)
246
 *
247
 * Safari is similar to IE, but does not fire keypress for ESC.
248
 *
249
 * Additionally, IE6 does not fire keydown or keypress events for letters when
250
 * the control or alt keys are held down and the shift key is not. IE7 does
251
 * fire keydown in these cases, though, but not keypress.
252
 *
253
 * @param {number} keyCode A key code.
254
 * @param {number=} opt_heldKeyCode Key code of a currently-held key.
255
 * @param {boolean=} opt_shiftKey Whether the shift key is held down.
256
 * @param {boolean=} opt_ctrlKey Whether the control key is held down.
257
 * @param {boolean=} opt_altKey Whether the alt key is held down.
258
 * @param {boolean=} opt_metaKey Whether the meta key is held down.
259
 * @return {boolean} Whether it's a key that fires a keypress event.
260
 */
261
goog.events.KeyCodes.firesKeyPressEvent = function(
262
    keyCode, opt_heldKeyCode, opt_shiftKey, opt_ctrlKey, opt_altKey,
263
    opt_metaKey) {
264
  if (!goog.userAgent.IE && !goog.userAgent.EDGE &&
265
      !(goog.userAgent.WEBKIT && goog.userAgent.isVersionOrHigher('525'))) {
266
    return true;
267
  }
268

269
  if (goog.userAgent.MAC && opt_altKey) {
270
    return goog.events.KeyCodes.isCharacterKey(keyCode);
271
  }
272

273
  // Alt but not AltGr which is represented as Alt+Ctrl.
274
  if (opt_altKey && !opt_ctrlKey) {
275
    return false;
276
  }
277

278
  // Saves Ctrl or Alt + key for IE and WebKit 525+, which won't fire keypress.
279
  // Non-IE browsers and WebKit prior to 525 won't get this far so no need to
280
  // check the user agent.
281
  if (goog.isNumber(opt_heldKeyCode)) {
282
    opt_heldKeyCode = goog.events.KeyCodes.normalizeKeyCode(opt_heldKeyCode);
283
  }
284
  var heldKeyIsModifier = opt_heldKeyCode == goog.events.KeyCodes.CTRL ||
285
      opt_heldKeyCode == goog.events.KeyCodes.ALT ||
286
      goog.userAgent.MAC && opt_heldKeyCode == goog.events.KeyCodes.META;
287
  // The Shift key blocks keypresses on Mac iff accompanied by another modifier.
288
  var modifiedShiftKey = opt_heldKeyCode == goog.events.KeyCodes.SHIFT &&
289
      (opt_ctrlKey || opt_metaKey);
290
  if ((!opt_shiftKey || goog.userAgent.MAC) && heldKeyIsModifier ||
291
      goog.userAgent.MAC && modifiedShiftKey) {
292
    return false;
293
  }
294

295
  // Some keys with Ctrl/Shift do not issue keypress in WEBKIT.
296
  if ((goog.userAgent.WEBKIT || goog.userAgent.EDGE) && opt_ctrlKey &&
297
      opt_shiftKey) {
298
    switch (keyCode) {
299
      case goog.events.KeyCodes.BACKSLASH:
300
      case goog.events.KeyCodes.OPEN_SQUARE_BRACKET:
301
      case goog.events.KeyCodes.CLOSE_SQUARE_BRACKET:
302
      case goog.events.KeyCodes.TILDE:
303
      case goog.events.KeyCodes.SEMICOLON:
304
      case goog.events.KeyCodes.DASH:
305
      case goog.events.KeyCodes.EQUALS:
306
      case goog.events.KeyCodes.COMMA:
307
      case goog.events.KeyCodes.PERIOD:
308
      case goog.events.KeyCodes.SLASH:
309
      case goog.events.KeyCodes.APOSTROPHE:
310
      case goog.events.KeyCodes.SINGLE_QUOTE:
311
        return false;
312
    }
313
  }
314

315
  // When Ctrl+<somekey> is held in IE, it only fires a keypress once, but it
316
  // continues to fire keydown events as the event repeats.
317
  if (goog.userAgent.IE && opt_ctrlKey && opt_heldKeyCode == keyCode) {
318
    return false;
319
  }
320

321
  switch (keyCode) {
322
    case goog.events.KeyCodes.ENTER:
323
      return true;
324
    case goog.events.KeyCodes.ESC:
325
      return !(goog.userAgent.WEBKIT || goog.userAgent.EDGE);
326
  }
327

328
  return goog.events.KeyCodes.isCharacterKey(keyCode);
329
};
330

331

332
/**
333
 * Returns true if the key produces a character.
334
 * This does not cover characters on non-US keyboards (Russian, Hebrew, etc.).
335
 *
336
 * @param {number} keyCode A key code.
337
 * @return {boolean} Whether it's a character key.
338
 */
339
goog.events.KeyCodes.isCharacterKey = function(keyCode) {
340
  if (keyCode >= goog.events.KeyCodes.ZERO &&
341
      keyCode <= goog.events.KeyCodes.NINE) {
342
    return true;
343
  }
344

345
  if (keyCode >= goog.events.KeyCodes.NUM_ZERO &&
346
      keyCode <= goog.events.KeyCodes.NUM_MULTIPLY) {
347
    return true;
348
  }
349

350
  if (keyCode >= goog.events.KeyCodes.A && keyCode <= goog.events.KeyCodes.Z) {
351
    return true;
352
  }
353

354
  // Safari sends zero key code for non-latin characters.
355
  if ((goog.userAgent.WEBKIT || goog.userAgent.EDGE) && keyCode == 0) {
356
    return true;
357
  }
358

359
  switch (keyCode) {
360
    case goog.events.KeyCodes.SPACE:
361
    case goog.events.KeyCodes.PLUS_SIGN:
362
    case goog.events.KeyCodes.QUESTION_MARK:
363
    case goog.events.KeyCodes.AT_SIGN:
364
    case goog.events.KeyCodes.NUM_PLUS:
365
    case goog.events.KeyCodes.NUM_MINUS:
366
    case goog.events.KeyCodes.NUM_PERIOD:
367
    case goog.events.KeyCodes.NUM_DIVISION:
368
    case goog.events.KeyCodes.SEMICOLON:
369
    case goog.events.KeyCodes.FF_SEMICOLON:
370
    case goog.events.KeyCodes.DASH:
371
    case goog.events.KeyCodes.EQUALS:
372
    case goog.events.KeyCodes.FF_EQUALS:
373
    case goog.events.KeyCodes.COMMA:
374
    case goog.events.KeyCodes.PERIOD:
375
    case goog.events.KeyCodes.SLASH:
376
    case goog.events.KeyCodes.APOSTROPHE:
377
    case goog.events.KeyCodes.SINGLE_QUOTE:
378
    case goog.events.KeyCodes.OPEN_SQUARE_BRACKET:
379
    case goog.events.KeyCodes.BACKSLASH:
380
    case goog.events.KeyCodes.CLOSE_SQUARE_BRACKET:
381
      return true;
382
    default:
383
      return false;
384
  }
385
};
386

387

388
/**
389
 * Normalizes key codes from OS/Browser-specific value to the general one.
390
 * @param {number} keyCode The native key code.
391
 * @return {number} The normalized key code.
392
 */
393
goog.events.KeyCodes.normalizeKeyCode = function(keyCode) {
394
  if (goog.userAgent.GECKO) {
395
    return goog.events.KeyCodes.normalizeGeckoKeyCode(keyCode);
396
  } else if (goog.userAgent.MAC && goog.userAgent.WEBKIT) {
397
    return goog.events.KeyCodes.normalizeMacWebKitKeyCode(keyCode);
398
  } else {
399
    return keyCode;
400
  }
401
};
402

403

404
/**
405
 * Normalizes key codes from their Gecko-specific value to the general one.
406
 * @param {number} keyCode The native key code.
407
 * @return {number} The normalized key code.
408
 */
409
goog.events.KeyCodes.normalizeGeckoKeyCode = function(keyCode) {
410
  switch (keyCode) {
411
    case goog.events.KeyCodes.FF_EQUALS:
412
      return goog.events.KeyCodes.EQUALS;
413
    case goog.events.KeyCodes.FF_SEMICOLON:
414
      return goog.events.KeyCodes.SEMICOLON;
415
    case goog.events.KeyCodes.FF_DASH:
416
      return goog.events.KeyCodes.DASH;
417
    case goog.events.KeyCodes.MAC_FF_META:
418
      return goog.events.KeyCodes.META;
419
    case goog.events.KeyCodes.WIN_KEY_FF_LINUX:
420
      return goog.events.KeyCodes.WIN_KEY;
421
    default:
422
      return keyCode;
423
  }
424
};
425

426

427
/**
428
 * Normalizes key codes from their Mac WebKit-specific value to the general one.
429
 * @param {number} keyCode The native key code.
430
 * @return {number} The normalized key code.
431
 */
432
goog.events.KeyCodes.normalizeMacWebKitKeyCode = function(keyCode) {
433
  switch (keyCode) {
434
    case goog.events.KeyCodes.MAC_WK_CMD_RIGHT:  // 93
435
      return goog.events.KeyCodes.META;          // 91
436
    default:
437
      return keyCode;
438
  }
439
};
440

441