1 /**
  2  * The Render Engine
  3  * AbstractTimer
  4  *
  5  * @fileoverview A collection of timer objects.
  6  *
  7  * @author: Brett Fattori (brettf@renderengine.com)
  8  * @author: $Author: bfattori $
  9  * @version: $Revision: 1555 $
 10  *
 11  * Copyright (c) 2011 Brett Fattori (brettf@renderengine.com)
 12  *
 13  * Permission is hereby granted, free of charge, to any person obtaining a copy
 14  * of this software and associated documentation files (the "Software"), to deal
 15  * in the Software without restriction, including without limitation the rights
 16  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 17  * copies of the Software, and to permit persons to whom the Software is
 18  * furnished to do so, subject to the following conditions:
 19  *
 20  * The above copyright notice and this permission notice shall be included in
 21  * all copies or substantial portions of the Software.
 22  *
 23  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 24  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 25  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 26  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 27  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 28  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 29  * THE SOFTWARE.
 30  *
 31  */
 32 
 33 // The class this file defines and its required classes
 34 R.Engine.define({
 35     "class":"R.lang.AbstractTimer",
 36     "requires":[
 37         "R.engine.BaseObject"
 38     ]
 39 });
 40 
 41 /**
 42  * @class The base abstract class for all timer objects.
 43  *
 44  * @param name {String} The name of the timer
 45  * @param interval {Number} The interval for the timer, in milliseconds
 46  * @param callback {Function} The function to call when the interval is reached
 47  *
 48  * @extends R.engine.BaseObject
 49  * @constructor
 50  * @description Create a timer object
 51  */
 52 R.lang.AbstractTimer = function () {
 53     "use strict";
 54     return R.engine.BaseObject.extend(/** @scope R.lang.AbstractTimer.prototype */{
 55 
 56         timer:null,
 57 
 58         running:false,
 59         paused:false,
 60         timerFn:null,
 61 
 62         /**
 63          * @private
 64          */
 65         constructor:function (name, interval, callback) {
 66             callback = name instanceof Number ? interval : callback;
 67             interval = name instanceof Number ? name : interval;
 68             name = name instanceof Number ? "Timer" : name;
 69 
 70             Assert((typeof callback == "function"), "Callback must be a function in Timer");
 71 
 72             this.base(name);
 73             this.interval = interval;
 74             this.callback = callback;
 75             this.timerFn = null;
 76 
 77             // The engine needs to know about this timer
 78             R.Engine.addTimer(this.getId(), this);
 79 
 80             this.restart();
 81         },
 82 
 83         /**
 84          * Releast the timer instance back into the pool
 85          */
 86         release:function () {
 87             this.base();
 88             this.timer = null;
 89             this.running = false;
 90             this.paused = false;
 91         },
 92 
 93         /**
 94          * Stop the timer and remove it from the system
 95          */
 96         destroy:function () {
 97             // The engine needs to remove this timer
 98             R.Engine.removeTimer(this.getId());
 99 
100             this.timer = null;
101             this.base();
102         },
103 
104         /**
105          * Get the underlying system timer object.
106          * @return {Object}
107          */
108         getTimer:function () {
109             return this.timer;
110         },
111 
112         /**
113          * Set the underlying system timer object.
114          *
115          * @param timer {Object} The timer object
116          */
117         setTimer:function (timer) {
118             this.timer = timer;
119         },
120 
121         /**
122          * Returns <tt>true</tt> if the timer is currently running.
123          * @return {Boolean} <tt>true</tt> if the timer is running
124          */
125         isRunning:function () {
126             return this.running;
127         },
128 
129         /**
130          * Cancel the timer.
131          */
132         cancel:function () {
133             this.timer = null;
134             this.running = false;
135         },
136 
137         /**
138          * Pause the timer.  In the case where a timer was already processing,
139          * a restart would begin the timing process again with the full time
140          * allocated to the timer.  In the case of multi-timers (ones that retrigger
141          * a callback, or restart automatically a number of times) only the remaining
142          * iterations will be processed.
143          */
144         pause:function () {
145             this.cancel();
146             this.paused = true;
147         },
148 
149         /**
150          * Cancel the running timer and restart it.
151          */
152         restart:function () {
153             this.cancel();
154             this.running = true;
155             this.paused = false;
156         },
157 
158         /**
159          * Set the callback function for this timer.  If the timer is
160          * currently running, it will be restarted.
161          *
162          * @param callback {Function} A function object to call
163          */
164         setCallback:function (callback) {
165             Assert((typeof callback == "function"), "Callback must be a function in Timer.setCallback");
166             this.callback = callback;
167             this.timerFn = null;
168             if (this.isRunning) {
169                 this.restart();
170             }
171         },
172 
173         /**
174          * Get the callback function for this timer.  When the callback is called,
175          * the scope of the function will be the {@link Timer} itself.
176          * @return {Function} The callback function
177          */
178         getCallback:function () {
179             if (this.timerFn === null) {
180                 var timerObj = {
181                     callback:this.callback,
182                     timer:this
183                 };
184                 this.timerFn = R.bind(timerObj, function () {
185                     this.callback.call(this.timer);
186                 });
187                 this.timerFn.cb = this.callback;
188                 this.timerFn.timer = this;
189             }
190             return this.timerFn;
191         },
192 
193         /**
194          * Set the interval of this timer.  If the timer is running, it
195          * will be cancelled.
196          *
197          * @param interval {Number} The interval of this timer, in milliseconds
198          */
199         setInterval:function (interval) {
200             this.cancel();
201             this.interval = interval;
202         },
203 
204         /**
205          * Get the interval of this timer, in milliseconds.
206          * @return {Number} The interval
207          */
208         getInterval:function () {
209             return this.interval;
210         }
211     }, /** @scope R.lang.AbstractTimer.prototype */ {
212         /**
213          * Get the class name of this object
214          * @return {String} "R.lang.AbstractTimer"
215          */
216         getClassName:function () {
217             return "R.lang.AbstractTimer";
218         }
219     });
220 
221 }