Summary

Global screen key shortcut.

/**
  * @fileoverview Global screen key shortcut.
  */

/**
  * SKeyShortcut is part of the <a href='http://sourceforge.net/projects/STools/'>STools</a>.<br/>
  * <br/>
  * Copyright 2005 STools<br/>
  *<br/>
  * Licensed under the Apache License, Version 2.0 (the "License");<br/>
  * you may not use this file except in compliance with the License.<br/>
  * You may obtain a copy of the License at<br/>
  * <br/>
  *     http://www.apache.org/licenses/LICENSE-2.0<br/>
  * <br/>
  * Unless required by applicable law or agreed to in writing, software<br/>
  * distributed under the License is distributed on an "AS IS" BASIS,<br/>
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.<br/>
  * See the License for the specific language governing permissions and<br/>
  * limitations under the License.<br/>
  * <br/>
  * <br/>
  * SKeyShortcut is a class that creates an association between a key (or an association of key) and a javascript function.<br/>
  * <br/>
  * Basic usage :<br/>
  * This class is usefull to get the user pressed 'Return' to close a dialog box.<br/>
  * This class is used in a menu to associate a shortcut to an item.
  * @author deltapositive (<a href='mailto:deltapositive@yahoo.fr'>deltapositive@yahoo.fr</a>)
  * @version 1.0
  * @constructor
  */
function SKeyShortcut() 
{
	SKeyShortcut._startEventHandling();

	this._instance = SKeyShortcut._instance++;
	SKeyShortcut._instances[this._instance] = this;
	
	this._params = {};
	this._event = {};
}

/**
  * The instance of document where tooltip is available.
  * @private
  * @type Document
  */
SKeyShortcut._document = document;

/** 
  * Number of instances created.<br/>
  * Allow each instance to have a unique id.
  * @private 
  * @type int
  */
SKeyShortcut._instance = 0;

/** 
  * All shortcut instances.<br/>
  * The key is the number of instance.<br/>
  * @private 
  * @type Map<int, SKeyShortcut>
  */
SKeyShortcut._instances = {};

/**
  * The number of instance.
  * @private
  * @type int
  */
SKeyShortcut.prototype._instance = 0;

/**
  * This constant defines the CTRL key prefix in a key sequence.
  * @type string
  */
SKeyShortcut.CTRL_KEY_MODIFIER = "Ctrl+";

/**
  * This constant defines the ALT key prefix in a key sequence.
  * @type string
  */
  
SKeyShortcut.ALT_KEY_MODIFIER = "Alt+";
/**
  * This constant defines the SHIFT key prefix in a key sequence.
  * @type string
  */
SKeyShortcut.SHIFT_KEY_MODIFIER = "Shift+";

/**
  * This constant defines the ESCAPE key code in a key sequence.
  * @type string
  */
SKeyShortcut.ESCAPE_KEY = "Esc";

/**
  * This constant defines the RETURN key code in a key sequence.
  * @type string
  */
SKeyShortcut.RETURN_KEY = "Return";

/**
  * This constant defines the prefix of the functions key (F1 to F12) code in a key sequence.
  * @type string
  */
SKeyShortcut.FUNCTION_PREFIX_KEY = "F";

/**
  * The key sequence bind to the shortcut.
  * @private
  * @type string
  */
SKeyShortcut.prototype._keySequence = null;

/**
  * The association "event: handler".
  * @private
  * @type map<string, function>
  */
SKeyShortcut.prototype._event = null;

/**
  * The association "parameterName: parameterValue".
  * @private
  * @type map<string, Object>
  */
SKeyShortcut.prototype._params = null;

/**
  * Set the key sequence for the shortcut<br/>
  * For example: SKeyShortcut.FUNCTION_PREFIX_KEY + '3' assign a shortcut for the F3 key<br/>
  * A sequence is defined by zero, one or more modifier (from Ctrl, Alt and Shift) and a key.
  * @param {string} sequence The sequence to bind.
  */
SKeyShortcut.prototype.setKeySequence = function (sequence)
{
	this._keySequence = sequence;
}

/**
  * Get a parameter's value<br/>
  * @param {string} name The name of the parameter to get.
  * @return The value of the parameter
  * @type Object
  */
SKeyShortcut.prototype.getParameter = function (name)
{
	return this._params[name];
}

/**
  * Set a parameter<br/>
  * @param {string} name The name of the parameter to set.
  * @param {Object} value The value of the parameter.
  */
SKeyShortcut.prototype.setParameter = function (name, value)
{
	this._params[name] = value;
}

/**
  * Set a listener for an event.
  * @param {string} event The name of the event to listen among:
  * <ul>
  * <li>"onkeydown" <code>boolean function (skeyshortcut, event)</code>,</li>
  * <li>"onkeyup" <code>boolean function (skeyshortcut, event)</code>,</li>
  * </ul>
  * All of the three functions may return false to stop event propagation.
  * @param {function} listener The function to call if corresponding event is fired.
  */
SKeyShortcut.prototype.setEventListener = function (event, listener)
{
	this._event[event] = listener;
}

/**
  * Destroy the internal structures.<br/>
  * Do not call, if you want to use after.
  * @private
  */
SKeyShortcut.prototype.dispose = function ()
{
	this._event = {};
	
	SKeyShortcut._instances[this._instance] = null;
}

/**
  * Determine if event handling has been started
  * @type boolean
  * @private
  */
SKeyShortcut._eventHandlingStarted = false;

/**
  * Start the event handling.
  * @private
  */
SKeyShortcut._startEventHandling = function ()
{
	if (SKeyShortcut._eventHandlingStarted)
		return;
	SKeyShortcut._eventHandlingStarted = true;
		
	if (!SUtilities.IS_IE)
	{
		SKeyShortcut._document.captureEvents(Event.KEYDOWN); // Defines what events to capture for Navigator
		SKeyShortcut._document.captureEvents(Event.KEYUP); // Defines what events to capture for Navigator
	}

	SUtilities.attachEvent(SKeyShortcut._document, "keydown", SKeyShortcut._onKeyDown);
	SUtilities.attachEvent(SKeyShortcut._document, "keyup", SKeyShortcut._onKeyUp);
}

/**
  * The method read from a key event, the key sequence.
  * @param {event} event The event object given by the navigator
  * @return The key sequence read from the event. For example: 'Ctrl+F1'. Can be null if sequence is not accepted (i.e. Ctrl alone)
  * @type string
  * @private
  */
SKeyShortcut._buildEventSequence = function(event)
{
	var independantEvent = SUtilities.IS_IE ? SKeyShortcut._document.parentWindow.event : event;
	var key = independantEvent.keyCode;
	
	if (key != 13 && key != 27 && (key < 65 || key > 90) && (key < 112 || key > 123))
		return null;
	
	var sequence = "";

	if (independantEvent.ctrlKey)
		sequence += SKeyShortcut.CTRL_KEY_MODIFIER;
	if (independantEvent.altKey)
		sequence += SKeyShortcut.ALT_KEY_MODIFIER;
	if (independantEvent.shiftKey)
		sequence += SKeyShortcut.SHIFT_KEY_MODIFIER;
		
	if (key >= 65 && key <= 90)
		sequence += String.fromCharCode(key).toUpperCase();
	else if (key == 13)
		sequence += SKeyShortcut.RETURN_KEY;
	else if (key == 27)
		sequence += SKeyShortcut.ESCAPE_KEY;
	else if (key >= 112 && key <= 123)
		sequence += SKeyShortcut.FUNCTION_PREFIX_KEY + (key - 111);

	return sequence;
}

/**
  * The method is call when a key is down
  * @param {event} event The event object given by the navigator
  * @private
  */
SKeyShortcut._onKeyDown = function(event)
{
	SKeyShortcut._onKeyEvent(event, "onkeydown");
}

/**
  * The method is call when a key is up
  * @param {event} event The event object given by the navigator
  * @private
  */
SKeyShortcut._onKeyUp = function(event)
{
	SKeyShortcut._onKeyEvent(event, "onkeyup");
}

/**
  * The method is call when a event occured on a key
  * @param {event} event The event object given by the navigator
  * @param {string} eventName The name of the event that happened (among onkeydown, onkeyup).
  * @private
  */
SKeyShortcut._onKeyEvent = function(event, eventName)
{
	var sequence = SKeyShortcut._buildEventSequence(event);
	if (sequence == null)
		return;

	for (var skeyshortcutIndex in SKeyShortcut._instances)
	{
		var skeyshortcut = SKeyShortcut._instances[skeyshortcutIndex];
		if (skeyshortcut != null && skeyshortcut._keySequence != null && skeyshortcut._keySequence.toLowerCase() == sequence.toLowerCase() && typeof skeyshortcut._event[eventName] == "function")
		{
			var result = skeyshortcut._event[eventName](skeyshortcut, event);

			if (result != false)
			{
				if (SUtilities.IS_IE) {
					SKeyShortcut._document.parentWindow.event.cancelBubble = true;
					SKeyShortcut._document.parentWindow.event.returnValue = false;
				} else {
					event.preventDefault();
					event.stopPropagation();
				}
			}
		}
	}
}

// Test for SUtilities presence
try 
{
	SUtilities;
} 
catch (e)
{
	alert("SKeyShortcut needs SUtilities to be imported.");
}