From 531cd49f06183bb4a7da85c8328acd3c062bd2a3 Mon Sep 17 00:00:00 2001 From: Paul Date: Tue, 29 Sep 2015 14:09:19 -0700 Subject: [PATCH] Created Phaser.KeyCode enumeration / pseudo-type - Impact: none/foward-migration; fully backwards compatible - Moves the key code constants in Keyboard to a KeyCode type. - Duplicates the KeyCodes in the Keyboard object for backward compatiblity. - KeyCode properties are listed in documentation - Updates documentaion to refer to Phaser.KeyCode - Adds in future 'keycode' expansion capabilities, as indicated by the KeyCode documentation, if the constants are used in code. Closes #2031 --- src/input/Key.js | 2 +- src/input/Keyboard.js | 368 ++++++++++++++++++++++++++++-------------- 2 files changed, 251 insertions(+), 119 deletions(-) diff --git a/src/input/Key.js b/src/input/Key.js index f38e2200b..cb9941123 100644 --- a/src/input/Key.js +++ b/src/input/Key.js @@ -10,7 +10,7 @@ * @class Phaser.Key * @constructor * @param {Phaser.Game} game - Current game instance. -* @param {number} keycode - The key code this Key is responsible for. +* @param {integer} keycode - The key code this Key is responsible for. See {@link Phaser.KeyCode}. */ Phaser.Key = function (game, keycode) { diff --git a/src/input/Keyboard.js b/src/input/Keyboard.js index 4ae0fd536..add34741c 100644 --- a/src/input/Keyboard.js +++ b/src/input/Keyboard.js @@ -7,8 +7,8 @@ /** * The Keyboard class monitors keyboard input and dispatches keyboard events. * -* _Be aware_ that many keyboards are unable to process certain combinations of keys due to hardware -* limitations known as ghosting. Full details here: http://www.html5gamedevs.com/topic/4876-impossible-to-use-more-than-2-keyboard-input-buttons-at-the-same-time/ +* _Note_: many keyboards are unable to process certain combinations of keys due to hardware limitations known as ghosting. +* See http://www.html5gamedevs.com/topic/4876-impossible-to-use-more-than-2-keyboard-input-buttons-at-the-same-time/ for more details. * * @class Phaser.Keyboard * @constructor @@ -142,7 +142,7 @@ Phaser.Keyboard.prototype = { * The Key object can then be polled, have events attached to it, etc. * * @method Phaser.Keyboard#addKey - * @param {number} keycode - The keycode of the key, i.e. Phaser.Keyboard.UP or Phaser.Keyboard.SPACEBAR + * @param {integer} keycode - The {@link Phaser.KeyCode keycode} of the key. * @return {Phaser.Key} The Key object which you can store locally and reference directly. */ addKey: function (keycode) { @@ -161,13 +161,15 @@ Phaser.Keyboard.prototype = { /** * A practical way to create an object containing user selected hotkeys. * - * For example: `addKeys( { 'up': Phaser.Keyboard.W, 'down': Phaser.Keyboard.S, 'left': Phaser.Keyboard.A, 'right': Phaser.Keyboard.D } );` + * For example, * - * Would return an object containing the properties `up`, `down`, `left` and `right` that you could poll just like a Phaser.Key object. + * addKeys( { 'up': Phaser.KeyCode.W, 'down': Phaser.KeyCode.S, 'left': Phaser.KeyCode.A, 'right': Phaser.KeyCode.D } ); + * + * would return an object containing properties (`up`, `down`, `left` and `right`) referring to {@link Phaser.Key} object. * * @method Phaser.Keyboard#addKeys - * @param {object} keys - A key mapping object, i.e. `{ 'up': Phaser.Keyboard.W, 'down': Phaser.Keyboard.S }` or `{ 'up': 52, 'down': 53 }`. - * @return {object} An object containing user selected properties + * @param {object} keys - A key mapping object, i.e. `{ 'up': Phaser.KeyCode.W, 'down': Phaser.KeyCode.S }` or `{ 'up': 52, 'down': 53 }`. + * @return {object} An object containing the properties mapped to {@link Phaser.Key} values. */ addKeys: function (keys) { @@ -186,7 +188,7 @@ Phaser.Keyboard.prototype = { * Removes a Key object from the Keyboard manager. * * @method Phaser.Keyboard#removeKey - * @param {number} keycode - The keycode of the key to remove, i.e. Phaser.Keyboard.UP or Phaser.Keyboard.SPACEBAR + * @param {integer} keycode - The {@link Phaser.KeyCode keycode} of the key to remove. */ removeKey: function (keycode) { @@ -203,11 +205,11 @@ Phaser.Keyboard.prototype = { * Creates and returns an object containing 4 hotkeys for Up, Down, Left and Right. * * @method Phaser.Keyboard#createCursorKeys - * @return {object} An object containing properties: up, down, left and right. Which can be polled like any other Phaser.Key object. + * @return {object} An object containing properties: `up`, `down`, `left` and `right` of {@link Phaser.Key} objects. */ createCursorKeys: function () { - return this.addKeys({ 'up': Phaser.Keyboard.UP, 'down': Phaser.Keyboard.DOWN, 'left': Phaser.Keyboard.LEFT, 'right': Phaser.Keyboard.RIGHT }); + return this.addKeys({ 'up': Phaser.KeyCode.UP, 'down': Phaser.KeyCode.DOWN, 'left': Phaser.KeyCode.LEFT, 'right': Phaser.KeyCode.RIGHT }); }, @@ -216,6 +218,7 @@ Phaser.Keyboard.prototype = { * This is called automatically by Phaser.Input and should not normally be invoked directly. * * @method Phaser.Keyboard#start + * @protected */ start: function () { @@ -287,11 +290,14 @@ Phaser.Keyboard.prototype = { /** * By default when a key is pressed Phaser will not stop the event from propagating up to the browser. * There are some keys this can be annoying for, like the arrow keys or space bar, which make the browser window scroll. - * You can use addKeyCapture to consume the keyboard event for specific keys so it doesn't bubble up to the the browser. + * + * The `addKeyCapture` method enables consuming keyboard event for specific keys so it doesn't bubble up to the the browser + * and cause the default browser behavior. + * * Pass in either a single keycode or an array/hash of keycodes. * * @method Phaser.Keyboard#addKeyCapture - * @param {number|array|object} keycode - Either a single numeric keycode or an array/hash of keycodes: [65, 67, 68]. + * @param {integer|integer[]|object} keycode - Either a single {@link Phaser.KeyCode keycode} or an array/hash of keycodes such as `[65, 67, 68]`. */ addKeyCapture: function (keycode) { @@ -312,7 +318,7 @@ Phaser.Keyboard.prototype = { * Removes an existing key capture. * * @method Phaser.Keyboard#removeKeyCapture - * @param {number} keycode + * @param {integer} keycode - The {@link Phaser.KeyCode keycode} to remove capturing of. */ removeKeyCapture: function (keycode) { @@ -475,7 +481,7 @@ Phaser.Keyboard.prototype = { * or was pressed down longer ago than then given duration. * * @method Phaser.Keyboard#downDuration - * @param {number} keycode - The keycode of the key to check, i.e. Phaser.Keyboard.UP or Phaser.Keyboard.SPACEBAR + * @param {integer} keycode - The {@link Phaser.KeyCode keycode} of the key to check: i.e. Phaser.KeyCode.UP or Phaser.KeyCode.SPACEBAR. * @param {number} [duration=50] - The duration within which the key is considered as being just pressed. Given in ms. * @return {boolean} True if the key was pressed down within the given duration, false if not or null if the Key wasn't found. */ @@ -497,7 +503,7 @@ Phaser.Keyboard.prototype = { * or was pressed down longer ago than then given duration. * * @method Phaser.Keyboard#upDuration - * @param {number} keycode - The keycode of the key to check, i.e. Phaser.Keyboard.UP or Phaser.Keyboard.SPACEBAR + * @param {Phaser.KeyCode|integer} keycode - The keycode of the key to check, i.e. Phaser.KeyCode.UP or Phaser.KeyCode.SPACEBAR. * @param {number} [duration=50] - The duration within which the key is considered as being just released. Given in ms. * @return {boolean} True if the key was released within the given duration, false if not or null if the Key wasn't found. */ @@ -518,7 +524,7 @@ Phaser.Keyboard.prototype = { * Returns true of the key is currently pressed down. Note that it can only detect key presses on the web browser. * * @method Phaser.Keyboard#isDown - * @param {number} keycode - The keycode of the key to check, i.e. Phaser.Keyboard.UP or Phaser.Keyboard.SPACEBAR + * @param {integer} keycode - The {@link Phaser.KeyCode keycode} of the key to check: i.e. Phaser.KeyCode.UP or Phaser.KeyCode.SPACEBAR. * @return {boolean} True if the key is currently down, false if not or null if the Key wasn't found. */ isDown: function (keycode) { @@ -577,105 +583,231 @@ Object.defineProperty(Phaser.Keyboard.prototype, "lastKey", { Phaser.Keyboard.prototype.constructor = Phaser.Keyboard; -Phaser.Keyboard.A = "A".charCodeAt(0); -Phaser.Keyboard.B = "B".charCodeAt(0); -Phaser.Keyboard.C = "C".charCodeAt(0); -Phaser.Keyboard.D = "D".charCodeAt(0); -Phaser.Keyboard.E = "E".charCodeAt(0); -Phaser.Keyboard.F = "F".charCodeAt(0); -Phaser.Keyboard.G = "G".charCodeAt(0); -Phaser.Keyboard.H = "H".charCodeAt(0); -Phaser.Keyboard.I = "I".charCodeAt(0); -Phaser.Keyboard.J = "J".charCodeAt(0); -Phaser.Keyboard.K = "K".charCodeAt(0); -Phaser.Keyboard.L = "L".charCodeAt(0); -Phaser.Keyboard.M = "M".charCodeAt(0); -Phaser.Keyboard.N = "N".charCodeAt(0); -Phaser.Keyboard.O = "O".charCodeAt(0); -Phaser.Keyboard.P = "P".charCodeAt(0); -Phaser.Keyboard.Q = "Q".charCodeAt(0); -Phaser.Keyboard.R = "R".charCodeAt(0); -Phaser.Keyboard.S = "S".charCodeAt(0); -Phaser.Keyboard.T = "T".charCodeAt(0); -Phaser.Keyboard.U = "U".charCodeAt(0); -Phaser.Keyboard.V = "V".charCodeAt(0); -Phaser.Keyboard.W = "W".charCodeAt(0); -Phaser.Keyboard.X = "X".charCodeAt(0); -Phaser.Keyboard.Y = "Y".charCodeAt(0); -Phaser.Keyboard.Z = "Z".charCodeAt(0); -Phaser.Keyboard.ZERO = "0".charCodeAt(0); -Phaser.Keyboard.ONE = "1".charCodeAt(0); -Phaser.Keyboard.TWO = "2".charCodeAt(0); -Phaser.Keyboard.THREE = "3".charCodeAt(0); -Phaser.Keyboard.FOUR = "4".charCodeAt(0); -Phaser.Keyboard.FIVE = "5".charCodeAt(0); -Phaser.Keyboard.SIX = "6".charCodeAt(0); -Phaser.Keyboard.SEVEN = "7".charCodeAt(0); -Phaser.Keyboard.EIGHT = "8".charCodeAt(0); -Phaser.Keyboard.NINE = "9".charCodeAt(0); -Phaser.Keyboard.NUMPAD_0 = 96; -Phaser.Keyboard.NUMPAD_1 = 97; -Phaser.Keyboard.NUMPAD_2 = 98; -Phaser.Keyboard.NUMPAD_3 = 99; -Phaser.Keyboard.NUMPAD_4 = 100; -Phaser.Keyboard.NUMPAD_5 = 101; -Phaser.Keyboard.NUMPAD_6 = 102; -Phaser.Keyboard.NUMPAD_7 = 103; -Phaser.Keyboard.NUMPAD_8 = 104; -Phaser.Keyboard.NUMPAD_9 = 105; -Phaser.Keyboard.NUMPAD_MULTIPLY = 106; -Phaser.Keyboard.NUMPAD_ADD = 107; -Phaser.Keyboard.NUMPAD_ENTER = 108; -Phaser.Keyboard.NUMPAD_SUBTRACT = 109; -Phaser.Keyboard.NUMPAD_DECIMAL = 110; -Phaser.Keyboard.NUMPAD_DIVIDE = 111; -Phaser.Keyboard.F1 = 112; -Phaser.Keyboard.F2 = 113; -Phaser.Keyboard.F3 = 114; -Phaser.Keyboard.F4 = 115; -Phaser.Keyboard.F5 = 116; -Phaser.Keyboard.F6 = 117; -Phaser.Keyboard.F7 = 118; -Phaser.Keyboard.F8 = 119; -Phaser.Keyboard.F9 = 120; -Phaser.Keyboard.F10 = 121; -Phaser.Keyboard.F11 = 122; -Phaser.Keyboard.F12 = 123; -Phaser.Keyboard.F13 = 124; -Phaser.Keyboard.F14 = 125; -Phaser.Keyboard.F15 = 126; -Phaser.Keyboard.COLON = 186; -Phaser.Keyboard.EQUALS = 187; -Phaser.Keyboard.COMMA = 188; -Phaser.Keyboard.UNDERSCORE = 189; -Phaser.Keyboard.PERIOD = 190; -Phaser.Keyboard.QUESTION_MARK = 191; -Phaser.Keyboard.TILDE = 192; -Phaser.Keyboard.OPEN_BRACKET = 219; -Phaser.Keyboard.BACKWARD_SLASH = 220; -Phaser.Keyboard.CLOSED_BRACKET = 221; -Phaser.Keyboard.QUOTES = 222; -Phaser.Keyboard.BACKSPACE = 8; -Phaser.Keyboard.TAB = 9; -Phaser.Keyboard.CLEAR = 12; -Phaser.Keyboard.ENTER = 13; -Phaser.Keyboard.SHIFT = 16; -Phaser.Keyboard.CONTROL = 17; -Phaser.Keyboard.ALT = 18; -Phaser.Keyboard.CAPS_LOCK = 20; -Phaser.Keyboard.ESC = 27; -Phaser.Keyboard.SPACEBAR = 32; -Phaser.Keyboard.PAGE_UP = 33; -Phaser.Keyboard.PAGE_DOWN = 34; -Phaser.Keyboard.END = 35; -Phaser.Keyboard.HOME = 36; -Phaser.Keyboard.LEFT = 37; -Phaser.Keyboard.UP = 38; -Phaser.Keyboard.RIGHT = 39; -Phaser.Keyboard.DOWN = 40; -Phaser.Keyboard.PLUS = 43; -Phaser.Keyboard.MINUS = 44; -Phaser.Keyboard.INSERT = 45; -Phaser.Keyboard.DELETE = 46; -Phaser.Keyboard.HELP = 47; -Phaser.Keyboard.NUM_LOCK = 144; +/** +* A key code represents a physical key on a keyboard. +* +* The KeyCode class contains commonly supported keyboard key codes which can be used +* as keycode`-parameters in several {@link Phaser.Keyboard} and {@link Phaser.Key} methods. +* +* _Note_: These values should only be used indirectly, eg. as `Phaser.KeyCode.KEY`. +* Future versions may replace the actual values, such that they remain compatible with `keycode`-parameters. +* The current implementation maps to the {@link https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/keyCode KeyboardEvent.keyCode} property. +* +* _Note_: Use `Phaser.KeyCode.KEY` instead of `Phaser.Keyboard.KEY` to refer to a key code; +* the latter approach is supported for compatibility. +* +* @namespace +*/ +Phaser.KeyCode = { + /** @static */ + A: "A".charCodeAt(0), + /** @static */ + B: "B".charCodeAt(0), + /** @static */ + C: "C".charCodeAt(0), + /** @static */ + D: "D".charCodeAt(0), + /** @static */ + E: "E".charCodeAt(0), + /** @static */ + F: "F".charCodeAt(0), + /** @static */ + G: "G".charCodeAt(0), + /** @static */ + H: "H".charCodeAt(0), + /** @static */ + I: "I".charCodeAt(0), + /** @static */ + J: "J".charCodeAt(0), + /** @static */ + K: "K".charCodeAt(0), + /** @static */ + L: "L".charCodeAt(0), + /** @static */ + M: "M".charCodeAt(0), + /** @static */ + N: "N".charCodeAt(0), + /** @static */ + O: "O".charCodeAt(0), + /** @static */ + P: "P".charCodeAt(0), + /** @static */ + Q: "Q".charCodeAt(0), + /** @static */ + R: "R".charCodeAt(0), + /** @static */ + S: "S".charCodeAt(0), + /** @static */ + T: "T".charCodeAt(0), + /** @static */ + U: "U".charCodeAt(0), + /** @static */ + V: "V".charCodeAt(0), + /** @static */ + W: "W".charCodeAt(0), + /** @static */ + X: "X".charCodeAt(0), + /** @static */ + Y: "Y".charCodeAt(0), + /** @static */ + Z: "Z".charCodeAt(0), + /** @static */ + ZERO: "0".charCodeAt(0), + /** @static */ + ONE: "1".charCodeAt(0), + /** @static */ + TWO: "2".charCodeAt(0), + /** @static */ + THREE: "3".charCodeAt(0), + /** @static */ + FOUR: "4".charCodeAt(0), + /** @static */ + FIVE: "5".charCodeAt(0), + /** @static */ + SIX: "6".charCodeAt(0), + /** @static */ + SEVEN: "7".charCodeAt(0), + /** @static */ + EIGHT: "8".charCodeAt(0), + /** @static */ + NINE: "9".charCodeAt(0), + /** @static */ + NUMPAD_0: 96, + /** @static */ + NUMPAD_1: 97, + /** @static */ + NUMPAD_2: 98, + /** @static */ + NUMPAD_3: 99, + /** @static */ + NUMPAD_4: 100, + /** @static */ + NUMPAD_5: 101, + /** @static */ + NUMPAD_6: 102, + /** @static */ + NUMPAD_7: 103, + /** @static */ + NUMPAD_8: 104, + /** @static */ + NUMPAD_9: 105, + /** @static */ + NUMPAD_MULTIPLY: 106, + /** @static */ + NUMPAD_ADD: 107, + /** @static */ + NUMPAD_ENTER: 108, + /** @static */ + NUMPAD_SUBTRACT: 109, + /** @static */ + NUMPAD_DECIMAL: 110, + /** @static */ + NUMPAD_DIVIDE: 111, + /** @static */ + F1: 112, + /** @static */ + F2: 113, + /** @static */ + F3: 114, + /** @static */ + F4: 115, + /** @static */ + F5: 116, + /** @static */ + F6: 117, + /** @static */ + F7: 118, + /** @static */ + F8: 119, + /** @static */ + F9: 120, + /** @static */ + F10: 121, + /** @static */ + F11: 122, + /** @static */ + F12: 123, + /** @static */ + F13: 124, + /** @static */ + F14: 125, + /** @static */ + F15: 126, + /** @static */ + COLON: 186, + /** @static */ + EQUALS: 187, + /** @static */ + COMMA: 188, + /** @static */ + UNDERSCORE: 189, + /** @static */ + PERIOD: 190, + /** @static */ + QUESTION_MARK: 191, + /** @static */ + TILDE: 192, + /** @static */ + OPEN_BRACKET: 219, + /** @static */ + BACKWARD_SLASH: 220, + /** @static */ + CLOSED_BRACKET: 221, + /** @static */ + QUOTES: 222, + /** @static */ + BACKSPACE: 8, + /** @static */ + TAB: 9, + /** @static */ + CLEAR: 12, + /** @static */ + ENTER: 13, + /** @static */ + SHIFT: 16, + /** @static */ + CONTROL: 17, + /** @static */ + ALT: 18, + /** @static */ + CAPS_LOCK: 20, + /** @static */ + ESC: 27, + /** @static */ + SPACEBAR: 32, + /** @static */ + PAGE_UP: 33, + /** @static */ + PAGE_DOWN: 34, + /** @static */ + END: 35, + /** @static */ + HOME: 36, + /** @static */ + LEFT: 37, + /** @static */ + UP: 38, + /** @static */ + RIGHT: 39, + /** @static */ + DOWN: 40, + /** @static */ + PLUS: 43, + /** @static */ + MINUS: 44, + /** @static */ + INSERT: 45, + /** @static */ + DELETE: 46, + /** @static */ + HELP: 47, + /** @static */ + NUM_LOCK: 144 +}; + +// Duplicate Phaser.KeyCode values in Phaser.Keyboard for compatibility +for (var key in Phaser.KeyCode) { + if (Phaser.KeyCode.hasOwnProperty(key) && !key.match(/[a-z]/)) { + Phaser.Keyboard[key] = Phaser.KeyCode[key]; + } +}