GreenSock

• Version: 1.02, Updated 12/17/2008
• Compatibility: AS2 and AS3
• File Size added to published SWF: About 4Kb (not including TweenLite and OverwriteManager which are about another 4kb combined)

Join Club GreenSock to get bonus classes, updates, and much more

SNEAK PEEK: A major update to TweenLite/Max is almost ready! Try it out and offer your input. Click here.

DESCRIPTION

TweenGroup is a very powerful, flexible tool for managing groups of TweenLite/TweenFilterLite/TweenMax tweens (and is included in each of their downloads). Here are a few of the features:

• pause(), resume(), reverse(), or restart() the group as a whole. (Tip: this is an easy way to add these capabilities to TweenLite instances without the extra Kb of TweenMax!)
• Treat a TweenGroup instance just like an Array, so you can push(), splice(), unshift(), pop(), slice(), shift(), loop through the elements, access them directly like myGroup[1], and set them directly like myGroup[2] = new TweenLite(mc, 1, {x:300}) and it'll automatically adjust the timing of the tweens in the group to honor the alignment and staggering effects you set with the "align" and "stagger" properties (more on that next...)
• Easily set the alignment of the tweens inside the group, like:
  1. myGroup.align = TweenGroup.ALIGN_SEQUENCE; //stacks them end-to-end, one after the other
  2. myGroup.align = TweenGroup.ALIGN_START; //tweens will start at the same time
  3. myGroup.align = TweenGroup.ALIGN_END; //tweens will end at the same time
  4. myGroup.align = TweenGroup.ALIGN_INIT; //same as ALIGN_START except that it honors any delay set in each tween.
  5. myGroup.align = TweenGroup.ALIGN_NONE; //no special alignment

• Stagger aligned tweens by a set amount of time (in seconds). For example, if the stagger value is 0.5 and the align property is set to ALIGN_START, the second tween will start 0.5 seconds after the first one starts, then 0.5 seconds later the third one will start, etc. If the align property is ALIGN_SEQUENCE, there would be 0.5 seconds added between each tween.
• Have precise control over the progress of the group by getting/setting the "progress" property anytime. For example, to skip to half-way through the entire group of tweens, simply do this:
  1. myGroup.progress = 0.5;

  You can even tween the progress property with another tween to fastforward/rewind an entire group!

• Call any function when the TweenGroup completes using the onComplete property, and pass any number of parameters to that function using the onCompleteParams property. The AS3 version even dispatches a COMPLETE event so you can addEventListener() instead of using the onComplete callback if you prefer.
• Loop or yoyo a set amount of times or inifinitely. For example, to have your TweenGroup yoyo (reverse() when it has completed) 2 times, just do myGroup.yoyo = 2; (to loop twice instead, do myGroup.loop = 2)
• Only adds about 4Kb to your SWF (not including TweenLite and OverwriteManager which are about another 4kb combined).

At first glance, it may be difficult to see the value of using TweenGroup, but once you wrap your head around it, you'll probably find all kinds of uses for it and wonder how you lived without it. For example, what if you have a menu that flies out and unfolds using several sequenced tweens but when the user clicks elsewhere, you want the menu to fold back into place. With TweenGroup, it's as simple as calling myGroup.reverse(). Or if you have a bunch of tweens that play and then you want to loop them back to the beginning, just call myGroup.restart() or set myGroup.progress = 0. It makes some rather complex management tasks very simple.

Note: this is a brand new class, so please check back regularly for updates and let me know if you run into any bugs/problems.

PROPERTIES

• length : uint - Number of tweens in the group
• progress : Number - Overall progress of the group of tweens (not including any initial delay) as represented numerically between 0 and 1 where 0 means the group hasn't started, 0.5 means it is halfway finished, and 1 means it has completed.
• progressWithDelay : Number - Overall progress of the group of tweens (including any initial delay) as represented numerically between 0 and 1 where 0 means the group hasn't started, 0.5 means it is halfway finished, and 1 means it has completed.
• paused : Boolean - Gets/Sets the paused state of the group.
• reversed : Boolean - Gets/Sets the reversed state of the group.
• align : String - Controls the alignment of the tweens within the group. Typically it's best to use the constants TweenGroup.ALIGN_SEQUENCE, TweenGroup.ALIGN_START, TweenGroup.ALIGN_END, TweenGroup.ALIGN_INIT, or TweenGroup.ALIGN_NONE
• stagger : Number - Controls the amount of time (in seconds) to offset each tween according to the current alignment. For example, if the align property is set to ALIGN_SEQUENCE and stagger is 0.5, this adds 0.5 seconds between each tween in the sequence. If align is set to ALIGN_START, it would add 0.5 seconds to the start time of each tween (0 for the first tween, 0.5 for the second, 1 for the third, etc.)
• duration : Number - [read-only] Duration (in seconds) of the group of tweens NOT including any initial delay
• durationWithDelay : Number - [read-only] Duration (in seconds) of the group of tweens including any initial delay
• onComplete : Function - Call any function when the entire TweenGroup has completed.
• onCompleteParams : Array - Use onCompleteParams if you'd like to pass certain parameters to your onComplete function.
• loop : Number - Set this to zero to loop the TweenGroup indefinitely, or set it to an integer to have it loop a set number of times. For example, to have the TweenGroup loop twice, set loop = 2.
• yoyo : Number - Set this to zero to have the TweenGroup go forward and backwards (yoyo) indefinitely, or set it to an integer to have it yoyo a set number of times (each direction is considered one yoyo). For example, to have the TweenGroup go forward, then backward, then forward again and stop, set yoyo = 2.
• timeScale : Number - Changes the timeScale of all TweenFilterLite and TweenMax instances in the TweenGroup, allowing you to speed up or slow down the whole group. Remember, TweenLite instances are NOT affected by timeScale!.

INSTANCE METHODS

(In addition to standard Array methods like concat(), push(), shift(), unshift(), splice(), etc.)

STATIC METHODS

EXAMPLES

FAQ

1. When I remove a tween from a TweenGroup (using pop(), shift(), splice(), etc.), does that tween stop tweening?
   No. If you want to kill the tween, you need to either use TweenLite.removeTween(myTween) or TweenLite.killTweensOf(myTarget) to stop it from playing.
2. What kind of tweens can I put into a TweenGroup? TweenLite? TweenFilterLite? TweenMax?
   Any of the above. TweenGroup works with TweenLite, TweenFilterLite, and TweenMax instances, and any combination thereof.
3. Do TweenGroups automatically start playing? What if I don't want them to?
   When you put tweens into a TweenGroup, it doesn't alter their paused state, so if they're active, they're remain active unless the TweeGroup is paused. Feel free to pause() your TweenGroup immediately after you create it if you'd like to prevent the tweens from playing.
4. Does using TweenGroup slow down my tweens at all? Do I need to be concerned about performance?
   Nope, not really. TweenGroup has no effect whatsoever on the performance of your tweens. It doesn't add any load to the processor unless you call one of its methods or properties at which point it runs its code and stops, so there is no continual drain on the processor.
5. I'm using the AS2 version and I cannot seem to directly set or get indexes above 99 (like myGroup[200]). Why?
   By default, the AS2 version of TweenGroup only allows direct access to indexes 0 through 99 because of a limitation in the AS2 language (which doesn't affect the AS3 version), but you can easily change that number by calling TweenGroup.capacity = 150 (or whatever number you want) before you create any groups. (you only need to do this once in your SWF). There is a slight memory/performance tradeoff when increasing that number, but it most likely would not be noticeable unless you use an extremely high number.
6. Do I have to purchase a license to use this code? Can I use it for commercial purposes?
   If you use it in a commercial project, I'd strongly encourage you to at least join Club GreenSock which gets you some bonus classes (only available to club members), update notifications, and more. Your donations keep this project going. However, donations are not mandatory. Just like TweenLite, TweenFilterLite, and TweenMax, TweenGroup is free for virtually all uses including commercial projects. The only exception is inclusion in commercial products for which you sell licenses to end users. If you don't charge licensing fees for your product, you don't get charged a licensing fee for this class. If you do license your product to end users and would like to use my code, please e-mail me at info@greensock.com and we can determine a very reasonable licensing fee. Don't hesitate to inquire or assume the licensing fee would be too much - you may be surprised. Many large companies as well as single developers have obtained licenses because in their view, it ultimately saved them time and gave them a better, more reliable end product.

Need Help?

Feel free to post your question on the forums. You'll increase your chances of getting a prompt answer if you include a simplified FLA file (and any class files) that clearly demonstrates the problem and provide a brief explanation.