X-Git-Url: http://git.ithinksw.org/extjs.git/blobdiff_plain/6a7e4474cba9d8be4b2ec445e10f1691f7277c50..7a654f8d43fdb43d78b63d90528bed6e86b608cc:/docs/source/KeyMap.html diff --git a/docs/source/KeyMap.html b/docs/source/KeyMap.html index 5478d99e..93c9d07d 100644 --- a/docs/source/KeyMap.html +++ b/docs/source/KeyMap.html @@ -1,100 +1,87 @@ - - - - The source code - - - - -
/*!
- * Ext JS Library 3.2.0
- * Copyright(c) 2006-2010 Ext JS, Inc.
- * licensing@extjs.com
- * http://www.extjs.com/license
- */
-
/** - * @class Ext.KeyMap +Sencha Documentation Project
/**
+ * @class Ext.util.KeyMap
  * Handles mapping keys to actions for an element. One key map can be used for multiple actions.
  * The constructor accepts the same config object as defined by {@link #addBinding}.
  * If you bind a callback function to a KeyMap, anytime the KeyMap handles an expected key
  * combination it will call the function with this signature (if the match is a multi-key
  * combination the callback will still be called only once): (String key, Ext.EventObject e)
- * A KeyMap can also handle a string representation of keys.
+ * A KeyMap can also handle a string representation of keys.<br /> * Usage: -

+ <pre><code>
 // map one key by key code
-var map = new Ext.KeyMap("my-element", {
+var map = new Ext.util.KeyMap("my-element", {
     key: 13, // or Ext.EventObject.ENTER
     fn: myHandler,
     scope: myObject
 });
 
 // map multiple keys to one action by string
-var map = new Ext.KeyMap("my-element", {
-    key: "a\r\n\t",
+var map = new Ext.util.KeyMap("my-element", {
+    key: "a\r\n\t",
     fn: myHandler,
     scope: myObject
 });
 
 // map multiple keys to multiple actions by strings and array of codes
-var map = new Ext.KeyMap("my-element", [
+var map = new Ext.util.KeyMap("my-element", [
     {
         key: [10,13],
-        fn: function(){ alert("Return was pressed"); }
+        fn: function(){ alert("Return was pressed"); }
     }, {
-        key: "abc",
+        key: "abc",
         fn: function(){ alert('a, b or c was pressed'); }
     }, {
-        key: "\t",
+        key: "\t",
         ctrl:true,
         shift:true,
         fn: function(){ alert('Control + shift + tab was pressed.'); }
     }
 ]);
-
- * Note: A KeyMap starts enabled +</code></pre> + * <b>Note: A KeyMap starts enabled</b> * @constructor * @param {Mixed} el The element to bind to - * @param {Object} config The config (see {@link #addBinding}) - * @param {String} eventName (optional) The event to bind to (defaults to "keydown") + * @param {Object} binding The binding (see {@link #addBinding}) + * @param {String} eventName (optional) The event to bind to (defaults to "keydown") */ -Ext.KeyMap = function(el, config, eventName){ - this.el = Ext.get(el); - this.eventName = eventName || "keydown"; - this.bindings = []; - if(config){ - this.addBinding(config); - } - this.enable(); -}; - -Ext.KeyMap.prototype = { -
/** - * True to stop the event from bubbling and prevent the default browser action if the - * key was handled by the KeyMap (defaults to false) - * @type Boolean - */ - stopEvent : false, +Ext.define('Ext.util.KeyMap', { + alternateClassName: 'Ext.KeyMap', + + constructor: function(el, binding, eventName){ + var me = this; + + Ext.apply(me, { + el: Ext.get(el), + eventName: eventName || me.eventName, + bindings: [] + }); + if (binding) { + me.addBinding(binding); + } + me.enable(); + }, + + eventName: 'keydown', -
/** - * Add a new binding to this KeyMap. The following config object properties are supported: - *
-Property    Type             Description
-----------  ---------------  ----------------------------------------------------------------------
-key         String/Array     A single keycode or an array of keycodes to handle
-shift       Boolean          True to handle key only when shift is pressed, False to handle the key only when shift is not pressed (defaults to undefined)
-ctrl        Boolean          True to handle key only when ctrl is pressed, False to handle the key only when ctrl is not pressed (defaults to undefined)
-alt         Boolean          True to handle key only when alt is pressed, False to handle the key only when alt is not pressed (defaults to undefined)
-handler     Function         The function to call when KeyMap finds the expected key combination
-fn          Function         Alias of handler (for backwards-compatibility)
-scope       Object           The scope of the callback function
-stopEvent   Boolean          True to stop the event from bubbling and prevent the default browser action if the key was handled by the KeyMap (defaults to false)
-
+ /** + * Add a new binding to this KeyMap. The following config object properties are supported: + * <pre> +Property Type Description +---------- --------------- ---------------------------------------------------------------------- +key String/Array A single keycode or an array of keycodes to handle +shift Boolean True to handle key only when shift is pressed, False to handle the key only when shift is not pressed (defaults to undefined) +ctrl Boolean True to handle key only when ctrl is pressed, False to handle the key only when ctrl is not pressed (defaults to undefined) +alt Boolean True to handle key only when alt is pressed, False to handle the key only when alt is not pressed (defaults to undefined) +handler Function The function to call when KeyMap finds the expected key combination +fn Function Alias of handler (for backwards-compatibility) +scope Object The scope of the callback function +defaultEventAction String A default action to apply to the event. Possible values are: stopEvent, stopPropagation, preventDefault. If no value is set no action is performed. +</pre> * * Usage: - *

+     * <pre><code>
 // Create a KeyMap
-var map = new Ext.KeyMap(document, {
+var map = new Ext.util.KeyMap(document, {
     key: Ext.EventObject.ENTER,
     fn: handleKey,
     scope: this
@@ -107,89 +94,152 @@ map.addBinding({
     fn: handleKey,
     scope: this
 });
-
- * @param {Object/Array} config A single KeyMap config or an array of configs +</code></pre> + * @param {Object/Array} binding A single KeyMap config or an array of configs */ - addBinding : function(config){ - if(Ext.isArray(config)){ - Ext.each(config, function(c){ - this.addBinding(c); - }, this); + addBinding : function(binding){ + if (Ext.isArray(binding)) { + Ext.each(binding, this.addBinding, this); return; } - var keyCode = config.key, - fn = config.fn || config.handler, - scope = config.scope; - - if (config.stopEvent) { - this.stopEvent = config.stopEvent; - } + + var keyCode = binding.key, + processed = false, + key, + keys, + keyString, + i, + len; - if(typeof keyCode == "string"){ - var ks = []; - var keyString = keyCode.toUpperCase(); - for(var j = 0, len = keyString.length; j < len; j++){ - ks.push(keyString.charCodeAt(j)); + if (Ext.isString(keyCode)) { + keys = []; + keyString = keyCode.toLowerCase(); + + for (i = 0, len = keyString.length; i < len; ++i){ + keys.push(keyString.charCodeAt(i)); } - keyCode = ks; + keyCode = keys; + processed = true; } - var keyArray = Ext.isArray(keyCode); - var handler = function(e){ - if(this.checkModifiers(config, e)){ - var k = e.getKey(); - if(keyArray){ - for(var i = 0, len = keyCode.length; i < len; i++){ - if(keyCode[i] == k){ - if(this.stopEvent){ - e.stopEvent(); - } - fn.call(scope || window, k, e); - return; - } - } - }else{ - if(k == keyCode){ - if(this.stopEvent){ - e.stopEvent(); - } - fn.call(scope || window, k, e); + if (!Ext.isArray(keyCode)) { + keyCode = [keyCode]; + } + + if (!processed) { + for (i = 0, len = keyCode.length; i < len; ++i) { + key = keyCode[i]; + if (Ext.isString(key)) { + keyCode[i] = key.toLowerCase().charCodeAt(0); + } + } + } + + this.bindings.push(Ext.apply({ + keyCode: keyCode + }, binding)); + }, + + /** + * Process any keydown events on the element + * @private + * @param {Ext.EventObject} event + */ + handleKeyDown: function(event) { + if (this.enabled) { //just in case + var bindings = this.bindings, + i = 0, + len = bindings.length; + + event = this.processEvent(event); + for(; i < len; ++i){ + this.processBinding(bindings[i], event); + } + } + }, + + /** + * Ugly hack to allow this class to be tested. Currently WebKit gives + * no way to raise a key event properly with both + * a) A keycode + * b) The alt/ctrl/shift modifiers + * So we have to simulate them here. Yuk! + * This is a stub method intended to be overridden by tests. + * More info: https://bugs.webkit.org/show_bug.cgi?id=16735 + * @private + */ + processEvent: function(event){ + return event; + }, + + /** + * Process a particular binding and fire the handler if necessary. + * @private + * @param {Object} binding The binding information + * @param {Ext.EventObject} event + */ + processBinding: function(binding, event){ + if (this.checkModifiers(binding, event)) { + var key = event.getKey(), + handler = binding.fn || binding.handler, + scope = binding.scope || this, + keyCode = binding.keyCode, + defaultEventAction = binding.defaultEventAction, + i, + len, + keydownEvent = new Ext.EventObjectImpl(event); + + + for (i = 0, len = keyCode.length; i < len; ++i) { + if (key === keyCode[i]) { + if (handler.call(scope, key, event) !== true && defaultEventAction) { + keydownEvent[defaultEventAction](); } + break; } } - }; - this.bindings.push(handler); - }, + } + }, - // private - checkModifiers: function(config, e){ - var val, key, keys = ['shift', 'ctrl', 'alt']; - for (var i = 0, len = keys.length; i < len; ++i){ + /** + * Check if the modifiers on the event match those on the binding + * @private + * @param {Object} binding + * @param {Ext.EventObject} event + * @return {Boolean} True if the event matches the binding + */ + checkModifiers: function(binding, e){ + var keys = ['shift', 'ctrl', 'alt'], + i = 0, + len = keys.length, + val, key; + + for (; i < len; ++i){ key = keys[i]; - val = config[key]; - if(!(val === undefined || (val === e[key + 'Key']))){ + val = binding[key]; + if (!(val === undefined || (val === e[key + 'Key']))) { return false; } } return true; }, -
/** - * Shorthand for adding a single key listener + /** + * Shorthand for adding a single key listener * @param {Number/Array/Object} key Either the numeric key code, array of key codes or an object with the * following options: * {key: (number or array), shift: (true/false), ctrl: (true/false), alt: (true/false)} * @param {Function} fn The function to call - * @param {Object} scope (optional) The scope (this reference) in which the function is executed. Defaults to the browser window. + * @param {Object} scope (optional) The scope (<code>this</code> reference) in which the function is executed. Defaults to the browser window. */ - on : function(key, fn, scope){ + on: function(key, fn, scope) { var keyCode, shift, ctrl, alt; - if(typeof key == "object" && !Ext.isArray(key)){ + if (Ext.isObject(key) && !Ext.isArray(key)) { keyCode = key.key; shift = key.shift; ctrl = key.ctrl; alt = key.alt; - }else{ + } else { keyCode = key; } this.addBinding({ @@ -202,51 +252,58 @@ map.addBinding({ }); }, - // private - handleKeyDown : function(e){ - if(this.enabled){ //just in case - var b = this.bindings; - for(var i = 0, len = b.length; i < len; i++){ - b[i].call(this, e); - } - } - }, + /** + * Returns true if this KeyMap is enabled + * @return {Boolean} + */ + isEnabled : function(){ + return this.enabled; + }, -
/** - * Returns true if this KeyMap is enabled - * @return {Boolean} - */ - isEnabled : function(){ - return this.enabled; - }, + /** + * Enables this KeyMap + */ + enable: function(){ + if(!this.enabled){ + this.el.on(this.eventName, this.handleKeyDown, this); + this.enabled = true; + } + }, -
/** - * Enables this KeyMap - */ - enable: function(){ - if(!this.enabled){ - this.el.on(this.eventName, this.handleKeyDown, this); - this.enabled = true; - } - }, + /** + * Disable this KeyMap + */ + disable: function(){ + if(this.enabled){ + this.el.removeListener(this.eventName, this.handleKeyDown, this); + this.enabled = false; + } + }, -
/** - * Disable this KeyMap - */ - disable: function(){ - if(this.enabled){ - this.el.removeListener(this.eventName, this.handleKeyDown, this); - this.enabled = false; - } - }, - -
/** - * Convenience function for setting disabled/enabled by boolean. + /** + * Convenience function for setting disabled/enabled by boolean. * @param {Boolean} disabled */ setDisabled : function(disabled){ - this[disabled ? "disable" : "enable"](); + if (disabled) { + this.disable(); + } else { + this.enable(); + } + }, + + /** + * Destroys the KeyMap instance and removes all handlers. + * @param {Boolean} removeEl True to also remove the attached element + */ + destroy: function(removeEl){ + var me = this; + + me.bindings = []; + me.disable(); + if (removeEl === true) { + me.el.remove(); + } + delete me.el; } -};
- - \ No newline at end of file +});
\ No newline at end of file