// @tag core/** * @class Ext.util.DelayedTask * * The DelayedTask class provides a convenient way to "buffer" the execution of a method, * performing setTimeout where a new timeout cancels the old timeout. When called, the * task will wait the specified time period before executing. If durng that time period, * the task is called again, the original call will be cancelled. This continues so that * the function is only called a single time for each iteration. * * This method is especially useful for things like detecting whether a user has finished * typing in a text field. An example would be performing validation on a keypress. You can * use this class to buffer the keypress events for a certain number of milliseconds, and * perform only if they stop for that amount of time. * * ## Usage * * var task = new Ext.util.DelayedTask(function(){ * alert(Ext.getDom('myInputField').value.length); * }); * * // Wait 500ms before calling our function. If the user presses another key * // during that 500ms, it will be cancelled and we'll wait another 500ms. * Ext.get('myInputField').on('keypress', function() { * task.delay(500); * }); * * Note that we are using a DelayedTask here to illustrate a point. The configuration * option `buffer` for {@link Ext.util.Observable#addListener addListener/on} will * also setup a delayed task for you to buffer events. * * @constructor The parameters to this constructor serve as defaults and are not required. * @param {Function} [fn] The default function to call. If not specified here, it must be * specified during the {@link #delay} call. * @param {Object} [scope] The default scope (The **`this`** reference) in which the * function is called. If not specified, `this` will refer to the browser window. * @param {Array} [args] The default Array of arguments. * @param {Boolean} [cancelOnDelay=true] By default, each call to {@link #delay} cancels * any pending invocation and reschedules a new invocation. Specifying this as `false` means * that calls to {@link #delay} when an invocation is pending just update the call settings, * `newDelay`, `newFn`, `newScope` or `newArgs`, whichever are passed. */Ext.util = Ext.util || {}; Ext.util.DelayedTask = function(fn, scope, args, cancelOnDelay, fireIdleEvent) {// @define Ext.util.DelayedTask// @uses Ext.GlobalEvents var me = this, delay, call = function() { me.id = null; if (!(scope && scope.destroyed)) { if (args) { fn.apply(scope, args); } else { fn.call(scope); } } if (fireIdleEvent === false) { Ext._suppressIdle = true; } }; //<debug> // DelayedTask can be called with no function upfront if (fn) { call.$origFn = fn.$origFn || fn; call.$skipTimerCheck = call.$origFn.$skipTimerCheck; } //</debug> cancelOnDelay = typeof cancelOnDelay === 'boolean' ? cancelOnDelay : true; /** * @property {Number} id * The id of the currently pending invocation. Will be set to `null` if there is no * invocation pending. */ me.id = null; /** * @method delay * By default, cancels any pending timeout and queues a new one. * * If the `cancelOnDelay` parameter was specified as `false` in the constructor, this does not * cancel and reschedule, but just updates the call settings, `newDelay`, `newFn`, `newScope` * or `newArgs`, whichever are passed. * * @param {Number} newDelay The milliseconds to delay. `-1` means schedule for the next * animation frame if supported. * @param {Function} [newFn] Overrides function passed to constructor * @param {Object} [newScope] Overrides scope passed to constructor. Remember that if no scope * is specified, `this` will refer to the browser window. * @param {Array} [newArgs] Overrides args passed to constructor * @return {Number} The timer id being used. */ me.delay = function(newDelay, newFn, newScope, newArgs) { if (cancelOnDelay) { me.cancel(); } if (typeof newDelay === 'number') { delay = newDelay; } fn = newFn || fn; scope = newScope || scope; args = newArgs || args; me.delayTime = delay; //<debug> if (fn) { call.$origFn = fn.$origFn || fn; call.$skipTimerCheck = call.$origFn.$skipTimerCheck; } //</debug> if (!me.id) { if (delay === -1) { me.id = Ext.raf(call); } else { me.id = Ext.defer(call, delay || 1); // 0 == immediate call } } return me.id; }; /** * Cancel the last queued timeout */ me.cancel = function() { if (me.id) { if (me.delayTime === -1) { Ext.unraf(me.id); } else { Ext.undefer(me.id); } me.id = null; } }; me.flush = function() { var was; if (me.id) { me.cancel(); // we're not running on our own timer so don't mess with whatever thread // is calling us... was = fireIdleEvent; fireIdleEvent = true; call(); fireIdleEvent = was; } }; /** * @private * Cancel the timeout if it was set for the specified fn and scope. */ me.stop = function(stopFn, stopScope) { // This kludginess is here because Classic components use shared focus task // and we need to be sure the task's current timeout was set for that // particular component before we can safely cancel it. if (stopFn && stopFn === fn && (!stopScope || stopScope === scope)) { me.cancel(); } };};