Jwee's Tween (animation) class is part of the wee.fx toolkit.
Jwee has a powerful animation engine all of its own. It has been built from the ground up for performance, smoothness, flexability, and ease-of-use for the developer.
- Start, stop, rewind, reverse, and continue Tweens.
- Tween any CSS property or a element property like scrollTop.
- You can tween by a % (percent), by + (plus) or - (minus)
- You can tween a property like “height” to the value of “auto”, to auto-fit a box
- Jwee keeps tracks of tweens internally, and will prevent concurrent tweens that are illogical. For example, if you animate opacity to 0 for 3 seconds, but then 1 second later animation opacity to 100, this would normally cause chaos. However, with Jwee, the first tween will automatically stop, and the second tween will start from the first tween's stopping position. Thus, a smooth uniterrupted animation is acheived throughout.
For those who are familiar with Flash's Tween class, you will find that jwee's methods and properties are almost identical. The easing equations themselves are currently identical to those used in Flash, which is also what YUI uses.
- HTML Elements also have the magic extended method animate().
- FX.Tween can be used directly with new if you want, or animations can be controlled from the animate() method on elements, which is easier..
See what the easing equations look like.
- You always pass the initial value as null. Frodo will figure it out from styles or offsets.
- You can specify a end value as a string like "+200". This means animate additional units from whatever the value is now.
- You can even specify "-25%". This would reduce the value of whatever, by 1/4th.
How to make a repeating or chaining animation?
The onComplete property of Tween can also be set to the instance of another Tween. This is the best way to chain tweens.
var flyright = new FX.Tween("foobox","left",null,"+350",0.6);
var flyleft = new FX.Tween("fooxbox","left",null,"-350",0.6);
flyright.onComplete = flyleft; // after flyright then execute flyleft
flyleft.onComplete = flyright; // and back again forever
flyright.start(); // start the sequence
You can also do it another way if you like:
That would make the element go down 500 then up 250 then down 100 one after the other.
If you just want to trigger something else when the tween ends, you can just assign your own function to the "onComplete" property. There is also the andThen() method of the Tween class.
More ways, doing simultaneous tween
Now this is a bit nuts, but in the code below, I'm creating an array of 3 tweens. Remember that tweens don't start until you call start(), unless you are using the animate() from the element directly. In code below I am calling the each method of the "Array" object, and passing in the name of the function to call upon every object in the array. This is a undocumented feature of the Array's each(). :)
[ new FX.Tween("foobox2","top",0,-100,2),
new FX.Tween("foobox2","width",null,100,2) ].each('.start()');
class new fx.Tween(...)( element, string property, [number startValue] or null, number endValue, [float duration] , [object options] )
|The Tween class is the brains of the animation engine.|
- The element of subject.
- The element's property to animate. Assumed to be a style property. Ex: "width" would mean "style.width". If you want to animate a html attribute like the "width" attribute on a IMG element, prefix the string with a period, like ".width".
- (optional) The start value for the animation. You can just put "null" here, and Jwee will figure the value out automatically
- The end value of the animation, such as 300 for "300px". You can also specify "auto", or "+50" or even "25%"
- (optional) The duration of the animation, in seconds, such as "5.5" for 5 and a half seconds.
- (optional) An object containing more options you can control.
|Returns||new instance of Tween class|
|Start the animation|
method wee.fx.Tween.stop(...)( boolean )
|Haults an animation in progress.|
method wee.fx.Tween.continueTo(...)( number value, [float duration] )
|Continue the animation with new values.|
Continue an animation on the same element / property to a new value.
- The duration is optional.
- If the current animation is already running it will be stopped. You don't need to stop it yourself.
- If the current animation is stopped prematurely the onComplete handler will NOT be called.
Run the animation again from the beginning.
|Run the opposite of the last animation, just like a yoyo.|
Run the reverse of the last animation.
|Is the animating currently going?|
A true or false whether the current Tween class's animation is currently running.