src/util/core/DelayedTask.js

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