# Yahoo! UI Library

### Container

Yahoo! UI Library > container > KeyListener.js (source view)

    /*
    Copyright (c) 2006, Yahoo! Inc. All rights reserved.
    Code licensed under the BSD License:
    http://developer.yahoo.net/yui/license.txt
    Version 0.12
    */

    /**
    * KeyListener is a utility that provides an easy interface for listening for keydown/keyup events fired against DOM elements.
    * @namespace YAHOO.util
    * @class KeyListener
    * @constructor
    * @param {HTMLElement}	attachTo	The element or element ID to which the key event should be attached
    * @param {String}	attachTo	The element or element ID to which the key event should be attached
    * @param {Object}	keyData		The object literal representing the key(s) to detect. Possible attributes are shift(boolean), alt(boolean), ctrl(boolean) and keys(either an int or an array of ints representing keycodes).
    * @param {Function}	handler		The CustomEvent handler to fire when the key event is detected
    * @param {Object}	handler		An object literal representing the handler.
    * @param {String}	event		Optional. The event (keydown or keyup) to listen for. Defaults automatically to keydown.
    */
    YAHOO.util.KeyListener = function(attachTo, keyData, handler, event) {
    	if (! event) {
    		event = YAHOO.util.KeyListener.KEYDOWN;
    	}

    	/**
    	* The CustomEvent fired internally when a key is pressed
    	* @event keyEvent
    	* @private
    	* @param {Object}	keyData		The object literal representing the key(s) to detect. Possible attributes are shift(boolean), alt(boolean), ctrl(boolean) and keys(either an int or an array of ints representing keycodes).
    	*/
    	var keyEvent = new YAHOO.util.CustomEvent("keyPressed");

    	/**
    	* The CustomEvent fired when the KeyListener is enabled via the enable() function
    	* @event enabledEvent
    	* @param {Object}	keyData		The object literal representing the key(s) to detect. Possible attributes are shift(boolean), alt(boolean), ctrl(boolean) and keys(either an int or an array of ints representing keycodes).
    	*/
    	this.enabledEvent = new YAHOO.util.CustomEvent("enabled");

    	/**
    	* The CustomEvent fired when the KeyListener is disabled via the disable() function
    	* @event disabledEvent
    	* @param {Object}	keyData		The object literal representing the key(s) to detect. Possible attributes are shift(boolean), alt(boolean), ctrl(boolean) and keys(either an int or an array of ints representing keycodes).
    	*/
    	this.disabledEvent = new YAHOO.util.CustomEvent("disabled");

    	if (typeof attachTo == 'string') {
    		attachTo = document.getElementById(attachTo);
    	}

    	if (typeof handler == 'function') {
    		keyEvent.subscribe(handler);
    	} else {
    		keyEvent.subscribe(handler.fn, handler.scope, handler.correctScope);
    	}

    	/**
    	* Handles the key event when a key is pressed.
    	* @method handleKeyPress
    	* @param {DOMEvent} e	The keypress DOM event
    	* @param {Object}	obj	The DOM event scope object
    	* @private
    	*/
    	function handleKeyPress(e, obj) {
    		if (! keyData.shift) {
    			keyData.shift = false;
    		}
    		if (! keyData.alt) {
    			keyData.alt = false;
    		}
    		if (! keyData.ctrl) {
    			keyData.ctrl = false;
    		}

    		// check held down modifying keys first
    		if (e.shiftKey == keyData.shift &&
    			e.altKey   == keyData.alt &&
    			e.ctrlKey  == keyData.ctrl) { // if we pass this, all modifiers match

    			var dataItem;
    			var keyPressed;

    			if (keyData.keys instanceof Array) {
    				for (var i=0;i<keyData.keys.length;i++) {
    					dataItem = keyData.keys[i];

    					if (dataItem == e.charCode ) {
    						keyEvent.fire(e.charCode, e);
    						break;
    					} else if (dataItem == e.keyCode) {
    						keyEvent.fire(e.keyCode, e);
    						break;
    					}
    				}
    			} else {
    				dataItem = keyData.keys;

    				if (dataItem == e.charCode ) {
    					keyEvent.fire(e.charCode, e);
    				} else if (dataItem == e.keyCode) {
    					keyEvent.fire(e.keyCode, e);
    				}
    			}
    		}
    	}

    	/**
    	* Enables the KeyListener by attaching the DOM event listeners to the target DOM element
    	* @method enable
    	*/
    	this.enable = function() {
    		if (! this.enabled) {
    			YAHOO.util.Event.addListener(attachTo, event, handleKeyPress);
    			this.enabledEvent.fire(keyData);
    		}
    		/**
    		* Boolean indicating the enabled/disabled state of the Tooltip
    		* @property enabled
    		* @type Boolean
    		*/
    		this.enabled = true;
    	};

    	/**
    	* Disables the KeyListener by removing the DOM event listeners from the target DOM element
    	* @method disable
    	*/
    	this.disable = function() {
    		if (this.enabled) {
    			YAHOO.util.Event.removeListener(attachTo, event, handleKeyPress);
    			this.disabledEvent.fire(keyData);
    		}
    		this.enabled = false;
    	};

    	/**
    	* Returns a String representation of the object.
    	* @method toString
    	* @return {String}	The string representation of the KeyListener
    	*/
    	this.toString = function() {
    		return "KeyListener [" + keyData.keys + "] " + attachTo.tagName + (attachTo.id ? "[" + attachTo.id + "]" : "");
    	};

    };

    /**
    * Constant representing the DOM "keydown" event.
    * @property YAHOO.util.KeyListener.KEYDOWN
    * @static
    * @final
    * @type String
    */
    YAHOO.util.KeyListener.KEYDOWN = "keydown";

    /**
    * Constant representing the DOM "keyup" event.
    * @property YAHOO.util.KeyListener.KEYUP
    * @static
    * @final
    * @type String
    */
    YAHOO.util.KeyListener.KEYUP = "keyup";

Copyright © 2006 Yahoo! Inc. All rights reserved.