docs/source/Ext.html

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