Rambox-CE/ext/packages/sencha-core/src/lang/Function.js

/**
 * @class Ext.Function
 *
 * A collection of useful static methods to deal with function callbacks.
 * @singleton
 */
Ext.Function = (function() {
// @define Ext.lang.Function
// @define Ext.Function
// @require Ext
// @require Ext.lang.Array
    var lastTime = 0,
        animFrameId,
        animFrameHandlers = [],
        animFrameNoArgs = [],
        idSource = 0,
        animFrameMap = {},
        win = window,
        requestAnimFrame = win.requestAnimationFrame || win.webkitRequestAnimationFrame ||
            win.mozRequestAnimationFrame || win.oRequestAnimationFrame ||
            function(callback) {
                var currTime = Ext.now(),
                    timeToCall = Math.max(0, 16 - (currTime - lastTime)),
                    id = win.setTimeout(function() {
                        callback(currTime + timeToCall);
                    }, timeToCall);
                lastTime = currTime + timeToCall;
                return id;
            },
        fireHandlers = function() {
            var len = animFrameHandlers.length,
                id, i, handler;

            animFrameId = null;
            // Fire all animation frame handlers in one go
            for (i = 0; i < len; i++) {
                handler = animFrameHandlers[i];
                id = handler[3];
                
                // Check if this timer has been canceled; its map entry is going to be removed
                if (animFrameMap[id]) {
                    handler[0].apply(handler[1] || Ext.global, handler[2] || animFrameNoArgs);
                    delete animFrameMap[id];
                }
            }

            // Clear all fired animation frame handlers, don't forget that new handlers
            // could have been created in user handler functions called in the loop above
            animFrameHandlers = animFrameHandlers.slice(len);
        },
        fireElevatedHandlers = function() {
            Ext.elevateFunction(fireHandlers);
        },
        ExtFunction = {
        /**
         * A very commonly used method throughout the framework. It acts as a wrapper around another method
         * which originally accepts 2 arguments for `name` and `value`.
         * The wrapped function then allows "flexible" value setting of either:
         *
         * - `name` and `value` as 2 arguments
         * - one single object argument with multiple key - value pairs
         *
         * For example:
         *
         *     var setValue = Ext.Function.flexSetter(function(name, value) {
         *         this[name] = value;
         *     });
         *
         *     // Afterwards
         *     // Setting a single name - value
         *     setValue('name1', 'value1');
         *
         *     // Settings multiple name - value pairs
         *     setValue({
         *         name1: 'value1',
         *         name2: 'value2',
         *         name3: 'value3'
         *     });
         *
         * @param {Function} setter The single value setter method.
         * @param {String} setter.name The name of the value being set.
         * @param {Object} setter.value The value being set.
         * @return {Function}
         */
        flexSetter: function(setter) {
            return function(name, value) {
                var k, i;

                if (name !== null) {
                    if (typeof name !== 'string') {
                        for (k in name) {
                            if (name.hasOwnProperty(k)) {
                                setter.call(this, k, name[k]);
                            }
                        }

                        if (Ext.enumerables) {
                            for (i = Ext.enumerables.length; i--;) {
                                k = Ext.enumerables[i];
                                if (name.hasOwnProperty(k)) {
                                    setter.call(this, k, name[k]);
                                }
                            }
                        }
                    } else {
                        setter.call(this, name, value);
                    }
                }

                return this;
            };
        },

        /**
         * Create a new function from the provided `fn`, change `this` to the provided scope,
         * optionally overrides arguments for the call. Defaults to the arguments passed by
         * the caller.
         *
         * {@link Ext#bind Ext.bind} is alias for {@link Ext.Function#bind Ext.Function.bind}
         * 
         * **NOTE:** This method is deprecated. Use the standard `bind` method of JavaScript
         * `Function` instead:
         * 
         *      function foo () {
         *          ...
         *      }
         *      
         *      var fn = foo.bind(this);
         *
         * This method is unavailable natively on IE8 and IE/Quirks but Ext JS provides a
         * "polyfill" to emulate the important features of the standard `bind` method. In
         * particular, the polyfill only provides binding of "this" and optional arguments.
         * 
         * @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 default global environment object (usually 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.
         */
        bind: function(fn, scope, args, appendArgs) {
            if (arguments.length === 2) {
                return function() {
                    return fn.apply(scope, arguments);
                };
            }

            var method = fn,
                slice = Array.prototype.slice;

            return function() {
                var callArgs = args || arguments;

                if (appendArgs === true) {
                    callArgs = slice.call(arguments, 0);
                    callArgs = callArgs.concat(args);
                }
                else if (typeof appendArgs == 'number') {
                    callArgs = slice.call(arguments, 0); // copy arguments first
                    Ext.Array.insert(callArgs, appendArgs, args);
                }

                return method.apply(scope || Ext.global, callArgs);
            };
        },

        /**
         * Captures the given parameters for a later call to `Ext.callback`. This binding is
         * most useful for resolving scopes for example to an `Ext.app.ViewController`.
         *
         * The arguments match that of `Ext.callback` except for the `args` which, if provided
         * to this method, are prepended to any arguments supplied by the eventual caller of
         * the returned function.
         *
         * @return {Function} A function that, when called, uses `Ext.callback` to call the
         * captured `callback`.
         * @since 5.0.0
         */
        bindCallback: function (callback, scope, args, delay, caller) {
            return function () {
                var a = Ext.Array.slice(arguments);
                return Ext.callback(callback, scope, args ? args.concat(a) : a, delay, caller);
            };
        },

        /**
         * Create a new function from the provided `fn`, the arguments of which are pre-set to `args`.
         * New arguments passed to the newly created callback when it's invoked are appended after the pre-set ones.
         * This is especially useful when creating callbacks.
         *
         * For example:
         *
         *     var originalFunction = function(){
         *         alert(Ext.Array.from(arguments).join(' '));
         *     };
         *
         *     var callback = Ext.Function.pass(originalFunction, ['Hello', 'World']);
         *
         *     callback(); // alerts 'Hello World'
         *     callback('by Me'); // alerts 'Hello World by Me'
         *
         * {@link Ext#pass Ext.pass} is alias for {@link Ext.Function#pass Ext.Function.pass}
         *
         * @param {Function} fn The original function.
         * @param {Array} args The arguments to pass to new callback.
         * @param {Object} scope (optional) The scope (`this` reference) in which the function is executed.
         * @return {Function} The new callback function.
         */
        pass: function(fn, args, scope) {
            if (!Ext.isArray(args)) {
                if (Ext.isIterable(args)) {
                    args = Ext.Array.clone(args);
                } else {
                    args = args !== undefined ? [args] : [];
                }
            }

            return function() {
                var fnArgs = args.slice();
                fnArgs.push.apply(fnArgs, arguments);
                return fn.apply(scope || this, fnArgs);
            };
        },

        /**
         * Create an alias to the provided method property with name `methodName` of `object`.
         * Note that the execution scope will still be bound to the provided `object` itself.
         *
         * @param {Object/Function} object
         * @param {String} methodName
         * @return {Function} aliasFn
         */
        alias: function(object, methodName) {
            return function() {
                return object[methodName].apply(object, arguments);
            };
        },

        /**
         * Create a "clone" of the provided method. The returned method will call the given
         * method passing along all arguments and the "this" pointer and return its result.
         *
         * @param {Function} method
         * @return {Function} cloneFn
         */
        clone: function(method) {
            return function() {
                return method.apply(this, arguments);
            };
        },

        /**
         * 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.Function.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] 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.**
         * @param {Object} [returnValue=null] The value to return if the passed function return `false`.
         * @return {Function} The new function.
         */
        createInterceptor: function(origFn, newFn, scope, returnValue) {
            if (!Ext.isFunction(newFn)) {
                return origFn;
            } else {
                returnValue = Ext.isDefined(returnValue) ? returnValue : null;
                return function() {
                    var me = this,
                        args = arguments;

                    newFn.target = me;
                    newFn.method = origFn;
                    return (newFn.apply(scope || me || Ext.global, args) !== false) ? 
                                origFn.apply(me || Ext.global, args) : returnValue;
                };
            }
        },

        /**
         * Creates a delegate (callback) which, when called, executes after a specific delay.
         *
         * @param {Function} fn The function which will be called on a delay when the returned function is called.
         * Optionally, a replacement (or additional) argument list may be specified.
         * @param {Number} delay The number of milliseconds to defer execution by whenever called.
         * @param {Object} scope (optional) The scope (`this` reference) used by the function at execution time.
         * @param {Array} args (optional) Override 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} A function which, when called, executes the original function after the specified delay.
         */
        createDelayed: function(fn, delay, scope, args, appendArgs) {
            if (scope || args) {
                fn = Ext.Function.bind(fn, scope, args, appendArgs);
            }

            return function() {
                var me = this,
                    args = Array.prototype.slice.call(arguments);

                setTimeout(function() {
                    if (Ext.elevateFunction) {
                        Ext.elevateFunction(fn, me, args);
                    } else {
                        fn.apply(me, args);
                    }
                }, delay);
            };
        },

        /**
         * Calls this function after the number of milliseconds specified, optionally in a specific scope. Example usage:
         *
         *     var sayHi = function(name){
         *         alert('Hi, ' + name);
         *     }
         *
         *     // executes immediately:
         *     sayHi('Fred');
         *
         *     // executes after 2 seconds:
         *     Ext.Function.defer(sayHi, 2000, this, ['Fred']);
         *
         *     // this syntax is sometimes useful for deferring
         *     // execution of an anonymous function:
         *     Ext.Function.defer(function(){
         *         alert('Anonymous');
         *     }, 100);
         *
         * {@link Ext#defer Ext.defer} is alias for {@link Ext.Function#defer Ext.Function.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] Overrides arguments for the call. Defaults to the arguments passed by the caller.
         * @param {Boolean/Number} [appendArgs=false] If `true` args are appended to call args instead of overriding,
         * or, if a number, then the args are inserted at the specified position.
         * @return {Number} The timeout id that can be used with `clearTimeout`.
         */
        defer: function(fn, millis, scope, args, appendArgs) {
            fn = Ext.Function.bind(fn, scope, args, appendArgs);
            if (millis > 0) {
                return setTimeout(function () {
                    if (Ext.elevateFunction) {
                        Ext.elevateFunction(fn);
                    } else {
                        fn();
                    }
                }, millis);
            }
            fn();
            return 0;
        },

        /**
         * Calls this function repeatedly at a given interval, optionally in a specific scope.
         *
         * {@link Ext#defer Ext.defer} is alias for {@link Ext.Function#defer Ext.Function.defer}
         *
         * @param {Function} fn The function to defer.
         * @param {Number} millis The number of milliseconds for the `setInterval` call
         * @param {Object} scope (optional) The scope (`this` reference) in which the function is executed.
         * **If omitted, defaults to the browser window.**
         * @param {Array} [args] Overrides arguments for the call. Defaults to the arguments passed by the caller.
         * @param {Boolean/Number} [appendArgs=false] If `true` args are appended to call args instead of overriding,
         * or, if a number, then the args are inserted at the specified position.
         * @return {Number} The interval id that can be used with `clearInterval`.
         */
        interval: function(fn, millis, scope, args, appendArgs) {
            fn = Ext.Function.bind(fn, scope, args, appendArgs);
            return setInterval(function () {
                if (Ext.elevateFunction) {
                    Ext.elevateFunction(fn);
                } else {
                    fn();
                }
            }, millis);
        },

        /**
         * 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 function 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.Function.createSequence(sayHi, function(name){
         *         alert('Bye, ' + name);
         *     });
         *
         *     sayGoodbye('Fred'); // both alerts show
         *
         * @param {Function} originalFn The original function.
         * @param {Function} newFn The function to sequence.
         * @param {Object} [scope] 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
         * default global environment object (usually the browser window).
         * @return {Function} The new function.
         */
        createSequence: function(originalFn, newFn, scope) {
            if (!newFn) {
                return originalFn;
            }
            else {
                return function() {
                    var result = originalFn.apply(this, arguments);
                    newFn.apply(scope || this, arguments);
                    return result;
                };
            }
        },

        /**
         * Creates a delegate function, optionally with a bound scope which, when called, buffers
         * the execution of the passed function for the configured number of milliseconds.
         * If called again within that period, the impending invocation will be canceled, and the
         * timeout period will begin again.
         *
         * @param {Function} fn The function to invoke on a buffered timer.
         * @param {Number} buffer The number of milliseconds by which to buffer the invocation of the
         * function.
         * @param {Object} [scope] The scope (`this` reference) in which.
         * the passed function is executed. If omitted, defaults to the scope specified by the caller.
         * @param {Array} [args] Override arguments for the call. Defaults to the arguments
         * passed by the caller.
         * @return {Function} A function which invokes the passed function after buffering for the specified time.
         */
        createBuffered: function(fn, buffer, scope, args) {
            var timerId;

            return function() {
                var callArgs = args || Array.prototype.slice.call(arguments, 0),
                    me = scope || this;

                if (timerId) {
                    clearTimeout(timerId);
                }

                timerId = setTimeout(function(){
                    if (Ext.elevateFunction) {
                        Ext.elevateFunction(fn, me, callArgs);
                    } else {
                        fn.apply(me, callArgs);
                    }
                }, buffer);
            };
        },

        /**
        * Creates a wrapped function that, when invoked, defers execution until the next
        * animation frame
         * @private
         * @param {Function} fn The function to call.
         * @param {Object} [scope] The scope (`this` reference) in which the function is executed. Defaults to the window object.
         * @param {Array} [args] The argument list to pass to the function.
         * @param {Number} [queueStrategy=3] A bit flag that indicates how multiple calls to
         * the returned function within the same animation frame should be handled.
         *
         * - 1: All calls will be queued - FIFO order
         * - 2: Only the first call will be queued
         * - 3: The last call will replace all previous calls
         *
         * @return {Function}
         */
        createAnimationFrame: function(fn, scope, args, queueStrategy) {
            var timerId;

            queueStrategy = queueStrategy || 3;

            return function() {
                var callArgs = args || Array.prototype.slice.call(arguments, 0);

                scope = scope || this;

                if (queueStrategy === 3 && timerId) {
                    ExtFunction.cancelAnimationFrame(timerId);
                }

                if ((queueStrategy & 1) || !timerId) {
                    timerId = ExtFunction.requestAnimationFrame(function() {
                        timerId = null;
                        fn.apply(scope, callArgs);
                    });
                }
            };
        },

        /**
         * @private
         * Schedules the passed function to be called on the next animation frame.
         * @param {Function} fn The function to call.
         * @param {Object} [scope] The scope (`this` reference) in which the function is executed. Defaults to the window object.
         * @param {Mixed[]} [args] The argument list to pass to the function.
         *
         * @return {Number} Timer id for the new animation frame to use when canceling it.
         */
        requestAnimationFrame: function(fn, scope, args) {
            var id = ++idSource,  // Ids start at 1
                handler = Array.prototype.slice.call(arguments, 0);

            handler[3] = id;
            animFrameMap[id] = 1; // A flag to indicate that the timer exists
            
            // We might be in fireHandlers at this moment but this new entry will not
            // be executed until the next frame
            animFrameHandlers.push(handler);

            if (!animFrameId) {
                animFrameId = requestAnimFrame(Ext.elevateFunction ? fireElevatedHandlers : fireHandlers);
            }
            return id;
        },

        cancelAnimationFrame: function(id) {
            // Don't remove any handlers from animFrameHandlers array, because
            // the might be in use at the moment (when cancelAnimationFrame is called).
            // Just remove the handler id from the map so it will not be executed
            delete animFrameMap[id];
        },

        /**
         * Creates a throttled version of the passed function which, when called repeatedly and
         * rapidly, invokes the passed function only after a certain interval has elapsed since the
         * previous invocation.
         *
         * This is useful for wrapping functions which may be called repeatedly, such as
         * a handler of a mouse move event when the processing is expensive.
         *
         * @param {Function} fn The function to execute at a regular time interval.
         * @param {Number} interval The interval in milliseconds on which the passed function is executed.
         * @param {Object} [scope] The scope (`this` reference) in which
         * the passed function is executed. If omitted, defaults to the scope specified by the caller.
         * @return {Function} A function which invokes the passed function at the specified interval.
         */
        createThrottled: function(fn, interval, scope) {
            var lastCallTime = 0,
                elapsed,
                lastArgs,
                timer,
                execute = function() {
                    if (Ext.elevateFunction) {
                        Ext.elevateFunction(fn, scope, lastArgs);
                    } else {
                        fn.apply(scope, lastArgs);
                    }
                    lastCallTime = Ext.now();
                    timer = null;
                };

            return function() {
                // Use scope of last call unless the creator specified a scope
                if (!scope) {
                    scope = this;
                }
                elapsed = Ext.now() - lastCallTime;
                lastArgs = arguments;

                // If this is the first invocation, or the throttle interval has been reached, clear any
                // pending invocation, and call the target function now.
                if (elapsed >= interval) {
                    clearTimeout(timer);
                    execute();
                }
                // Throttle interval has not yet been reached. Only set the timer to fire if not already set.
                else if (!timer) {
                    timer = Ext.defer(execute, interval - elapsed);
                }
            };
        },

        /**
         * Wraps the passed function in a barrier function which will call the passed function after the passed number of invocations.
         * @param {Number} count The number of invocations which will result in the calling of the passed function.
         * @param {Function} fn The function to call after the required number of invocations.
         * @param {Object} scope The scope (`this` reference) in which the function will be called.
         */    
        createBarrier: function(count, fn, scope) {
            return function() {
                if (!--count) {
                    fn.apply(scope, arguments);
                }
            };
        },

        /**
         * Adds behavior to an existing method that is executed before the
         * original behavior of the function.  For example:
         * 
         *     var soup = {
         *         contents: [],
         *         add: function(ingredient) {
         *             this.contents.push(ingredient);
         *         }
         *     };
         *     Ext.Function.interceptBefore(soup, "add", function(ingredient){
         *         if (!this.contents.length && ingredient !== "water") {
         *             // Always add water to start with
         *             this.contents.push("water");
         *         }
         *     });
         *     soup.add("onions");
         *     soup.add("salt");
         *     soup.contents; // will contain: water, onions, salt
         * 
         * @param {Object} object The target object
         * @param {String} methodName Name of the method to override
         * @param {Function} fn Function with the new behavior.  It will
         * be called with the same arguments as the original method.  The
         * return value of this function will be the return value of the
         * new method.
         * @param {Object} [scope] The scope to execute the interceptor function. Defaults to the object.
         * @return {Function} The new function just created.
         */
        interceptBefore: function(object, methodName, fn, scope) {
            var method = object[methodName] || Ext.emptyFn;

            return (object[methodName] = function() {
                var ret = fn.apply(scope || this, arguments);
                method.apply(this, arguments);

                return ret;
            });
        },

        /**
         * Adds behavior to an existing method that is executed after the
         * original behavior of the function.  For example:
         * 
         *     var soup = {
         *         contents: [],
         *         add: function(ingredient) {
         *             this.contents.push(ingredient);
         *         }
         *     };
         *     Ext.Function.interceptAfter(soup, "add", function(ingredient){
         *         // Always add a bit of extra salt
         *         this.contents.push("salt");
         *     });
         *     soup.add("water");
         *     soup.add("onions");
         *     soup.contents; // will contain: water, salt, onions, salt
         * 
         * @param {Object} object The target object
         * @param {String} methodName Name of the method to override
         * @param {Function} fn Function with the new behavior.  It will
         * be called with the same arguments as the original method.  The
         * return value of this function will be the return value of the
         * new method.
         * @param {Object} [scope] The scope to execute the interceptor function. Defaults to the object.
         * @return {Function} The new function just created.
         */
        interceptAfter: function(object, methodName, fn, scope) {
            var method = object[methodName] || Ext.emptyFn;

            return (object[methodName] = function() {
                method.apply(this, arguments);
                return fn.apply(scope || this, arguments);
            });
        },

        makeCallback: function (callback, scope) {
            //<debug>
            if (!scope[callback]) {
                if (scope.$className) {
                    Ext.Error.raise('No method "' + callback + '" on ' + scope.$className);
                }
                Ext.Error.raise('No method "' + callback + '"');
            }
            //</debug>

            return function () {
                return scope[callback].apply(scope, arguments);
            };
        }
    };

    /**
     * @method
     * @member Ext
     * @inheritdoc Ext.Function#defer
     */
    Ext.defer = ExtFunction.defer;

    /**
     * @method
     * @member Ext
     * @inheritdoc Ext.Function#interval
     */
    Ext.interval = ExtFunction.interval;

    /**
     * @method
     * @member Ext
     * @inheritdoc Ext.Function#pass
     */
    Ext.pass = ExtFunction.pass;

    /**
     * @method
     * @member Ext
     * @inheritdoc Ext.Function#bind
     */
    Ext.bind = ExtFunction.bind;

    Ext.deferCallback = ExtFunction.requestAnimationFrame;

    return ExtFunction;
})();