Debian Codegraph @

closure-library/closure/goog/fx/animation.js

raw
1 // Copyright 2006 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 Classes for doing animations and visual effects.
17 *
18 * (Based loosly on my animation code for 13thparallel.org, with extra
19 * inspiration from the DojoToolkit's modifications to my code)
20 * @author [email protected] (Erik Arvidsson)
21 */
22
23 goog.provide('goog.fx.Animation');
24 goog.provide('goog.fx.Animation.EventType');
25 goog.provide('goog.fx.Animation.State');
26 goog.provide('goog.fx.AnimationEvent');
27
28 goog.require('goog.array');
29 goog.require('goog.asserts');
30 goog.require('goog.events.Event');
31 goog.require('goog.fx.Transition');
32 goog.require('goog.fx.TransitionBase');
33 goog.require('goog.fx.anim');
34 goog.require('goog.fx.anim.Animated');
35
36
37
38 /**
39 * Constructor for an animation object.
40 * @param {Array<number>} start Array for start coordinates.
41 * @param {Array<number>} end Array for end coordinates.
42 * @param {number} duration Length of animation in milliseconds.
43 * @param {Function=} opt_acc Acceleration function, returns 0-1 for inputs 0-1.
44 * @constructor
45 * @struct
46 * @implements {goog.fx.anim.Animated}
47 * @implements {goog.fx.Transition}
48 * @extends {goog.fx.TransitionBase}
49 */
50 goog.fx.Animation = function(start, end, duration, opt_acc) {
51 goog.fx.Animation.base(this, 'constructor');
52
53 if (!goog.isArray(start) || !goog.isArray(end)) {
54 throw new Error('Start and end parameters must be arrays');
55 }
56
57 if (start.length != end.length) {
58 throw new Error('Start and end points must be the same length');
59 }
60
61 /**
62 * Start point.
63 * @type {Array<number>}
64 * @protected
65 */
66 this.startPoint = start;
67
68 /**
69 * End point.
70 * @type {Array<number>}
71 * @protected
72 */
73 this.endPoint = end;
74
75 /**
76 * Duration of animation in milliseconds.
77 * @type {number}
78 * @protected
79 */
80 this.duration = duration;
81
82 /**
83 * Acceleration function, which must return a number between 0 and 1 for
84 * inputs between 0 and 1.
85 * @type {Function|undefined}
86 * @private
87 */
88 this.accel_ = opt_acc;
89
90 /**
91 * Current coordinate for animation.
92 * @type {Array<number>}
93 * @protected
94 */
95 this.coords = [];
96
97 /**
98 * Whether the animation should use "right" rather than "left" to position
99 * elements in RTL. This is a temporary flag to allow clients to transition
100 * to the new behavior at their convenience. At some point it will be the
101 * default.
102 * @type {boolean}
103 * @private
104 */
105 this.useRightPositioningForRtl_ = false;
106
107 /**
108 * Current frame rate.
109 * @private {number}
110 */
111 this.fps_ = 0;
112
113 /**
114 * Percent of the way through the animation.
115 * @protected {number}
116 */
117 this.progress = 0;
118
119 /**
120 * Timestamp for when last frame was run.
121 * @protected {?number}
122 */
123 this.lastFrame = null;
124 };
125 goog.inherits(goog.fx.Animation, goog.fx.TransitionBase);
126
127
128 /**
129 * @return {number} The duration of this animation in milliseconds.
130 */
131 goog.fx.Animation.prototype.getDuration = function() {
132 return this.duration;
133 };
134
135
136 /**
137 * Sets whether the animation should use "right" rather than "left" to position
138 * elements. This is a temporary flag to allow clients to transition
139 * to the new component at their convenience. At some point "right" will be
140 * used for RTL elements by default.
141 * @param {boolean} useRightPositioningForRtl True if "right" should be used for
142 * positioning, false if "left" should be used for positioning.
143 */
144 goog.fx.Animation.prototype.enableRightPositioningForRtl = function(
145 useRightPositioningForRtl) {
146 this.useRightPositioningForRtl_ = useRightPositioningForRtl;
147 };
148
149
150 /**
151 * Whether the animation should use "right" rather than "left" to position
152 * elements. This is a temporary flag to allow clients to transition
153 * to the new component at their convenience. At some point "right" will be
154 * used for RTL elements by default.
155 * @return {boolean} True if "right" should be used for positioning, false if
156 * "left" should be used for positioning.
157 */
158 goog.fx.Animation.prototype.isRightPositioningForRtlEnabled = function() {
159 return this.useRightPositioningForRtl_;
160 };
161
162
163 /**
164 * Events fired by the animation.
165 * @enum {string}
166 */
167 goog.fx.Animation.EventType = {
168 /**
169 * Dispatched when played for the first time OR when it is resumed.
170 * @deprecated Use goog.fx.Transition.EventType.PLAY.
171 */
172 PLAY: goog.fx.Transition.EventType.PLAY,
173
174 /**
175 * Dispatched only when the animation starts from the beginning.
176 * @deprecated Use goog.fx.Transition.EventType.BEGIN.
177 */
178 BEGIN: goog.fx.Transition.EventType.BEGIN,
179
180 /**
181 * Dispatched only when animation is restarted after a pause.
182 * @deprecated Use goog.fx.Transition.EventType.RESUME.
183 */
184 RESUME: goog.fx.Transition.EventType.RESUME,
185
186 /**
187 * Dispatched when animation comes to the end of its duration OR stop
188 * is called.
189 * @deprecated Use goog.fx.Transition.EventType.END.
190 */
191 END: goog.fx.Transition.EventType.END,
192
193 /**
194 * Dispatched only when stop is called.
195 * @deprecated Use goog.fx.Transition.EventType.STOP.
196 */
197 STOP: goog.fx.Transition.EventType.STOP,
198
199 /**
200 * Dispatched only when animation comes to its end naturally.
201 * @deprecated Use goog.fx.Transition.EventType.FINISH.
202 */
203 FINISH: goog.fx.Transition.EventType.FINISH,
204
205 /**
206 * Dispatched when an animation is paused.
207 * @deprecated Use goog.fx.Transition.EventType.PAUSE.
208 */
209 PAUSE: goog.fx.Transition.EventType.PAUSE,
210
211 /**
212 * Dispatched each frame of the animation. This is where the actual animator
213 * will listen.
214 */
215 ANIMATE: 'animate',
216
217 /**
218 * Dispatched when the animation is destroyed.
219 */
220 DESTROY: 'destroy'
221 };
222
223
224 /**
225 * @deprecated Use goog.fx.anim.TIMEOUT.
226 */
227 goog.fx.Animation.TIMEOUT = goog.fx.anim.TIMEOUT;
228
229
230 /**
231 * Enum for the possible states of an animation.
232 * @deprecated Use goog.fx.Transition.State instead.
233 * @enum {number}
234 */
235 goog.fx.Animation.State = goog.fx.TransitionBase.State;
236
237
238 /**
239 * @deprecated Use goog.fx.anim.setAnimationWindow.
240 * @param {Window} animationWindow The window in which to animate elements.
241 */
242 goog.fx.Animation.setAnimationWindow = function(animationWindow) {
243 goog.fx.anim.setAnimationWindow(animationWindow);
244 };
245
246
247 /**
248 * Starts or resumes an animation.
249 * @param {boolean=} opt_restart Whether to restart the
250 * animation from the beginning if it has been paused.
251 * @return {boolean} Whether animation was started.
252 * @override
253 */
254 goog.fx.Animation.prototype.play = function(opt_restart) {
255 if (opt_restart || this.isStopped()) {
256 this.progress = 0;
257 this.coords = this.startPoint;
258 } else if (this.isPlaying()) {
259 return false;
260 }
261
262 goog.fx.anim.unregisterAnimation(this);
263
264 var now = /** @type {number} */ (goog.now());
265
266 this.startTime = now;
267 if (this.isPaused()) {
268 this.startTime -= this.duration * this.progress;
269 }
270
271 this.endTime = this.startTime + this.duration;
272 this.lastFrame = this.startTime;
273
274 if (!this.progress) {
275 this.onBegin();
276 }
277
278 this.onPlay();
279
280 if (this.isPaused()) {
281 this.onResume();
282 }
283
284 this.setStatePlaying();
285
286 goog.fx.anim.registerAnimation(this);
287 this.cycle(now);
288
289 return true;
290 };
291
292
293 /**
294 * Stops the animation.
295 * @param {boolean=} opt_gotoEnd If true the animation will move to the
296 * end coords.
297 * @override
298 */
299 goog.fx.Animation.prototype.stop = function(opt_gotoEnd) {
300 goog.fx.anim.unregisterAnimation(this);
301 this.setStateStopped();
302
303 if (opt_gotoEnd) {
304 this.progress = 1;
305 }
306
307 this.updateCoords_(this.progress);
308
309 this.onStop();
310 this.onEnd();
311 };
312
313
314 /**
315 * Pauses the animation (iff it's playing).
316 * @override
317 */
318 goog.fx.Animation.prototype.pause = function() {
319 if (this.isPlaying()) {
320 goog.fx.anim.unregisterAnimation(this);
321 this.setStatePaused();
322 this.onPause();
323 }
324 };
325
326
327 /**
328 * @return {number} The current progress of the animation, the number
329 * is between 0 and 1 inclusive.
330 */
331 goog.fx.Animation.prototype.getProgress = function() {
332 return this.progress;
333 };
334
335
336 /**
337 * Sets the progress of the animation.
338 * @param {number} progress The new progress of the animation.
339 */
340 goog.fx.Animation.prototype.setProgress = function(progress) {
341 this.progress = progress;
342 if (this.isPlaying()) {
343 var now = goog.now();
344 // If the animation is already playing, we recompute startTime and endTime
345 // such that the animation plays consistently, that is:
346 // now = startTime + progress * duration.
347 this.startTime = now - this.duration * this.progress;
348 this.endTime = this.startTime + this.duration;
349 }
350 };
351
352
353 /**
354 * Disposes of the animation. Stops an animation, fires a 'destroy' event and
355 * then removes all the event handlers to clean up memory.
356 * @override
357 * @protected
358 */
359 goog.fx.Animation.prototype.disposeInternal = function() {
360 if (!this.isStopped()) {
361 this.stop(false);
362 }
363 this.onDestroy();
364 goog.fx.Animation.base(this, 'disposeInternal');
365 };
366
367
368 /**
369 * Stops an animation, fires a 'destroy' event and then removes all the event
370 * handlers to clean up memory.
371 * @deprecated Use dispose() instead.
372 */
373 goog.fx.Animation.prototype.destroy = function() {
374 this.dispose();
375 };
376
377
378 /** @override */
379 goog.fx.Animation.prototype.onAnimationFrame = function(now) {
380 this.cycle(now);
381 };
382
383
384 /**
385 * Handles the actual iteration of the animation in a timeout
386 * @param {number} now The current time.
387 */
388 goog.fx.Animation.prototype.cycle = function(now) {
389 goog.asserts.assertNumber(this.startTime);
390 goog.asserts.assertNumber(this.endTime);
391 goog.asserts.assertNumber(this.lastFrame);
392 // Happens in rare system clock reset.
393 if (now < this.startTime) {
394 this.endTime = now + this.endTime - this.startTime;
395 this.startTime = now;
396 }
397 this.progress = (now - this.startTime) / (this.endTime - this.startTime);
398
399 if (this.progress > 1) {
400 this.progress = 1;
401 }
402
403 this.fps_ = 1000 / (now - this.lastFrame);
404 this.lastFrame = now;
405
406 this.updateCoords_(this.progress);
407
408 // Animation has finished.
409 if (this.progress == 1) {
410 this.setStateStopped();
411 goog.fx.anim.unregisterAnimation(this);
412
413 this.onFinish();
414 this.onEnd();
415
416 // Animation is still under way.
417 } else if (this.isPlaying()) {
418 this.onAnimate();
419 }
420 };
421
422
423 /**
424 * Calculates current coordinates, based on the current state. Applies
425 * the acceleration function if it exists.
426 * @param {number} t Percentage of the way through the animation as a decimal.
427 * @private
428 */
429 goog.fx.Animation.prototype.updateCoords_ = function(t) {
430 if (goog.isFunction(this.accel_)) {
431 t = this.accel_(t);
432 }
433 this.coords = new Array(this.startPoint.length);
434 for (var i = 0; i < this.startPoint.length; i++) {
435 this.coords[i] =
436 (this.endPoint[i] - this.startPoint[i]) * t + this.startPoint[i];
437 }
438 };
439
440
441 /**
442 * Dispatches the ANIMATE event. Sub classes should override this instead
443 * of listening to the event.
444 * @protected
445 */
446 goog.fx.Animation.prototype.onAnimate = function() {
447 this.dispatchAnimationEvent(goog.fx.Animation.EventType.ANIMATE);
448 };
449
450
451 /**
452 * Dispatches the DESTROY event. Sub classes should override this instead
453 * of listening to the event.
454 * @protected
455 */
456 goog.fx.Animation.prototype.onDestroy = function() {
457 this.dispatchAnimationEvent(goog.fx.Animation.EventType.DESTROY);
458 };
459
460
461 /** @override */
462 goog.fx.Animation.prototype.dispatchAnimationEvent = function(type) {
463 this.dispatchEvent(new goog.fx.AnimationEvent(type, this));
464 };
465
466
467
468 /**
469 * Class for an animation event object.
470 * @param {string} type Event type.
471 * @param {goog.fx.Animation} anim An animation object.
472 * @constructor
473 * @struct
474 * @extends {goog.events.Event}
475 */
476 goog.fx.AnimationEvent = function(type, anim) {
477 goog.fx.AnimationEvent.base(this, 'constructor', type);
478
479 /**
480 * The current coordinates.
481 * @type {Array<number>}
482 */
483 this.coords = anim.coords;
484
485 /**
486 * The x coordinate.
487 * @type {number}
488 */
489 this.x = anim.coords[0];
490
491 /**
492 * The y coordinate.
493 * @type {number}
494 */
495 this.y = anim.coords[1];
496
497 /**
498 * The z coordinate.
499 * @type {number}
500 */
501 this.z = anim.coords[2];
502
503 /**
504 * The current duration.
505 * @type {number}
506 */
507 this.duration = anim.duration;
508
509 /**
510 * The current progress.
511 * @type {number}
512 */
513 this.progress = anim.getProgress();
514
515 /**
516 * Frames per second so far.
517 */
518 this.fps = anim.fps_;
519
520 /**
521 * The state of the animation.
522 * @type {number}
523 */
524 this.state = anim.getStateInternal();
525
526 /**
527 * The animation object.
528 * @type {goog.fx.Animation}
529 */
530 // TODO(arv): This can be removed as this is the same as the target
531 this.anim = anim;
532 };
533 goog.inherits(goog.fx.AnimationEvent, goog.events.Event);
534
535
536 /**
537 * Returns the coordinates as integers (rounded to nearest integer).
538 * @return {!Array<number>} An array of the coordinates rounded to
539 * the nearest integer.
540 */
541 goog.fx.AnimationEvent.prototype.coordsAsInts = function() {
542 return goog.array.map(this.coords, Math.round);
543 };