src/core/src/util/DelayedTask.js

   1 /**
   2  * @class Ext.util.DelayedTask
   3  *
   4  * The DelayedTask class provides a convenient way to "buffer" the execution of a method,
   5  * performing setTimeout where a new timeout cancels the old timeout. When called, the
   6  * task will wait the specified time period before executing. If durng that time period,
   7  * the task is called again, the original call will be cancelled. This continues so that
   8  * the function is only called a single time for each iteration.
   9  *
  10  * This method is especially useful for things like detecting whether a user has finished
  11  * typing in a text field. An example would be performing validation on a keypress. You can
  12  * use this class to buffer the keypress events for a certain number of milliseconds, and
  13  * perform only if they stop for that amount of time.
  14  *
  15  * ## Usage
  16  *
  17  *     var task = new Ext.util.DelayedTask(function(){
  18  *         alert(Ext.getDom('myInputField').value.length);
  19  *     });
  20  *
  21  *     // Wait 500ms before calling our function. If the user presses another key
  22  *     // during that 500ms, it will be cancelled and we'll wait another 500ms.
  23  *     Ext.get('myInputField').on('keypress', function(){
  24  *         task.{@link #delay}(500);
  25  *     });
  26  *
  27  * Note that we are using a DelayedTask here to illustrate a point. The configuration
  28  * option `buffer` for {@link Ext.util.Observable#addListener addListener/on} will
  29  * also setup a delayed task for you to buffer events.
  30  *
  31  * @constructor The parameters to this constructor serve as defaults and are not required.
  32  * @param {Function} fn (optional) The default function to call.
  33  * @param {Object} scope The default scope (The <code><b>this</b></code> reference) in which the
  34  * function is called. If not specified, <code>this</code> will refer to the browser window.
  35  * @param {Array} args (optional) The default Array of arguments.
  36  */
  37 Ext.util.DelayedTask = function(fn, scope, args) {
  38     var me = this,
  39         id,
  40         call = function() {
  41             clearInterval(id);
  42             id = null;
  43             fn.apply(scope, args || []);
  44         };
  45
  46     /**
  47      * Cancels any pending timeout and queues a new one
  48      * @param {Number} delay The milliseconds to delay
  49      * @param {Function} newFn (optional) Overrides function passed to constructor
  50      * @param {Object} newScope (optional) Overrides scope passed to constructor. Remember that if no scope
  51      * is specified, <code>this</code> will refer to the browser window.
  52      * @param {Array} newArgs (optional) Overrides args passed to constructor
  53      */
  54     this.delay = function(delay, newFn, newScope, newArgs) {
  55         me.cancel();
  56         fn = newFn || fn;
  57         scope = newScope || scope;
  58         args = newArgs || args;
  59         id = setInterval(call, delay);
  60     };
  61
  62     /**
  63      * Cancel the last queued timeout
  64      */
  65     this.cancel = function(){
  66         if (id) {
  67             clearInterval(id);
  68             id = null;
  69         }
  70     };
  71 };