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