GreenSock

• Compatibility: Flash Player 9 and later (ActionScript 3.0) (Click here for the AS2 version)
• File Size added to published SWF: About 6Kb

Join Club GreenSock to get updates and a lot more

RECENT VERSION HIGHLIGHTS

• IMPORTANT: syntax change! - instead of defining a "type" property that indicates the kind of filter, you define a property like "blurFilter", "glowFilter", "colorMatrixFilter", "dropShadowFilter", or "bevelFilter" and pass an object with whatever properties you want to tween. So

  OLD SYNTAX:
  TweenFilterLite.to(mc, 2, {type:"blur", blurX:20, blurY:20, delay:1});

  NEW SYNTAX:
  TweenFilterLite.to(mc, 2, {blurFilter:{blurX:20, blurY:20}, delay:1});

  Why make this change? Here are a few reasons:

  1. It allows you to tween multiple filters with a single call, like:
     TweenFilterLite.to(mc, 2, {blurFilter:{blurX:30}, colorMatrixFilter:{colorize:0xFF0000}});
  2. It eliminates problems with ambiguous properties like "alpha". Some people wanted to be able to tween a Sprite's alpha property AND a DropShadowFilter on that Sprite with the drop shadow's alpha changing too, but with the old syntax, you could only define one alpha
  3. It makes it more flexible to extend (e.g. my upcoming TweenMax class)
• Removed DisplayObject limitation: - Previously, TweenFilterLite only allowed you to tween DisplayObjects, but you can now use it for any object. It is still recommended that you use TweenLite directly to tween non-DisplayObject because it'll perform slightly faster, but unless you doing a LOT of tweens simultaneously, you'd probably never notice a difference.

DESCRIPTION

TweenFilterLite extends the extremely lightweight (about 3k), powerful TweenLite "core" class, adding the ability to tween filters (like blurs, glows, drop shadows, bevels, etc.) as well as image effects like contrast, colorization, brightness, saturation, hue, and threshold (combined size: about 6k). The syntax is identical to the TweenLite class. If you're unfamiliar with TweenLite, I'd highly recommend that you check it out. It provides easy way to tween multiple object properties over time including a MovieClip's position, alpha, volume, color, etc. Just like the TweenLite class, TweenFilterLite allows you to build in a delay, call any function when the tween starts or has completed (even passing any number of parameters you define), automatically kill other tweens that are affecting the same object (to avoid conflicts), tween arrays, etc. One of the big benefits of this class (and the reason "Lite" is in the name) is that it was carefully built to minimize file size. There are several other Tweening engines out there, but in my experience, they required more than triple the file size which was unacceptable when dealing with strict file size requirements (like banner ads). I haven't been able to find a faster tween engine either. The syntax is simple and the class doesn't rely on complicated prototype alterations that can cause problems with certain compilers. TweenFilterLite is simple, very fast, and more lightweight (about 6k) than any other popular tweening engine.

And if you want even more features and don't mind a few extra Kb, check out the new TweenMax class which adds bezier tweening, pause/resume, easier sequencing, and more. It can do everything TweenFilterLite does plus more.

(Click here for the ActionScript 2.0 version of this class)

OBJECTIVES

• Minimize file size
• Maximize flexibility and efficiency by extending the TweenLite class. That way, if you don't need to tween filters, you can just use TweenLite (about 3k); otherwise, this class will only add another 3k (6k total)
• Minimize the amount of code required to initiate a tween
• Maximize performance
• Allow for very flexible callbacks (onComplete, onUpdate, onStart, all with the ability to pass any number of parameters)

FILTERS & PROPERTIES:

• blurFilter
  blurX, blurY, quality
• glowFilter
  alpha, blurX, blurY, color, strength, quality
• colorMatrixFilter
  colorize, amount, contrast, brightness, saturation, hue, threshold, relative, matrix
• dropShadowFilter
  alpha, angle, blurX, blurY, color, distance, strength, quality
• bevelFilter
  angle, blurX, blurY, distance, highlightAlpha, highlightColor, shadowAlpha, shadowColor, strength, quality

USAGE

EXAMPLES

FAQ

1. How do I install the class? Do I have to import it on every frame?
   Just make sure the "gs" folder from the download is in the same folder as your FLA file. Keep the class files in the "gs" folder (don't remove them). That's it. And, yes, just like any Class, you need to import TweenFilterLite at the top of any frame that contains code referencing it. This does NOT add extra Kb to your file size very time you import it. Flash is smart enough to embed it once and all the other import statments just act as a "pointer" to the embedded Class.

2. Why doesn't the tweening engine selectively overwrite ONLY tweens that are affecting the same property? How can I achieve this effect?
   As you can tell from the speed tests, performance is a primary concern. Searching through potentially hundreds or thousands of tweens for overlapping tween properties can get expensive in terms of performance. Therefore, the TweenFilterLite family opted for a much faster approach: all or nothing. But don't worry - in almost every case, you can achieve the result you're after with a little bit of extra code. Trust me, it's worth the increased speed and efficiency you'll get.

   You can selectively kill tweens by keeping track of the TweenFilterLite instance that’s returned by the to() or from() methods, and calling removeTween() on them. For example, if you want to have a button scale up when you roll over it, and scale back down when you roll off (those tweens should overwrite each other) but you don't want them to overwrite a from() call that fades the button in over the course of 2 seconds, you could do:

   1. myButton.addEventListener(MouseEvent.MOUSE_OVER, onMouseOver);
   2. myButton.addEventListener(MouseEvent.MOUSE_OUT, onMouseOut);
   3. var scaleTween:TweenFilterLite;
   4. TweenFilterLite.from(myButton, 2, {alpha:0, overwrite:false});
   5. function onMouseOver($e:MouseEvent):void {
   6.     TweenFilterLite.removeTween(scaleTween);
   7.     scaleTween = TweenFilterLite.to(myButton, 0.5, {scaleX:1.2, scaleY:1.2, overwrite:false});
   8. }
   9. function onMouseOut($e:MouseEvent):void {
   10.     TweenFilterLite.removeTween(scaleTween);
   11.     scaleTween = TweenFilterLite.to(myButton, 0.5, {scaleX:1, scaleY:1, overwrite:false});
   12. }

   Remember, other tweens of the same object will always be overwritten by default. You must set overwrite:false to avoid that behavior. The above example is essentially allowing you to selectively handle overwriting yourself instead of relying on the tweening engine to do the "all or nothing" technique.

3. Can I set up a sequence of tweens so that they occur one after the other?
   Of course! Just use the delay property and make sure you set the overwrite property to false (otherwise tweens of the same object will always overwrite each other to avoid conflicts). Here's an example where we colorize a MovieClip red over the course of 2 seconds, and then blur it over the course of 1 second:
   1. import gs.TweenFilterLite;
   2. TweenFilterLite.to(clip_mc, 2, {colorMatrixFilter:{colorize:0xFF0000, amount:1}});
   3. TweenFilterLite.to(clip_mc, 1, {blurFilter:{blurX:20, blurY:20}, delay:2, overwrite:false});

4. Why aren't my filters working?
   If you're using a filter that has an alpha property, try setting it to 1. The default alpha value is zero, so the filter may be working just fine, but you're not seeing it.

5. Do the properties have to be in a specific order?
   Nope. The only thing that matters is that the first parameter is the object you're tweening, the second parameter is the time (in seconds), and the third parameter contains all the properties you want to tween (in any order). So TweenFilterLite.to(clip_mc, 1, {colorMatrixFilter:{colorize:0xFF0000, amount:1}}) is the same as TweenFilterLite.to(clip_mc, 1, {colorMatrixFilter:{amount:1, colorize:0xFF0000}});

6. Can I use TweenFilterLite to tween things other than filters?
   Sure. It extends TweenLite, so you can tween any property you want. TweenFilterLite.to(my_mc, 1, {x:200}) gives you the same result as TweenLite.to(my_mc, 1, {x:200}). However, I'd recommend using TweenLite to tween properties other than filters for two reasons:
   1. In order to accommodate the specialized nature of filters, TweenFilterLite's code is a bit lengthier which translates into more work for the processor. It's doubtful that anyone would notice a performance hit unless you're tweening hundreds or thousands of instances simultaneously, but I'm a bit of an efficiency freak.
   2. TweenLite can tween any property of ANY object whereas TweenFilterLite tweens properties of DisplayObjects (like MovieClips, Sprites, etc.)

7. Why are TweenLite and TweenFilterLite split into 2 classes instead of building all the functionality into one class?
   1. File size. Only a portion of projects out there require tweening of filters. Almost every project I work on uses TweenLite, but only a few require tweening filters (TweenFilterLite). TweenLite is 3k whereas TweenFilterLite is 5k. Again, one of the stated purposes of TweenLite is to minimize file size & code bloat. If someone only wants to use TweenFilterLite, fine. But I think many people appreciate being able to use the most lightweight option for their needs and shave off the 3k when possible.
   2. Speed. Tweening filters is a more complex task. There are additional if/else statements and calculations in the rendering loop inside TweenFilterLite which could potentially slow things down a bit, even for non-filter tweens (I doubt anyone would notice a difference unless they’re running hundreds or thousands of simultaneous tweens, but I’m a big fan of keeping things as efficient & fast as possible)

8. Do I have to purchase a license to use this code? Can I use it for commercial purposes?
   TweenFilterLite is free. You're welcome to use it for commercial purposes - I only ask that you donate what you think the class is worth in your project(s), and consider joining Club GreenSock which gives you some bonus classes, updates, and more. If you want to use one (or more) of my classes in your commerical software product which would entail distributing the class files, please get my permission first by e-mailing me at jack -at- greensock.com.

Need Help?

Feel free to e-mail me a question. I'd highly recommend joining Club GreenSock to get prioritized access to my time in answering your question, and so that you receive updates and lots more. When you e-mail your question, please include a simplified FLA file (and any class files) that clearly demonstrates the problem and provide a brief explanation.