projects / roojs1 / blob
? search:


e83b4866e296a449ccd831965c6009e2417ff26b
[roojs1] / docs / src / Roo_KeyMap.js.html
1 <html><head><title>/home/edward/gitlive/roojs1/Roo/KeyMap.js</title><link rel="stylesheet" type="text/css" href="../../css/highlight-js.css"/></head><body class="highlightpage"><code class="jsdoc-pretty"><span class="jsdoc-comment">/*
2  * Based on:
3  * Ext JS Library 1.1.1
4  * Copyright(c) 2006-2007, Ext JS, LLC.
5  *
6  * Originally Released Under LGPL - original licence link has changed is not relivant.
7  *
8  * Fork - LGPL
9  * &lt;script type=&quot;text/javascript&quot;&gt;
10  */
11
12
13 /**
14  * @class Roo.KeyMap
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.&lt;br /&gt;
21  * Usage:
22  &lt;pre&gt;&lt;code&gt;
23 // map one key by key code
24 var map = new Roo.KeyMap(&quot;my-element&quot;, {
25     key: 13, // or Roo.EventObject.ENTER
26     fn: myHandler,
27     scope: myObject
28 });
29
30 // map multiple keys to one action by string
31 var map = new Roo.KeyMap(&quot;my-element&quot;, {
32     key: &quot;a\r\n\t&quot;,
33     fn: myHandler,
34     scope: myObject
35 });
36
37 // map multiple keys to multiple actions by strings and array of codes
38 var map = new Roo.KeyMap(&quot;my-element&quot;, [
39     {
40         key: [10,13],
41         fn: function(){ alert(&quot;Return was pressed&quot;); }
42     }, {
43         key: &quot;abc&quot;,
44         fn: function(){ alert('a, b or c was pressed'); }
45     }, {
46         key: &quot;\t&quot;,
47         ctrl:true,
48         shift:true,
49         fn: function(){ alert('Control + shift + tab was pressed.'); }
50     }
51 ]);
52 &lt;/code&gt;&lt;/pre&gt;
53  * &lt;b&gt;Note: A KeyMap starts enabled&lt;/b&gt;
54  * @constructor
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 &quot;keydown&quot;)
58  */
59 </span><span class="jsdoc-var">Roo.KeyMap </span><span class="jsdoc-syntax">= </span><span class="jsdoc-keyword">function</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">el</span><span class="jsdoc-syntax">, </span><span class="jsdoc-var">config</span><span class="jsdoc-syntax">, </span><span class="jsdoc-var">eventName</span><span class="jsdoc-syntax">){
60     </span><span class="jsdoc-var">this.el  </span><span class="jsdoc-syntax">= </span><span class="jsdoc-var">Roo.get</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">el</span><span class="jsdoc-syntax">);
61     </span><span class="jsdoc-var">this.eventName </span><span class="jsdoc-syntax">= </span><span class="jsdoc-var">eventName </span><span class="jsdoc-syntax">|| </span><span class="jsdoc-string">&quot;keydown&quot;</span><span class="jsdoc-syntax">;
62     </span><span class="jsdoc-var">this.bindings </span><span class="jsdoc-syntax">= [];
63     </span><span class="jsdoc-keyword">if</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">config</span><span class="jsdoc-syntax">){
64         </span><span class="jsdoc-var">this.addBinding</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">config</span><span class="jsdoc-syntax">);
65     }
66     </span><span class="jsdoc-var">this.enable</span><span class="jsdoc-syntax">();
67 };
68
69 </span><span class="jsdoc-var">Roo.KeyMap.prototype </span><span class="jsdoc-syntax">= {
70     </span><span class="jsdoc-comment">/**
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)
73      * @type Boolean
74      */
75     </span><span class="jsdoc-var">stopEvent </span><span class="jsdoc-syntax">: </span><span class="jsdoc-keyword">false</span><span class="jsdoc-syntax">,
76
77     </span><span class="jsdoc-comment">/**
78      * Add a new binding to this KeyMap. The following config object properties are supported:
79      * &lt;pre&gt;
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
88 &lt;/pre&gt;
89      *
90      * Usage:
91      * &lt;pre&gt;&lt;code&gt;
92 // Create a KeyMap
93 var map = new Roo.KeyMap(document, {
94     key: Roo.EventObject.ENTER,
95     fn: handleKey,
96     scope: this
97 });
98
99 //Add a new binding to the existing KeyMap later
100 map.addBinding({
101     key: 'abc',
102     shift: true,
103     fn: handleKey,
104     scope: this
105 });
106 &lt;/code&gt;&lt;/pre&gt;
107      * @param {Object/Array} config A single KeyMap config or an array of configs
108      */
109         </span><span class="jsdoc-var">addBinding </span><span class="jsdoc-syntax">: </span><span class="jsdoc-keyword">function</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">config</span><span class="jsdoc-syntax">){
110         </span><span class="jsdoc-keyword">if</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">config </span><span class="jsdoc-keyword">instanceof </span><span class="jsdoc-var">Array</span><span class="jsdoc-syntax">){
111             </span><span class="jsdoc-keyword">for</span><span class="jsdoc-syntax">(</span><span class="jsdoc-keyword">var </span><span class="jsdoc-var">i </span><span class="jsdoc-syntax">= 0, </span><span class="jsdoc-var">len </span><span class="jsdoc-syntax">= </span><span class="jsdoc-var">config.length</span><span class="jsdoc-syntax">; </span><span class="jsdoc-var">i </span><span class="jsdoc-syntax">&lt; </span><span class="jsdoc-var">len</span><span class="jsdoc-syntax">; </span><span class="jsdoc-var">i</span><span class="jsdoc-syntax">++){
112                 </span><span class="jsdoc-var">this.addBinding</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">config</span><span class="jsdoc-syntax">[</span><span class="jsdoc-var">i</span><span class="jsdoc-syntax">]);
113             }
114             </span><span class="jsdoc-keyword">return</span><span class="jsdoc-syntax">;
115         }
116         </span><span class="jsdoc-keyword">var </span><span class="jsdoc-var">keyCode </span><span class="jsdoc-syntax">= </span><span class="jsdoc-var">config.key</span><span class="jsdoc-syntax">,
117             </span><span class="jsdoc-var">shift </span><span class="jsdoc-syntax">= </span><span class="jsdoc-var">config.shift</span><span class="jsdoc-syntax">,
118             </span><span class="jsdoc-var">ctrl </span><span class="jsdoc-syntax">= </span><span class="jsdoc-var">config.ctrl</span><span class="jsdoc-syntax">,
119             </span><span class="jsdoc-var">alt </span><span class="jsdoc-syntax">= </span><span class="jsdoc-var">config.alt</span><span class="jsdoc-syntax">,
120             </span><span class="jsdoc-var">fn </span><span class="jsdoc-syntax">= </span><span class="jsdoc-var">config.fn</span><span class="jsdoc-syntax">,
121             </span><span class="jsdoc-var">scope </span><span class="jsdoc-syntax">= </span><span class="jsdoc-var">config.scope</span><span class="jsdoc-syntax">;
122         </span><span class="jsdoc-keyword">if</span><span class="jsdoc-syntax">(</span><span class="jsdoc-keyword">typeof </span><span class="jsdoc-var">keyCode </span><span class="jsdoc-syntax">== </span><span class="jsdoc-string">&quot;string&quot;</span><span class="jsdoc-syntax">){
123             </span><span class="jsdoc-keyword">var </span><span class="jsdoc-var">ks </span><span class="jsdoc-syntax">= [];
124             </span><span class="jsdoc-keyword">var </span><span class="jsdoc-var">keyString </span><span class="jsdoc-syntax">= </span><span class="jsdoc-var">keyCode.toUpperCase</span><span class="jsdoc-syntax">();
125             </span><span class="jsdoc-keyword">for</span><span class="jsdoc-syntax">(</span><span class="jsdoc-keyword">var </span><span class="jsdoc-var">j </span><span class="jsdoc-syntax">= 0, </span><span class="jsdoc-var">len </span><span class="jsdoc-syntax">= </span><span class="jsdoc-var">keyString.length</span><span class="jsdoc-syntax">; </span><span class="jsdoc-var">j </span><span class="jsdoc-syntax">&lt; </span><span class="jsdoc-var">len</span><span class="jsdoc-syntax">; </span><span class="jsdoc-var">j</span><span class="jsdoc-syntax">++){
126                 </span><span class="jsdoc-var">ks.push</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">keyString.charCodeAt</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">j</span><span class="jsdoc-syntax">));
127             }
128             </span><span class="jsdoc-var">keyCode </span><span class="jsdoc-syntax">= </span><span class="jsdoc-var">ks</span><span class="jsdoc-syntax">;
129         }
130         </span><span class="jsdoc-keyword">var </span><span class="jsdoc-var">keyArray </span><span class="jsdoc-syntax">= </span><span class="jsdoc-var">keyCode </span><span class="jsdoc-keyword">instanceof </span><span class="jsdoc-var">Array</span><span class="jsdoc-syntax">;
131         </span><span class="jsdoc-keyword">var </span><span class="jsdoc-var">handler </span><span class="jsdoc-syntax">= </span><span class="jsdoc-keyword">function</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">e</span><span class="jsdoc-syntax">){
132             </span><span class="jsdoc-keyword">if</span><span class="jsdoc-syntax">((!</span><span class="jsdoc-var">shift </span><span class="jsdoc-syntax">|| </span><span class="jsdoc-var">e.shiftKey</span><span class="jsdoc-syntax">) &amp;&amp; (!</span><span class="jsdoc-var">ctrl </span><span class="jsdoc-syntax">|| </span><span class="jsdoc-var">e.ctrlKey</span><span class="jsdoc-syntax">) &amp;&amp;  (!</span><span class="jsdoc-var">alt </span><span class="jsdoc-syntax">|| </span><span class="jsdoc-var">e.altKey</span><span class="jsdoc-syntax">)){
133                 </span><span class="jsdoc-keyword">var </span><span class="jsdoc-var">k </span><span class="jsdoc-syntax">= </span><span class="jsdoc-var">e.getKey</span><span class="jsdoc-syntax">();
134                 </span><span class="jsdoc-keyword">if</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">keyArray</span><span class="jsdoc-syntax">){
135                     </span><span class="jsdoc-keyword">for</span><span class="jsdoc-syntax">(</span><span class="jsdoc-keyword">var </span><span class="jsdoc-var">i </span><span class="jsdoc-syntax">= 0, </span><span class="jsdoc-var">len </span><span class="jsdoc-syntax">= </span><span class="jsdoc-var">keyCode.length</span><span class="jsdoc-syntax">; </span><span class="jsdoc-var">i </span><span class="jsdoc-syntax">&lt; </span><span class="jsdoc-var">len</span><span class="jsdoc-syntax">; </span><span class="jsdoc-var">i</span><span class="jsdoc-syntax">++){
136                         </span><span class="jsdoc-keyword">if</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">keyCode</span><span class="jsdoc-syntax">[</span><span class="jsdoc-var">i</span><span class="jsdoc-syntax">] == </span><span class="jsdoc-var">k</span><span class="jsdoc-syntax">){
137                           </span><span class="jsdoc-keyword">if</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">this.stopEvent</span><span class="jsdoc-syntax">){
138                               </span><span class="jsdoc-var">e.stopEvent</span><span class="jsdoc-syntax">();
139                           }
140                           </span><span class="jsdoc-var">fn.call</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">scope </span><span class="jsdoc-syntax">|| </span><span class="jsdoc-var">window</span><span class="jsdoc-syntax">, </span><span class="jsdoc-var">k</span><span class="jsdoc-syntax">, </span><span class="jsdoc-var">e</span><span class="jsdoc-syntax">);
141                           </span><span class="jsdoc-keyword">return</span><span class="jsdoc-syntax">;
142                         }
143                     }
144                 }</span><span class="jsdoc-keyword">else</span><span class="jsdoc-syntax">{
145                     </span><span class="jsdoc-keyword">if</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">k </span><span class="jsdoc-syntax">== </span><span class="jsdoc-var">keyCode</span><span class="jsdoc-syntax">){
146                         </span><span class="jsdoc-keyword">if</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">this.stopEvent</span><span class="jsdoc-syntax">){
147                            </span><span class="jsdoc-var">e.stopEvent</span><span class="jsdoc-syntax">();
148                         }
149                         </span><span class="jsdoc-var">fn.call</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">scope </span><span class="jsdoc-syntax">|| </span><span class="jsdoc-var">window</span><span class="jsdoc-syntax">, </span><span class="jsdoc-var">k</span><span class="jsdoc-syntax">, </span><span class="jsdoc-var">e</span><span class="jsdoc-syntax">);
150                     }
151                 }
152             }
153         };
154         </span><span class="jsdoc-var">this.bindings.push</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">handler</span><span class="jsdoc-syntax">);
155         },
156
157     </span><span class="jsdoc-comment">/**
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
160      * following options:
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
164      */
165     </span><span class="jsdoc-var">on </span><span class="jsdoc-syntax">: </span><span class="jsdoc-keyword">function</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">key</span><span class="jsdoc-syntax">, </span><span class="jsdoc-var">fn</span><span class="jsdoc-syntax">, </span><span class="jsdoc-var">scope</span><span class="jsdoc-syntax">){
166         </span><span class="jsdoc-keyword">var </span><span class="jsdoc-var">keyCode</span><span class="jsdoc-syntax">, </span><span class="jsdoc-var">shift</span><span class="jsdoc-syntax">, </span><span class="jsdoc-var">ctrl</span><span class="jsdoc-syntax">, </span><span class="jsdoc-var">alt</span><span class="jsdoc-syntax">;
167         </span><span class="jsdoc-keyword">if</span><span class="jsdoc-syntax">(</span><span class="jsdoc-keyword">typeof </span><span class="jsdoc-var">key </span><span class="jsdoc-syntax">== </span><span class="jsdoc-string">&quot;object&quot; </span><span class="jsdoc-syntax">&amp;&amp; !(</span><span class="jsdoc-var">key </span><span class="jsdoc-keyword">instanceof </span><span class="jsdoc-var">Array</span><span class="jsdoc-syntax">)){
168             </span><span class="jsdoc-var">keyCode </span><span class="jsdoc-syntax">= </span><span class="jsdoc-var">key.key</span><span class="jsdoc-syntax">;
169             </span><span class="jsdoc-var">shift </span><span class="jsdoc-syntax">= </span><span class="jsdoc-var">key.shift</span><span class="jsdoc-syntax">;
170             </span><span class="jsdoc-var">ctrl </span><span class="jsdoc-syntax">= </span><span class="jsdoc-var">key.ctrl</span><span class="jsdoc-syntax">;
171             </span><span class="jsdoc-var">alt </span><span class="jsdoc-syntax">= </span><span class="jsdoc-var">key.alt</span><span class="jsdoc-syntax">;
172         }</span><span class="jsdoc-keyword">else</span><span class="jsdoc-syntax">{
173             </span><span class="jsdoc-var">keyCode </span><span class="jsdoc-syntax">= </span><span class="jsdoc-var">key</span><span class="jsdoc-syntax">;
174         }
175         </span><span class="jsdoc-var">this.addBinding</span><span class="jsdoc-syntax">({
176             </span><span class="jsdoc-var">key</span><span class="jsdoc-syntax">: </span><span class="jsdoc-var">keyCode</span><span class="jsdoc-syntax">,
177             </span><span class="jsdoc-var">shift</span><span class="jsdoc-syntax">: </span><span class="jsdoc-var">shift</span><span class="jsdoc-syntax">,
178             </span><span class="jsdoc-var">ctrl</span><span class="jsdoc-syntax">: </span><span class="jsdoc-var">ctrl</span><span class="jsdoc-syntax">,
179             </span><span class="jsdoc-var">alt</span><span class="jsdoc-syntax">: </span><span class="jsdoc-var">alt</span><span class="jsdoc-syntax">,
180             </span><span class="jsdoc-var">fn</span><span class="jsdoc-syntax">: </span><span class="jsdoc-var">fn</span><span class="jsdoc-syntax">,
181             </span><span class="jsdoc-var">scope</span><span class="jsdoc-syntax">: </span><span class="jsdoc-var">scope
182         </span><span class="jsdoc-syntax">})
183     },
184
185     </span><span class="jsdoc-comment">// private
186     </span><span class="jsdoc-var">handleKeyDown </span><span class="jsdoc-syntax">: </span><span class="jsdoc-keyword">function</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">e</span><span class="jsdoc-syntax">){
187             </span><span class="jsdoc-keyword">if</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">this.enabled</span><span class="jsdoc-syntax">){ </span><span class="jsdoc-comment">//just in case
188             </span><span class="jsdoc-keyword">var </span><span class="jsdoc-var">b </span><span class="jsdoc-syntax">= </span><span class="jsdoc-var">this.bindings</span><span class="jsdoc-syntax">;
189             </span><span class="jsdoc-keyword">for</span><span class="jsdoc-syntax">(</span><span class="jsdoc-keyword">var </span><span class="jsdoc-var">i </span><span class="jsdoc-syntax">= 0, </span><span class="jsdoc-var">len </span><span class="jsdoc-syntax">= </span><span class="jsdoc-var">b.length</span><span class="jsdoc-syntax">; </span><span class="jsdoc-var">i </span><span class="jsdoc-syntax">&lt; </span><span class="jsdoc-var">len</span><span class="jsdoc-syntax">; </span><span class="jsdoc-var">i</span><span class="jsdoc-syntax">++){
190                 </span><span class="jsdoc-var">b</span><span class="jsdoc-syntax">[</span><span class="jsdoc-var">i</span><span class="jsdoc-syntax">]</span><span class="jsdoc-var">.call</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">this</span><span class="jsdoc-syntax">, </span><span class="jsdoc-var">e</span><span class="jsdoc-syntax">);
191             }
192             }
193         },
194
195         </span><span class="jsdoc-comment">/**
196          * Returns true if this KeyMap is enabled
197          * @return {Boolean} 
198          */
199         </span><span class="jsdoc-var">isEnabled </span><span class="jsdoc-syntax">: </span><span class="jsdoc-keyword">function</span><span class="jsdoc-syntax">(){
200             </span><span class="jsdoc-keyword">return </span><span class="jsdoc-var">this.enabled</span><span class="jsdoc-syntax">;
201         },
202
203         </span><span class="jsdoc-comment">/**
204          * Enables this KeyMap
205          */
206         </span><span class="jsdoc-var">enable</span><span class="jsdoc-syntax">: </span><span class="jsdoc-keyword">function</span><span class="jsdoc-syntax">(){
207                 </span><span class="jsdoc-keyword">if</span><span class="jsdoc-syntax">(!</span><span class="jsdoc-var">this.enabled</span><span class="jsdoc-syntax">){
208                     </span><span class="jsdoc-var">this.el.on</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">this.eventName</span><span class="jsdoc-syntax">, </span><span class="jsdoc-var">this.handleKeyDown</span><span class="jsdoc-syntax">, </span><span class="jsdoc-var">this</span><span class="jsdoc-syntax">);
209                     </span><span class="jsdoc-var">this.enabled </span><span class="jsdoc-syntax">= </span><span class="jsdoc-keyword">true</span><span class="jsdoc-syntax">;
210                 }
211         },
212
213         </span><span class="jsdoc-comment">/**
214          * Disable this KeyMap
215          */
216         </span><span class="jsdoc-var">disable</span><span class="jsdoc-syntax">: </span><span class="jsdoc-keyword">function</span><span class="jsdoc-syntax">(){
217                 </span><span class="jsdoc-keyword">if</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">this.enabled</span><span class="jsdoc-syntax">){
218                     </span><span class="jsdoc-var">this.el.removeListener</span><span class="jsdoc-syntax">(</span><span class="jsdoc-var">this.eventName</span><span class="jsdoc-syntax">, </span><span class="jsdoc-var">this.handleKeyDown</span><span class="jsdoc-syntax">, </span><span class="jsdoc-var">this</span><span class="jsdoc-syntax">);
219                     </span><span class="jsdoc-var">this.enabled </span><span class="jsdoc-syntax">= </span><span class="jsdoc-keyword">false</span><span class="jsdoc-syntax">;
220                 }
221         }
222 };</span></code></body></html>
RooJS - Version 1