Upgrade to ExtJS 3.0.3 - Released 10/11/2009
[extjs.git] / docs / source / Ext.html
index c503375..453dca1 100644 (file)
@@ -1,11 +1,17 @@
-<html>\r
-<head>\r
-  <title>The source code</title>\r
-    <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />\r
-    <script type="text/javascript" src="../resources/prettify/prettify.js"></script>\r
-</head>\r
-<body  onload="prettyPrint();">\r
-    <pre class="prettyprint lang-js">\r
+<html>
+<head>
+  <title>The source code</title>
+    <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
+    <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
+</head>
+<body  onload="prettyPrint();">
+    <pre class="prettyprint lang-js">/*!
+ * Ext JS Library 3.0.3
+ * Copyright(c) 2006-2009 Ext JS, LLC
+ * licensing@extjs.com
+ * http://www.extjs.com/license
+ */
+\r
 // for old browsers\r
 window.undefined = window.undefined;\r
 \r
@@ -20,7 +26,7 @@ Ext = {
      * The version of the framework\r
      * @type String\r
      */\r
-    version : '3.0'\r
+    version : '3.0.1'\r
 };\r
 \r
 <div id="method-Ext-apply"></div>/**\r
@@ -47,20 +53,6 @@ Ext.apply = function(o, c, defaults){
 (function(){\r
     var idSeed = 0,\r
         toString = Object.prototype.toString,\r
-        //assume it's not null and not an array\r
-        isIterable = function(v){\r
-            //check for array or arguments\r
-            if(Ext.isArray(v) || v.callee){\r
-                return true;\r
-            }\r
-            //check for node list type\r
-            if(/NodeList|HTMLCollection/.test(toString.call(v))){\r
-                return true;\r
-            }\r
-            //NodeList has an item and length property\r
-            //IXMLDOMNodeList has nextNode method, needs to be checked first.\r
-            return ((v.nextNode || v.item) && Ext.isNumber(v.length));\r
-        },\r
         ua = navigator.userAgent.toLowerCase(),\r
         check = function(r){\r
             return r.test(ua);\r
@@ -98,10 +90,10 @@ Ext.apply = function(o, c, defaults){
     Ext.apply(Ext, {\r
         <div id="prop-Ext-SSL_SECURE_URL"></div>/**\r
          * URL to a blank file used by Ext when in secure mode for iframe src and onReady src to prevent\r
-         * the IE insecure content warning (defaults to javascript:false).\r
+         * the IE insecure content warning (<tt>'about:blank'</tt>, except for IE in secure mode, which is <tt>'javascript:""'</tt>).\r
          * @type String\r
          */\r
-        SSL_SECURE_URL : 'javascript:false',\r
+        SSL_SECURE_URL : isSecure && isIE ? 'javascript:""' : 'about:blank', \r
         <div id="prop-Ext-isStrict"></div>/**\r
          * True if the browser is in strict (standards-compliant) mode, as opposed to quirks mode\r
          * @type Boolean\r
@@ -155,7 +147,7 @@ Ext.apply = function(o, c, defaults){
         applyIf : function(o, c){\r
             if(o){\r
                 for(var p in c){\r
-                    if(Ext.isEmpty(o[p])){\r
+                    if(!Ext.isDefined(o[p])){\r
                         o[p] = c[p];\r
                     }\r
                 }\r
@@ -174,30 +166,27 @@ Ext.apply = function(o, c, defaults){
         },\r
 \r
         <div id="method-Ext-extend"></div>/**\r
-         * Extends one class with another class and optionally overrides members with the passed literal. This class\r
-         * also adds the function "override()" to the class that can be used to override\r
-         * members on an instance.\r
-         * * <p>\r
-         * This function also supports a 2-argument call in which the subclass's constructor is\r
-         * not passed as an argument. In this form, the parameters are as follows:</p><p>\r
-         * <div class="mdetail-params"><ul>\r
-         * <li><code>superclass</code>\r
-         * <div class="sub-desc">The class being extended</div></li>\r
-         * <li><code>overrides</code>\r
-         * <div class="sub-desc">A literal with members which are copied into the subclass's\r
-         * prototype, and are therefore shared among all instances of the new class.<p>\r
-         * This may contain a special member named <tt><b>constructor</b></tt>. This is used\r
-         * to define the constructor of the new class, and is returned. If this property is\r
-         * <i>not</i> specified, a constructor is generated and returned which just calls the\r
-         * superclass's constructor passing on its parameters.</p></div></li>\r
-         * </ul></div></p><p>\r
-         * For example, to create a subclass of the Ext GridPanel:\r
+         * <p>Extends one class to create a subclass and optionally overrides members with the passed literal. This method\r
+         * also adds the function "override()" to the subclass that can be used to override members of the class.</p>\r
+         * For example, to create a subclass of Ext GridPanel:\r
          * <pre><code>\r
 MyGridPanel = Ext.extend(Ext.grid.GridPanel, {\r
     constructor: function(config) {\r
-        // Your preprocessing here\r
-        MyGridPanel.superclass.constructor.apply(this, arguments);\r
-        // Your postprocessing here\r
+\r
+//      Create configuration for this Grid.\r
+        var store = new Ext.data.Store({...});\r
+        var colModel = new Ext.grid.ColumnModel({...});\r
+\r
+//      Create a new config object containing our computed properties\r
+//      *plus* whatever was in the config parameter.\r
+        config = Ext.apply({\r
+            store: store,\r
+            colModel: colModel\r
+        }, config);\r
+\r
+        MyGridPanel.superclass.constructor.call(this, config);\r
+\r
+//      Your postprocessing here\r
     },\r
 \r
     yourMethod: function() {\r
@@ -205,13 +194,25 @@ MyGridPanel = Ext.extend(Ext.grid.GridPanel, {
     }\r
 });\r
 </code></pre>\r
-         * </p>\r
-         * @param {Function} subclass The class inheriting the functionality\r
-         * @param {Function} superclass The class being extended\r
-         * @param {Object} overrides (optional) A literal with members which are copied into the subclass's\r
-         * prototype, and are therefore shared between all instances of the new class.\r
+         *\r
+         * <p>This function also supports a 3-argument call in which the subclass's constructor is\r
+         * passed as an argument. In this form, the parameters are as follows:</p>\r
+         * <div class="mdetail-params"><ul>\r
+         * <li><code>subclass</code> : Function <div class="sub-desc">The subclass constructor.</div></li>\r
+         * <li><code>superclass</code> : Function <div class="sub-desc">The constructor of class being extended</div></li>\r
+         * <li><code>overrides</code> : Object <div class="sub-desc">A literal with members which are copied into the subclass's\r
+         * prototype, and are therefore shared among all instances of the new class.</div></li>\r
+         * </ul></div>\r
+         *\r
+         * @param {Function} subclass The constructor of class being extended.\r
+         * @param {Object} overrides <p>A literal with members which are copied into the subclass's\r
+         * prototype, and are therefore shared between all instances of the new class.</p>\r
+         * <p>This may contain a special member named <tt><b>constructor</b></tt>. This is used\r
+         * to define the constructor of the new class, and is returned. If this property is\r
+         * <i>not</i> specified, a constructor is generated and returned which just calls the\r
+         * superclass's constructor passing on its parameters.</p>\r
+         * <p><b>It is essential that you call the superclass constructor in any provided constructor. See example code.</b></p>\r
          * @return {Function} The subclass constructor.\r
-         * @method extend\r
          */\r
         extend : function(){\r
             // inline overrides\r
@@ -247,7 +248,7 @@ MyGridPanel = Ext.extend(Ext.grid.GridPanel, {
                 });\r
                 sbp.override = io;\r
                 Ext.override(sb, overrides);\r
-                sb.extend = function(o){Ext.extend(sb, o);};\r
+                sb.extend = function(o){return Ext.extend(sb, o);};\r
                 return sb;\r
             };\r
         }(),\r
@@ -279,7 +280,7 @@ Ext.override(MyClass, {
             }\r
         },\r
 \r
-        /**\r
+        <div id="method-Ext-namespace"></div>/**\r
          * Creates namespaces to be used for scoping variables and classes so that they are not global.\r
          * Specifying the last node of a namespace implicitly creates all other nodes. Usage:\r
          * <pre><code>\r
@@ -291,6 +292,7 @@ Company.data.CustomStore = function(config) { ... }
          * @param {String} namespace1\r
          * @param {String} namespace2\r
          * @param {String} etc\r
+         * @return {Object} The namespace object. (If multiple arguments are passed, this will be the last namespace created)\r
          * @method namespace\r
          */\r
         namespace : function(){\r
@@ -311,18 +313,20 @@ Company.data.CustomStore = function(config) { ... }
          * @param {String} pre (optional) A prefix to add to the url encoded string\r
          * @return {String}\r
          */\r
-        urlEncode: function(o, pre){\r
-            var undef, buf = [], key, e = encodeURIComponent;\r
+        urlEncode : function(o, pre){\r
+            var empty,\r
+                buf = [],\r
+                e = encodeURIComponent;\r
 \r
-            for(key in o){\r
-                undef = !Ext.isDefined(o[key]);\r
-                Ext.each(undef ? key : o[key], function(val, i){\r
-                    buf.push("&", e(key), "=", (val != key || !undef) ? e(val) : "");\r
+            Ext.iterate(o, function(key, item){\r
+                empty = Ext.isEmpty(item);\r
+                Ext.each(empty ? key : item, function(val){\r
+                    buf.push('&', e(key), '=', (!Ext.isEmpty(val) && (val != key || !empty)) ? (Ext.isDate(val) ? Ext.encode(val).replace(/"/g, '') : e(val)) : '');\r
                 });\r
-            }\r
+            });\r
             if(!pre){\r
                 buf.shift();\r
-                pre = "";\r
+                pre = '';\r
             }\r
             return pre + buf.join('');\r
         },\r
@@ -337,6 +341,9 @@ Ext.urlDecode("foo=1&bar=2&bar=3&bar=4", false); // returns {foo: "1", bar: ["2"
          * @return {Object} A literal with members\r
          */\r
         urlDecode : function(string, overwrite){\r
+            if(Ext.isEmpty(string)){\r
+                return {};\r
+            }\r
             var obj = {},\r
                 pairs = string.split('&'),\r
                 d = decodeURIComponent,\r
@@ -353,11 +360,11 @@ Ext.urlDecode("foo=1&bar=2&bar=3&bar=4", false); // returns {foo: "1", bar: ["2"
         },\r
 \r
         <div id="method-Ext-urlAppend"></div>/**\r
-         * Appends content to the query string of a URL, which handles logic for whether to place\r
+         * Appends content to the query string of a URL, handling logic for whether to place\r
          * a question mark or ampersand.\r
-         * @param {String} url The url to append to.\r
-         * @@param {String} s The content to append to the url.\r
-         * @return (String) The appended string\r
+         * @param {String} url The URL to append to.\r
+         * @param {String} s The content to append to the URL.\r
+         * @return (String) The resulting URL\r
          */\r
         urlAppend : function(url, s){\r
             if(!Ext.isEmpty(s)){\r
@@ -387,19 +394,48 @@ Ext.urlDecode("foo=1&bar=2&bar=3&bar=4", false); // returns {foo: "1", bar: ["2"
                 }\r
         }(),\r
 \r
+        isIterable : function(v){\r
+            //check for array or arguments\r
+            if(Ext.isArray(v) || v.callee){\r
+                return true;\r
+            }\r
+            //check for node list type\r
+            if(/NodeList|HTMLCollection/.test(toString.call(v))){\r
+                return true;\r
+            }\r
+            //NodeList has an item and length property\r
+            //IXMLDOMNodeList has nextNode method, needs to be checked first.\r
+            return ((v.nextNode || v.item) && Ext.isNumber(v.length));\r
+        },\r
+\r
         <div id="method-Ext-each"></div>/**\r
-         * Iterates an array calling the passed function with each item, stopping if your function returns false. If the\r
-         * passed array is not really an array, your function is called once with it.\r
-         * The supplied function is called with (Object item, Number index, Array allItems).\r
-         * @param {Array/NodeList/Mixed} array\r
-         * @param {Function} fn\r
-         * @param {Object} scope\r
-         */\r
-        each: function(array, fn, scope){\r
+         * Iterates an array calling the supplied function.\r
+         * @param {Array/NodeList/Mixed} array The array to be iterated. If this\r
+         * argument is not really an array, the supplied function is called once.\r
+         * @param {Function} fn The function to be called with each item. If the\r
+         * supplied function returns false, iteration stops and this method returns\r
+         * the current <code>index</code>. This function is called with\r
+         * the following arguments:\r
+         * <div class="mdetail-params"><ul>\r
+         * <li><code>item</code> : <i>Mixed</i>\r
+         * <div class="sub-desc">The item at the current <code>index</code>\r
+         * in the passed <code>array</code></div></li>\r
+         * <li><code>index</code> : <i>Number</i>\r
+         * <div class="sub-desc">The current index within the array</div></li>\r
+         * <li><code>allItems</code> : <i>Array</i>\r
+         * <div class="sub-desc">The <code>array</code> passed as the first\r
+         * argument to <code>Ext.each</code>.</div></li>\r
+         * </ul></div>\r
+         * @param {Object} scope The scope (<code>this</code> reference) in which the specified function is executed.\r
+         * Defaults to the <code>item</code> at the current <code>index</code>\r
+         * within the passed <code>array</code>.\r
+         * @return See description for the fn parameter.\r
+         */\r
+        each : function(array, fn, scope){\r
             if(Ext.isEmpty(array, true)){\r
                 return;\r
             }\r
-            if(!isIterable(array) || Ext.isPrimitive(array)){\r
+            if(!Ext.isIterable(array) || Ext.isPrimitive(array)){\r
                 array = [array];\r
             }\r
             for(var i = 0, len = array.length; i < len; i++){\r
@@ -426,11 +462,14 @@ Ext.urlDecode("foo=1&bar=2&bar=3&bar=4", false); // returns {foo: "1", bar: ["2"
          * When iterating an object, the supplied function is called with each key-value pair in\r
          * the object.</div></li>\r
          * </ul></div>\r
-         * @param {Object} scope The scope to call the supplied function with, defaults to\r
-         * the specified <tt>object</tt>\r
+         * @param {Object} scope The scope (<code>this</code> reference) in which the specified function is executed. Defaults to\r
+         * the <code>object</code> being iterated.\r
          */\r
         iterate : function(obj, fn, scope){\r
-            if(isIterable(obj)){\r
+            if(Ext.isEmpty(obj)){\r
+                return;\r
+            }\r
+            if(Ext.isIterable(obj)){\r
                 Ext.each(obj, fn, scope);\r
                 return;\r
             }else if(Ext.isObject(obj)){\r
@@ -516,25 +555,34 @@ function(el){
         },\r
 \r
         <div id="method-Ext-isArray"></div>/**\r
-         * Returns true if the passed object is a JavaScript array, otherwise false.\r
-         * @param {Object} object The object to test\r
+         * Returns true if the passed value is a JavaScript array, otherwise false.\r
+         * @param {Mixed} value The value to test\r
          * @return {Boolean}\r
          */\r
         isArray : function(v){\r
             return toString.apply(v) === '[object Array]';\r
         },\r
 \r
-        <div id="method-Ext-isObject"></div>/**\r
-         * Returns true if the passed object is a JavaScript Object, otherwise false.\r
+        <div id="method-Ext-isDate"></div>/**\r
+         * Returns true if the passed object is a JavaScript date object, otherwise false.\r
          * @param {Object} object The object to test\r
          * @return {Boolean}\r
          */\r
+        isDate : function(v){\r
+            return toString.apply(v) === '[object Date]';\r
+        },\r
+\r
+        <div id="method-Ext-isObject"></div>/**\r
+         * Returns true if the passed value is a JavaScript Object, otherwise false.\r
+         * @param {Mixed} value The value to test\r
+         * @return {Boolean}\r
+         */\r
         isObject : function(v){\r
             return v && typeof v == "object";\r
         },\r
 \r
         <div id="method-Ext-isPrimitive"></div>/**\r
-         * Returns true if the passed object is a JavaScript 'primitive', a string, number or boolean.\r
+         * Returns true if the passed value is a JavaScript 'primitive', a string, number or boolean.\r
          * @param {Mixed} value The value to test\r
          * @return {Boolean}\r
          */\r
@@ -543,8 +591,8 @@ function(el){
         },\r
 \r
         <div id="method-Ext-isFunction"></div>/**\r
-         * Returns true if the passed object is a JavaScript Function, otherwise false.\r
-         * @param {Object} object The object to test\r
+         * Returns true if the passed value is a JavaScript Function, otherwise false.\r
+         * @param {Mixed} value The value to test\r
          * @return {Boolean}\r
          */\r
         isFunction : function(v){\r
@@ -552,38 +600,38 @@ function(el){
         },\r
 \r
         <div id="method-Ext-isNumber"></div>/**\r
-         * Returns true if the passed object is a number. Returns false for non-finite numbers.\r
-         * @param {Object} v The object to test\r
+         * Returns true if the passed value is a number. Returns false for non-finite numbers.\r
+         * @param {Mixed} value The value to test\r
          * @return {Boolean}\r
          */\r
-        isNumber: function(v){\r
+        isNumber : function(v){\r
             return typeof v === 'number' && isFinite(v);\r
         },\r
 \r
         <div id="method-Ext-isString"></div>/**\r
-         * Returns true if the passed object is a string.\r
-         * @param {Object} v The object to test\r
+         * Returns true if the passed value is a string.\r
+         * @param {Mixed} value The value to test\r
          * @return {Boolean}\r
          */\r
-        isString: function(v){\r
+        isString : function(v){\r
             return typeof v === 'string';\r
         },\r
 \r
         <div id="method-Ext-isBoolean"></div>/**\r
-         * Returns true if the passed object is a boolean.\r
-         * @param {Object} v The object to test\r
+         * Returns true if the passed value is a boolean.\r
+         * @param {Mixed} value The value to test\r
          * @return {Boolean}\r
          */\r
-        isBoolean: function(v){\r
+        isBoolean : function(v){\r
             return typeof v === 'boolean';\r
         },\r
 \r
         <div id="method-Ext-isDefined"></div>/**\r
-         * Returns true if the passed object is not undefined.\r
-         * @param {Object} v The object to test\r
+         * Returns true if the passed value is not undefined.\r
+         * @param {Mixed} value The value to test\r
          * @return {Boolean}\r
          */\r
-        isDefined: function(v){\r
+        isDefined : function(v){\r
             return typeof v !== 'undefined';\r
         },\r
 \r
@@ -596,7 +644,7 @@ function(el){
          * True if the detected browser uses WebKit.\r
          * @type Boolean\r
          */\r
-        isWebKit: isWebKit,\r
+        isWebKit : isWebKit,\r
         <div id="prop-Ext-isChrome"></div>/**\r
          * True if the detected browser is Chrome.\r
          * @type Boolean\r
@@ -684,7 +732,7 @@ function(el){
         isAir : isAir\r
     });\r
 \r
-    <div id="method-Ext-namespace"></div>/**\r
+    <div id="method-Ext-ns"></div>/**\r
      * Creates namespaces to be used for scoping variables and classes so that they are not global.\r
      * Specifying the last node of a namespace implicitly creates all other nodes. Usage:\r
      * <pre><code>\r
@@ -696,7 +744,8 @@ Company.data.CustomStore = function(config) { ... }
      * @param {String} namespace1\r
      * @param {String} namespace2\r
      * @param {String} etc\r
-     * @method namespace\r
+     * @return {Object} The namespace object. (If multiple arguments are passed, this will be the last namespace created)\r
+     * @method ns\r
      */\r
     Ext.ns = Ext.namespace;\r
 })();\r
@@ -710,9 +759,9 @@ Ext.ns("Ext", "Ext.util", "Ext.lib", "Ext.data");
  */\r
 Ext.apply(Function.prototype, {\r
      <div id="method-Function-createInterceptor"></div>/**\r
-     * Creates an interceptor function. The passed fcn is called before the original one. If it returns false,\r
+     * Creates an interceptor function. The passed function is called before the original one. If it returns false,\r
      * the original one is not called. The resulting function returns the results of the original function.\r
-     * The passed fcn is called with the parameters of the original function. Example usage:\r
+     * The passed function is called with the parameters of the original function. Example usage:\r
      * <pre><code>\r
 var sayHi = function(name){\r
     alert('Hi, ' + name);\r
@@ -730,7 +779,8 @@ sayHiToFriend('Fred');  // no alert
 sayHiToFriend('Brian'); // alerts "Hi, Brian"\r
 </code></pre>\r
      * @param {Function} fcn The function to call before the original\r
-     * @param {Object} scope (optional) The scope of the passed fcn (Defaults to scope of original function or window)\r
+     * @param {Object} scope (optional) The scope (<code><b>this</b></code> reference) in which the passed function is executed.\r
+     * <b>If omitted, defaults to the scope in which the original function is called or the browser window.</b>\r
      * @return {Function} The new function\r
      */\r
     createInterceptor : function(fcn, scope){\r
@@ -805,10 +855,11 @@ var btn = new Ext.Button({
 // "Hi, Fred. You clicked the "Say Hi" button."\r
 btn.on('click', sayHi.createDelegate(btn, ['Fred']));\r
 </code></pre>\r
-     * @param {Object} obj (optional) The object for which the scope is set\r
+     * @param {Object} scope (optional) The scope (<code><b>this</b></code> reference) in which the function is executed.\r
+     * <b>If omitted, defaults to the browser window.</b>\r
      * @param {Array} args (optional) Overrides arguments for the call. (Defaults to the arguments passed by the caller)\r
      * @param {Boolean/Number} appendArgs (optional) if True args are appended to call args instead of overriding,\r
-     *                                             if a number the args are inserted at the specified position\r
+     * if a number the args are inserted at the specified position\r
      * @return {Function} The new function\r
      */\r
     createDelegate : function(obj, args, appendArgs){\r
@@ -847,10 +898,11 @@ sayHi.defer(2000, this, ['Fred']);
 }).defer(100);\r
 </code></pre>\r
      * @param {Number} millis The number of milliseconds for the setTimeout call (if less than or equal to 0 the function is executed immediately)\r
-     * @param {Object} obj (optional) The object for which the scope is set\r
+     * @param {Object} scope (optional) The scope (<code><b>this</b></code> reference) in which the function is executed.\r
+     * <b>If omitted, defaults to the browser window.</b>\r
      * @param {Array} args (optional) Overrides arguments for the call. (Defaults to the arguments passed by the caller)\r
      * @param {Boolean/Number} appendArgs (optional) if True args are appended to call args instead of overriding,\r
-     *                                             if a number the args are inserted at the specified position\r
+     * if a number the args are inserted at the specified position\r
      * @return {Number} The timeout id that can be used with clearTimeout\r
      */\r
     defer : function(millis, obj, args, appendArgs){\r
@@ -897,12 +949,16 @@ Ext.applyIf(Array.prototype, {
     <div id="method-Array-indexOf"></div>/**\r
      * Checks whether or not the specified object exists in the array.\r
      * @param {Object} o The object to check for\r
+     * @param {Number} from (Optional) The index at which to begin the search\r
      * @return {Number} The index of o in the array (or -1 if it is not found)\r
      */\r
-    indexOf : function(o){\r
-        for (var i = 0, len = this.length; i < len; i++){\r
-            if(this[i] == o){\r
-                return i;\r
+    indexOf : function(o, from){\r
+        var len = this.length;\r
+        from = from || 0;\r
+        from += (from < 0) ? len : 0;\r
+        for (; from < len; ++from){\r
+            if(this[from] === o){\r
+                return from;\r
             }\r
         }\r
         return -1;\r
@@ -921,6 +977,6 @@ Ext.applyIf(Array.prototype, {
         return this;\r
     }\r
 });\r
-</pre>    \r
-</body>\r
+</pre>
+</body>
 </html>
\ No newline at end of file