Upgrade to ExtJS 4.0.2 - Released 06/09/2011
[extjs.git] / docs / source / Ext.html
1 <!DOCTYPE html>
2 <html>
3 <head>
4   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
5   <title>The source code</title>
6   <link href="../prettify/prettify.css" type="text/css" rel="stylesheet" />
7   <script type="text/javascript" src="../prettify/prettify.js"></script>
8   <style type="text/css">
9     .highlight { display: block; background-color: #ddd; }
10   </style>
11   <script type="text/javascript">
12     function highlight() {
13       document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
14     }
15   </script>
16 </head>
17 <body onload="prettyPrint(); highlight();">
18   <pre class="prettyprint lang-js"><span id='Ext'>/**
19 </span> * @class Ext
20  * @singleton
21  */
22 (function() {
23     var global = this,
24         objectPrototype = Object.prototype,
25         toString = objectPrototype.toString,
26         enumerables = true,
27         enumerablesTest = { toString: 1 },
28         i;
29
30     if (typeof Ext === 'undefined') {
31         global.Ext = {};
32     }
33
34     Ext.global = global;
35
36     for (i in enumerablesTest) {
37         enumerables = null;
38     }
39
40     if (enumerables) {
41         enumerables = ['hasOwnProperty', 'valueOf', 'isPrototypeOf', 'propertyIsEnumerable',
42                        'toLocaleString', 'toString', 'constructor'];
43     }
44
45 <span id='Ext-property-enumerables'>    /**
46 </span>     * An array containing extra enumerables for old browsers
47      * @type Array
48      */
49     Ext.enumerables = enumerables;
50
51 <span id='Ext-method-apply'>    /**
52 </span>     * Copies all the properties of config to the specified object.
53      * Note that if recursive merging and cloning without referencing the original objects / arrays is needed, use
54      * {@link Ext.Object#merge} instead.
55      * @param {Object} object The receiver of the properties
56      * @param {Object} config The source of the properties
57      * @param {Object} defaults A different object that will also be applied for default values
58      * @return {Object} returns obj
59      */
60     Ext.apply = function(object, config, defaults) {
61         if (defaults) {
62             Ext.apply(object, defaults);
63         }
64
65         if (object &amp;&amp; config &amp;&amp; typeof config === 'object') {
66             var i, j, k;
67
68             for (i in config) {
69                 object[i] = config[i];
70             }
71
72             if (enumerables) {
73                 for (j = enumerables.length; j--;) {
74                     k = enumerables[j];
75                     if (config.hasOwnProperty(k)) {
76                         object[k] = config[k];
77                     }
78                 }
79             }
80         }
81
82         return object;
83     };
84
85     Ext.buildSettings = Ext.apply({
86         baseCSSPrefix: 'x-',
87         scopeResetCSS: false
88     }, Ext.buildSettings || {});
89
90     Ext.apply(Ext, {
91 <span id='Ext-method-emptyFn'>        /**
92 </span>         * A reusable empty function
93          */
94         emptyFn: function() {},
95
96         baseCSSPrefix: Ext.buildSettings.baseCSSPrefix,
97
98 <span id='Ext-method-applyIf'>        /**
99 </span>         * Copies all the properties of config to object if they don't already exist.
100          * @param {Object} object The receiver of the properties
101          * @param {Object} config The source of the properties
102          * @return {Object} returns obj
103          */
104         applyIf: function(object, config) {
105             var property;
106
107             if (object) {
108                 for (property in config) {
109                     if (object[property] === undefined) {
110                         object[property] = config[property];
111                     }
112                 }
113             }
114
115             return object;
116         },
117
118 <span id='Ext-method-iterate'>        /**
119 </span>         * Iterates either an array or an object. This method delegates to
120          * {@link Ext.Array#each Ext.Array.each} if the given value is iterable, and {@link Ext.Object#each Ext.Object.each} otherwise.
121          *
122          * @param {Object/Array} object The object or array to be iterated.
123          * @param {Function} fn The function to be called for each iteration. See and {@link Ext.Array#each Ext.Array.each} and
124          * {@link Ext.Object#each Ext.Object.each} for detailed lists of arguments passed to this function depending on the given object
125          * type that is being iterated.
126          * @param {Object} scope (Optional) The scope (`this` reference) in which the specified function is executed.
127          * Defaults to the object being iterated itself.
128          * @markdown
129          */
130         iterate: function(object, fn, scope) {
131             if (Ext.isEmpty(object)) {
132                 return;
133             }
134
135             if (scope === undefined) {
136                 scope = object;
137             }
138
139             if (Ext.isIterable(object)) {
140                 Ext.Array.each.call(Ext.Array, object, fn, scope);
141             }
142             else {
143                 Ext.Object.each.call(Ext.Object, object, fn, scope);
144             }
145         }
146     });
147
148     Ext.apply(Ext, {
149
150 <span id='Ext-method-extend'>        /**
151 </span>         * This method deprecated. Use {@link Ext#define Ext.define} instead.
152          * @method
153          * @param {Function} superclass
154          * @param {Object} overrides
155          * @return {Function} The subclass constructor from the &lt;tt&gt;overrides&lt;/tt&gt; parameter, or a generated one if not provided.
156          * @deprecated 4.0.0 Use {@link Ext#define Ext.define} instead
157          */
158         extend: function() {
159             // inline overrides
160             var objectConstructor = objectPrototype.constructor,
161                 inlineOverrides = function(o) {
162                 for (var m in o) {
163                     if (!o.hasOwnProperty(m)) {
164                         continue;
165                     }
166                     this[m] = o[m];
167                 }
168             };
169
170             return function(subclass, superclass, overrides) {
171                 // First we check if the user passed in just the superClass with overrides
172                 if (Ext.isObject(superclass)) {
173                     overrides = superclass;
174                     superclass = subclass;
175                     subclass = overrides.constructor !== objectConstructor ? overrides.constructor : function() {
176                         superclass.apply(this, arguments);
177                     };
178                 }
179
180                 //&lt;debug&gt;
181                 if (!superclass) {
182                     Ext.Error.raise({
183                         sourceClass: 'Ext',
184                         sourceMethod: 'extend',
185                         msg: 'Attempting to extend from a class which has not been loaded on the page.'
186                     });
187                 }
188                 //&lt;/debug&gt;
189
190                 // We create a new temporary class
191                 var F = function() {},
192                     subclassProto, superclassProto = superclass.prototype;
193
194                 F.prototype = superclassProto;
195                 subclassProto = subclass.prototype = new F();
196                 subclassProto.constructor = subclass;
197                 subclass.superclass = superclassProto;
198
199                 if (superclassProto.constructor === objectConstructor) {
200                     superclassProto.constructor = superclass;
201                 }
202
203                 subclass.override = function(overrides) {
204                     Ext.override(subclass, overrides);
205                 };
206
207                 subclassProto.override = inlineOverrides;
208                 subclassProto.proto = subclassProto;
209
210                 subclass.override(overrides);
211                 subclass.extend = function(o) {
212                     return Ext.extend(subclass, o);
213                 };
214
215                 return subclass;
216             };
217         }(),
218
219 <span id='Ext-method-override'>        /**
220 </span>         * Proxy to {@link Ext.Base#override}. Please refer {@link Ext.Base#override} for further details.
221
222     Ext.define('My.cool.Class', {
223         sayHi: function() {
224             alert('Hi!');
225         }
226     }
227
228     Ext.override(My.cool.Class, {
229         sayHi: function() {
230             alert('About to say...');
231
232             this.callOverridden();
233         }
234     });
235
236     var cool = new My.cool.Class();
237     cool.sayHi(); // alerts 'About to say...'
238                   // alerts 'Hi!'
239
240          * Please note that `this.callOverridden()` only works if the class was previously
241          * created with {@link Ext#define)
242          *
243          * @param {Object} cls The class to override
244          * @param {Object} overrides The list of functions to add to origClass. This should be specified as an object literal
245          * containing one or more methods.
246          * @method override
247          * @markdown
248          */
249         override: function(cls, overrides) {
250             if (cls.prototype.$className) {
251                 return cls.override(overrides);
252             }
253             else {
254                 Ext.apply(cls.prototype, overrides);
255             }
256         }
257     });
258
259     // A full set of static methods to do type checking
260     Ext.apply(Ext, {
261
262 <span id='Ext-method-valueFrom'>        /**
263 </span>         * Returns the given value itself if it's not empty, as described in {@link Ext#isEmpty}; returns the default
264          * value (second argument) otherwise.
265          *
266          * @param {Mixed} value The value to test
267          * @param {Mixed} defaultValue The value to return if the original value is empty
268          * @param {Boolean} allowBlank (optional) true to allow zero length strings to qualify as non-empty (defaults to false)
269          * @return {Mixed} value, if non-empty, else defaultValue
270          */
271         valueFrom: function(value, defaultValue, allowBlank){
272             return Ext.isEmpty(value, allowBlank) ? defaultValue : value;
273         },
274
275 <span id='Ext-method-typeOf'>        /**
276 </span>         * Returns the type of the given variable in string format. List of possible values are:
277          *
278          * - `undefined`: If the given value is `undefined`
279          * - `null`: If the given value is `null`
280          * - `string`: If the given value is a string
281          * - `number`: If the given value is a number
282          * - `boolean`: If the given value is a boolean value
283          * - `date`: If the given value is a `Date` object
284          * - `function`: If the given value is a function reference
285          * - `object`: If the given value is an object
286          * - `array`: If the given value is an array
287          * - `regexp`: If the given value is a regular expression
288          * - `element`: If the given value is a DOM Element
289          * - `textnode`: If the given value is a DOM text node and contains something other than whitespace
290          * - `whitespace`: If the given value is a DOM text node and contains only whitespace
291          *
292          * @param {Mixed} value
293          * @return {String}
294          * @markdown
295          */
296         typeOf: function(value) {
297             if (value === null) {
298                 return 'null';
299             }
300
301             var type = typeof value;
302
303             if (type === 'undefined' || type === 'string' || type === 'number' || type === 'boolean') {
304                 return type;
305             }
306
307             var typeToString = toString.call(value);
308
309             switch(typeToString) {
310                 case '[object Array]':
311                     return 'array';
312                 case '[object Date]':
313                     return 'date';
314                 case '[object Boolean]':
315                     return 'boolean';
316                 case '[object Number]':
317                     return 'number';
318                 case '[object RegExp]':
319                     return 'regexp';
320             }
321
322             if (type === 'function') {
323                 return 'function';
324             }
325
326             if (type === 'object') {
327                 if (value.nodeType !== undefined) {
328                     if (value.nodeType === 3) {
329                         return (/\S/).test(value.nodeValue) ? 'textnode' : 'whitespace';
330                     }
331                     else {
332                         return 'element';
333                     }
334                 }
335
336                 return 'object';
337             }
338
339             //&lt;debug error&gt;
340             Ext.Error.raise({
341                 sourceClass: 'Ext',
342                 sourceMethod: 'typeOf',
343                 msg: 'Failed to determine the type of the specified value &quot;' + value + '&quot;. This is most likely a bug.'
344             });
345             //&lt;/debug&gt;
346         },
347
348 <span id='Ext-method-isEmpty'>        /**
349 </span>         * Returns true if the passed value is empty, false otherwise. The value is deemed to be empty if it is either:
350          *
351          * - `null`
352          * - `undefined`
353          * - a zero-length array
354          * - a zero-length string (Unless the `allowEmptyString` parameter is set to `true`)
355          *
356          * @param {Mixed} value The value to test
357          * @param {Boolean} allowEmptyString (optional) true to allow empty strings (defaults to false)
358          * @return {Boolean}
359          * @markdown
360          */
361         isEmpty: function(value, allowEmptyString) {
362             return (value === null) || (value === undefined) || (!allowEmptyString ? value === '' : false) || (Ext.isArray(value) &amp;&amp; value.length === 0);
363         },
364
365 <span id='Ext-method-isArray'>        /**
366 </span>         * Returns true if the passed value is a JavaScript Array, false otherwise.
367          *
368          * @param {Mixed} target The target to test
369          * @return {Boolean}
370          * @method
371          */
372         isArray: ('isArray' in Array) ? Array.isArray : function(value) {
373             return toString.call(value) === '[object Array]';
374         },
375
376 <span id='Ext-method-isDate'>        /**
377 </span>         * Returns true if the passed value is a JavaScript Date object, false otherwise.
378          * @param {Object} object The object to test
379          * @return {Boolean}
380          */
381         isDate: function(value) {
382             return toString.call(value) === '[object Date]';
383         },
384
385 <span id='Ext-method-isObject'>        /**
386 </span>         * Returns true if the passed value is a JavaScript Object, false otherwise.
387          * @param {Mixed} value The value to test
388          * @return {Boolean}
389          * @method
390          */
391         isObject: (toString.call(null) === '[object Object]') ?
392         function(value) {
393             // check ownerDocument here as well to exclude DOM nodes
394             return value !== null &amp;&amp; value !== undefined &amp;&amp; toString.call(value) === '[object Object]' &amp;&amp; value.ownerDocument === undefined;
395         } :
396         function(value) {
397             return toString.call(value) === '[object Object]';
398         },
399
400 <span id='Ext-method-isPrimitive'>        /**
401 </span>         * Returns true if the passed value is a JavaScript 'primitive', a string, number or boolean.
402          * @param {Mixed} value The value to test
403          * @return {Boolean}
404          */
405         isPrimitive: function(value) {
406             var type = typeof value;
407
408             return type === 'string' || type === 'number' || type === 'boolean';
409         },
410
411 <span id='Ext-method-isFunction'>        /**
412 </span>         * Returns true if the passed value is a JavaScript Function, false otherwise.
413          * @param {Mixed} value The value to test
414          * @return {Boolean}
415          * @method
416          */
417         isFunction:
418         // Safari 3.x and 4.x returns 'function' for typeof &lt;NodeList&gt;, hence we need to fall back to using
419         // Object.prorotype.toString (slower)
420         (typeof document !== 'undefined' &amp;&amp; typeof document.getElementsByTagName('body') === 'function') ? function(value) {
421             return toString.call(value) === '[object Function]';
422         } : function(value) {
423             return typeof value === 'function';
424         },
425
426 <span id='Ext-method-isNumber'>        /**
427 </span>         * Returns true if the passed value is a number. Returns false for non-finite numbers.
428          * @param {Mixed} value The value to test
429          * @return {Boolean}
430          */
431         isNumber: function(value) {
432             return typeof value === 'number' &amp;&amp; isFinite(value);
433         },
434
435 <span id='Ext-method-isNumeric'>        /**
436 </span>         * Validates that a value is numeric.
437          * @param {Mixed} value Examples: 1, '1', '2.34'
438          * @return {Boolean} True if numeric, false otherwise
439          */
440         isNumeric: function(value) {
441             return !isNaN(parseFloat(value)) &amp;&amp; isFinite(value);
442         },
443
444 <span id='Ext-method-isString'>        /**
445 </span>         * Returns true if the passed value is a string.
446          * @param {Mixed} value The value to test
447          * @return {Boolean}
448          */
449         isString: function(value) {
450             return typeof value === 'string';
451         },
452
453 <span id='Ext-method-isBoolean'>        /**
454 </span>         * Returns true if the passed value is a boolean.
455          *
456          * @param {Mixed} value The value to test
457          * @return {Boolean}
458          */
459         isBoolean: function(value) {
460             return typeof value === 'boolean';
461         },
462
463 <span id='Ext-method-isElement'>        /**
464 </span>         * Returns true if the passed value is an HTMLElement
465          * @param {Mixed} value The value to test
466          * @return {Boolean}
467          */
468         isElement: function(value) {
469             return value ? value.nodeType === 1 : false;
470         },
471
472 <span id='Ext-method-isTextNode'>        /**
473 </span>         * Returns true if the passed value is a TextNode
474          * @param {Mixed} value The value to test
475          * @return {Boolean}
476          */
477         isTextNode: function(value) {
478             return value ? value.nodeName === &quot;#text&quot; : false;
479         },
480
481 <span id='Ext-method-isDefined'>        /**
482 </span>         * Returns true if the passed value is defined.
483          * @param {Mixed} value The value to test
484          * @return {Boolean}
485          */
486         isDefined: function(value) {
487             return typeof value !== 'undefined';
488         },
489
490 <span id='Ext-method-isIterable'>        /**
491 </span>         * Returns true if the passed value is iterable, false otherwise
492          * @param {Mixed} value The value to test
493          * @return {Boolean}
494          */
495         isIterable: function(value) {
496             return (value &amp;&amp; typeof value !== 'string') ? value.length !== undefined : false;
497         }
498     });
499
500     Ext.apply(Ext, {
501
502 <span id='Ext-method-clone'>        /**
503 </span>         * Clone almost any type of variable including array, object, DOM nodes and Date without keeping the old reference
504          * @param {Mixed} item The variable to clone
505          * @return {Mixed} clone
506          */
507         clone: function(item) {
508             if (item === null || item === undefined) {
509                 return item;
510             }
511
512             // DOM nodes
513             // TODO proxy this to Ext.Element.clone to handle automatic id attribute changing
514             // recursively
515             if (item.nodeType &amp;&amp; item.cloneNode) {
516                 return item.cloneNode(true);
517             }
518
519             var type = toString.call(item);
520
521             // Date
522             if (type === '[object Date]') {
523                 return new Date(item.getTime());
524             }
525
526             var i, j, k, clone, key;
527
528             // Array
529             if (type === '[object Array]') {
530                 i = item.length;
531
532                 clone = [];
533
534                 while (i--) {
535                     clone[i] = Ext.clone(item[i]);
536                 }
537             }
538             // Object
539             else if (type === '[object Object]' &amp;&amp; item.constructor === Object) {
540                 clone = {};
541
542                 for (key in item) {
543                     clone[key] = Ext.clone(item[key]);
544                 }
545
546                 if (enumerables) {
547                     for (j = enumerables.length; j--;) {
548                         k = enumerables[j];
549                         clone[k] = item[k];
550                     }
551                 }
552             }
553
554             return clone || item;
555         },
556
557 <span id='Ext-method-getUniqueGlobalNamespace'>        /**
558 </span>         * @private
559          * Generate a unique reference of Ext in the global scope, useful for sandboxing
560          */
561         getUniqueGlobalNamespace: function() {
562             var uniqueGlobalNamespace = this.uniqueGlobalNamespace;
563
564             if (uniqueGlobalNamespace === undefined) {
565                 var i = 0;
566
567                 do {
568                     uniqueGlobalNamespace = 'ExtBox' + (++i);
569                 } while (Ext.global[uniqueGlobalNamespace] !== undefined);
570
571                 Ext.global[uniqueGlobalNamespace] = Ext;
572                 this.uniqueGlobalNamespace = uniqueGlobalNamespace;
573             }
574
575             return uniqueGlobalNamespace;
576         },
577
578 <span id='Ext-method-functionFactory'>        /**
579 </span>         * @private
580          */
581         functionFactory: function() {
582             var args = Array.prototype.slice.call(arguments);
583
584             if (args.length &gt; 0) {
585                 args[args.length - 1] = 'var Ext=window.' + this.getUniqueGlobalNamespace() + ';' +
586                     args[args.length - 1];
587             }
588
589             return Function.prototype.constructor.apply(Function.prototype, args);
590         }
591     });
592
593 <span id='Ext-method-type'>    /**
594 </span>     * Old alias to {@link Ext#typeOf}
595      * @deprecated 4.0.0 Use {@link Ext#typeOf} instead
596      * @method
597      * @alias Ext#typeOf
598      */
599     Ext.type = Ext.typeOf;
600
601 })();
602 </pre>
603 </body>
604 </html>