/
TweenMax.as
executable file
·1988 lines (1905 loc) · 114 KB
/
TweenMax.as
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/**
* VERSION: 12.0.3
* DATE: 2013-02-28
* AS3 (AS2 version is also available)
* UPDATES AND DOCS AT: http://www.greensock.com
**/
package com.greensock {
import com.greensock.TweenLite;
import com.greensock.core.Animation;
import com.greensock.core.PropTween;
import com.greensock.core.SimpleTimeline;
import com.greensock.events.TweenEvent;
import com.greensock.plugins.*;
import flash.display.DisplayObject;
import flash.display.DisplayObjectContainer;
import flash.display.Shape;
import flash.events.Event;
import flash.events.EventDispatcher;
import flash.events.IEventDispatcher;
import flash.utils.getTimer;
/**
* TweenMax extends TweenLite, adding many useful (but non-essential) features like repeat(),
* repeatDelay(), yoyo(), AS3 event dispatching, updateTo(), pauseAll(), and more. It also activates many extra plugins
* by default, making it extremely full-featured. Any of the plugins can work with TweenLite too, but TweenMax saves
* you the step of activating the common ones. Since TweenMax extends TweenLite, it can do <strong>ANYTHING</strong>
* TweenLite can do plus more. The syntax is identical. You can mix and match TweenLite and TweenMax in your
* project as you please, but if file size is a concern it is best to stick with TweenLite unless you need
* a particular TweenMax-only feature.
*
* <p>Like TweenLite, a TweenMax instance handles tweening one or more properties of <strong>any object</strong>
* (or array of objects) over time. TweenMax can be used on its own or in conjuction with advanced sequencing
* tools like TimelineLite or TimelineMax to make complex tasks much simpler. With scores of other animation
* frameworks to choose from, why consider the GreenSock Animation Platform?:</p>
*
* <ul>
* <li><strong> SPEED </strong>- The platform has been highly optimized for maximum performance.
* See some speed comparisons yourself at
* <a href="http://www.greensock.com/tweening-speed-test/">http://www.greensock.com/tweening-speed-test/</a></li>
*
* <li><strong> Freakishly robust feature set </strong>- In addition to tweening any numeric property
* of any object, plugins can be activated to tween hex colors, beziers, arrays, filters, plus
* <strong>LOTS</strong> more. It can round values, use relative values, smoothly reverse() on the
* fly, automatically detect and accommodate getter/setter functions, employ virtually any easing
* equation, <code>pause()/resume()</code> anytime, and intelligently manage conflicting tweens of
* the same object with various overwrite modes. TweenMax extends TweenLite and adds even
* more capabilities like repeat, yoyo, repeatDelay, on-the-fly destination value
* updates and more.</li>
*
* <li><strong> Sequencing, grouping, and management features </strong>- TimelineLite and TimelineMax
* make it surprisingly simple to create complex sequences or groups of tweens that you can
* control as a whole. play(), pause(), restart(), or reverse(). You can even tween a timeline's
* <code>time</code> or <code>progress</code> to fastforward or rewind the entire timeline. Add
* labels, change the timeline's timeScale, nest timelines within timelines, and much more.
* This can revolutionize your animation workflow, making it more modular and concise.</li>
*
* <li><strong> AS3, AS2, and JavaScript </strong>- Most other engines are only developed for one language,
* but the GreenSock Animation Platform allows you to use a consistent API across all your Flash and
* HTML5 projects.</li>
*
* <li><strong> Ease of use </strong>- Designers and Developers alike rave about how intuitive the platform is.</li>
*
* <li><strong> Support and reliability </strong>- With frequent updates, <a href="http://forums.greensock.com">dedicated forums</a>,
* committed authorship, a solid track record, a proven funding mechansim, and a thriving community of users,
* the platform is a safe long-term bet (unlike many open source projects).</li>
*
* <li><strong> Expandability </strong>- With its plugin architecture, you can activate as many (or as few)
* extra features as your project requires. Write your own plugin to handle particular special
* properties in custom ways. Minimize bloat and maximize performance.</li>
*
* </ul>
*
* <p><strong>USAGE</strong></p>
* <p>The most common type of tween is a <a href="TweenMax.html#to()">to()</a> tween which allows you
* to define the destination values:</p>
*
* <p><code>
* TweenMax.to(myObject, 2, {x:100, y:200});
* </code></p>
*
* <p>The above code will tween <code>myObject.x</code> from whatever it currently is to 100 and
* <code>myObject.y</code> property to 200 over the course of 2 seconds. Notice the x and y values are
* defined inside a generic object (between curly braces). Put as many properties there as you want.</p>
*
* <p>By default, tweens begin immediately, although you can delay them using the <code>delay</code>
* special property or pause them initially using the <code>paused</code> special property (see below).</p>
*
* <p>The <code>target</code> can also be an array of objects. For example, the following tween will
* tween the alpha property to 0.5 and y property to 100 for obj1, obj2, and obj3:</p>
*
* <p><code>
* TweenMax.to([obj1, obj2, obj3], 1, {alpha:0.5, y:100});
* </code></p>
*
* <p>You can also use a <a href="TweenMax.html#from()">from()</a> tween if you want to define the
* <strong>starting</strong> values instead of the ending values so that the target tweens <em>from</em>
* the defined values to wherever they currently are. Or a <a href="TweenMax.html#fromTo()">fromTo()</a>
* lets you define both starting and ending values.</p>
*
* <p>Although the <code>to()</code>, <code>from()</code>, and <code>fromTo()</code> static methods
* are popular because they're quick and can avoid some garbage collection hassles, you can also
* use the more object-oriented syntax like this:</p>
*
* <p><code>
* var tween = new TweenMax(myObject, 2, {x:100, y:200});
* </code></p>
*
* <p>or even:</p>
*
* <p><code>
* var tween = TweenMax.to(myObject, 2, {x:100, y:200});
* </code></p>
*
*
* <p><strong>SPECIAL PROPERTIES:</strong></p>
* <p>Typically the <code>vars</code> parameter is used to define ending values for tweening
* properties of the <code>target</code> (or beginning values for <code>from()</code> tweens)
* like <code>{x:100, y:200, alpha:0}</code>, but the following optional special properties
* serve other purposes:</p>
*
* <ul>
* <li><strong> delay </strong>:<em> Number</em> -
* Amount of delay in seconds (or frames for frames-based tweens) before the tween should begin.</li>
*
* <li><strong> ease </strong>:<em> Ease (or Function)</em> -
* You can choose from various eases to control the rate of change during
* the animation, giving it a specific "feel". For example, <code>ElasticOut.ease</code>
* or <code>StrongInOut.ease</code>. For best performance, use one of the GreenSock eases
* (which are in the <code>com.greensock.easing</code> package). TweenMax also works with
* any standard easing equation that uses the typical 4 parameters (<code>time, start,
* change, duration</code>) like Adobe's <code>fl.motion.easing</code> eases.
* The default is <code>Power1.easeOut</code>. For linear animation, use the GreenSock
* <code>Linear.ease</code> ease</li>
*
* <li><strong> onComplete </strong>:<em> Function</em> -
* A function that should be called when the tween has completed</li>
*
* <li><strong> onCompleteParams </strong>:<em> Array</em> -
* An Array of parameters to pass the <code>onComplete</code> function. For example,
* <code>TweenMax.to(mc, 1, {x:100, onComplete:myFunction, onCompleteParams:[mc, "param2"]});</code>
* To self-reference the tween instance itself in one of the parameters, use <code>"{self}"</code>,
* like: <code>onCompleteParams:["{self}", "param2"]</code></li>
*
* <li><strong> useFrames </strong>:<em> Boolean</em> -
* If <code>useFrames</code> is <code>true</code>, the tweens's timing will be
* based on frames instead of seconds because it is intially added to the root
* frames-based timeline. This causes both its <code>duration</code>
* and <code>delay</code> to be based on frames. An animations's timing mode is
* always determined by its parent <code>timeline</code>.</li>
*
* <li><strong> easeParams </strong>:<em> Array</em> [deprecated] -
* Some GreenSock eases (like <code>OutIn</code> or <code>ElasticOut</code>) have a <code>config()</code>
* method that allows them to be configured to change their behavior (like <code>TweenMax.to(mc, 1, {x:100, ease:ElasticOut.ease.config(0.5, 1)})</code>
* but if you are using a non-GreenSock ease that accepts extra parameters like Adobe's
* <code>fl.motion.easing.Elastic</code>, <code>easeParams</code> allows you to define
* those extra parameters as an array like <code>TweenMax.to(mc, 1, {x:100, ease:Elastic.easeOut, easeParams:[0.5, 1]})</code>.
* Most easing equations, however, don't require extra parameters so you won't need to
* pass in any easeParams. GreenSock eases provide the best performance, so use them
* whenever possible.</li>
*
* <li><strong> immediateRender </strong>:<em> Boolean</em> -
* Normally when you create a tween, it begins rendering on the very next frame (update cycle)
* unless you specify a <code>delay</code>. However, if you prefer to force the tween to
* render immediately when it is created, set <code>immediateRender</code> to <code>true</code>.
* Or to prevent a <code>from()</code> from rendering immediately, set <code>immediateRender</code>
* to <code>false</code>. By default, <code>from()</code> tweens set <code>immediateRender</code> to <code>true</code>.</li>
*
* <li><strong> onStart </strong>:<em> Function</em> -
* A function that should be called when the tween begins (when its <code>time</code>
* changes from 0 to some other value which can happen more than once if the
* tween is restarted multiple times).</li>
*
* <li><strong> onStartParams </strong>:<em> Array</em> -
* An Array of parameters to pass the <code>onStart</code> function. For example,
* <code>TweenMax.to(mc, 1, {x:100, delay:1, onStart:myFunction, onStartParams:[mc, "param2"]});</code>
* To self-reference the tween instance itself in one of the parameters, use <code>"{self}"</code>,
* like: <code>onStartParams:["{self}", "param2"]</code></li>
*
* <li><strong> onUpdate </strong>:<em> Function</em> -
* A function that should be called every time the tween updates
* (on every frame while the tween is active)</li>
*
* <li><strong> onUpdateParams </strong>:<em> Array</em> -
* An Array of parameters to pass the <code>onUpdate</code> function. For example,
* <code>TweenMax.to(mc, 1, {x:100, onUpdate:myFunction, onUpdateParams:[mc, "param2"]});</code>
* To self-reference the tween instance itself in one of the parameters, use <code>"{self}"</code>,
* like: <code>onUpdateParams:["{self}", "param2"]</code></li>
*
* <li><strong> onReverseComplete </strong>:<em> Function</em> -
* A function that should be called when the tween has reached its beginning again from the
* reverse direction. For example, if <code>reverse()</code> is called the tween will move
* back towards its beginning and when its <code>time</code> reaches 0, <code>onReverseComplete</code>
* will be called. This can also happen if the tween is placed in a TimelineLite or TimelineMax instance
* that gets reversed and plays the tween backwards to (or past) the beginning.</li>
*
* <li><strong> onReverseCompleteParams </strong>:<em> Array</em> -
* An Array of parameters to pass the <code>onReverseComplete</code> function. For example,
* <code>TweenMax.to(mc, 1, {x:100, onReverseComplete:myFunction, onReverseCompleteParams:[mc, "param2"]});</code>
* To self-reference the tween instance itself in one of the parameters, use <code>"{self}"</code>,
* like: <code>onReverseCompleteParams:["{self}", "param2"]</code></li>
*
* <li><strong> paused </strong>:<em> Boolean</em> -
* If <code>true</code>, the tween will pause itself immediately upon creation.</li>
*
* <li><strong> overwrite </strong>:<em> String (or integer)</em> -
* Controls how (and if) other tweens of the same target are overwritten.
* There are several modes to choose from, but <code>"auto"</code> is the default (although
* you can change the default mode using the <code>TweenLite.defaultOverwrite</code> property):
* <ul>
* <li><code>"none"</code> (0) (or <code>false</code>) - no overwriting will occur.</li>
*
* <li><code>"all"</code> (1) (or <code>true</code>) - immediately overwrites all existing
* tweens of the same target even if they haven't started yet or don't have
* conflicting properties.</li>
*
* <li><code>"auto"</code> (2) - when the tween renders for the first time, it will analyze
* tweens of the same target that are currently active/running and only overwrite
* individual tweening properties that overlap/conflict. Tweens that haven't begun
* yet are ignored. For example, if another active tween is found that is tweening
* 3 properties, only 1 of which it shares in common with the new tween, the other
* 2 properties will be left alone. Only the conflicting property gets overwritten/killed.
* This is the default mode and typically the most intuitive for developers.</li>
*
* <li><code>"concurrent"</code> (3) - when the tween renders for the first time, it kills
* only the active (in-progress) tweens of the same target regardless of whether
* or not they contain conflicting properties. Like a mix of <code>"all"</code>
* and <code>"auto"</code>. Good for situations where you only want one tween
* controling the target at a time.</li>
*
* <li><code>"allOnStart"</code> (4) - Identical to <code>"all"</code> but waits to run
* the overwrite logic until the tween begins (after any delay). Kills
* tweens of the same target even if they don't contain conflicting properties
* or haven't started yet.</li>
*
* <li><code>"preexisting"</code> (5) - when the tween renders for the first time, it kills
* only the tweens of the same target that existed BEFORE this tween was created
* regardless of their scheduled start times. So, for example, if you create a tween
* with a delay of 10 and then a tween with a delay of 1 and then a tween with a
* delay of 2 (all of the same target), the 2nd tween would overwrite the first
* but not the second even though scheduling might seem to dictate otherwise.
* <code>"preexisting"</code> only cares about the order in which the instances
* were actually created. This can be useful when the order in which your code runs
* plays a critical role.</li>
*
* </ul></li>
*
* <li><strong> repeat </strong>:<em> Number</em> -
* Number of times that the tween should repeat after its first iteration. For example,
* if <code>repeat</code> is 1, the tween will play a total of twice (the initial play
* plus 1 repeat). To repeat indefinitely, use -1. <code>repeat</code> should always be an integer.</li>
*
* <li><strong> repeatDelay </strong>:<em> Number</em> -
* Amount of time in seconds (or frames for frames-based tweens) between repeats. For example,
* if <code>repeat</code> is 2 and <code>repeatDelay</code> is 1, the tween will play initially,
* then wait for 1 second before it repeats, then play again, then wait 1 second again before
* doing its final repeat.</li>
*
* <li><strong> yoyo </strong>:<em> Boolean</em> -
* If <code>true</code>, every other <code>repeat</code> cycle will run in the opposite
* direction so that the tween appears to go back and forth (forward then backward).
* This has no affect on the "<code>reversed</code>" property though. So if <code>repeat</code>
* is 2 and <code>yoyo</code> is <code>false</code>, it will look like:
* start - 1 - 2 - 3 - 1 - 2 - 3 - 1 - 2 - 3 - end. But if <code>yoyo</code> is <code>true</code>,
* it will look like: start - 1 - 2 - 3 - 3 - 2 - 1 - 1 - 2 - 3 - end.</li>
*
* <li><strong> onRepeat </strong>:<em> Function</em> -
* A function that should be called each time the tween repeats</li>
*
* <li><strong> onRepeatParams </strong>:<em> Array</em> -
* An Array of parameters to pass the onRepeat function. For example,
* <code>TweenMax.to(mc, 1, {x:100, onRepeat:myFunction, onRepeatParams:[mc, "param2"]});</code>
* To self-reference the tween instance itself in one of the parameters, use <code>"{self}"</code>,
* like: <code>onRepeatParams:["{self}", "param2"]</code></li>
*
* <li><strong> onStartListener </strong>:<em> Function</em> [AS3 only] -
* A function that should be called (and passed an event parameter) when the tween begins
* (when its <code>totalTime</code> changes from 0 to some other value which can happen more
* than once if the tween is restarted multiple times). Identical to <code>onStart</code> except
* that the function will always be passed an event parameter whose <code>target</code> property points
* to the tween. It's the same as doing <code>myTween.addEventListener("start", myFunction);</code>.
* Unless you need the event parameter, it's better/faster to use <code>onStart</code>.</li>
*
* <li><strong> onUpdateListener </strong>:<em> Function</em> [AS3 only] -
* A function that should be called (and passed an event parameter) each time the tween updates
* (on every frame while the tween is active). Identical to <code>onUpdate</code> except
* that the function will always be passed an event parameter whose <code>target</code> property points
* to the tween. It's the same as doing <code>myTween.addEventListener("update", myFunction);</code>.
* Unless you need the event parameter, it's better/faster to use <code>onUpdate</code>.</li>
*
* <li><strong> onCompleteListener </strong>:<em> Function</em> [AS3 only] -
* A function that should be called (and passed an event parameter) each time the tween completes.
* Identical to <code>onComplete</code> except that the function will always be passed an event
* parameter whose <code>target</code> property points to the tween. It's the same as doing
* <code>myTween.addEventListener("complete", myFunction);</code>.
* Unless you need the event parameter, it's better/faster to use <code>onComplete</code>.</li>
*
* <li><strong> onReverseCompleteListener </strong>:<em> Function</em> [AS3 only] -
* A function that should be called (and passed an event parameter) each time the tween has reached
* its beginning again from the reverse direction. For example, if <code>reverse()</code> is called
* the tween will move back towards its beginning and when its <code>totalTime</code> reaches 0,
* <code>onReverseCompleteListener</code> will be called. This can also happen if the tween is placed
* in a TimelineLite or TimelineMax instance that gets reversed and plays the tween backwards to
* (or past) the beginning. Identical to <code>onReverseComplete</code> except that the function
* will always be passed an event parameter whose <code>target</code> property points to the tween.
* It's the same as doing <code>myTween.addEventListener("reverseComplete", myFunction);</code>.
* Unless you need the event parameter, it's better/faster to use <code>onReverseComplete</code>.</li>
*
* <li><strong> onRepeatListener </strong>:<em> Function</em> [AS3 only] -
* A function that should be called (and passed an event parameter) each time the tween repeats.
* Identical to <code>onRepeat</code> except that the function will always be passed an event
* parameter whose <code>target</code> property points to the tween. It's the same as doing
* <code>myTween.addEventListener("repeat", myFunction);</code>.
* Unless you need the event parameter, it's better/faster to use <code>onRepeat</code>.</li>
*
* <li><strong> startAt </strong>:<em> Object</em> -
* Allows you to define the starting values for tweening properties. Typically, TweenMax uses
* the current value (whatever it happens to be at the time the tween begins) as the starting
* value, but <code>startAt</code> allows you to override that behavior. Simply pass an object
* in with whatever properties you'd like to set just before the tween begins. For example,
* if <code>mc.x</code> is currently 100, and you'd like to tween it from 0 to 500, do
* <code>TweenMax.to(mc, 2, {x:500, startAt:{x:0}});</code></li>
* </ul>
*
* <p><strong>AS3 note:</strong> In AS3, using a <code><a href="data/TweenMaxVars.html">TweenMaxVars</a></code>
* instance instead of a generic object to define your <code>vars</code> is a bit more verbose but provides
* code hinting and improved debugging because it enforces strict data typing. Use whichever one you prefer.</p>
*
*
*
* <p><strong>PLUGINS:</strong></p>
*
* <p>Think of plugins like special properties that are dynamically added, delivering extra abilities without
* forcing them to be baked into the core engine, keeping it relatively lean and mean. Each plugin is associated
* with a property name and it takes responsibility for handling that property. For example, the TintPlugin
* is associated with the "tint" property name so if it is activated it will intercept the "tint" property
* in the following tween and manage it uniquely:</p>
*
* <p><code>
* TweenLite.to(mc, 1, {tint:0xFF0000});
* </code></p>
*
* <p>If the TintPlugin wasn't activated, TweenLite would act as though you were trying to literally tween the
* <code>mc.tint</code> property (and there is no such thing).</p>
*
* <p>In the JavaScript version of TweenMax, activating a plugin is as simple as loading the associated .js file.
* No extra activation code is necessary. And by default, the JavaScript version of TweenMax includes the CSSPlugin
* and RoundPropsPlugin so you don't need to load those separately. In the ActionScript version, activating a plugin
* requires a single line of code and you only need to do it once, so it's pretty easy. Simply pass an Array containing
* the names of all the plugins you'd like to activate to the <code>TweenPlugin.activate()</code> method, like this:</p>
*
* <p><code>
* TweenPlugin.activate([FrameLabelPlugin, ColorTransformPlugin, TintPlugin]);
* </code></p>
*
* <p>To make it even easier, there is a <a href="http://www.greensock.com/tweenlite/#plugins">Plugin Explorer</a>
* which writes the code for you. All you need to do is select the plugins and copy/paste the code
* from the bottom of the tool. It also displays interactive examples of each plugin and the assocaited
* code so that it’s easy to see the correct syntax.</p>
*
* <p>The following plugins are automatically activated by TweenMax:</p>
*
* <ul>
* <li><strong> autoAlpha </strong>:<em> Number</em> -
* <code>autoAlpha</code> is identical to tweening <code>alpha</code> except that it also
* automatically hides the target when the value hits zero, and shows the target when the
* value isn't zero. In AS3, this means it toggles the target's <code>visible</code> property.
* In AS2, the <code>_visible</code> property is toggled, and in JS the <code>visibility</code>
* style property is set to <code>"hidden"</code> to hide. This can help improve rendering performance.</li>
*
* <li><strong> visible </strong>:<em> Boolean</em> [AS3/AS2 only] -
* hides or shows the target when the tween completes. In AS3, this means it toggles the target's
* <code>visible</code> property. In AS2, the <code>_visible</code> property is toggled, and in
* JS the <code>display</code> style is set to <code>"none"</code> to hide.</li>
*
* <li><strong> volume </strong>:<em> Number</em> [AS3/AS2 only] -
* Tweens the volume of an object. In AS3, it can handle anything with a <code>soundTransform</code>
* property (MovieClip/SoundChannel/NetStream, etc.). In AS2, it is for MovieClips or Sound objects.</li>
*
* <li><strong> tint </strong>:<em> Number</em> [AS3/AS2 only] -
* Tweens the color (tint) of the target. Use a hex value, for example: 0xFF0000 for red or 0x0000FF
* for blue, etc. To remove the tint, use <code>null</code>.</li>
*
* <li><strong> frame </strong>:<em> Number</em> [AS3/AS2 only] -
* Tweens a MovieClip to a particular frame. To tween to a label, use the FrameLabelPlugin.</li>
*
* <li><strong> bezier </strong>:<em> Array</em> -
* Bezier tweening allows you to tween in a non-linear way. For example, you may want to tween
* the target's position from the origin (0,0) 500 pixels to the right (500,0) but curve downwards
* through the middle of the tween. Simply pass as many objects in the bezier array as you'd like,
* one for each "control point". See the BezierPlugin documentation for more details. In this example,
* let's say the control point would be at x/y coordinates 250,50. Just make sure your mc is at
* coordinates 0,0 and then do: <code>TweenMax.to(my_mc, 3, {bezier:[{x:250, y:50}, {x:500, y:0}]});</code></li>
*
* <li><strong> bezierThrough </strong>:<em> Array</em> -
* Identical to <code>bezier</code> except that instead of passing bezier control point values, you
* pass values through which the bezier values should move. This can be more intuitive than using
* control points.</li>
*
* <li><strong> orientToBezier </strong>:<em> Boolean (or Array)</em> -
* When doing a <code>bezier</code> or <code>bezierThrough</code> tween, you can use
* <code>orientToBezier</code> to cause the target to alter its rotation in the direction
* of the bezier, making it appear to turn with the curves. The simplest way is to set
* <code>orientToBezier</code> to <code>true</code>, but you can accomplish advanced effects
* like using a different property than "rotation" or adding a certain number of degrees to the
* standard rotational value, etc. by using an array instead. The array should contain the
* following 4 elements (in this order):
* <ol>
* <li> Position property 1 (typically "x")</li>
* <li> Position property 2 (typically "y")</li>
* <li> Rotational property (typically "rotation")</li>
* <li> Number of degrees to add (optional - makes it easy to orient your target properly)</li>
* </ol>
* For maximum flexibility, you can pass in any number of arrays inside the container array, one
* for each rotational property. This can be convenient when working in 3D because you can rotate
* on multiple axis. If you're doing a standard 2D x/y tween on a bezier, you can simply pass
* in a boolean value of true and TweenMax will use a typical setup, <code>[["x", "y", "rotation", 0]]</code>.
* Hint: Don't forget the container Array (notice the double outer brackets)</li>
*
* <li><strong> hexColors </strong>:<em> Object</em> -
* Although hex colors are technically numbers, if you try to tween them conventionally,
* you'll notice that they don't tween smoothly. To tween them properly, the red, green, and
* blue components must be extracted and tweened independently. TweenMax makes it easy. To tween
* a property of your object that's a hex color, just pass an Object with properties named the
* same as your object's hex color properties that should be tweened. For example, if your mc
* object has a "myHexProp" property that you'd like to tween to red (0xFF0000) over the course
* of 2 seconds, do: <code>TweenMax.to(mc, 2, {hexColors:{myHexProp:0xFF0000}});</code>
* You can pass in any number of hexColor properties.</li>
*
* <li><strong> shortRotation </strong>:<em> Object</em> -
* For rotational tweens, it can be useful to have the engine figure out the shortest direction
* to the destination value and go that way. For example, if the target's rotation property is
* at 0 and you need to rotate to 270, it would actually be shorter to go from 0 to -90.
* If <code>rotation</code> is currently 170 degrees and you want to tween it to -170 degrees,
* a normal rotation tween would travel a total of 340 degrees in the counter-clockwise direction,
* but if you use shortRotation, it would travel 20 degrees in the clockwise direction instead.
* In order to accommodate any rotational property (including 3D ones like rotationX, rotationY,
* and rotationZ or even a custom one), <code>shortRotation</code> should be an object whose properties
* correspond to the ones you want tweened. For example, to tween <code>mc.rotation</code> to 270 in ths shortest
* direction, do: <code>TweenMax.to(mc, 1, {shortRotation:{rotation:270}});</code> or to tween
* its <code>rotationX</code> to -80 and <code>rotationY</code> to 30 in the shortest direction, do:
* <code>TweenMax.to(mc, 1, {shortRotation:{rotationX:-80, rotationY:30}});</code></li>
*
* <li><strong> roundProps </strong>:<em> String</em> -
* A comma-delimited list of property names whose value should be rounded to the nearest integer
* anytime they are updated during the tween. For example, if you're tweening the
* x, y, and alpha properties of mc and you want to round the x and y values (not alpha)
* every time the tween is rendered, do:
* <code>TweenMax.to(mc, 2, {x:300, y:200, alpha:0.5, roundProps:"x,y"});</code></li>
*
* <li><strong> blurFilter </strong>:<em> Object</em> [AS3/AS2 only] -
* Creates a BlurFilter tween affecting any of the following properties:
* <code>blurX, blurY, quality, remove, addFilter, index</code>. For example,
* to blur the object 20 pixels on each axis, do:
* <code>TweenMax.to(mc, 1, {blurFilter:{blurX:20, blurY:20}});</code>
* To remove the filter as soon as the tween completes, set <code>remove:true</code>
* inside the <code>blurFilter</code> object.</li>
*
* <li><strong> glowFilter </strong>:<em> Object</em> [AS3/AS2 only] -
* Creates a GlowFilter tween affecting any of the following properties:
* <code>alpha, blurX, blurY, color, strength, quality, inner, knockout, remove, addFilter, index</code>.
* For example, to create a 20 pixel red glow with a strength of 1.5 and alpha of 1, do:
* <code>TweenMax.to(mc, 1, {glowFilter:{blurX:20, blurY:20, color:0xFF0000, strength:1.5, alpha:1}});</code>
* To remove the filter as soon as the tween completes, set <code>remove:true</code>
* inside the <code>glowFilter</code> object.</li>
*
* <li><strong> colorMatrixFilter </strong>:<em> Object</em> [AS3/AS2 only] -
* Creates a ColorMatrixFilter tween affecting any of the following properties:
* <code>colorize, amount, contrast, brightness, saturation, hue, threshold, relative, matrix, remove, addFilter, index</code>
* For example, to completely desaturate the target, do:
* <code>TweenMax.to(mc, 1, {colorMatrixFilter:{saturation:0}});</code>
* Or to colorize the object red at 50% strength, do:
* <code>TweenMax.to(mc, 1, {colorMatrixFilter:{colorize:0xFF0000, amount:0.5}});</code>
* To remove the filter as soon as the tween completes, set <code>remove:true</code>
* inside the <code>colorMatrixFilter</code> object.</li>
*
* <li><strong> dropShadowFilter </strong>:<em> Object</em> [AS3/AS2 only] -
* Creates a DropShadowFilter tween affecting any of the following properties:
* <code>alpha, angle, blurX, blurY, color, distance, strength, quality, remove, addFilter, index</code>
* For example, to create a 10 pixel red drop shadow with an alpha of 0.8 and an angle of 45, do:
* <code>TweenMax.to(mc, 1, {dropShadowFilter:{blurX:10, blurY:10, color:0xFF0000, angle:45, alpha:0.8}});</code>
* To remove the filter as soon as the tween completes, set <code>remove:true</code>
* inside the <code>dropShadowFilter</code> object.</li>
*
* <li><strong> bevelFilter </strong>:<em> Object</em> [AS3/AS2 only] -
* Creates a BevelFilter tween affecting any of the following properties:
* <code>angle, blurX, blurY, distance, highlightAlpha, highlightColor, shadowAlpha, shadowColor, strength, quality, remove, addFilter, index</code>
* For example, to create a 10 pixel bevel with a strength of 1.5 and distance of 10 and shadowAlpha of 0.8, do:
* <code>TweenMax.to(mc, 1, {bevelFilter:{blurX:10, blurY:10, strength:1.5, distance:10, shadowAlpha:0.8}});</code>
* To remove the filter as soon as the tween completes, set <code>remove:true</code>
* inside the <code>bevelFilter</code> object.</li>
* </ul>
*
*
* <p><strong>EXAMPLES:</strong></p>
* <p>Please see <a href="http://www.greensock.com">http://www.greensock.com</a> for
* examples, tutorials, and interactive demos.</p>
*
* <strong>NOTES / TIPS:</strong>
* <ul>
* <li> Passing values as Strings and a preceding "+=" or "-=" will make the tween relative to the
* current value. For example, if you do <code>TweenMax.to(mc, 2, {x:"-=20"});</code> it'll
* tween <code>mc.x</code> to the left 20 pixels. <code>{x:"+=20"}</code> would move it to the right.</li>
*
* <li> You can use <code>addEventListener()</code> to add listeners to the tween instance manually
* instead of using the onCompleteListener, onStartListener, and onUpdateListener special properties.
* Like <code>myTween.addEventListener("complete", myFunction);</code></li>
*
* <li> You can change the default ease by setting the <code>TweenLite.defaultEase</code> static property.
* The default is <code>Power1.easeOut</code>.</li>
*
* <li> You can kill all tweens of a particular object anytime with <code>TweenMax.killTweensOf(myObject); </code></li>
*
* <li> You can kill all delayedCalls to a particular function with <code>TweenMax.killDelayedCallsTo(myFunction)</code>
* or <code>TweenMax.killTweensOf(myFunction);</code></li>
*
* <li> Use the <code>TweenMax.from()</code> method to animate things into place. For example,
* if you have things set up on the stage in the spot where they should end up, and you
* just want to animate them into place, you can pass in the beginning x and/or y and/or
* alpha (or whatever properties you want).</li>
*
* <li> If you find this class useful, please consider joining <a href="http://www.greensock.com/club/">Club GreenSock</a>
* which not only helps to sustain ongoing development, but also gets you bonus plugins, classes
* and other benefits that are ONLY available to members. Learn more at
* <a href="http://www.greensock.com/club/">http://www.greensock.com/club/</a></li>
* </ul>
*
* <p><strong>Copyright 2008-2013, GreenSock. All rights reserved.</strong> This work is subject to the terms in <a href="http://www.greensock.com/terms_of_use.html">http://www.greensock.com/terms_of_use.html</a> or for <a href="http://www.greensock.com/club/">Club GreenSock</a> members, the software agreement that was issued with the membership.</p>
*
* @author Jack Doyle, jack@greensock.com
*/
public class TweenMax extends TweenLite implements IEventDispatcher {
/** @private **/
public static const version:String = "12.0.3";
TweenPlugin.activate([
//ACTIVATE (OR DEACTIVATE) PLUGINS HERE...
AutoAlphaPlugin, //tweens alpha and then toggles "visible" to false if/when alpha is zero
EndArrayPlugin, //tweens numbers in an Array
FramePlugin, //tweens MovieClip frames
RemoveTintPlugin, //allows you to remove a tint
TintPlugin, //tweens tints
VisiblePlugin, //tweens a target's "visible" property
VolumePlugin, //tweens the volume of a MovieClip or SoundChannel or anything with a "soundTransform" property
BevelFilterPlugin, //tweens BevelFilters
BezierPlugin, //enables bezier tweening
BezierThroughPlugin, //enables bezierThrough tweening
BlurFilterPlugin, //tweens BlurFilters
ColorMatrixFilterPlugin, //tweens ColorMatrixFilters (including hue, saturation, colorize, contrast, brightness, and threshold)
ColorTransformPlugin, //tweens advanced color properties like exposure, brightness, tintAmount, redOffset, redMultiplier, etc.
DropShadowFilterPlugin, //tweens DropShadowFilters
FrameLabelPlugin, //tweens a MovieClip to particular label
GlowFilterPlugin, //tweens GlowFilters
HexColorsPlugin, //tweens hex colors
RoundPropsPlugin, //enables the roundProps special property for rounding values
ShortRotationPlugin //tweens rotation values in the shortest direction
]);
/** @private **/
protected static var _listenerLookup:Object = {onCompleteListener:TweenEvent.COMPLETE, onUpdateListener:TweenEvent.UPDATE, onStartListener:TweenEvent.START, onRepeatListener:TweenEvent.REPEAT, onReverseCompleteListener:TweenEvent.REVERSE_COMPLETE};
/**
* The object that dispatches a <code>"tick"</code> event each time the engine updates, making it easy for
* you to add your own listener(s) to run custom logic after each update (great for game developers).
* Add as many listeners as you want. The basic syntax is the same for all versions (AS2, AS3, and JavaScript):
*
* <p><strong>Basic example (AS2, AS3, and JavaScript):</strong></p><listing version="3.0">
//add listener
TweenMax.ticker.addEventListener("tick", myFunction);
function myFunction(event) {
//executes on every tick after the core engine updates
}
//to remove the listener later...
TweenMax.ticker.removeEventListener("tick", myFunction);
</listing>
*
* <p>Due to differences in the core languages (and to maximize efficiency), the advanced syntax is slightly different
* for the AS3 version compared to AS2 and JavaScript. The parameters beyond the first 2 in the addEventListener()
* method are outlined below:</p>
*
* <p><strong>JavaScript and AS2</strong></p>
* <p><code>addEventListener(type, callback, scope, useParam, priority)</code></p>
* <p>Parameters:
* <ol>
* <li><strong>type</strong> <em>: String</em> - type of listener, should always be <code>"tick"</code></li>
* <li><strong>callback</strong> <em>: Function</em> - the function to call when the event occurs</li>
* <li><strong>scope</strong> <em>: Object</em> - binds the scope to a particular object (scope is basically what "<code>this</code>" refers to in your function). This can be very useful in JavaScript and AS2 because scope isn't generally maintained. </li>
* <li><strong>useParam</strong> <em>: Boolean</em> - if <code>true</code>, an event object will be generated and fed to the callback each time the event occurs. The event is a generic object and has two properties: <code>type</code> (always <code>"tick"</code>) and <code>target</code> which refers to the ticker instance. The default for <code>useParam</code> is <code>false</code> because it improves performance.</li>
* <li><strong>priority</strong> <em>: Integer</em> - influences the order in which the listeners are called. Listeners with lower priorities are called after ones with higher priorities.</li>
* </ol>
* </p>
*
* <p><strong>Advanced example (JavaScript and AS2):</strong></p><listing version="3.0">
//add listener that requests an event object parameter, binds scope to the current scope (this), and sets priority to 1 so that it is called before any other listeners that had a priority lower than 1...
TweenMax.ticker.addEventListener("tick", myFunction, this, true, 1);
function myFunction(event) {
//executes on every tick after the core engine updates
}
//to remove the listener later...
TweenMax.ticker.removeEventListener("tick", myFunction);
</listing>
*
* <p><strong>AS3</strong></p>
* <p>The AS3 version uses the standard <code>EventDispatcher.addEventListener()</code> syntax which
* basically allows you to define a priority and whether or not to use weak references (see Adobe's
* docs for details).</p>
*
* <p><strong>Advanced example [AS3 only]:</strong></p><listing version="3.0">
import flash.events.Event;
//add listener with weak reference (standard syntax - notice the 5th parameter is true)
TweenMax.ticker.addEventListener("tick", myFunction, false, 0, true);
function myFunction(event:Event):void {
//executes on every tick after the core engine updates
}
//to remove the listener later...
TweenMax.ticker.removeEventListener("tick", myFunction);
</listing>
**/
public static var ticker:Shape = Animation.ticker;
/**
* Kills all the tweens (or specific tweening properties) of a particular object or
* the delayedCalls to a particular function. If, for example, you want to kill all
* tweens of <code>myObject</code>, you'd do this:
*
* <p><code>
* TweenMax.killTweensOf(myObject);
* </code></p>
*
* <p>To kill only particular tweening properties of the object, use the second parameter.
* For example, if you only want to kill all the tweens of <code>myObject.alpha</code> and
* <code>myObject.x</code>, you'd do this:</p>
*
* <p><code>
* TweenMax.killTweensOf(myObject, {alpha:true, x:true});
* </code></p>
*
* <p>To kill all the delayedCalls (like ones created using <code>TweenMax.delayedCall(5, myFunction);</code>),
* you can simply call <code>TweenMax.killTweensOf(myFunction);</code> because delayedCalls
* are simply tweens that have their <code>target</code> and <code>onComplete</code> set to
* the same function (as well as a <code>delay</code> of course).</p>
*
* <p><code>killTweensOf()</code> affects tweens that haven't begun yet too. If, for example,
* a tween of <code>myObject</code> has a <code>delay</code> of 5 seconds and
* <code>TweenLite.killTweensOf(mc)</code> is called 2 seconds after the tween was created,
* it will still be killed even though it hasn't started yet. </p>
*
* @param target Object whose tweens should be killed immediately
* @param vars To kill only specific properties, use a generic object containing enumerable properties corresponding to the ones that should be killed like <code>{x:true, y:true}</code>. The values assigned to each property of the object don't matter - the sole purpose of the object is for iteration over the named properties (in this case, <code>x</code> and <code>y</code>). If no object (or <code>null</code>) is defined, all matched tweens will be killed in their entirety.
*/
public static function killTweensOf(target:*, vars:Object=null):void {
TweenLite.killTweensOf(target, vars);
}
/**
* Immediately kills all of the delayedCalls to a particular function. If, for example,
* you want to kill all delayedCalls to <code>myFunction</code>, you'd do this:
*
* <p><code>
* TweenMax.killDelayedCallsTo(myFunction);
* </code></p>
*
* <p>Since a delayedCall is just a tween that uses the function/callback as both its <code>target</code>
* and its <code>onComplete</code>, <code>TweenMax.killTweensOf(myFunction)</code> produces exactly the
* same result as <code>TweenMax.killDelayedCallsTo(myFunction)</code>.</p>
*
* <p>This method affects all delayedCalls that were created using <code>TweenLite.delayedCall()</code>
* or <code>TweenMax.delayedCall()</code> or the <code>call()</code> or <code>addCallback()</code> methods
* of TimelineLite or TimelineMax. Basically, any tween whose target is the function you supply will
* be killed.</p>
*
* @param func The function for which all delayedCalls should be killed/cancelled.
**/
public static function killDelayedCallsTo(func:Function):void {
TweenLite.killTweensOf(func);
}
/**
* Returns an array containing all the tweens of a particular target (or group of targets) that have not
* been released for garbage collection yet which typically happens within a few seconds after the tween completes.
* For example, <code>TweenMax.getTweensOf(myObject)</code> returns an array of all tweens
* of <code>myObject</code>, even tweens that haven't begun yet. <code>TweenMax.getTweensOf([myObject1, myObject2]);</code>
* will return a condensed array of the tweens of <code>myObject1</code> plus all the tweens
* of <code>myObject2</code> combined into one array with duplicates removed.
*
* <p>Since the method only finds tweens that haven't been released for garbage collection, if you create a tween
* and then let it finish and then a while later try to find it with <code>getTweensOf()</code>, it may not be found
* because it was released by the engine for garbage collection. Remember, one of the best parts of GSAP is that it
* saves you from the headache of managing gc. Otherwise, you'd need to manually dispose each tween you create, making
* things much more cumbersome.</p>
*
* <listing version="3.0">
TweenMax.to(myObject1, 1, {x:100});
TweenMax.to(myObject2, 1, {x:100});
TweenMax.to([myObject1, myObject2], 1, {alpha:0});
var a1 = TweenMax.getTweensOf(myObject1); //finds 2 tweens
var a2 = TweenMax.getTweensOf([myObject1, myObject2]); //finds 3 tweens
</listing>
* @param target The target whose tweens should be returned, or an array of such targets
* @return An array of tweens
**/
public static function getTweensOf(target:*):Array {
return TweenLite.getTweensOf(target);
}
/** @private **/
protected var _dispatcher:EventDispatcher;
/** @private **/
protected var _hasUpdateListener:Boolean;
/** @private **/
protected var _repeat:int = 0;
/** @private **/
protected var _repeatDelay:Number = 0;
/** @private **/
protected var _cycle:int = 0;
/** @private **/
public var _yoyo:Boolean;
/**
* Constructor
*
* @param target Target object (or array of objects) whose properties this tween affects
* @param duration Duration in seconds (or frames if <code>useFrames:true</code> is set in the <code>vars</code> parameter)
* @param vars An object defining the end value for each property that should be tweened as well as any special properties like <code>onComplete</code>, <code>ease</code>, etc. For example, to tween <code>mc.x</code> to 100 and <code>mc.y</code> to 200 and then call <code>myFunction</code>, do this: <code>new TweenMax(mc, 1, {x:100, y:200, onComplete:myFunction})</code>.
*/
public function TweenMax(target:Object, duration:Number, vars:Object) {
super(target, duration, vars);
_yoyo = (this.vars.yoyo == true);
_repeat = uint(this.vars.repeat);
_repeatDelay = this.vars.repeatDelay || 0;
_dirty = true; //ensures that if there is any repeat, the _totalDuration will get recalculated to accurately report it.
if (this.vars.onCompleteListener || this.vars.onUpdateListener || this.vars.onStartListener || this.vars.onRepeatListener || this.vars.onReverseCompleteListener) {
_initDispatcher();
if (_duration == 0) if (_delay == 0) if (this.vars.immediateRender) {
_dispatcher.dispatchEvent(new TweenEvent(TweenEvent.UPDATE));
_dispatcher.dispatchEvent(new TweenEvent(TweenEvent.COMPLETE));
}
}
}
/** @inheritDoc **/
override public function invalidate():* {
_yoyo = Boolean(this.vars.yoyo == true);
_repeat = this.vars.repeat || 0;
_repeatDelay = this.vars.repeatDelay || 0;
_hasUpdateListener = false;
_initDispatcher();
_uncache(true);
return super.invalidate();
}
/**
* Updates tweening values on the fly so that they appear to seamlessly change course even if
* the tween is in-progress. Think of it like dynamically updating the <code>vars</code> object
* that was passed in to the tween when it was originally created. You do <strong>NOT</strong>
* need to redefine all of the <code>vars</code> properties/values - only the ones that you want
* to update. You can even define new properties that you didn't define in the original <code>vars</code>
* object.
*
* <p>If the <code>resetDuration</code> parameter is <code>true</code> and the tween has already
* started (or finished), <code>updateTo()</code> will restart the tween. Otherwise, the tween's
* timing will be honored. And if <code>resetDuration</code> is <code>false</code> and the tween
* is in-progress, the starting values of each property will be adjusted so that the tween appears
* to seamlessly redirect to the new destination values. This is typically not advisable if you
* plan to reverse the tween later on or jump to a previous point because the starting values would
* have been adjusted.</p>
*
* <p><code>updateTo()</code> is only meant for non-plugin values. It's much more complicated to
* dynamically update values that are being handled inside plugins - that is not what this method
* is intended to do.</p>
*
* <p>Note: If you plan to constantly update values, please look into using the <code>DynamicPropsPlugin</code>.</p>
*
* <listing version="3.0">
//create the tween
var tween:TweenMax = new TweenMax(mc, 2, {x:100, y:200, alpha:0.5});
//then later, update the destination x and y values, restarting the tween
tween.updateTo({x:300, y:0}, true);
//or to update the values mid-tween without restarting, do this:
tween.updateTo({x:300, y:0}, false);
</listing>
*
* @param vars Object containing properties with the destination values that should be udpated. You do <strong>NOT</strong> need to redefine all of the original <code>vars</code> values - only the ones that should be updated (although if you change a plugin value, you will need to fully define it). For example, to update the destination <code>x</code> value to 300 and the destination <code>y</code> value to 500, pass: <code>{x:300, y:500}</code>.
* @param resetDuration If the tween has already started (or finished) and <code>resetDuration</code> is <code>true</code>, the tween will restart. If <code>resetDuration</code> is <code>false</code>, the tween's timing will be honored (no restart) and each tweening property's starting value will be adjusted so that it appears to seamlessly redirect to the new destination value.
* @return self (makes chaining easier)
**/
public function updateTo(vars:Object, resetDuration:Boolean=false):* {
var curRatio:Number = ratio;
if (resetDuration) if (timeline != null) if (_startTime < _timeline._time) {
_startTime = _timeline._time;
_uncache(false);
if (_gc) {
_enabled(true, false);
} else {
_timeline.insert(this, _startTime - _delay); //ensures that any necessary re-sequencing of Animations in the timeline occurs to make sure the rendering order is correct.
}
}
for (var p:String in vars) {
this.vars[p] = vars[p];
}
if (_initted) {
if (resetDuration) {
_initted = false;
} else {
if (_notifyPluginsOfEnabled) if (_firstPT != null) {
_onPluginEvent("_onDisable", this); //in case a plugin like MotionBlur must perform some cleanup tasks
}
if (_time / _duration > 0.998) { //if the tween has finished (or come extremely close to finishing), we just need to rewind it to 0 and then render it again at the end which forces it to re-initialize (parsing the new vars). We allow tweens that are close to finishing (but haven't quite finished) to work this way too because otherwise, the values are so small when determining where to project the starting values that binary math issues creep in and can make the tween appear to render incorrectly when run backwards.
var prevTime:Number = _time;
render(0, true, false);
_initted = false;
render(prevTime, true, false);
} else if (_time > 0) {
_initted = false;
_init();
var inv:Number = 1 / (1 - curRatio),
pt:PropTween = _firstPT, endValue:Number;
while (pt) {
endValue = pt.s + pt.c;
pt.c *= inv;
pt.s = endValue - pt.c;
pt = pt._next;
}
}
}
}
return this;
}
/**
* @private
* Renders the tween at a particular time (or frame number for frames-based tweens).
* The time is based simply on the overall duration. For example, if a tween's duration
* is 3, <code>renderTime(1.5)</code> would render it at the halfway finished point.
*
* @param time time (or frame number for frames-based tweens) to render.
* @param suppressEvents If true, no events or callbacks will be triggered for this render (like onComplete, onUpdate, onReverseComplete, etc.)
* @param force Normally the tween will skip rendering if the time matches the cachedTotalTime (to improve performance), but if force is true, it forces a render. This is primarily used internally for tweens with durations of zero in TimelineLite/Max instances.
*/
override public function render(time:Number, suppressEvents:Boolean=false, force:Boolean=false):void {
var totalDur:Number = (!_dirty) ? _totalDuration : totalDuration(),
prevTime:Number = _time,
prevTotalTime:Number = _totalTime,
prevCycle:Number = _cycle,
isComplete:Boolean, callback:String, pt:PropTween;
if (time >= totalDur) {
_totalTime = totalDur;
_cycle = _repeat;
if (_yoyo && (_cycle & 1) != 0) {
_time = 0;
ratio = _ease._calcEnd ? _ease.getRatio(0) : 0;
} else {
_time = _duration;
ratio = _ease._calcEnd ? _ease.getRatio(1) : 1;
}
if (!_reversed) {
isComplete = true;
callback = "onComplete";
}
if (_duration == 0) { //zero-duration tweens are tricky because we must discern the momentum/direction of time in order to determine whether the starting values should be rendered or the ending values. If the "playhead" of its timeline goes past the zero-duration tween in the forward direction or lands directly on it, the end values should be rendered, but if the timeline's "playhead" moves past it in the backward direction (from a postitive time to a negative time), the starting values must be rendered.
if (time == 0 || _rawPrevTime < 0) if (_rawPrevTime != time) {
force = true;
}
_rawPrevTime = time;
}
} else if (time <= 0) {
_totalTime = _time = _cycle = 0;
ratio = _ease._calcEnd ? _ease.getRatio(0) : 0;
if (prevTotalTime != 0 || (_duration == 0 && _rawPrevTime > 0)) {
callback = "onReverseComplete";
isComplete = _reversed;
}
if (time < 0) {
_active = false;
if (_duration == 0) { //zero-duration tweens are tricky because we must discern the momentum/direction of time in order to determine whether the starting values should be rendered or the ending values. If the "playhead" of its timeline goes past the zero-duration tween in the forward direction or lands directly on it, the end values should be rendered, but if the timeline's "playhead" moves past it in the backward direction (from a postitive time to a negative time), the starting values must be rendered.
if (_rawPrevTime >= 0) {
force = true;
}
_rawPrevTime = time;
}
} else if (!_initted) { //if we render the very beginning (time == 0) of a fromTo(), we must force the render (normal tweens wouldn't need to render at a time of 0 when the prevTime was also 0). This is also mandatory to make sure overwriting kicks in immediately.
force = true;
}
} else {
_totalTime = _time = time;
if (_repeat != 0) {
var cycleDuration:Number = _duration + _repeatDelay;
_cycle = (_totalTime / cycleDuration) >> 0; //originally _totalTime % cycleDuration but floating point errors caused problems, so I normalized it. (4 % 0.8 should be 0 but Flash reports it as 0.79999999!)
if (_cycle !== 0) if (_cycle === _totalTime / cycleDuration) {
_cycle--; //otherwise when rendered exactly at the end time, it will act as though it is repeating (at the beginning)
}
_time = _totalTime - (_cycle * cycleDuration);
if (_yoyo) if ((_cycle & 1) != 0) {
_time = _duration - _time;
}
if (_time > _duration) {
_time = _duration;
} else if (_time < 0) {
_time = 0;
}
}
if (_easeType) {
var r:Number = _time / _duration, type:int = _easeType, pow:int = _easePower;
if (type == 1 || (type == 3 && r >= 0.5)) {
r = 1 - r;
}
if (type == 3) {
r *= 2;
}
if (pow == 1) {
r *= r;
} else if (pow == 2) {
r *= r * r;
} else if (pow == 3) {
r *= r * r * r;
} else if (pow == 4) {
r *= r * r * r * r;
}
if (type == 1) {
ratio = 1 - r;
} else if (type == 2) {
ratio = r;
} else if (_time / _duration < 0.5) {
ratio = r / 2;
} else {
ratio = 1 - (r / 2);
}
} else {
ratio = _ease.getRatio(_time / _duration);
}
}
if (prevTime == _time && !force) {
if (prevTotalTime !== _totalTime) if (_onUpdate != null) if (!suppressEvents) { //so that onUpdate fires even during the repeatDelay - as long as the totalTime changed, we should trigger onUpdate.
_onUpdate.apply(vars.onUpdateScope || this, vars.onUpdateParams);
}
return;
} else if (!_initted) {
_init();
if (!isComplete && _time) { //_ease is initially set to defaultEase, so now that init() has run, _ease is set properly and we need to recalculate the ratio. Overall this is faster than using conditional logic earlier in the method to avoid having to set ratio twice because we only init() once but renderTime() gets called VERY frequently.
ratio = _ease.getRatio(_time / _duration);
}
}
if (!_active) if (!_paused) {
_active = true; //so that if the user renders a tween (as opposed to the timeline rendering it), the timeline is forced to re-render and align it with the proper time/frame on the next rendering cycle. Maybe the tween already finished but the user manually re-renders it as halfway done.
}
if (prevTotalTime == 0) {
if (_startAt != null) {
_startAt.render(time, suppressEvents, force);
}
if (_totalTime != 0 || _duration == 0) if (!suppressEvents) {
if (vars.onStart) {
vars.onStart.apply(null, vars.onStartParams);
}
if (_dispatcher) {
_dispatcher.dispatchEvent(new TweenEvent(TweenEvent.START));
}
}
}
pt = _firstPT;
while (pt) {
if (pt.f) {
pt.t[pt.p](pt.c * ratio + pt.s);
} else {
pt.t[pt.p] = pt.c * ratio + pt.s;
}
pt = pt._next;
}
if (_onUpdate != null) {
if (time < 0 && _startAt != null) {
_startAt.render(time, suppressEvents, force); //note: for performance reasons, we tuck this conditional logic inside less traveled areas (most tweens don't have an onUpdate). We'd just have it at the end before the onComplete, but the values should be updated before any onUpdate is called, so we ALSO put it here and then if it's not called, we do so later near the onComplete.
}
if (!suppressEvents) {
_onUpdate.apply(null, vars.onUpdateParams);
}
}
if (_hasUpdateListener) {
if (time < 0 && _startAt != null && _onUpdate == null) {