Package	com.greensock.plugins
Class	public class ThrowPropsPlugin
Inheritance	ThrowPropsPlugin TweenPlugin

ThrowPropsPlugin allows you to simply define an initial velocity for a property (or multiple properties) as well as optional maximum and/or minimum end values and then it will calculate the appropriate landing position and plot a smooth course based on the easing equation you define (Quad.easeOut by default, as set in TweenLite). This is perfect for flick-scrolling or animating things as though they are being thrown.

For example, let's say a user clicks and drags a ball and you track its velocity using an ENTER_FRAME handler and then when the user releases the mouse button, you'd determine the velocity but you can't do a normal tween because you don't know exactly where it should land or how long the tween should last (faster initial velocity would mean a longer duration). You need the tween to pick up exactly where the user left off so that it appears to smoothly continue moving in the same direction and at the same velocity they were dragging and then decelerate based on whatever ease you define in your tween.

Oh, and one more challenge: maybe you want the final resting value to always lie within a particular range so that things don't land way off the edge of the screen. But you don't want it to suddenly jerk to a stop when it hits the edge of the screen; instead, you want it to ease gently into place even if that means going past the landing spot briefly and easing back (if the initial velocity is fast enough to require that). The whole point is to make it look smooth.

No problem.

In its simplest form, you can pass just the initial velocity for each property like this:

TweenLite.to(mc, 2, {throwProps:{x:500, y:-300}});

In the above example, mc.x will animate at 500 pixels per second initially and mc.y will animate at -300 pixels per second. Both will decelerate smoothly until they come to rest 2 seconds later (because the tween's duration is 2 seconds).

To use the Strong.easeOut easing equation and impose maximum and minimum boundaries on the end values, use the object syntax with the max and min special properties like this:

TweenLite.to(mc, 2, {throwProps:{x:{velocity:500, max:1024, min:0}, y:{velocity:-300, max:720, min:0}}, ease:Strong.easeOut});

Notice the nesting of the objects ({}). The max and min values refer to the range for the final resting position (coordinates in this case), NOT the velocity. So mc.x would always land between 0 and 1024 in this case, and mc.y would always land between 0 and 720. If you want the target object to land on a specific value rather than within a range, simply set max and min to identical values. Also notice that you must define a velocity value for each property.

ThrowPropsPlugin isn't just for tweening x and y coordinates. It works with any numeric property, so you could use it for spinning the rotation of an object as well. Or the scaleX/scaleY properties. Maybe the user drags to spin a wheel and lets go and you want it to continue increasing the rotation at that velocity, decelerating smoothly until it stops.

One of the trickiest parts of creating a throwProps tween that looks fluid and natural, particularly if you're applying maximum and/or minimum values, is determining its duration. Typically it's best to have a relatively consistent level of resistance so that if the initial velocity is very fast, it takes longer for the object to come to rest compared to when the initial velocity is slower. You also may want to impose some restrictions on how long a tween can last (if the user drags incredibly fast, you might not want the tween to last 200 seconds). The duration will also affect how far past a max/min boundary the property can potentially go, so you might want to only allow a certain amount of overshoot tolerance. That's why ThrowPropsPlugin has a few static helper methods that make managing all these variables much easier. The one you'll probably use most often is the to() method which is very similar to TweenLite.to() except that it doesn't have a duration parameter and it adds several other optional parameters. Read the docs below for details.

Feel free to experiment with using different easing equations to control how the values ease into place at the end. You don't need to put the "ease" special property inside the throwProps object. Just keep it in the same place it has always been, like:

TweenLite.to(mc, 1, {throwProps:{x:500, y:-300}, ease:Strong.easeOut});

A unique convenience of ThrowPropsPlugin compared to most other solutions out there which use ENTER_FRAME loops is that everything is reverseable and you can jump to any spot in the tween immediately. So if you create several throwProps tweens, for example, and dump them into a TimelineLite, you could simply call reverse() on the timeline to watch the objects retrace their steps right back to the beginning.

(note: it is best to use an easeOut with throwProps tweens, but you can vary the strength by using different flavors like Strong.easeOut, Cubic.easeOut, Quad.easeOut, Back.easeOut, etc.)

The following example creates a Sprite (mc), populates it with a long TextField and makes it vertically draggable. Then it tracks its velocity in an ENTER_FRAME handler and then allows it to be thrown within the bounds defined by the bounds rectangle, smoothly easing into place regardless of where and how fast it is thrown:

Example
Example AS3 code: ThrowPropsPlugin is a Club GreenSock membership benefit. You must have a valid membership to use this class without violating the terms of use. Visit http://www.greensock.com/club/ to sign up or get more details.

Copyright 2011, GreenSock. All rights reserved. This work is subject to the terms in http://www.greensock.com/terms_of_use.html or for corporate Club GreenSock members, the software agreement that was issued with the corporate membership.

---

defaultResistance

property

calculateChange

()

method

calculateDuration

()

method

calculateTweenDuration

()

method

to

()

method

---