1
// Copyright 2012 The Closure Library Authors. All Rights Reserved.
2
//
3
// Licensed under the Apache License, Version 2.0 (the "License");
4
// you may not use this file except in compliance with the License.
5
// You may obtain a copy of the License at
6
//
7
//      http://www.apache.org/licenses/LICENSE-2.0
8
//
9
// Unless required by applicable law or agreed to in writing, software
10
// distributed under the License is distributed on an "AS-IS" BASIS,
11
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
// See the License for the specific language governing permissions and
13
// limitations under the License.
14

15
/**
16
 * @fileoverview A delayed callback that pegs to the next animation frame
17
 * instead of a user-configurable timeout.
18
 *
19
 * @author [email protected] (Nick Santos)
20
 */
21

22
goog.provide('goog.async.AnimationDelay');
23

24
goog.require('goog.Disposable');
25
goog.require('goog.events');
26
goog.require('goog.functions');
27

28

29

30
// TODO(nicksantos): Should we factor out the common code between this and
31
// goog.async.Delay? I'm not sure if there's enough code for this to really
32
// make sense. Subclassing seems like the wrong approach for a variety of
33
// reasons. Maybe there should be a common interface?
34

35

36

37
/**
38
 * A delayed callback that pegs to the next animation frame
39
 * instead of a user configurable timeout. By design, this should have
40
 * the same interface as goog.async.Delay.
41
 *
42
 * Uses requestAnimationFrame and friends when available, but falls
43
 * back to a timeout of goog.async.AnimationDelay.TIMEOUT.
44
 *
45
 * For more on requestAnimationFrame and how you can use it to create smoother
46
 * animations, see:
47
 * @see http://paulirish.com/2011/requestanimationframe-for-smart-animating/
48
 *
49
 * @param {function(this:THIS, number)} listener Function to call
50
 *     when the delay completes. Will be passed the timestamp when it's called,
51
 *     in unix ms.
52
 * @param {Window=} opt_window The window object to execute the delay in.
53
 *     Defaults to the global object.
54
 * @param {THIS=} opt_handler The object scope to invoke the function in.
55
 * @template THIS
56
 * @constructor
57
 * @struct
58
 * @extends {goog.Disposable}
59
 * @final
60
 */
61
goog.async.AnimationDelay = function(listener, opt_window, opt_handler) {
62
  goog.async.AnimationDelay.base(this, 'constructor');
63

64
  /**
65
   * Identifier of the active delay timeout, or event listener,
66
   * or null when inactive.
67
   * @private {goog.events.Key|number}
68
   */
69
  this.id_ = null;
70

71
  /**
72
   * If we're using dom listeners.
73
   * @private {?boolean}
74
   */
75
  this.usingListeners_ = false;
76

77
  /**
78
   * The function that will be invoked after a delay.
79
   * @const
80
   * @private
81
   */
82
  this.listener_ = listener;
83

84
  /**
85
   * The object context to invoke the callback in.
86
   * @const
87
   * @private {(THIS|undefined)}
88
   */
89
  this.handler_ = opt_handler;
90

91
  /**
92
   * @private {Window}
93
   */
94
  this.win_ = opt_window || window;
95

96
  /**
97
   * Cached callback function invoked when the delay finishes.
98
   * @private {function()}
99
   */
100
  this.callback_ = goog.bind(this.doAction_, this);
101
};
102
goog.inherits(goog.async.AnimationDelay, goog.Disposable);
103

104

105
/**
106
 * Default wait timeout for animations (in milliseconds).  Only used for timed
107
 * animation, which uses a timer (setTimeout) to schedule animation.
108
 *
109
 * @type {number}
110
 * @const
111
 */
112
goog.async.AnimationDelay.TIMEOUT = 20;
113

114

115
/**
116
 * Name of event received from the requestAnimationFrame in Firefox.
117
 *
118
 * @type {string}
119
 * @const
120
 * @private
121
 */
122
goog.async.AnimationDelay.MOZ_BEFORE_PAINT_EVENT_ = 'MozBeforePaint';
123

124

125
/**
126
 * Starts the delay timer. The provided listener function will be called
127
 * before the next animation frame.
128
 */
129
goog.async.AnimationDelay.prototype.start = function() {
130
  this.stop();
131
  this.usingListeners_ = false;
132

133
  var raf = this.getRaf_();
134
  var cancelRaf = this.getCancelRaf_();
135
  if (raf && !cancelRaf && this.win_.mozRequestAnimationFrame) {
136
    // Because Firefox (Gecko) runs animation in separate threads, it also saves
137
    // time by running the requestAnimationFrame callbacks in that same thread.
138
    // Sadly this breaks the assumption of implicit thread-safety in JS, and can
139
    // thus create thread-based inconsistencies on counters etc.
140
    //
141
    // Calling cycleAnimations_ using the MozBeforePaint event instead of as
142
    // callback fixes this.
143
    //
144
    // Trigger this condition only if the mozRequestAnimationFrame is available,
145
    // but not the W3C requestAnimationFrame function (as in draft) or the
146
    // equivalent cancel functions.
147
    this.id_ = goog.events.listen(
148
        this.win_, goog.async.AnimationDelay.MOZ_BEFORE_PAINT_EVENT_,
149
        this.callback_);
150
    this.win_.mozRequestAnimationFrame(null);
151
    this.usingListeners_ = true;
152
  } else if (raf && cancelRaf) {
153
    this.id_ = raf.call(this.win_, this.callback_);
154
  } else {
155
    this.id_ = this.win_.setTimeout(
156
        // Prior to Firefox 13, Gecko passed a non-standard parameter
157
        // to the callback that we want to ignore.
158
        goog.functions.lock(this.callback_), goog.async.AnimationDelay.TIMEOUT);
159
  }
160
};
161

162

163
/**
164
 * Starts the delay timer if it's not already active.
165
 */
166
goog.async.AnimationDelay.prototype.startIfNotActive = function() {
167
  if (!this.isActive()) {
168
    this.start();
169
  }
170
};
171

172

173
/**
174
 * Stops the delay timer if it is active. No action is taken if the timer is not
175
 * in use.
176
 */
177
goog.async.AnimationDelay.prototype.stop = function() {
178
  if (this.isActive()) {
179
    var raf = this.getRaf_();
180
    var cancelRaf = this.getCancelRaf_();
181
    if (raf && !cancelRaf && this.win_.mozRequestAnimationFrame) {
182
      goog.events.unlistenByKey(this.id_);
183
    } else if (raf && cancelRaf) {
184
      cancelRaf.call(this.win_, /** @type {number} */ (this.id_));
185
    } else {
186
      this.win_.clearTimeout(/** @type {number} */ (this.id_));
187
    }
188
  }
189
  this.id_ = null;
190
};
191

192

193
/**
194
 * Fires delay's action even if timer has already gone off or has not been
195
 * started yet; guarantees action firing. Stops the delay timer.
196
 */
197
goog.async.AnimationDelay.prototype.fire = function() {
198
  this.stop();
199
  this.doAction_();
200
};
201

202

203
/**
204
 * Fires delay's action only if timer is currently active. Stops the delay
205
 * timer.
206
 */
207
goog.async.AnimationDelay.prototype.fireIfActive = function() {
208
  if (this.isActive()) {
209
    this.fire();
210
  }
211
};
212

213

214
/**
215
 * @return {boolean} True if the delay is currently active, false otherwise.
216
 */
217
goog.async.AnimationDelay.prototype.isActive = function() {
218
  return this.id_ != null;
219
};
220

221

222
/**
223
 * Invokes the callback function after the delay successfully completes.
224
 * @private
225
 */
226
goog.async.AnimationDelay.prototype.doAction_ = function() {
227
  if (this.usingListeners_ && this.id_) {
228
    goog.events.unlistenByKey(this.id_);
229
  }
230
  this.id_ = null;
231

232
  // We are not using the timestamp returned by requestAnimationFrame
233
  // because it may be either a Date.now-style time or a
234
  // high-resolution time (depending on browser implementation). Using
235
  // goog.now() will ensure that the timestamp used is consistent and
236
  // compatible with goog.fx.Animation.
237
  this.listener_.call(this.handler_, goog.now());
238
};
239

240

241
/** @override */
242
goog.async.AnimationDelay.prototype.disposeInternal = function() {
243
  this.stop();
244
  goog.async.AnimationDelay.base(this, 'disposeInternal');
245
};
246

247

248
/**
249
 * @return {?function(function(number)): number} The requestAnimationFrame
250
 *     function, or null if not available on this browser.
251
 * @private
252
 */
253
goog.async.AnimationDelay.prototype.getRaf_ = function() {
254
  var win = this.win_;
255
  return win.requestAnimationFrame || win.webkitRequestAnimationFrame ||
256
      win.mozRequestAnimationFrame || win.oRequestAnimationFrame ||
257
      win.msRequestAnimationFrame || null;
258
};
259

260

261
/**
262
 * @return {?function(number): undefined} The cancelAnimationFrame function,
263
 *     or null if not available on this browser.
264
 * @private
265
 */
266
goog.async.AnimationDelay.prototype.getCancelRaf_ = function() {
267
  var win = this.win_;
268
  return win.cancelAnimationFrame || win.cancelRequestAnimationFrame ||
269
      win.webkitCancelRequestAnimationFrame ||
270
      win.mozCancelRequestAnimationFrame || win.oCancelRequestAnimationFrame ||
271
      win.msCancelRequestAnimationFrame || null;
272
};
273

274