4 * Copyright(c) 2006-2007, Ext JS, LLC.
6 * Originally Released Under LGPL - original licence link has changed is not relivant.
9 * <script type="text/javascript">
15 * Handles mapping keys to actions for an element. One key map can be used for multiple actions.
16 * The constructor accepts the same config object as defined by {@link #addBinding}.
17 * If you bind a callback function to a KeyMap, anytime the KeyMap handles an expected key
18 * combination it will call the function with this signature (if the match is a multi-key
19 * combination the callback will still be called only once): (String key, Roo.EventObject e)
20 * A KeyMap can also handle a string representation of keys.<br />
23 // map one key by key code
24 var map = new Roo.KeyMap("my-element", {
25 key: 13, // or Roo.EventObject.ENTER
30 // map multiple keys to one action by string
31 var map = new Roo.KeyMap("my-element", {
37 // map multiple keys to multiple actions by strings and array of codes
38 var map = new Roo.KeyMap("my-element", [
41 fn: function(){ alert("Return was pressed"); }
44 fn: function(){ alert('a, b or c was pressed'); }
49 fn: function(){ alert('Control + shift + tab was pressed.'); }
53 * <b>Note: A KeyMap starts enabled</b>
55 * @param {String/HTMLElement/Roo.Element} el The element to bind to
56 * @param {Object} config The config (see {@link #addBinding})
57 * @param {String} eventName (optional) The event to bind to (defaults to "keydown")
59 Roo.KeyMap = function(el, config, eventName){
60 this.el = Roo.get(el);
61 this.eventName = eventName || "keydown";
64 this.addBinding(config);
69 Roo.KeyMap.prototype = {
71 * True to stop the event from bubbling and prevent the default browser action if the
72 * key was handled by the KeyMap (defaults to false)
78 * Add a new binding to this KeyMap. The following config object properties are supported:
80 Property Type Description
81 ---------- --------------- ----------------------------------------------------------------------
82 key String/Array A single keycode or an array of keycodes to handle
83 shift Boolean True to handle key only when shift is pressed (defaults to false)
84 ctrl Boolean True to handle key only when ctrl is pressed (defaults to false)
85 alt Boolean True to handle key only when alt is pressed (defaults to false)
86 fn Function The function to call when KeyMap finds the expected key combination
87 scope Object The scope of the callback function
93 var map = new Roo.KeyMap(document, {
94 key: Roo.EventObject.ENTER,
99 //Add a new binding to the existing KeyMap later
107 * @param {Object/Array} config A single KeyMap config or an array of configs
109 addBinding : function(config){
110 if(config instanceof Array){
111 for(var i = 0, len = config.length; i < len; i++){
112 this.addBinding(config[i]);
116 var keyCode = config.key,
117 shift = config.shift,
121 scope = config.scope;
122 if(typeof keyCode == "string"){
124 var keyString = keyCode.toUpperCase();
125 for(var j = 0, len = keyString.length; j < len; j++){
126 ks.push(keyString.charCodeAt(j));
130 var keyArray = keyCode instanceof Array;
131 var handler = function(e){
132 if((!shift || e.shiftKey) && (!ctrl || e.ctrlKey) && (!alt || e.altKey)){
135 for(var i = 0, len = keyCode.length; i < len; i++){
140 fn.call(scope || window, k, e);
149 fn.call(scope || window, k, e);
154 this.bindings.push(handler);
158 * Shorthand for adding a single key listener
159 * @param {Number/Array/Object} key Either the numeric key code, array of key codes or an object with the
161 * {key: (number or array), shift: (true/false), ctrl: (true/false), alt: (true/false)}
162 * @param {Function} fn The function to call
163 * @param {Object} scope (optional) The scope of the function
165 on : function(key, fn, scope){
166 var keyCode, shift, ctrl, alt;
167 if(typeof key == "object" && !(key instanceof Array)){
186 handleKeyDown : function(e){
187 if(this.enabled){ //just in case
188 var b = this.bindings;
189 for(var i = 0, len = b.length; i < len; i++){
196 * Returns true if this KeyMap is enabled
199 isEnabled : function(){
204 * Enables this KeyMap
208 this.el.on(this.eventName, this.handleKeyDown, this);
214 * Disable this KeyMap
218 this.el.removeListener(this.eventName, this.handleKeyDown, this);
219 this.enabled = false;