Upgrade to ExtJS 3.2.1 - Released 04/27/2010
[extjs.git] / docs / source / KeyMap.html
index 073915d..2b8e51c 100644 (file)
 <html>
 <head>
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    
   <title>The source code</title>
     <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
     <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
 </head>
 <body  onload="prettyPrint();">
     <pre class="prettyprint lang-js">/*!
- * Ext JS Library 3.0.3
- * Copyright(c) 2006-2009 Ext JS, LLC
+ * Ext JS Library 3.2.1
+ * Copyright(c) 2006-2010 Ext JS, Inc.
  * licensing@extjs.com
  * http://www.extjs.com/license
  */
-<div id="cls-Ext.KeyMap"></div>/**\r
- * @class Ext.KeyMap\r
- * Handles mapping keys to actions for an element. One key map can be used for multiple actions.\r
- * The constructor accepts the same config object as defined by {@link #addBinding}.\r
- * If you bind a callback function to a KeyMap, anytime the KeyMap handles an expected key\r
- * combination it will call the function with this signature (if the match is a multi-key\r
- * combination the callback will still be called only once): (String key, Ext.EventObject e)\r
- * A KeyMap can also handle a string representation of keys.<br />\r
- * Usage:\r
- <pre><code>\r
-// map one key by key code\r
-var map = new Ext.KeyMap("my-element", {\r
-    key: 13, // or Ext.EventObject.ENTER\r
-    fn: myHandler,\r
-    scope: myObject\r
-});\r
-\r
-// map multiple keys to one action by string\r
-var map = new Ext.KeyMap("my-element", {\r
-    key: "a\r\n\t",\r
-    fn: myHandler,\r
-    scope: myObject\r
-});\r
-\r
-// map multiple keys to multiple actions by strings and array of codes\r
-var map = new Ext.KeyMap("my-element", [\r
-    {\r
-        key: [10,13],\r
-        fn: function(){ alert("Return was pressed"); }\r
-    }, {\r
-        key: "abc",\r
-        fn: function(){ alert('a, b or c was pressed'); }\r
-    }, {\r
-        key: "\t",\r
-        ctrl:true,\r
-        shift:true,\r
-        fn: function(){ alert('Control + shift + tab was pressed.'); }\r
-    }\r
-]);\r
-</code></pre>\r
- * <b>Note: A KeyMap starts enabled</b>\r
- * @constructor\r
- * @param {Mixed} el The element to bind to\r
- * @param {Object} config The config (see {@link #addBinding})\r
- * @param {String} eventName (optional) The event to bind to (defaults to "keydown")\r
- */\r
-Ext.KeyMap = function(el, config, eventName){\r
-    this.el  = Ext.get(el);\r
-    this.eventName = eventName || "keydown";\r
-    this.bindings = [];\r
-    if(config){\r
-        this.addBinding(config);\r
-    }\r
-    this.enable();\r
-};\r
-\r
-Ext.KeyMap.prototype = {\r
-    <div id="prop-Ext.KeyMap-stopEvent"></div>/**\r
-     * True to stop the event from bubbling and prevent the default browser action if the\r
-     * key was handled by the KeyMap (defaults to false)\r
-     * @type Boolean\r
-     */\r
-    stopEvent : false,\r
-\r
-    <div id="method-Ext.KeyMap-addBinding"></div>/**\r
-     * Add a new binding to this KeyMap. The following config object properties are supported:\r
-     * <pre>\r
-Property    Type             Description\r
-----------  ---------------  ----------------------------------------------------------------------\r
-key         String/Array     A single keycode or an array of keycodes to handle\r
-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)\r
-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)\r
-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)\r
-handler     Function         The function to call when KeyMap finds the expected key combination\r
-fn          Function         Alias of handler (for backwards-compatibility)\r
-scope       Object           The scope of the callback function\r
-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)\r
-</pre>\r
-     *\r
-     * Usage:\r
-     * <pre><code>\r
-// Create a KeyMap\r
-var map = new Ext.KeyMap(document, {\r
-    key: Ext.EventObject.ENTER,\r
-    fn: handleKey,\r
-    scope: this\r
-});\r
-\r
-//Add a new binding to the existing KeyMap later\r
-map.addBinding({\r
-    key: 'abc',\r
-    shift: true,\r
-    fn: handleKey,\r
-    scope: this\r
-});\r
-</code></pre>\r
-     * @param {Object/Array} config A single KeyMap config or an array of configs\r
-     */\r
-       addBinding : function(config){\r
-        if(Ext.isArray(config)){\r
-            Ext.each(config, function(c){\r
-                this.addBinding(c);\r
-            }, this);\r
-            return;\r
-        }\r
-        var keyCode = config.key,\r
-            fn = config.fn || config.handler,\r
-            scope = config.scope;\r
-\r
-       if (config.stopEvent) {\r
-           this.stopEvent = config.stopEvent;    \r
-       }       \r
-\r
-        if(typeof keyCode == "string"){\r
-            var ks = [];\r
-            var keyString = keyCode.toUpperCase();\r
-            for(var j = 0, len = keyString.length; j < len; j++){\r
-                ks.push(keyString.charCodeAt(j));\r
-            }\r
-            keyCode = ks;\r
-        }\r
-        var keyArray = Ext.isArray(keyCode);\r
-        \r
-        var handler = function(e){\r
-            if(this.checkModifiers(config, e)){\r
-                var k = e.getKey();\r
-                if(keyArray){\r
-                    for(var i = 0, len = keyCode.length; i < len; i++){\r
-                        if(keyCode[i] == k){\r
-                          if(this.stopEvent){\r
-                              e.stopEvent();\r
-                          }\r
-                          fn.call(scope || window, k, e);\r
-                          return;\r
-                        }\r
-                    }\r
-                }else{\r
-                    if(k == keyCode){\r
-                        if(this.stopEvent){\r
-                           e.stopEvent();\r
-                        }\r
-                        fn.call(scope || window, k, e);\r
-                    }\r
-                }\r
-            }\r
-        };\r
-        this.bindings.push(handler);\r
-       },\r
-    \r
-    // private\r
-    checkModifiers: function(config, e){\r
-        var val, key, keys = ['shift', 'ctrl', 'alt'];\r
-        for (var i = 0, len = keys.length; i < len; ++i){\r
-            key = keys[i];\r
-            val = config[key];\r
-            if(!(val === undefined || (val === e[key + 'Key']))){\r
-                return false;\r
-            }\r
-        }\r
-        return true;\r
-    },\r
-\r
-    <div id="method-Ext.KeyMap-on"></div>/**\r
-     * Shorthand for adding a single key listener\r
-     * @param {Number/Array/Object} key Either the numeric key code, array of key codes or an object with the\r
-     * following options:\r
-     * {key: (number or array), shift: (true/false), ctrl: (true/false), alt: (true/false)}\r
-     * @param {Function} fn The function to call\r
-     * @param {Object} scope (optional) The scope of the function\r
-     */\r
-    on : function(key, fn, scope){\r
-        var keyCode, shift, ctrl, alt;\r
-        if(typeof key == "object" && !Ext.isArray(key)){\r
-            keyCode = key.key;\r
-            shift = key.shift;\r
-            ctrl = key.ctrl;\r
-            alt = key.alt;\r
-        }else{\r
-            keyCode = key;\r
-        }\r
-        this.addBinding({\r
-            key: keyCode,\r
-            shift: shift,\r
-            ctrl: ctrl,\r
-            alt: alt,\r
-            fn: fn,\r
-            scope: scope\r
-        });\r
-    },\r
-\r
-    // private\r
-    handleKeyDown : function(e){\r
-           if(this.enabled){ //just in case\r
-           var b = this.bindings;\r
-           for(var i = 0, len = b.length; i < len; i++){\r
-               b[i].call(this, e);\r
-           }\r
-           }\r
-       },\r
-\r
-       <div id="method-Ext.KeyMap-isEnabled"></div>/**\r
-        * Returns true if this KeyMap is enabled\r
-        * @return {Boolean}\r
-        */\r
-       isEnabled : function(){\r
-           return this.enabled;\r
-       },\r
-\r
-       <div id="method-Ext.KeyMap-enable"></div>/**\r
-        * Enables this KeyMap\r
-        */\r
-       enable: function(){\r
-               if(!this.enabled){\r
-                   this.el.on(this.eventName, this.handleKeyDown, this);\r
-                   this.enabled = true;\r
-               }\r
-       },\r
-\r
-       <div id="method-Ext.KeyMap-disable"></div>/**\r
-        * Disable this KeyMap\r
-        */\r
-       disable: function(){\r
-               if(this.enabled){\r
-                   this.el.removeListener(this.eventName, this.handleKeyDown, this);\r
-                   this.enabled = false;\r
-               }\r
-       },\r
-    \r
-    <div id="method-Ext.KeyMap-setDisabled"></div>/**\r
-     * Convenience function for setting disabled/enabled by boolean.\r
-     * @param {Boolean} disabled\r
-     */\r
-    setDisabled : function(disabled){\r
-        this[disabled ? "disable" : "enable"]();\r
-    }\r
-};</pre>
+<div id="cls-Ext.KeyMap"></div>/**
+ * @class Ext.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.<br />
+ * Usage:
+ <pre><code>
+// map one key by key code
+var map = new Ext.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",
+    fn: myHandler,
+    scope: myObject
+});
+
+// map multiple keys to multiple actions by strings and array of codes
+var map = new Ext.KeyMap("my-element", [
+    {
+        key: [10,13],
+        fn: function(){ alert("Return was pressed"); }
+    }, {
+        key: "abc",
+        fn: function(){ alert('a, b or c was pressed'); }
+    }, {
+        key: "\t",
+        ctrl:true,
+        shift:true,
+        fn: function(){ alert('Control + shift + tab was pressed.'); }
+    }
+]);
+</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")
+ */
+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 = {
+    <div id="prop-Ext.KeyMap-stopEvent"></div>/**
+     * 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,
+
+    <div id="method-Ext.KeyMap-addBinding"></div>/**
+     * 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
+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)
+</pre>
+     *
+     * Usage:
+     * <pre><code>
+// Create a KeyMap
+var map = new Ext.KeyMap(document, {
+    key: Ext.EventObject.ENTER,
+    fn: handleKey,
+    scope: this
+});
+
+//Add a new binding to the existing KeyMap later
+map.addBinding({
+    key: 'abc',
+    shift: true,
+    fn: handleKey,
+    scope: this
+});
+</code></pre>
+     * @param {Object/Array} config 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);
+            return;
+        }
+        var keyCode = config.key,
+            fn = config.fn || config.handler,
+            scope = config.scope;
+
+       if (config.stopEvent) {
+           this.stopEvent = config.stopEvent;    
+       }       
+
+        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));
+            }
+            keyCode = ks;
+        }
+        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);
+                    }
+                }
+            }
+        };
+        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){
+            key = keys[i];
+            val = config[key];
+            if(!(val === undefined || (val === e[key + 'Key']))){
+                return false;
+            }
+        }
+        return true;
+    },
+
+    <div id="method-Ext.KeyMap-on"></div>/**
+     * 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 (<code>this</code> reference) in which the function is executed. Defaults to the browser window.
+     */
+    on : function(key, fn, scope){
+        var keyCode, shift, ctrl, alt;
+        if(typeof key == "object" && !Ext.isArray(key)){
+            keyCode = key.key;
+            shift = key.shift;
+            ctrl = key.ctrl;
+            alt = key.alt;
+        }else{
+            keyCode = key;
+        }
+        this.addBinding({
+            key: keyCode,
+            shift: shift,
+            ctrl: ctrl,
+            alt: alt,
+            fn: fn,
+            scope: scope
+        });
+    },
+
+    // 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);
+           }
+           }
+       },
+
+       <div id="method-Ext.KeyMap-isEnabled"></div>/**
+        * Returns true if this KeyMap is enabled
+        * @return {Boolean}
+        */
+       isEnabled : function(){
+           return this.enabled;
+       },
+
+       <div id="method-Ext.KeyMap-enable"></div>/**
+        * Enables this KeyMap
+        */
+       enable: function(){
+               if(!this.enabled){
+                   this.el.on(this.eventName, this.handleKeyDown, this);
+                   this.enabled = true;
+               }
+       },
+
+       <div id="method-Ext.KeyMap-disable"></div>/**
+        * Disable this KeyMap
+        */
+       disable: function(){
+               if(this.enabled){
+                   this.el.removeListener(this.eventName, this.handleKeyDown, this);
+                   this.enabled = false;
+               }
+       },
+    
+    <div id="method-Ext.KeyMap-setDisabled"></div>/**
+     * Convenience function for setting disabled/enabled by boolean.
+     * @param {Boolean} disabled
+     */
+    setDisabled : function(disabled){
+        this[disabled ? "disable" : "enable"]();
+    }
+};</pre>    
 </body>
 </html>
\ No newline at end of file