Added Key Events.

Author: photonstorm

src/input/keyboard/KeyboardPlugin.js

@@ -6,6 +6,7 @@
 
 var Class = require('../../utils/Class');
 var EventEmitter = require('eventemitter3');
+var Events = require('./events');
 var GetValue = require('../../utils/object/GetValue');
 var InputPluginCache = require('../InputPluginCache');
 var Key = require('./keys/Key');
@@ -720,16 +721,14 @@ var KeyboardPlugin = new Class({
 
                 if (!event.cancelled && (!key || !repeat))
                 {
-                    //  keydown_code event
                     if (KeyMap[code])
                     {
-                        this.emit('keydown_' + KeyMap[code], event);
+                        this.emit(Events.KEY_DOWN + KeyMap[code], event);
                     }
 
                     if (!event.cancelled)
                     {
-                        //  keydown event
-                        this.emit(event.type, event);
+                        this.emit(Events.ANY_KEY_DOWN, event);
                     }
                 }
             }
@@ -743,16 +742,14 @@ var KeyboardPlugin = new Class({
 
                 if (!event.cancelled)
                 {
-                    //  keyup_code event
                     if (KeyMap[code])
                     {
-                        this.emit('keyup_' + KeyMap[code], event);
+                        this.emit(Events.KEY_UP + KeyMap[code], event);
                     }
 
                     if (!event.cancelled)
                     {
-                        //  keyup event
-                        this.emit(event.type, event);
+                        this.emit(Events.ANY_KEY_UP, event);
                     }
                 }
             }

src/input/keyboard/combo/KeyCombo.js

@@ -5,6 +5,7 @@
  */
 
 var Class = require('../../../utils/Class');
+var Events = require('../events');
 var GetFastValue = require('../../../utils/object/GetFastValue');
 var ProcessKeyCombo = require('./ProcessKeyCombo');
 var ResetKeyCombo = require('./ResetKeyCombo');
@@ -235,7 +236,7 @@ var KeyCombo = new Class({
 
             if (matched)
             {
-                _this.manager.emit('keycombomatch', _this, event);
+                _this.manager.emit(Events.COMBO_MATCH, _this, event);
 
                 if (_this.resetOnMatch)
                 {
@@ -254,6 +255,7 @@ var KeyCombo = new Class({
          * @name Phaser.Input.Keyboard.KeyCombo#onKeyDown
          * @private
          * @type {KeyboardKeydownCallback}
+         * @fires Phaser.Input.Keyboard.Events#COMBO_MATCH
          * @since 3.0.0
          */
         this.onKeyDown = onKeyDownHandler;

src/input/keyboard/events/ANY_KEY_DOWN_EVENT.js

@@ -0,0 +1,29 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @copyright    2019 Photon Storm Ltd.
+ * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
+ */
+
+/**
+ * The Global Key Down Event.
+ * 
+ * This event is dispatched by the Keyboard Plugin when any key on the keyboard is pressed down.
+ * 
+ * Listen to this event from within a Scene using: `this.input.keyboard.on('keydown', listener)`.
+ * 
+ * You can also listen for a specific key being pressed. See [Keyboard.Events.KEY_DOWN]{Phaser.Input.Keyboard.Events#KEY_DOWN} for details.
+ * 
+ * Finally, you can create Key objects, which you can also listen for events from. See [Keyboard.Events.DOWN]{Phaser.Input.Keyboard.Events#DOWN} for details.
+ * 
+ * _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.
+ *
+ * Also, please be aware that some browser extensions can disable or override Phaser keyboard handling.
+ * For example, the Chrome extension vimium is known to disable Phaser from using the D key, while EverNote disables the backtick key.
+ * There are others. So, please check your extensions if you find you have specific keys that don't work.
+ *
+ * @event Phaser.Input.Keyboard.Events#ANY_KEY_DOWN
+ * 
+ * @param {KeyboardEvent} event - The native DOM Keyboard Event. You can inspect this to learn more about the key that was pressed, any modifiers, etc.
+ */
+module.exports = 'keydown';

src/input/keyboard/events/ANY_KEY_UP_EVENT.js

@@ -0,0 +1,22 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @copyright    2019 Photon Storm Ltd.
+ * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
+ */
+
+/**
+ * The Global Key Up Event.
+ * 
+ * This event is dispatched by the Keyboard Plugin when any key on the keyboard is released.
+ * 
+ * Listen to this event from within a Scene using: `this.input.keyboard.on('keyup', listener)`.
+ * 
+ * You can also listen for a specific key being released. See [Keyboard.Events.KEY_UP]{Phaser.Input.Keyboard.Events#KEY_UP} for details.
+ * 
+ * Finally, you can create Key objects, which you can also listen for events from. See [Keyboard.Events.UP]{Phaser.Input.Keyboard.Events#UP} for details.
+ *
+ * @event Phaser.Input.Keyboard.Events#ANY_KEY_UP
+ * 
+ * @param {KeyboardEvent} event - The native DOM Keyboard Event. You can inspect this to learn more about the key that was released, any modifiers, etc.
+ */
+module.exports = 'keyup';

src/input/keyboard/events/COMBO_MATCH_EVENT.js

@@ -0,0 +1,27 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @copyright    2019 Photon Storm Ltd.
+ * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
+ */
+
+/**
+ * The Key Combo Match Event.
+ * 
+ * This event is dispatched by the Keyboard Plugin when a [Key Combo]{Phaser.Input.Keyboard.KeyCombo} is matched.
+ * 
+ * Listen for this event from the Key Plugin after a combo has been created:
+ * 
+ * ```javascript
+ * this.input.keyboard.createCombo([ 38, 38, 40, 40, 37, 39, 37, 39, 66, 65, 13 ], { resetOnMatch: true });
+ *
+ * this.input.keyboard.on('keycombomatch', function (event) {
+ *     console.log('Konami Code entered!');
+ * });
+ * ```
+ *
+ * @event Phaser.Input.Keyboard.Events#COMBO_MATCH
+ * 
+ * @param {Phaser.Input.Keyboard.KeyCombo} keycombo - The Key Combo object that was matched.
+ * @param {KeyboardEvent} event - The native DOM Keyboard Event of the final key in the combo. You can inspect this to learn more about any modifiers, etc.
+ */
+module.exports = 'keycombomatch';

src/input/keyboard/events/DOWN_EVENT.js

@@ -0,0 +1,27 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @copyright    2019 Photon Storm Ltd.
+ * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
+ */
+
+/**
+ * The Key Down Event.
+ * 
+ * This event is dispatched by a [Key]{Phaser.Input.Keyboard.Key} object when it is pressed.
+ * 
+ * Listen for this event from the Key object instance directly:
+ * 
+ * ```javascript
+ * var spaceBar = this.input.keyboard.addKey(Phaser.Input.Keyboard.KeyCodes.SPACE);
+ * 
+ * spaceBar.on('down', listener)
+ * ```
+ * 
+ * You can also create a generic 'global' listener. See [Keyboard.Events.ANY_KEY_DOWN]{Phaser.Input.Keyboard.Events#ANY_KEY_DOWN} for details.
+ *
+ * @event Phaser.Input.Keyboard.Events#DOWN
+ * 
+ * @param {Phaser.Input.Keyboard.Key} key - The Key object that was pressed.
+ * @param {KeyboardEvent} event - The native DOM Keyboard Event. You can inspect this to learn more about any modifiers, etc.
+ */
+module.exports = 'down';

src/input/keyboard/events/KEY_DOWN_EVENT.js

@@ -0,0 +1,32 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @copyright    2019 Photon Storm Ltd.
+ * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
+ */
+
+/**
+ * The Key Down Event.
+ * 
+ * This event is dispatched by the Keyboard Plugin when any key on the keyboard is pressed down.
+ * 
+ * Unlike the `ANY_KEY_DOWN` event, this one has a special dynamic event name. For example, to listen for the `A` key being pressed
+ * use the following from within a Scene: `this.input.keyboard.on('keydown-A', listener)`. You can replace the `-A` part of the event
+ * name with any valid [Key Code string]{Phaser.Input.Keyboard.KeyCodes}. For example, this will listen for the space bar: 
+ * `this.input.keyboard.on('keydown-SPACE', listener)`.
+ * 
+ * You can also create a generic 'global' listener. See [Keyboard.Events.ANY_KEY_DOWN]{Phaser.Input.Keyboard.Events#ANY_KEY_DOWN} for details.
+ * 
+ * Finally, you can create Key objects, which you can also listen for events from. See [Keyboard.Events.DOWN]{Phaser.Input.Keyboard.Events#DOWN} for details.
+ * 
+ * _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.
+ *
+ * Also, please be aware that some browser extensions can disable or override Phaser keyboard handling.
+ * For example, the Chrome extension vimium is known to disable Phaser from using the D key, while EverNote disables the backtick key.
+ * There are others. So, please check your extensions if you find you have specific keys that don't work.
+ *
+ * @event Phaser.Input.Keyboard.Events#KEY_DOWN
+ * 
+ * @param {KeyboardEvent} event - The native DOM Keyboard Event. You can inspect this to learn more about the key that was pressed, any modifiers, etc.
+ */
+module.exports = 'keydown-';

src/input/keyboard/events/KEY_UP_EVENT.js

@@ -0,0 +1,25 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @copyright    2019 Photon Storm Ltd.
+ * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
+ */
+
+/**
+ * The Key Up Event.
+ * 
+ * This event is dispatched by the Keyboard Plugin when any key on the keyboard is released.
+ * 
+ * Unlike the `ANY_KEY_UP` event, this one has a special dynamic event name. For example, to listen for the `A` key being released
+ * use the following from within a Scene: `this.input.keyboard.on('keyup-A', listener)`. You can replace the `-A` part of the event
+ * name with any valid [Key Code string]{Phaser.Input.Keyboard.KeyCodes}. For example, this will listen for the space bar: 
+ * `this.input.keyboard.on('keyup-SPACE', listener)`.
+ * 
+ * You can also create a generic 'global' listener. See [Keyboard.Events.ANY_KEY_UP]{Phaser.Input.Keyboard.Events#ANY_KEY_UP} for details.
+ * 
+ * Finally, you can create Key objects, which you can also listen for events from. See [Keyboard.Events.UP]{Phaser.Input.Keyboard.Events#UP} for details.
+ *
+ * @event Phaser.Input.Keyboard.Events#KEY_UP
+ * 
+ * @param {KeyboardEvent} event - The native DOM Keyboard Event. You can inspect this to learn more about the key that was released, any modifiers, etc.
+ */
+module.exports = 'keyup-';

src/input/keyboard/events/UP_EVENT.js

@@ -0,0 +1,27 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @copyright    2019 Photon Storm Ltd.
+ * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
+ */
+
+/**
+ * The Key Up Event.
+ * 
+ * This event is dispatched by a [Key]{Phaser.Input.Keyboard.Key} object when it is released.
+ * 
+ * Listen for this event from the Key object instance directly:
+ * 
+ * ```javascript
+ * var spaceBar = this.input.keyboard.addKey(Phaser.Input.Keyboard.KeyCodes.SPACE);
+ * 
+ * spaceBar.on('up', listener)
+ * ```
+ * 
+ * You can also create a generic 'global' listener. See [Keyboard.Events.ANY_KEY_UP]{Phaser.Input.Keyboard.Events#ANY_KEY_UP} for details.
+ *
+ * @event Phaser.Input.Keyboard.Events#UP
+ * 
+ * @param {Phaser.Input.Keyboard.Key} key - The Key object that was released.
+ * @param {KeyboardEvent} event - The native DOM Keyboard Event. You can inspect this to learn more about any modifiers, etc.
+ */
+module.exports = 'up';

src/input/keyboard/events/index.js

@@ -0,0 +1,21 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @copyright    2019 Photon Storm Ltd.
+ * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
+ */
+
+/**
+ * @namespace Phaser.Input.Keyboard.Events
+ */
+
+module.exports = {
+
+    ANY_KEY_DOWN: require('./ANY_KEY_DOWN_EVENT'),
+    ANY_KEY_UP: require('./ANY_KEY_UP_EVENT'),
+    COMBO_MATCH: require('./COMBO_MATCH_EVENT'),
+    DOWN: require('./DOWN_EVENT'),
+    KEY_DOWN: require('./KEY_DOWN_EVENT'),
+    KEY_UP: require('./KEY_UP_EVENT'),
+    UP: require('./UP_EVENT')
+
+};