API Docs for: 1.3.0
Show:

File: src\input\Keyboard.ts

/**
* 
* @module Kiwi
* @submodule Input
* 
*/

module Kiwi.Input {

	/**
	* Handles and Manages the dispatching of keyboard events. When the user press's a button a new Key object is created.
	*
	* @class Keyboard
	* @constructor
	* @namespace Kiwi.Input
	* @param game {Kiwi.Game}
	* @return {Kiwi.Input.Keyboard} This object.
	*
	*/
	export class Keyboard {

		constructor (game: Kiwi.Game) {

			this.game = game;

		}

		/**
		* The type of object that this is.
		* @method objType
		* @return {String} "Keyboard"
		* @public
		*/
		public objType() {
			return "Keyboard";
		}

		/** 
		* The game that this Keyboard belongs to.
		* @property game
		* @type Kiwi.Game
		* @public
		*/
		public game: Kiwi.Game;

		/** 
		* Contains a reference to each Key object when they are either added to this Keyboard manager (by the developer), or when an event fires with that keycode.
		* @property _keys
		* @type Key[]
		* @private
		*/
		private _keys:Key[] = [];

		/**
		* Returns all of the Key objects that currently exist. This is READ ONLY.
		* @property keys
		* @type Keys[]
		* @public
		*/
		public get keys():Key[] {
			return this._keys;
		}

		/** 
		* The time in milliseconds which determines if a key was just pressed or not.
		* @property justPressedRate
		* @type Number
		* @default 200
		* @public
		*/
		public justPressedRate: number = 200;

		/** 
		* The time in milliseconds which determines if a key was just released or not.
		* @property justReleasedRate
		* @type Number
		* @default 200
		* @public
		*/
		public justReleasedRate: number = 200;

		/** 
		* Is executed when the DOMElements that are need to get the game going are loaded and thus the game can 'boot'
		* @method boot
		* @public
		*/
		public boot() {
			this.onKeyUp = new Kiwi.Signal;
			this.onKeyDown = new Kiwi.Signal;
			this.onKeyDownOnce = new Kiwi.Signal;
			this.start();
		}

		/** 
		* The update loop that is executed every frame.
		* @method update
		* @public
		*/
		public update() {

		}

		/**
		* A Signal that dispatches events when a key is released/is now up.
		* Callbacks fired by this Signal will contain two parameters, the keyCode and key object.
		* 1) KeyCode - The keyCode of the key that was just released.
		* 2) Key - The key object for that keycode.
		* @property onKeyUp
		* @type Kiwi.Signal
		* @public
		*/
		public onKeyUp: Kiwi.Signal;

		/**
		* A Signal that dispatches events when a key is pressed/is down.
		* This mimics the natural 'keydown' event listener, so it will keep dispatching events if the user holds the key down. 
		* Note: This fires after the 'onKeyDownOnce' signal.
		* Callbacks fired by this Signal will contain two parameters, the keyCode and key object.
		* 1) KeyCode - The keyCode of the key that was just released.
		* 2) Key - The key object for that keycode.
		*
		* @property onKeyDown
		* @type Kiwi.Signal
		* @public
		*/
		public onKeyDown: Kiwi.Signal;

		/**
		* A Signal that dispatches events when a key is pressed/is down initially. 
		* This event only fires the first time that the key is pressed, so it won't dispatch events if the user is holding the key down.
		* Note: This fires before the 'onKeyDown' signal;
		* Callbacks fired by this Signal will contain two parameters, the keyCode and key object.
		* 1) KeyCode - The keyCode of the key that was just released.
		* 2) Key - The key object for that keycode.
		*
		* @property onKeyDownOnce
		* @type Kiwi.Signal
		* @public
		*/
		public onKeyDownOnce: Kiwi.Signal;

		/** 
		* Adds the event listeners to the browser to listen for key events.
		* @method start
		* @public 
		*/
		public start() {
			if (this.game.deviceTargetOption=== Kiwi.TARGET_BROWSER) {
				//this._domElement.addEventListener('keydown', (event:KeyboardEvent) => this.onKeyDown(event), false);
				//this._domElement.addEventListener('keyup', (event:KeyboardEvent) => this.onKeyUp(event), false);
				document.body.addEventListener('keydown', (event: KeyboardEvent) => this._keyPressed(event), false);
				document.body.addEventListener('keyup', (event: KeyboardEvent) => this._keyReleased(event), false);
			}
		}

		/** 
		* Removes the event listeners and so effectively 'stops' all keyboard events.
		* @method stop
		* @public
		*/
		public stop() {
			if (this.game.deviceTargetOption === Kiwi.TARGET_BROWSER) {
				//this._domElement.removeEventListener('keydown', (event:KeyboardEvent) => this.onKeyDown(event), false);
				//this._domElement.removeEventListener('keyup', (event:KeyboardEvent) => this.onKeyUp(event), false);
				document.body.removeEventListener('keydown', (event: KeyboardEvent) => this._keyPressed(event), false);
				document.body.removeEventListener('keyup', (event: KeyboardEvent) => this._keyReleased(event), false);
			}
		}

		/** 
		* Is executed when a key is pressed/is down. This then either creates a new Key (if one does not currently exist) for that keycode, 
		* or it updates the key that was pressed (if one does exist). 
		* @method onKeyDown
		* @param {KeyboardEvent} event.
		* @private
		*/
		private _keyPressed(event:KeyboardEvent) {

			if (this._keys[event.keyCode]) {
				this._keys[event.keyCode].update(event);

			} else {
				this._keys[event.keyCode] = new Kiwi.Input.Key(this, event.keyCode, event);

			}

			if (this._keys[event.keyCode].repeats == 0) this.onKeyDownOnce.dispatch(event.keyCode, this._keys[event.keyCode]);

			this.onKeyDown.dispatch(event.keyCode, this._keys[event.keyCode]);
		}

		/** 
		* Is executed when a key is release/is now up. This then either creates a new Key (if one does not currently exist) for that keycode, 
		* or it updates the key that was released (if one does exist). 
		* @method onKeyUp
		* @param {KeyboardEvent} event.
		* @private
		*/
		private _keyReleased(event:KeyboardEvent) {

			if (this._keys[event.keyCode]) {
				this._keys[event.keyCode].update(event);

			} else {
				this._keys[event.keyCode] = new Kiwi.Input.Key(this, event.keyCode, event);

			}
			this.onKeyUp.dispatch(event.keyCode, this._keys[event.keyCode]);
		}

		/** 
		* Creates a new Key object for a keycode that is specified.
		* Not strictly needed (as one will be created once an event occurs on that keycode) but can be good for setting the game up
		* and choosing whether to prevent that keys any default action.
		* @method addKey
		* @param keycode {Number} The keycode of the key that you want to add. 
		* @param [preventDefault=false] {Boolean} If the default action for that key should be prevented or not when an event fires.
		* @return {Kiwi.Input.Key}
		* @public
		*/
		public addKey(keycode: number, preventDefault:boolean = false): Key {

			var key = new Kiwi.Input.Key(this, keycode);
			key.preventDefault = preventDefault;

			return this._keys[keycode] = key;

		}

		/** 
		* Returns a boolean indicating if a key (that you pass via a keycode) was just pressed or not. 
		* @method justPressed
		* @param keycode {Number} The keycode of the key that you would like to check against.
		* @param [duration=this.justPressedRate] {Number} The duration at which determines if a key was 'just' pressed or not. If not specified defaults to the justPressedRate
		* @public
		*/
		public justPressed(keycode, duration:number=this.justPressedRate):boolean {

			if (this._keys[keycode]) {
				return this._keys[keycode].justPressed(duration);
			} 

			return false;
		}


		/** 
		* Returns a boolean indicating if a key (that you pass via a keycode) was just released or not. 
		* @method justReleased
		* @param keycode {Number} The keycode of the key that you would like to check against.
		* @param [duration=this.justReleasedRate] {Number} The duration at which determines if a key was 'just' released or not. If not specified defaults to the justReleasedRate
		* @public
		*/
		public justReleased(keycode, duration:number=this.justReleasedRate):boolean {

			if (this._keys[keycode]) {
				return this._keys[keycode].justReleased(duration);
			}

			return false;
		}

		/** 
		* Returns a boolean indicating whether a key (that you pass via its keycode) is down or not.
		* @method isDown
		* @param keycode {Number} The keycode of the key that you are checking.
		* @return {boolean}
		* @public
		*/
		public isDown(keycode: number): boolean {

			if (this._keys[keycode]) {
				return this._keys[keycode].isDown;
			} else {
				return false;
			}

		}

		/** 
		* Returns a boolean indicating whether a key (that you pass via its keycode) is up or not.
		* @method isUp
		* @param keycode {Number} The keycode of the key that you are checking.
		* @return {boolean}
		* @public
		*/
		public isUp(keycode: number): boolean {

			if (this._keys[keycode]) {
				return this._keys[keycode].isUp;
			} else {
				return false;
			}

		}

		/**
		* Executes the reset method on every Key that currently exists.
		* @method reset
		* @public
		*/
		public reset() {
			for (var index in this._keys) {
				this._keys[index].reset();
			}
		}

	}

}