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