+Show TOC
×Hide TOC

Key

Kind of class:	public class
Package:	org.casalib.ui
Inherits from:	RemovableEventDispatcher < EventDispatcher
Version:	10/26/08
Author:	Aaron Clinger
Classpath:	org.casalib.ui.Key
File last modified:	Wednesday, 31 December 2008, 20:18:28

► View source

▼ Hide source

/*
    CASA Lib for ActionScript 3.0
    Copyright (c) 2009, Aaron Clinger & Contributors of CASA Lib
    All rights reserved.
    
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions are met:
    
    - Redistributions of source code must retain the above copyright notice,
      this list of conditions and the following disclaimer.
    
    - Redistributions in binary form must reproduce the above copyright notice,
      this list of conditions and the following disclaimer in the documentation
      and/or other materials provided with the distribution.
    
    - Neither the name of the CASA Lib nor the names of its contributors
      may be used to endorse or promote products derived from this software
      without specific prior written permission.
    
    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
    ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
    LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
    CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
    SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
    INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
    CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
    ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
    POSSIBILITY OF SUCH DAMAGE.
*/
package org.casalib.ui {
    import flash.events.Event;
    import org.casalib.ui.KeyCombo;
    import flash.events.KeyboardEvent;
    import flash.display.Stage;
    import flash.utils.Dictionary;
    import org.casalib.events.KeyComboEvent;
    import org.casalib.events.RemovableEventDispatcher;
    import org.casalib.util.ArrayUtil;
    import org.casalib.util.StageReference;
    
    [Event(name="keyDown", type="flash.events.KeyboardEvent")]
    [Event(name="keyUp", type="flash.events.KeyboardEvent")]
    [Event(name="down", type="org.casalib.events.KeyComboEvent")]
    [Event(name="release", type="org.casalib.events.KeyComboEvent")]
    [Event(name="sequence", type="org.casalib.events.KeyComboEvent")]
    
    /**
        Key class that simplifies listening to global key strokes and adds additional keyboard events. Key enables you to recieve events when multiple keys are {@link KeyComboEvent held/released} and when a {@link KeyComboEvent#SEQUENCE sequence of keys are pressed}.
        
        @author Aaron Clinger
        @version 10/26/08
        @usageNote You must first initialize {@link StageReference} before using this class.
        @example
            <code>
                package {
                    import flash.events.KeyboardEvent;
                    import flash.display.MovieClip;
                    import org.casalib.ui.Key;
                    import org.casalib.ui.KeyCombo;
                    import org.casalib.events.KeyComboEvent;
                    import org.casalib.util.StageReference;
                    
                    
                    public class MyExample extends MovieClip {
                        protected var _asdfCombo:KeyCombo;
                        protected var _casaCombo:KeyCombo;
                        protected var _key:Key;
                        
                        
                        public function MyExample() {
                            super();
                            
                            StageReference.setStage(this.stage);
                            
                            this._key = Key.getInstance();
                            
                            this._asdfCombo = new KeyCombo(new Array(65, 83, 68, 70));
                            this._key.addKeyCombo(this._asdfCombo);
                            
                            this._casaCombo = new KeyCombo(new Array(67, 65, 83, 65));
                            this._key.addKeyCombo(this._casaCombo);
                            
                            this._key.addEventListener(KeyComboEvent.DOWN, this._onComboDown);
                            this._key.addEventListener(KeyComboEvent.RELEASE, this._onComboRelease);
                            this._key.addEventListener(KeyComboEvent.SEQUENCE, this._onComboTyped);
                            this._key.addEventListener(KeyboardEvent.KEY_DOWN, this._onKeyPressed);
                            this._key.addEventListener(KeyboardEvent.KEY_UP, this._onKeyReleased);
                        }
                        
                        protected function _onComboDown(e:KeyComboEvent):void {
                            if (this._asdfCombo.equals(e.keyCombo)) {
                                trace("User is holding down keys a-s-d-f.");
                            }
                        }
                        
                        protected function _onComboRelease(e:KeyComboEvent):void {
                            if (this._asdfCombo.equals(e.keyCombo)) {
                                trace("User no longer holding down keys a-s-d-f.");
                            }
                        }
                        
                        protected function _onComboTyped(e:KeyComboEvent):void {
                            if (this._casaCombo.equals(e.keyCombo)) {
                                trace("User typed casa.");
                            }
                        }
                        
                        protected function _onKeyPressed(e:KeyboardEvent):void {
                            trace("User pressed key with code: " + e.keyCode + ".");
                        }
                        
                        protected function _onKeyReleased(e:KeyboardEvent):void {
                            trace("User released key with code: " + e.keyCode + ".");
                        }
                    }
                }
            </code>
    */
    public class Key extends RemovableEventDispatcher {
        protected static var _instance:Key;
        protected var _keysDown:Dictionary;
        protected var _keysTyped:Array;
        protected var _combosDown:Array;
        protected var _combinations:Array;
        protected var _longestCombo:uint;
        
        
        /**
            @return The Key instance.
            @usageNote You must first initialize {@link StageReference} before using this class.
        */
        public static function getInstance():Key {
            if (Key._instance == null)
                Key._instance = new Key(new SingletonEnforcer());
            
            return Key._instance;
        }
        
        /**
            @exclude
        */
        public function Key(singletonEnforcer:SingletonEnforcer) {
            var stage:Stage = StageReference.getStage();
            
            stage.addEventListener(KeyboardEvent.KEY_DOWN, this._onKeyDown);
            stage.addEventListener(KeyboardEvent.KEY_UP, this._onKeyUp);
            stage.addEventListener(Event.DEACTIVATE, this._onDeactivate);
            
            this._keysDown     = new Dictionary();
            this._keysTyped    = new Array();
            this._combosDown   = new Array();
            this._combinations = new Array();
            this._longestCombo = 0;
        }
        
        /**
            Determines if is key is down.
            
            @param keyCode: The key code value assigned to a specific key or a Keyboard class constant associated with the key.
            @return Returns {@code true} if key is currently pressed; otherwise {@code false}.
        */
        public function isDown(keyCode:uint):Boolean {
            return this._keysDown[keyCode];
        }
        
        /**
            Sets a key combination to trigger a {@link KeyComboEvent}.
            
            @param keyCombo: A defined {@link KeyCombo} object.
        */
        public function addKeyCombo(keyCombo:KeyCombo):void {
            var l:uint = this._combinations.length;
            while (l--)
                if (this._combinations[l].equals(keyCombo))
                    return;
            
            this._longestCombo = Math.max(this._longestCombo, keyCombo.keyCodes.length);
            
            this._combinations.push(keyCombo);
        }
        
        /**
            Removes a key combination from triggering a {@link KeyComboEvent}.
            
            @param keyCombo: A defined {@link KeyCombo} object.
        */
        public function removeKeyCombo(keyCombo:KeyCombo):void {
            var i:int  = -1;
            var l:uint = this._combinations.length;
            
            while (l--) {
                if (this._combinations[l].equals(keyCombo)) {
                    i = int(l);
                    break;
                }
            }
            
            if (i == -1)
                return;
            
            this._combinations.splice(i, 1);
            
            if (keyCombo.keyCodes.length == this._longestCombo) {
                var size:uint = 0;
                
                l = this._combinations.length;
                while (l--)
                    size = Math.max(size, this._combinations[l].keyCodes.length);
                
                this._longestCombo = size;
            }
        }
        
        /**
            @throws Error if called. Cannot destroy a singleton.
        */
        override public function destroy():void {
            throw new Error('Cannot destroy a singleton.');
        }
        
        /**
            @sends KeyboardEvent#KEY_DOWN - Dispatched when the user presses a key.
        */
        protected function _onKeyDown(e:KeyboardEvent):void {
            var alreadyDown:Boolean   = this._keysDown[e.keyCode];
            this._keysDown[e.keyCode] = true;
            
            this._keysTyped.push(e.keyCode);
            
            if (this._keysTyped.length > this._longestCombo)
                this._keysTyped.splice(0, 1);
            
            var l:uint = this._combinations.length;
            while (l--) {
                this._checkedTypedKeys(this._combinations[l]);
                
                if (!alreadyDown)
                    this._checkDownKeys(this._combinations[l]);
            }
            
            this.dispatchEvent(e.clone());
        }
        
        /**
            @sends KeyboardEvent#KEY_UP - Dispatched when the user releases a key.
            @sends KeyComboEvent#RELEASE - Dispatched whens all keys in an added {@link KeyCombo} are no longer being held together at once.
        */
        protected function _onKeyUp(e:KeyboardEvent):void {
            var l:uint = this._combosDown.length;
            while (l--) {
                if (this._combosDown[l].keyCodes.indexOf(e.keyCode) != -1) {
                    var keyComboHold:KeyComboEvent = new KeyComboEvent(KeyComboEvent.RELEASE);
                    keyComboHold.keyCombo = this._combosDown[l];
                    
                    this._combosDown.splice(l, 1);
                    
                    this.dispatchEvent(keyComboHold);
                }
            }
            
            delete this._keysDown[e.keyCode];
            
            this.dispatchEvent(e.clone());
        }
        
        protected function _onDeactivate(e:Event):void {
            var l:uint = this._combosDown.length;
            while (l--) {
                var keyComboHold:KeyComboEvent = new KeyComboEvent(KeyComboEvent.RELEASE);
                keyComboHold.keyCombo = this._combosDown[l];
                
                this.dispatchEvent(keyComboHold);
            }
            
            this._combosDown = new Array();
            this._keysDown   = new Dictionary();
        }
        
        /**
            @sends KeyComboEvent#SEQUENCE - Dispatched when all keys in an added {@link KeyCombo} are typed in order.
        */
        protected function _checkedTypedKeys(keyCombo:KeyCombo):void {
            if (ArrayUtil.equals(keyCombo.keyCodes, this._keysTyped.slice(-keyCombo.keyCodes.length))) {
                var keyComboSeq:KeyComboEvent = new KeyComboEvent(KeyComboEvent.SEQUENCE);
                keyComboSeq.keyCombo = keyCombo;
                
                this.dispatchEvent(keyComboSeq);
            }
        }
        
        /**
            @sends KeyComboEvent#DOWN - Dispatched when all keys in an added {@link KeyCombo} are held down together at once.
        */
        protected function _checkDownKeys(keyCombo:KeyCombo):void {
            var uniqueCombo:Array = ArrayUtil.removeDuplicates(keyCombo.keyCodes);
            var i:uint            = uniqueCombo.length;
            
            while (i--)
                if (!this.isDown(uniqueCombo[i]))
                    return;
            
            var keyComboDown:KeyComboEvent = new KeyComboEvent(KeyComboEvent.DOWN);
            keyComboDown.keyCombo = keyCombo;
            
            this._combosDown.push(keyCombo);
            
            this.dispatchEvent(keyComboDown);
        }
    }
}

class SingletonEnforcer {}

Key class that simplifies listening to global key strokes and adds additional keyboard events. Key enables you to recieve events when multiple keys are held/released and when a sequence of keys are pressed.

Usage note:

You must first initialize StageReference before using this class.

Example:

package {
    import flash.events.KeyboardEvent;
    import flash.display.MovieClip;
    import org.casalib.ui.Key;
    import org.casalib.ui.KeyCombo;
    import org.casalib.events.KeyComboEvent;
    import org.casalib.util.StageReference;


    public class MyExample extends MovieClip {
        protected var _asdfCombo:KeyCombo;
        protected var _casaCombo:KeyCombo;
        protected var _key:Key;


        public function MyExample() {
            super();

            StageReference.setStage(this.stage);

            this._key = Key.getInstance();

            this._asdfCombo = new KeyCombo(new Array(65, 83, 68, 70));
            this._key.addKeyCombo(this._asdfCombo);

            this._casaCombo = new KeyCombo(new Array(67, 65, 83, 65));
            this._key.addKeyCombo(this._casaCombo);

            this._key.addEventListener(KeyComboEvent.DOWN, this._onComboDown);
            this._key.addEventListener(KeyComboEvent.RELEASE, this._onComboRelease);
            this._key.addEventListener(KeyComboEvent.SEQUENCE, this._onComboTyped);
            this._key.addEventListener(KeyboardEvent.KEY_DOWN, this._onKeyPressed);
            this._key.addEventListener(KeyboardEvent.KEY_UP, this._onKeyReleased);
        }

        protected function _onComboDown(e:KeyComboEvent):void {
            if (this._asdfCombo.equals(e.keyCombo)) {
                trace("User is holding down keys a-s-d-f.");
            }
        }

        protected function _onComboRelease(e:KeyComboEvent):void {
            if (this._asdfCombo.equals(e.keyCombo)) {
                trace("User no longer holding down keys a-s-d-f.");
            }
        }

        protected function _onComboTyped(e:KeyComboEvent):void {
            if (this._casaCombo.equals(e.keyCombo)) {
                trace("User typed casa.");
            }
        }

        protected function _onKeyPressed(e:KeyboardEvent):void {
            trace("User pressed key with code: " + e.keyCode + ".");
        }

        protected function _onKeyReleased(e:KeyboardEvent):void {
            trace("User released key with code: " + e.keyCode + ".");
        }
    }
}

Events broadcasted to listeners:

KeyboardEvent with type: KEY_DOWN - Dispatched when the user presses a key.
KeyboardEvent with type: KEY_UP - Dispatched when the user releases a key.
KeyComboEvent with type: RELEASE - Dispatched whens all keys in an added held/released are no longer being held together at once.
KeyComboEvent with type: SEQUENCE - Dispatched when all keys in an added held/released are typed in order.
KeyComboEvent with type: DOWN - Dispatched when all keys in an added held/released are held down together at once.

Summary

Instance properties

Instance properties inherited from RemovableEventDispatcher

_isDestroyed _listenerManager destroyed

Class methods

getInstance : Key

Instance methods

isDown (keyCode:uint) : Boolean
- Determines if is key is down.
addKeyCombo (keyCombo:KeyCombo) : void
- Sets a key combination to trigger a KeyComboEvent.
removeKeyCombo (keyCombo:KeyCombo) : void
- Removes a key combination from triggering a KeyComboEvent.
destroy : void

Instance methods inherited from RemovableEventDispatcher

addEventListener destroy dispatchEvent removeEventListener removeEventListeners removeEventsForListener removeEventsForType

Class methods

getInstance

public static function getInstance (

) : Key

Returns:

The Key instance.

Usage note:

You must first initialize StageReference before using this class.

Instance methods

addKeyCombo

public function addKeyCombo (

keyCombo:KeyCombo) : void

Sets a key combination to trigger a KeyComboEvent.

Parameters:

keyCombo:

A defined KeyCombo object.

destroy

override public function destroy (

) : void

Throws:

Error if called. Cannot destroy a singleton.

Overrides:

RemovableEventDispatcher.destroy

isDown

public function isDown (

keyCode:uint) : Boolean

Determines if is key is down.

Parameters:

keyCode:

The key code value assigned to a specific key or a Keyboard class constant associated with the key.

Returns:

Returns true if key is currently pressed; otherwise false.

removeKeyCombo

public function removeKeyCombo (

keyCombo:KeyCombo) : void

Removes a key combination from triggering a KeyComboEvent.

Parameters:

keyCombo:

A defined KeyCombo object.