Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / source / Function.html
index f275f16..f02f436 100644 (file)
+<!DOCTYPE html>
 <html>
 <head>
-  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   <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>
+  <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
+  <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
+  <style type="text/css">
+    .highlight { display: block; background-color: #ddd; }
+  </style>
+  <script type="text/javascript">
+    function highlight() {
+      document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
+    }
+  </script>
 </head>
-<body  onload="prettyPrint();">
-    <pre class="prettyprint lang-js">/*!
- * Ext JS Library 3.3.1
- * Copyright(c) 2006-2010 Sencha Inc.
- * licensing@sencha.com
- * http://www.sencha.com/license
- */
-<div id="cls-Ext.util.Functions"></div>/**
- * @class Ext.util.Functions
- * @singleton
+<body onload="prettyPrint(); highlight();">
+  <pre class="prettyprint lang-js"><span id='Function'>/**
+</span> * @class Function
+ *
+ * Every function in JavaScript is actually a `Function` object.
+ *
+ * `Function` objects created with the `Function` constructor are parsed when the
+ * function is created. This is less efficient than declaring a function and
+ * calling it within your code, because functions declared with the function
+ * statement are parsed with the rest of the code.
+ *
+ * All arguments passed to the function are treated as the names of the
+ * identifiers of the parameters in the function to be created, in the order in
+ * which they are passed.
+ *
+ * Invoking the `Function` constructor as a function (without using the `new`
+ * operator) has the same effect as invoking it as a constructor.
+ *
+ * # Specifying arguments with the `Function` constructor
+ *
+ * The following code creates a `Function` object that takes two arguments.
+ *
+ *     // Example can be run directly in your JavaScript console
+ *
+ *     // Create a function that takes two arguments and returns the sum of those
+ *     arguments
+ *     var adder = new Function(&quot;a&quot;, &quot;b&quot;, &quot;return a + b&quot;);
+ *
+ *     // Call the function
+ *     adder(2, 6);
+ *     // &gt; 8
+ *
+ * The arguments &quot;a&quot; and &quot;b&quot; are formal argument names that are used in the
+ * function body, &quot;return a + b&quot;.
+ *
+ * &lt;div class=&quot;notice&quot;&gt;
+ * Documentation for this class comes from &lt;a href=&quot;https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Function&quot;&gt;MDN&lt;/a&gt;
+ * and is available under &lt;a href=&quot;http://creativecommons.org/licenses/by-sa/2.0/&quot;&gt;Creative Commons: Attribution-Sharealike license&lt;/a&gt;.
+ * &lt;/div&gt;
  */
-Ext.util.Functions = {
-    <div id="method-Ext.util.Functions-createInterceptor"></div>/**
-     * Creates an interceptor function. The passed function is called before the original one. If it returns false,
-     * the original one is not called. The resulting function returns the results of the original function.
-     * The passed function is called with the parameters of the original function. Example usage:
-     * <pre><code>
-var sayHi = function(name){
-    alert('Hi, ' + name);
-}
-
-sayHi('Fred'); // alerts "Hi, Fred"
-
-// create a new function that validates input without
-// directly modifying the original function:
-var sayHiToFriend = Ext.createInterceptor(sayHi, function(name){
-    return name == 'Brian';
-});
-
-sayHiToFriend('Fred');  // no alert
-sayHiToFriend('Brian'); // alerts "Hi, Brian"
-       </code></pre>
-     * @param {Function} origFn The original function.
-     * @param {Function} newFn The function to call before the original
-     * @param {Object} scope (optional) The scope (<code><b>this</b></code> reference) in which the passed function is executed.
-     * <b>If omitted, defaults to the scope in which the original function is called or the browser window.</b>
-     * @return {Function} The new function
-     */
-    createInterceptor: function(origFn, newFn, scope) { 
-        var method = origFn;
-        if (!Ext.isFunction(newFn)) {
-            return origFn;
-        }
-        else {
-            return function() {
-                var me = this,
-                    args = arguments;
-                newFn.target = me;
-                newFn.method = origFn;
-                return (newFn.apply(scope || me || window, args) !== false) ?
-                        origFn.apply(me || window, args) :
-                        null;
-            };
-        }
-    },
-
-    <div id="method-Ext.util.Functions-createDelegate"></div>/**
-     * Creates a delegate (callback) that sets the scope to obj.
-     * Call directly on any function. Example: <code>Ext.createDelegate(this.myFunction, this, [arg1, arg2])</code>
-     * Will create a function that is automatically scoped to obj so that the <tt>this</tt> variable inside the
-     * callback points to obj. Example usage:
-     * <pre><code>
-var sayHi = function(name){
-    // Note this use of "this.text" here.  This function expects to
-    // execute within a scope that contains a text property.  In this
-    // example, the "this" variable is pointing to the btn object that
-    // was passed in createDelegate below.
-    alert('Hi, ' + name + '. You clicked the "' + this.text + '" button.');
-}
-
-var btn = new Ext.Button({
-    text: 'Say Hi',
-    renderTo: Ext.getBody()
-});
-
-// This callback will execute in the scope of the
-// button instance. Clicking the button alerts
-// "Hi, Fred. You clicked the "Say Hi" button."
-btn.on('click', Ext.createDelegate(sayHi, btn, ['Fred']));
-       </code></pre>
-     * @param {Function} fn The function to delegate.
-     * @param {Object} scope (optional) The scope (<code><b>this</b></code> reference) in which the function is executed.
-     * <b>If omitted, defaults to the browser window.</b>
-     * @param {Array} args (optional) Overrides arguments for the call. (Defaults to the arguments passed by the caller)
-     * @param {Boolean/Number} appendArgs (optional) if True args are appended to call args instead of overriding,
-     * if a number the args are inserted at the specified position
-     * @return {Function} The new function
-     */
-    createDelegate: function(fn, obj, args, appendArgs) {
-        if (!Ext.isFunction(fn)) {
-            return fn;
-        }
-        return function() {
-            var callArgs = args || arguments;
-            if (appendArgs === true) {
-                callArgs = Array.prototype.slice.call(arguments, 0);
-                callArgs = callArgs.concat(args);
-            }
-            else if (Ext.isNumber(appendArgs)) {
-                callArgs = Array.prototype.slice.call(arguments, 0);
-                // copy arguments first
-                var applyArgs = [appendArgs, 0].concat(args);
-                // create method call params
-                Array.prototype.splice.apply(callArgs, applyArgs);
-                // splice them in
-            }
-            return fn.apply(obj || window, callArgs);
-        };
-    },
-
-    <div id="method-Ext.util.Functions-defer"></div>/**
-     * Calls this function after the number of millseconds specified, optionally in a specific scope. Example usage:
-     * <pre><code>
-var sayHi = function(name){
-    alert('Hi, ' + name);
-}
-
-// executes immediately:
-sayHi('Fred');
-
-// executes after 2 seconds:
-Ext.defer(sayHi, 2000, this, ['Fred']);
 
-// this syntax is sometimes useful for deferring
-// execution of an anonymous function:
-Ext.defer(function(){
-    alert('Anonymous');
-}, 100);
-       </code></pre>
-     * @param {Function} fn The function to defer.
-     * @param {Number} millis The number of milliseconds for the setTimeout call (if less than or equal to 0 the function is executed immediately)
-     * @param {Object} scope (optional) The scope (<code><b>this</b></code> reference) in which the function is executed.
-     * <b>If omitted, defaults to the browser window.</b>
-     * @param {Array} args (optional) Overrides arguments for the call. (Defaults to the arguments passed by the caller)
-     * @param {Boolean/Number} appendArgs (optional) if True args are appended to call args instead of overriding,
-     * if a number the args are inserted at the specified position
-     * @return {Number} The timeout id that can be used with clearTimeout
-     */
-    defer: function(fn, millis, obj, args, appendArgs) {
-        fn = Ext.util.Functions.createDelegate(fn, obj, args, appendArgs);
-        if (millis > 0) {
-            return setTimeout(fn, millis);
-        }
-        fn();
-        return 0;
-    },
-
-
-    <div id="method-Ext.util.Functions-createSequence"></div>/**
-     * Create a combined function call sequence of the original function + the passed function.
-     * The resulting function returns the results of the original function.
-     * The passed fcn is called with the parameters of the original function. Example usage:
-     * 
-
-var sayHi = function(name){
-    alert('Hi, ' + name);
-}
-
-sayHi('Fred'); // alerts "Hi, Fred"
-
-var sayGoodbye = Ext.createSequence(sayHi, function(name){
-    alert('Bye, ' + name);
-});
-
-sayGoodbye('Fred'); // both alerts show
-
-     * @param {Function} origFn The original function.
-     * @param {Function} newFn The function to sequence
-     * @param {Object} scope (optional) The scope (this reference) in which the passed function is executed.
-     * If omitted, defaults to the scope in which the original function is called or the browser window.
-     * @return {Function} The new function
-     */
-    createSequence: function(origFn, newFn, scope) {
-        if (!Ext.isFunction(newFn)) {
-            return origFn;
-        }
-        else {
-            return function() {
-                var retval = origFn.apply(this || window, arguments);
-                newFn.apply(scope || this || window, arguments);
-                return retval;
-            };
-        }
-    }
-};
-
-/**
- * Shorthand for {@link Ext.util.Functions#defer}   
- * @param {Function} fn The function to defer.
- * @param {Number} millis The number of milliseconds for the setTimeout call (if less than or equal to 0 the function is executed immediately)
- * @param {Object} scope (optional) The scope (<code><b>this</b></code> reference) in which the function is executed.
- * <b>If omitted, defaults to the browser window.</b>
- * @param {Array} args (optional) Overrides arguments for the call. (Defaults to the arguments passed by the caller)
- * @param {Boolean/Number} appendArgs (optional) if True args are appended to call args instead of overriding,
- * if a number the args are inserted at the specified position
- * @return {Number} The timeout id that can be used with clearTimeout
- * @member Ext
- * @method defer
+<span id='Function-method-constructor'>/**
+</span> * @method constructor
+ * Creates new Function object.
+ *
+ * @param {String...} args
+ * Names to be used by the function as formal argument names. Each must be a
+ * string that corresponds to a valid JavaScript identifier or a list of such
+ * strings separated with a comma; for example &quot;`x`&quot;, &quot;`theValue`&quot;, or &quot;`a,b`&quot;.
+ * @param {String} functionBody
+ * A string containing the JavaScript statements comprising the function
+ * definition.
  */
 
-Ext.defer = Ext.util.Functions.defer;
+// Properties
 
-/**
- * Shorthand for {@link Ext.util.Functions#createInterceptor}   
- * @param {Function} origFn The original function.
- * @param {Function} newFn The function to call before the original
- * @param {Object} scope (optional) The scope (<code><b>this</b></code> reference) in which the passed function is executed.
- * <b>If omitted, defaults to the scope in which the original function is called or the browser window.</b>
- * @return {Function} The new function
- * @member Ext
- * @method defer
+<span id='Function-property-length'>/**
+</span> * @property {Number} length
+ * Specifies the number of arguments expected by the function.
  */
 
-Ext.createInterceptor = Ext.util.Functions.createInterceptor;
+//Methods
 
-/**
- * Shorthand for {@link Ext.util.Functions#createSequence}
- * @param {Function} origFn The original function.
- * @param {Function} newFn The function to sequence
- * @param {Object} scope (optional) The scope (this reference) in which the passed function is executed.
- * If omitted, defaults to the scope in which the original function is called or the browser window.
- * @return {Function} The new function
- * @member Ext
- * @method defer
+<span id='Function-method-apply'>/**
+</span> * @method apply
+ * Applies the method of another object in the context of a different object (the
+ * calling object); arguments can be passed as an Array object.
+ *
+ * You can assign a different this object when calling an existing function. `this` refers to the
+ * current object, the calling object. With `apply`, you can write a method once and then inherit it
+ * in another object, without having to rewrite the method for the new object.
+ *
+ * `apply` is very similar to call, except for the type of arguments it supports. You can use an
+ * arguments array instead of a named set of parameters. With apply, you can use an array literal, for
+ * example, `fun.apply(this, ['eat', 'bananas'])`, or an Array object, for example, `fun.apply(this,
+ * new Array('eat', 'bananas'))`.
+ *
+ * You can also use arguments for the `argsArray` parameter. `arguments` is a local variable of a
+ * function. It can be used for all unspecified arguments of the called object. Thus, you do not have
+ * to know the arguments of the called object when you use the `apply` method. You can use arguments
+ * to pass all the arguments to the called object. The called object is then responsible for handling
+ * the arguments.
+ *
+ * Since ECMAScript 5th Edition you can also use any kind of object which is array like, so in
+ * practice this means it's going to have a property length and integer properties in the range
+ * `[0...length)`. As an example you can now use a NodeList or a own custom object like `{'length': 2,
+ * '0': 'eat', '1': 'bananas'}`.
+ *
+ * You can use `apply` to chain constructors for an object, similar to Java. In the following example,
+ * the constructor for the `Product` object is defined with two parameters, `name` and `value`. Two
+ * other functions `Food` and `Toy` invoke `Product` passing `this` and `arguments`. `Product`
+ * initializes the properties `name` and `price`, both specialized functions define the category. In
+ * this example, the `arguments` object is fully passed to the product constructor and corresponds to
+ * the two defined parameters.
+ *
+ *     function Product(name, price) {
+ *         this.name = name;
+ *         this.price = price;
+ *
+ *         if (price &lt; 0)
+ *             throw RangeError('Cannot create product &quot;' + name + '&quot; with a negative price');
+ *         return this;
+ *     }
+ *
+ *     function Food(name, price) {
+ *         Product.apply(this, arguments);
+ *         this.category = 'food';
+ *     }
+ *     Food.prototype = new Product();
+ *
+ *     function Toy(name, price) {
+ *         Product.apply(this, arguments);
+ *         this.category = 'toy';
+ *     }
+ *     Toy.prototype = new Product();
+ *
+ *     var cheese = new Food('feta', 5);
+ *     var fun = new Toy('robot', 40);
+ *
+ * Clever usage of `apply` allows you to use built-ins functions for some tasks that otherwise
+ * probably would have been written by looping over the array values. As an example here we are going
+ * to use Math.max/Math.min to find out the maximum/minimum value in an array.
+ *
+ *     //min/max number in an array
+ *     var numbers = [5, 6, 2, 3, 7];
+ *
+ *     //using Math.min/Math.max apply
+ *     var max = Math.max.apply(null, numbers); // This about equal to Math.max(numbers[0], ...) or
+ *     // Math.max(5, 6, ..)
+ *     var min = Math.min.apply(null, numbers);
+ *
+ *     //vs. simple loop based algorithm
+ *     max = -Infinity, min = +Infinity;
+ *
+ *     for (var i = 0; i &lt; numbers.length; i++) {
+ *     if (numbers[i] &gt; max)
+ *         max = numbers[i];
+ *     if (numbers[i] &lt; min)
+ *         min = numbers[i];
+ *     }
+ *
+ * But beware: in using `apply` this way, you run the risk of exceeding the JavaScript engine's
+ * argument length limit. The consequences of applying a function with too many arguments (think more
+ * than tens of thousands of arguments) vary across engines, because the limit (indeed even the nature
+ * of any excessively-large-stack behavior) is unspecified. Some engines will throw an exception. More
+ * perniciously, others will arbitrarily limit the number of arguments actually passed to the applied
+ * function. (To illustrate this latter case: if such an engine had a limit of four arguments [actual
+ * limits are of course significantly higher], it would be as if the arguments 5, 6, 2, 3 had been
+ * passed to apply in the examples above, rather than the full array.)  If your value array might grow
+ * into the tens of thousands, use a hybrid strategy: apply your function to chunks of the array at a
+ * time:
+ *
+ *     function minOfArray(arr)
+ *     {
+ *         var min = Infinity;
+ *         var QUANTUM = 32768;
+ *         for (var i = 0, len = arr.length; i &lt; len; i += QUANTUM)
+ *         {
+ *             var submin = Math.min.apply(null, numbers.slice(i, Math.min(i + QUANTUM, len)));
+ *             min = Math.min(submin, min);
+ *         }
+ *     return min;
+ *     }
+ *
+ *     var min = minOfArray([5, 6, 2, 3, 7]);
+ *
+ * @param {Object} thisArg The value of this provided for the call to fun. Note that this may not be
+ * the actual value seen by the method: if the method is a function in non-strict mode code, null and
+ * undefined will be replaced with the global object, and primitive values will be boxed.
+ * @param {Array} argsArray An array like object, specifying the arguments with which fun should be
+ * called, or null or undefined if no arguments should be provided to the function.
+ * @return {Object} Returns what the function returns.
  */
 
-Ext.createSequence = Ext.util.Functions.createSequence;
-
-<div id="method-Ext-defer"></div>/**
- * Shorthand for {@link Ext.util.Functions#createDelegate}
- * @param {Function} fn The function to delegate.
- * @param {Object} scope (optional) The scope (<code><b>this</b></code> reference) in which the function is executed.
- * <b>If omitted, defaults to the browser window.</b>
- * @param {Array} args (optional) Overrides arguments for the call. (Defaults to the arguments passed by the caller)
- * @param {Boolean/Number} appendArgs (optional) if True args are appended to call args instead of overriding,
- * if a number the args are inserted at the specified position
- * @return {Function} The new function
- * @member Ext
- * @method defer
+<span id='Function-method-call'>/**
+</span> * @method call
+ * Calls (executes) a method of another object in the context of a different
+ * object (the calling object); arguments can be passed as they are.
+ *
+ * You can assign a different this object when calling an existing function. `this` refers to the
+ * current object, the calling object.
+ *
+ * With `call`, you can write a method once and then inherit it in another object, without having to
+ * rewrite the method for the new object.
+ *
+ * You can use call to chain constructors for an object, similar to Java. In the following example,
+ * the constructor for the product object is defined with two parameters, name and value. Another
+ * object, `prod_dept`, initializes its unique variable (`dept`) and calls the constructor for
+ * `product` in its constructor to initialize the other variables.
+ *
+ *     function Product(name, price) {
+ *         this.name = name;
+ *         this.price = price;
+ *
+ *         if (price &lt; 0)
+ *             throw RangeError('Cannot create product &quot;' + name + '&quot; with a negative price');
+ *         return this;
+ *     }
+ *
+ *     function Food(name, price) {
+ *         Product.call(this, name, price);
+ *         this.category = 'food';
+ *     }
+ *     Food.prototype = new Product();
+ *
+ *     function Toy(name, price) {
+ *         Product.call(this, name, price);
+ *         this.category = 'toy';
+ *     }
+ *     Toy.prototype = new Product();
+ *
+ *     var cheese = new Food('feta', 5);
+ *     var fun = new Toy('robot', 40);
+ *
+ * In this purely constructed example, we create anonymous function and use `call` to invoke it on
+ * every object in an array. The main purpose of the anonymous function here is to add a print
+ * function to every object, which is able to print the right index of the object in the array.
+ * Passing the object as `this` value was not strictly necessary, but is done for explanatory purpose.
+ *
+ *     var animals = [
+ *     {species: 'Lion', name: 'King'},
+ *     {species: 'Whale', name: 'Fail'}
+ *     ];
+ *
+ *     for (var i = 0; i &lt; animals.length; i++) {
+ *         (function (i) {
+ *         this.print = function () {
+ *             console.log('#' + i  + ' ' + this.species + ': ' + this.name);
+ *         }
+ *     }).call(animals[i], i);
+ *     }
+ *
+ * @param {Object} thisArg The value of this provided for the call to `fun`.Note that this may not be
+ * the actual value seen by the method: if the method is a function in non-strict mode code, `null`
+ * and `undefined` will be replaced with the global object, and primitive values will be boxed.
+ * @param {Object...} args Arguments for the object.
+ * @return {Object} Returns what the function returns.
  */
-Ext.createDelegate = Ext.util.Functions.createDelegate;
-</pre>    
+
+<span id='Function-method-toString'>/**
+</span> * @method toString
+ * Returns a string representing the source code of the function. Overrides the
+ * `Object.toString` method.
+ *
+ * The {@link Function} object overrides the `toString` method of the Object object; it does
+ * not inherit Object.toString. For `Function` objects, the `toString` method returns a string
+ * representation of the object.
+ *
+ * JavaScript calls the `toString` method automatically when a `Function` is to be represented as a
+ * text value or when a Function is referred to in a string concatenation.
+ *
+ * For `Function` objects, the built-in `toString` method decompiles the function back into the
+ * JavaScript source that defines the function. This string includes the `function` keyword, the
+ * argument list, curly braces, and function body.
+ *
+ * @return {String} The function as a string.
+ */</pre>
 </body>
-</html>
\ No newline at end of file
+</html>