Jump to content
GreenSock

Search In
  • More options...
Find results that contain...
Find results in...

ThrowPropsPlugin.track()

ThrowPropsPlugin.track( target:Object, props:String, type:String ) : VelocityTracker

[static] Allows you to have the velocity of particular properties automatically tracked for you so that ThrowPropsPlugin tweens can access that data internally instead of manually calculating it and feeding it into each tween.

Parameters

target: Object

the target object whose properties will be tracked

props: String

a comma-delimited list of property names, like "y" or "x,y"

type: String

a comma-delimited list of property types (only helpful if they are rotation-based), "rad" for radian-based rotation or "deg" for degree-based rotation – this is only useful you’d like to have VelocityTracker compensate for artificial jumps in rotational values when the rotational midline is crossed, like when rotation goes from 179 to -178 degrees it would interpret that as a change of 3 instead of 357 degrees. Leave this blank unless you want the rotational compensation. You can use "num" to indicate normal numeric behavior (or leave it blank).

Returns : VelocityTracker

a VelocityTracker object that’s responsible for doing the tracking. You can use this if you want – the most useful method is its getVelocity() method that you feed the property name to like myTracker.getVelocity("y") to get the target’s y velocity anytime. Normally, however, you don’t need to keep track of this VelocityTracker object at all because the work is done internally and ThrowPropsPlugin knows how to find it.

Details

Allows you to have the velocity of particular properties automatically tracked for you so that ThrowPropsPlugin tweens can access that data internally instead of manually calculating it and feeding it into each tween. For example, let's say there's an object that the user interacts with by dragging it or maybe it is being tweened and then at some point you want to create athrowProps tween that smoothly continues that motion and glides to a rest. Normally, you'd need to write your own tracking code that records that object's x and y properties and the time stamps so that when it comes time to feed the velocity into the throwProps tween, you'd have the necessary data to calculate it. But let's face it: that can be cumbersome to do manually, and that's precisely why the track() method exists.

Just feed in the target and a comma-delimited list of its properties that you want tracked like this:

ThrowPropsPlugin.track(obj, "x,y");

Then every time the core tweening engine updates (at whatever frame rate you're running), the x and y values (or whichever properties you define) will be recorded along with time stamps (it keeps a maximum of 2 of these values and continually writes over the previous ones, so don't worry about memory buildup). This even works with function-based properties like getters and setters.

Then, after at least 100ms and 2 "ticks" of the core engine have elapsed (so that some data has been recorded), you can create throwProps tweens for those properties and omit the"velocity" values and it will automatically populate them for you internally. For example:

//first, start tracking "x" and "y":
ThrowPropsPlugin.track(obj, "x,y");

//then, after at least 100ms, let's smoothly tween to EXACTLY x:200, y:300
TweenLite.to(obj, 2, {throwProps:{x:{end:200}, y:{end:300}}, ease:Strong.easeOut});

//and if you want things to use the defaults and have obj.x and obj.y glide to a stop based on the velocity rather than setting any destination values, just use "auto":
TweenLite.to(obj, 2, {throwProps:{x:"auto", y:"auto"}, ease:Strong.easeOut});

Notice that "auto" is a valid option when you're tracking the properties too, but only for tracked properties.

What kinds of properties can be tracked?

Pretty much any numeric property of any object can be tracked, including function-based ones. For example, obj.x or obj.rotation or even obj.myCustomProp(). In fact, for getters and setters that start with the word "get" or "set" (like getCustomProp() and setCustomProp()), it will automatically find the matching counterpart method and use the getter appropriately, so you can track the getter or setter and it'll work. You cannot, however, track custom plugin-related values like "directionalRotation" or "autoAlpha" or "physics2D" because those aren't real properties of the object. You should instead track the real properties that those plugins affect, like "rotation" or "alpha" or "x" or "y".

IMPORTANT: you should untrack() properties when you no longer need them tracked in order to maximize performance and ensure things are released for garbage collection. To untrack, simply use the untrack() method:

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.
×