X-Git-Url: http://git.ithinksw.org/extjs.git/blobdiff_plain/f5240829880f87e0cf581c6a296e436fdef0ef80..HEAD:/docs/source/Function.html diff --git a/docs/source/Function.html b/docs/source/Function.html index fdc5d6a2..f02f436c 100644 --- a/docs/source/Function.html +++ b/docs/source/Function.html @@ -1,251 +1,275 @@ + - + The source code - - + + + + - -
/*!
- * Ext JS Library 3.3.0
- * Copyright(c) 2006-2010 Ext JS, Inc.
- * licensing@extjs.com
- * http://www.extjs.com/license
- */
-
/** - * @class Ext.util.Functions - * @singleton + +
/**
+ * @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("a", "b", "return a + b");
+ *
+ *     // Call the function
+ *     adder(2, 6);
+ *     // > 8
+ *
+ * The arguments "a" and "b" are formal argument names that are used in the
+ * function body, "return a + b".
+ *
+ * <div class="notice">
+ * Documentation for this class comes from <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Function">MDN</a>
+ * and is available under <a href="http://creativecommons.org/licenses/by-sa/2.0/">Creative Commons: Attribution-Sharealike license</a>.
+ * </div>
  */
-Ext.util.Functions = {
-    
/** - * 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: - *

-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"
-       
- * @param {Function} origFn The original function. - * @param {Function} newFn The function to call before the original - * @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 - */ - 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; - }; - } - }, - -
/** - * Creates a delegate (callback) that sets the scope to obj. - * Call directly on any function. Example: Ext.createDelegate(this.myFunction, this, [arg1, arg2]) - * Will create a function that is automatically scoped to obj so that the this variable inside the - * callback points to obj. Example usage: - *

-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']));
-       
- * @param {Function} fn The function to delegate. - * @param {Object} scope (optional) The scope (this reference) in which the function is executed. - * If omitted, defaults to the browser window. - * @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); - }; - }, - -
/** - * Calls this function after the number of millseconds specified, optionally in a specific scope. Example usage: - *

-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);
-       
- * @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 (this reference) in which the function is executed. - * If omitted, defaults to the browser window. - * @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; - }, - - -
/** - * 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 (this reference) in which the function is executed. - * If omitted, defaults to the browser window. - * @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 +/** + * @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 "`x`", "`theValue`", or "`a,b`". + * @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 (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 +/** + * @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 +/** + * @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 < 0) + * throw RangeError('Cannot create product "' + name + '" 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 < numbers.length; i++) { + * if (numbers[i] > max) + * max = numbers[i]; + * if (numbers[i] < 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 < 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; - -
/** - * Shorthand for {@link Ext.util.Functions#createDelegate} - * @param {Function} fn The function to delegate. - * @param {Object} scope (optional) The scope (this reference) in which the function is executed. - * If omitted, defaults to the browser window. - * @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 +/** + * @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 < 0) + * throw RangeError('Cannot create product "' + name + '" 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 < 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; -
+ +/** + * @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. + */
- \ No newline at end of file +