Upgrade to ExtJS 3.2.2 - Released 06/02/2010
[extjs.git] / docs / source / KeyNav.html
1 <html>
2 <head>
3   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    
4   <title>The source code</title>
5     <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
6     <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
7 </head>
8 <body  onload="prettyPrint();">
9     <pre class="prettyprint lang-js">/*!
10  * Ext JS Library 3.2.2
11  * Copyright(c) 2006-2010 Ext JS, Inc.
12  * licensing@extjs.com
13  * http://www.extjs.com/license
14  */
15 <div id="cls-Ext.KeyNav"></div>/**
16  * @class Ext.KeyNav
17  * <p>Provides a convenient wrapper for normalized keyboard navigation.  KeyNav allows you to bind
18  * navigation keys to function calls that will get called when the keys are pressed, providing an easy
19  * way to implement custom navigation schemes for any UI component.</p>
20  * <p>The following are all of the possible keys that can be implemented: enter, left, right, up, down, tab, esc,
21  * pageUp, pageDown, del, home, end.  Usage:</p>
22  <pre><code>
23 var nav = new Ext.KeyNav("my-element", {
24     "left" : function(e){
25         this.moveLeft(e.ctrlKey);
26     },
27     "right" : function(e){
28         this.moveRight(e.ctrlKey);
29     },
30     "enter" : function(e){
31         this.save();
32     },
33     scope : this
34 });
35 </code></pre>
36  * @constructor
37  * @param {Mixed} el The element to bind to
38  * @param {Object} config The config
39  */
40 Ext.KeyNav = function(el, config){
41     this.el = Ext.get(el);
42     Ext.apply(this, config);
43     if(!this.disabled){
44         this.disabled = true;
45         this.enable();
46     }
47 };
48
49 Ext.KeyNav.prototype = {
50     <div id="cfg-Ext.KeyNav-disabled"></div>/**
51      * @cfg {Boolean} disabled
52      * True to disable this KeyNav instance (defaults to false)
53      */
54     disabled : false,
55     <div id="cfg-Ext.KeyNav-defaultEventAction"></div>/**
56      * @cfg {String} defaultEventAction
57      * The method to call on the {@link Ext.EventObject} after this KeyNav intercepts a key.  Valid values are
58      * {@link Ext.EventObject#stopEvent}, {@link Ext.EventObject#preventDefault} and
59      * {@link Ext.EventObject#stopPropagation} (defaults to 'stopEvent')
60      */
61     defaultEventAction: "stopEvent",
62     <div id="cfg-Ext.KeyNav-forceKeyDown"></div>/**
63      * @cfg {Boolean} forceKeyDown
64      * Handle the keydown event instead of keypress (defaults to false).  KeyNav automatically does this for IE since
65      * IE does not propagate special keys on keypress, but setting this to true will force other browsers to also
66      * handle keydown instead of keypress.
67      */
68     forceKeyDown : false,
69
70     // private
71     relay : function(e){
72         var k = e.getKey();
73         var h = this.keyToHandler[k];
74         if(h && this[h]){
75             if(this.doRelay(e, this[h], h) !== true){
76                 e[this.defaultEventAction]();
77             }
78         }
79     },
80
81     // private
82     doRelay : function(e, h, hname){
83         return h.call(this.scope || this, e);
84     },
85
86     // possible handlers
87     enter : false,
88     left : false,
89     right : false,
90     up : false,
91     down : false,
92     tab : false,
93     esc : false,
94     pageUp : false,
95     pageDown : false,
96     del : false,
97     home : false,
98     end : false,
99
100     // quick lookup hash
101     keyToHandler : {
102         37 : "left",
103         39 : "right",
104         38 : "up",
105         40 : "down",
106         33 : "pageUp",
107         34 : "pageDown",
108         46 : "del",
109         36 : "home",
110         35 : "end",
111         13 : "enter",
112         27 : "esc",
113         9  : "tab"
114     },
115     
116     stopKeyUp: function(e) {
117         var k = e.getKey();
118
119         if (k >= 37 && k <= 40) {
120             // *** bugfix - safari 2.x fires 2 keyup events on cursor keys
121             // *** (note: this bugfix sacrifices the "keyup" event originating from keyNav elements in Safari 2)
122             e.stopEvent();
123         }
124     },
125     
126     <div id="method-Ext.KeyNav-destroy"></div>/**
127      * Destroy this KeyNav (this is the same as calling disable).
128      */
129     destroy: function(){
130         this.disable();    
131     },
132
133         <div id="method-Ext.KeyNav-enable"></div>/**
134          * Enable this KeyNav
135          */
136         enable: function() {
137         if (this.disabled) {
138             if (Ext.isSafari2) {
139                 // call stopKeyUp() on "keyup" event
140                 this.el.on('keyup', this.stopKeyUp, this);
141             }
142
143             this.el.on(this.isKeydown()? 'keydown' : 'keypress', this.relay, this);
144             this.disabled = false;
145         }
146     },
147
148         <div id="method-Ext.KeyNav-disable"></div>/**
149          * Disable this KeyNav
150          */
151         disable: function() {
152         if (!this.disabled) {
153             if (Ext.isSafari2) {
154                 // remove "keyup" event handler
155                 this.el.un('keyup', this.stopKeyUp, this);
156             }
157
158             this.el.un(this.isKeydown()? 'keydown' : 'keypress', this.relay, this);
159             this.disabled = true;
160         }
161     },
162     
163     <div id="method-Ext.KeyNav-setDisabled"></div>/**
164      * Convenience function for setting disabled/enabled by boolean.
165      * @param {Boolean} disabled
166      */
167     setDisabled : function(disabled){
168         this[disabled ? "disable" : "enable"]();
169     },
170     
171     // private
172     isKeydown: function(){
173         return this.forceKeyDown || Ext.EventManager.useKeydown;
174     }
175 };
176 </pre>    
177 </body>
178 </html>