← Back to branch summary

~cdparra/gelee/trunk

« back to all changes in this revision

Viewing changes to webui/ecosystem/workspace/extjs/docs/source/KeyMap.html

  • Committer: parra
  • Date: 2010-03-15 15:56:56 UTC
  • Revision ID: svn-v4:ac5bba68-f036-4e09-846e-8f32731cc928:trunk/gelee:1448
merged gelee at svn

Show diffs side-by-side

added added

removed removed

Lines of Context:
webui/ecosystem/workspace/extjs/docs/source/KeyMap.html
 
1
<html>
 
2
<head>
 
3
  <title>The source code</title>
 
4
    <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
 
5
    <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
 
6
</head>
 
7
<body  onload="prettyPrint();">
 
8
    <pre class="prettyprint lang-js"><div id="cls-Ext.KeyMap"></div>/**
 
9
 * @class Ext.KeyMap
 
10
 * Handles mapping keys to actions for an element. One key map can be used for multiple actions.
 
11
 * The constructor accepts the same config object as defined by {@link #addBinding}.
 
12
 * If you bind a callback function to a KeyMap, anytime the KeyMap handles an expected key
 
13
 * combination it will call the function with this signature (if the match is a multi-key
 
14
 * combination the callback will still be called only once): (String key, Ext.EventObject e)
 
15
 * A KeyMap can also handle a string representation of keys.<br />
 
16
 * Usage:
 
17
 <pre><code>
 
18
// map one key by key code
 
19
var map = new Ext.KeyMap("my-element", {
 
20
    key: 13, // or Ext.EventObject.ENTER
 
21
    fn: myHandler,
 
22
    scope: myObject
 
23
});
 
24
 
 
25
// map multiple keys to one action by string
 
26
var map = new Ext.KeyMap("my-element", {
 
27
    key: "a\r\n\t",
 
28
    fn: myHandler,
 
29
    scope: myObject
 
30
});
 
31
 
 
32
// map multiple keys to multiple actions by strings and array of codes
 
33
var map = new Ext.KeyMap("my-element", [
 
34
    {
 
35
        key: [10,13],
 
36
        fn: function(){ alert("Return was pressed"); }
 
37
    }, {
 
38
        key: "abc",
 
39
        fn: function(){ alert('a, b or c was pressed'); }
 
40
    }, {
 
41
        key: "\t",
 
42
        ctrl:true,
 
43
        shift:true,
 
44
        fn: function(){ alert('Control + shift + tab was pressed.'); }
 
45
    }
 
46
]);
 
47
</code></pre>
 
48
 * <b>Note: A KeyMap starts enabled</b>
 
49
 * @constructor
 
50
 * @param {Mixed} el The element to bind to
 
51
 * @param {Object} config The config (see {@link #addBinding})
 
52
 * @param {String} eventName (optional) The event to bind to (defaults to "keydown")
 
53
 */
 
54
Ext.KeyMap = function(el, config, eventName){
 
55
    this.el  = Ext.get(el);
 
56
    this.eventName = eventName || "keydown";
 
57
    this.bindings = [];
 
58
    if(config){
 
59
        this.addBinding(config);
 
60
    }
 
61
    this.enable();
 
62
};
 
63
 
 
64
Ext.KeyMap.prototype = {
 
65
    <div id="prop-Ext.KeyMap-stopEvent"></div>/**
 
66
     * True to stop the event from bubbling and prevent the default browser action if the
 
67
     * key was handled by the KeyMap (defaults to false)
 
68
     * @type Boolean
 
69
     */
 
70
    stopEvent : false,
 
71
 
 
72
    <div id="method-Ext.KeyMap-addBinding"></div>/**
 
73
     * Add a new binding to this KeyMap. The following config object properties are supported:
 
74
     * <pre>
 
75
Property    Type             Description
 
76
----------  ---------------  ----------------------------------------------------------------------
 
77
key         String/Array     A single keycode or an array of keycodes to handle
 
78
shift       Boolean          True to handle key only when shift is pressed, False to handle the key only when shift is not pressed (defaults to undefined)
 
79
ctrl        Boolean          True to handle key only when ctrl is pressed, False to handle the key only when ctrl is not pressed (defaults to undefined)
 
80
alt         Boolean          True to handle key only when alt is pressed, False to handle the key only when alt is not pressed (defaults to undefined)
 
81
handler     Function         The function to call when KeyMap finds the expected key combination
 
82
fn          Function         Alias of handler (for backwards-compatibility)
 
83
scope       Object           The scope of the callback function
 
84
stopEvent   Boolean          True to stop the event from bubbling and prevent the default browser action if the key was handled by the KeyMap (defaults to false)
 
85
</pre>
 
86
     *
 
87
     * Usage:
 
88
     * <pre><code>
 
89
// Create a KeyMap
 
90
var map = new Ext.KeyMap(document, {
 
91
    key: Ext.EventObject.ENTER,
 
92
    fn: handleKey,
 
93
    scope: this
 
94
});
 
95
 
 
96
//Add a new binding to the existing KeyMap later
 
97
map.addBinding({
 
98
    key: 'abc',
 
99
    shift: true,
 
100
    fn: handleKey,
 
101
    scope: this
 
102
});
 
103
</code></pre>
 
104
     * @param {Object/Array} config A single KeyMap config or an array of configs
 
105
     */
 
106
        addBinding : function(config){
 
107
        if(Ext.isArray(config)){
 
108
            Ext.each(config, function(c){
 
109
                this.addBinding(c);
 
110
            }, this);
 
111
            return;
 
112
        }
 
113
        var keyCode = config.key,
 
114
            fn = config.fn || config.handler,
 
115
            scope = config.scope;
 
116
 
 
117
        if (config.stopEvent) {
 
118
            this.stopEvent = config.stopEvent;    
 
119
        }       
 
120
 
 
121
        if(typeof keyCode == "string"){
 
122
            var ks = [];
 
123
            var keyString = keyCode.toUpperCase();
 
124
            for(var j = 0, len = keyString.length; j < len; j++){
 
125
                ks.push(keyString.charCodeAt(j));
 
126
            }
 
127
            keyCode = ks;
 
128
        }
 
129
        var keyArray = Ext.isArray(keyCode);
 
130
        
 
131
        var handler = function(e){
 
132
            if(this.checkModifiers(config, e)){
 
133
                var k = e.getKey();
 
134
                if(keyArray){
 
135
                    for(var i = 0, len = keyCode.length; i < len; i++){
 
136
                        if(keyCode[i] == k){
 
137
                          if(this.stopEvent){
 
138
                              e.stopEvent();
 
139
                          }
 
140
                          fn.call(scope || window, k, e);
 
141
                          return;
 
142
                        }
 
143
                    }
 
144
                }else{
 
145
                    if(k == keyCode){
 
146
                        if(this.stopEvent){
 
147
                           e.stopEvent();
 
148
                        }
 
149
                        fn.call(scope || window, k, e);
 
150
                    }
 
151
                }
 
152
            }
 
153
        };
 
154
        this.bindings.push(handler);
 
155
        },
 
156
    
 
157
    // private
 
158
    checkModifiers: function(config, e){
 
159
        var val, key, keys = ['shift', 'ctrl', 'alt'];
 
160
        for (var i = 0, len = keys.length; i < len; ++i){
 
161
            key = keys[i];
 
162
            val = config[key];
 
163
            if(!(val === undefined || (val === e[key + 'Key']))){
 
164
                return false;
 
165
            }
 
166
        }
 
167
        return true;
 
168
    },
 
169
 
 
170
    <div id="method-Ext.KeyMap-on"></div>/**
 
171
     * Shorthand for adding a single key listener
 
172
     * @param {Number/Array/Object} key Either the numeric key code, array of key codes or an object with the
 
173
     * following options:
 
174
     * {key: (number or array), shift: (true/false), ctrl: (true/false), alt: (true/false)}
 
175
     * @param {Function} fn The function to call
 
176
     * @param {Object} scope (optional) The scope of the function
 
177
     */
 
178
    on : function(key, fn, scope){
 
179
        var keyCode, shift, ctrl, alt;
 
180
        if(typeof key == "object" && !Ext.isArray(key)){
 
181
            keyCode = key.key;
 
182
            shift = key.shift;
 
183
            ctrl = key.ctrl;
 
184
            alt = key.alt;
 
185
        }else{
 
186
            keyCode = key;
 
187
        }
 
188
        this.addBinding({
 
189
            key: keyCode,
 
190
            shift: shift,
 
191
            ctrl: ctrl,
 
192
            alt: alt,
 
193
            fn: fn,
 
194
            scope: scope
 
195
        });
 
196
    },
 
197
 
 
198
    // private
 
199
    handleKeyDown : function(e){
 
200
            if(this.enabled){ //just in case
 
201
            var b = this.bindings;
 
202
            for(var i = 0, len = b.length; i < len; i++){
 
203
                b[i].call(this, e);
 
204
            }
 
205
            }
 
206
        },
 
207
 
 
208
        <div id="method-Ext.KeyMap-isEnabled"></div>/**
 
209
         * Returns true if this KeyMap is enabled
 
210
         * @return {Boolean}
 
211
         */
 
212
        isEnabled : function(){
 
213
            return this.enabled;
 
214
        },
 
215
 
 
216
        <div id="method-Ext.KeyMap-enable"></div>/**
 
217
         * Enables this KeyMap
 
218
         */
 
219
        enable: function(){
 
220
                if(!this.enabled){
 
221
                    this.el.on(this.eventName, this.handleKeyDown, this);
 
222
                    this.enabled = true;
 
223
                }
 
224
        },
 
225
 
 
226
        <div id="method-Ext.KeyMap-disable"></div>/**
 
227
         * Disable this KeyMap
 
228
         */
 
229
        disable: function(){
 
230
                if(this.enabled){
 
231
                    this.el.removeListener(this.eventName, this.handleKeyDown, this);
 
232
                    this.enabled = false;
 
233
                }
 
234
        },
 
235
    
 
236
    <div id="method-Ext.KeyMap-setDisabled"></div>/**
 
237
     * Convenience function for setting disabled/enabled by boolean.
 
238
     * @param {Boolean} disabled
 
239
     */
 
240
    setDisabled : function(disabled){
 
241
        this[disabled ? "disable" : "enable"]();
 
242
    }
 
243
};</pre>    
 
244
</body>
 
245
</html>
 
 
b'\\ No newline at end of file'