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