Jump to content
GreenSock

ThrowPropsPlugin.to()

ThrowPropsPlugin.to( target:Object, vars:Object, maxDuration:Number, minDuration:Number, overshootTolerance:Number ) : TweenLite

[static] Automatically analyzes various throwProps variables (like velocity, max, min, and resistance) and creates a TweenLite instance with the appropriate duration.

Parameters

target: Object

Target object whose properties the tween affects. This can be ANY object, not just a DOM element.

vars: Object

An object containing the end values of the properties you’re tweening, and it must also contain a throwProps object. For example, to create a tween that tweensobj.x at an initial velocity of 500 and obj.y at an initial velocity of -300 and applies a resistance of 80 and uses the Strong.easeOut easing equation and calls the methodtweenCompleteHandler when it is done, the vars object would look like: {throwProps:{x:500, y:-300, resistance:80}, ease:Strong.easeOut, onComplete:tweenCompleteHandler}.

maxDuration: Number

(default = 100) — Maximum duration of the tween

minDuration: Number

(default = 0.25) — Minimum duration of the tween

overshootTolerance: Number

(default = 1) — sets a maximum number of seconds that can be added to the tween’s duration (if necessary) to accommodate temporarily overshooting the end value before smoothly returning to it at the end of the tween. This can happen in situations where the initial velocity would normally cause it to exceed the maxor min values. An example of this would be in the iOS (iPhone or iPad) when you flick-scroll so quickly that the content would shoot past the end of the scroll area. Instead of jerking to a sudden stop when it reaches the edge, the content briefly glides past the max/min position and gently eases back into place. The larger the overshootTolerance the more leeway the tween has to temporarily shoot past the max/min if necessary.

Returns : TweenLite

TweenLite instance

Details

Automatically analyzes various throwProps variables (like velocitymaxmin, and resistance) and creates a TweenLite instance with the appropriate duration. You can useThrowPropsPlugin.to() instead of TweenLite.to() to create a tween - they're identical except that ThrowPropsPlugin.to() doesn't have a duration parameter (it figures it out for you) and it adds a few extra parameters to the end that can optionally be used to affect the duration.

Another key difference is that ThrowPropsPlugin.to() will recognize the resistance special property which basically controls how quickly each property's velocity decelerates (and consequently influences the duration of the tween). For example, if the initial velocity is 500 and the resistance is 300, it will decelerate much faster than if the resistance was 20. You can define a resistance value either for each individual property in the throwProps tween like this:

ThrowPropsPlugin.to(obj, {throwProps:{x:{velocity:500, resistance:150}, y:{velocity:-300, resistance:50}}});

OR you can define a single resistance value that will be used for all of the properties in that particular throwProps tween like this:

ThrowPropsPlugin.to(obj, {throwProps:{x:500, y:-300, resistance:150}});

//-OR-

ThrowPropsPlugin.to(obj, {throwProps:{x:{velocity:500, max:800, min:0}, y:{velocity:-300, max:700, min:100}, resistance:150}});

resistance should always be a positive value, although velocity can be negative. resistance always works against velocity. If no resistance value is found, theThrowPropsPlugin.defaultResistance value will be used. The resistance values merely affect the duration of the tween and can be overriden by the maxDuration andminDuration parameters. Think of the resistance as more of a suggestion that ThrowPropsPlugin uses in its calculations rather than an absolute set-in-stone value. When there are multiple properties in one throwProps tween (like x and y) and the calculated duration for each one is different, the longer duration is always preferred in order to make things animate more smoothly.

You also may want to impose some restrictions on the tween's duration (if the user drags incredibly fast, for example, you might not want the tween to last 200 seconds). UsemaxDuration and minDuration parameters for that. You can use the overshootTolerance parameter to set a maximum number of seconds that can be added to the tween's duration (if necessary) to accommodate temporarily overshooting the end value before smoothly returning to it at the end of the tween. This can happen in situations where the initial velocity would normally cause it to exceed the max or min values. An example of this would be in the iOS (iPhone or iPad) when you flick-scroll so quickly that the content would shoot past the end of the scroll area. Instead of jerking to a sudden stop when it reaches the edge, the content briefly glides past the max/min position and gently eases back into place. The larger the overshootTolerance the more leeway the tween has to temporarily shoot past the max/min if necessary.

If you'd like to have ThrowPropsPlugin automatically track the velocity of certain properties for you and auto-populate them internally so that you don't have to pass velocity values in, use the track() method.

Valid properties for object syntax

  • velocity : Number or "auto" - the initial velocity, measured in units per second (or per frame for frames-based tweens). You may omit velocity or just use "auto" for properties that are being tracked automatically using the track() method.
  • min : Number - the minimum end value of the property. For example, if you don't want x to land at a value below 0, your throwProps may look like {x:{velocity:-500, min:0}}
  • max : Number - the maximum end value of the property. For example, if you don't want x to exceed 1024, your throwProps may look like {x:{velocity:500, max:1024}}
  • end : [Number | Array | Function] - if end is defined as a Number, the target will land EXACTLY there (just as if you set both the max and min to identical values). If end is defined as a numeric Array, those values will be treated like "notches" or "snap-to" values so that the closest one to the natural landing spot will be selected. For example, if[0,100,200] is used, and the value would have naturally landed at 141, it will use the closest number (100 in this case) and land there instead. If end is defined as a Function, that function will be called and passed the natural landing value as the only parameter, and your function can run whatever logic you want, and then return the number at which it should land. This can be useful if, for example, you have a rotational tween and you want it to snap to 10-degree increments no matter how big or small, you could use a function that just rounds the natural value to the closest 10-degree increment. So any of these are valid: end:100 or end:[0,100,200,300] or end:function(n) { return Math.round(n / 10) * 10; }
  • resistance : Number - think of resistance like the rate of velocity decay. If no resistance value is found, the ThrowPropsPlugin.defaultResistance value will be used. Theresistance values merely affect the duration of the tween and can be overriden by the maxDuration and minDuration parameters.

 

Copyright 2017, GreenSock. All rights reserved. This work is subject to theterms of useor for Club GreenSock members, the software agreement that was issued with the membership.
×