| Package | com.greensock.utils |
| Class | public final class VelocityTracker |
| Inheritance | VelocityTracker  Object |
getVelocity()
method, like myTracker.getVelocity("y"). 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 a tween based on that velocity. Normally, you'd need to write your own tracking code
that records that object's x and y properties (as well as time stamps)
so that when it comes time to feed the velocity into whatever other code you need to run,
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 VelocityTracker exists.
Use the static VelocityTracker.track() method to start tracking properties. You generally
should not use the VelocityTracker's constructor because there needs to only be one
VelocityTracker instance associated with any particular object. The track() method will
return the instance that you can then use to getVelocity() like:
//first, start tracking "x" and "y":
var tracker:VelocityTracker = VelocityTracker.track(obj, "x,y");
//then, after at least 100ms and 2 "ticks", we can get the velocity of each property:
var vx:Number = tracker.getVelocity("x");
var vy:Number = tracker.getVelocity("y");
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".
This class is used in ThrowPropsPlugin to make it easy to create velocity-based tweens
that smoothly transition an object's movement (or rotation or whatever) and glide to a stop.
Note: In order to report accurately, at least 100ms and 2 ticks of the core tweening engine must have been elapsed before you check velocity.
Copyright 2008-2013, GreenSock. All rights reserved. This work is subject to the terms in http://www.greensock.com/terms_of_use.html or for Club GreenSock members, the software agreement that was issued with the membership.
| Property | Defined By | ||
|---|---|---|---|
| target : Object Returns the target object with which the VelocityTracker is associated. | VelocityTracker | ||
| Method | Defined By | ||
|---|---|---|---|
addProp(prop:String, type:String = num):void
Adds a property to track
| VelocityTracker | ||
getByTarget(target:Object):VelocityTracker [static]
Returns the VelocityTracker associated with a particular object. | VelocityTracker | ||
getVelocity(prop:String):Number
Returns the current velocity of the given property. | VelocityTracker | ||
isTracking(target:Object, prop:String = null):Boolean [static]
Allows you to discern whether the velocity of a particular target or one of its properties is being tracked
(typically initiated using the VelocityTracker.track() method). | VelocityTracker | ||
isTrackingProp(prop:String):Boolean
Allows you to discern whether the velocity of a particular property is being tracked. | VelocityTracker | ||
removeProp(prop:String):void
Stops tracking a particular property
| VelocityTracker | ||
track(target:Object, props:String, types:String = num):VelocityTracker [static]
Allows you to have the velocity of particular properties automatically tracked for you
so that you can access them anytime using the VelocityTracker's getVelocity()
method, like myTracker.getVelocity("y"). | VelocityTracker | ||
untrack(target:Object, props:String = null):void [static]
Stops tracking the velocity of certain properties (or all properties of an object), like ones initiated with
the track() method. | VelocityTracker | ||
| target | property |
public var target:ObjectReturns the target object with which the VelocityTracker is associated.
| addProp | () | method |
public function addProp(prop:String, type:String = num):voidAdds a property to track
Parameters
prop:String — "rad" for radian-based rotation or "deg" for degree-based rotation - this is only useful to define if the property is rotation-related and you'd like to have VelocityTracker compensate for artificial jumps in the value 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.
| |
type:String (default = num) |
| getByTarget | () | method |
public static function getByTarget(target:Object):VelocityTracker
Returns the VelocityTracker associated with a particular object. If none exists,
null will be returned.
Parameters
target:Object — The object whose VelocityTracker should be returned
|
VelocityTracker — the VelocityTracker associated with the object (or null if none exists)
|
| getVelocity | () | method |
public function getVelocity(prop:String):NumberReturns the current velocity of the given property.
Parameters
prop:String — Property name (like "x")
|
Number — The current velocity
|
| isTracking | () | method |
public static function isTracking(target:Object, prop:String = null):Boolean
Allows you to discern whether the velocity of a particular target or one of its properties is being tracked
(typically initiated using the VelocityTracker.track() method).
Parameters
target:Object — The target object
| |
prop:String (default = null)"x" or "y".
|
Boolean — true if the target/property is being tracked, false if not.
|
See also
| isTrackingProp | () | method |
public function isTrackingProp(prop:String):BooleanAllows you to discern whether the velocity of a particular property is being tracked.
Parameters
prop:String — the name of the property to check, like "x" or "y".
|
Boolean — true if the target/property is being tracked, false if not.
|
See also
| removeProp | () | method |
public function removeProp(prop:String):voidStops tracking a particular property
Parameters
prop:String — the property name to stop tracking
|
| track | () | method |
public static function track(target:Object, props:String, types:String = num):VelocityTracker
Allows you to have the velocity of particular properties automatically tracked for you
so that you can access them anytime using the VelocityTracker's getVelocity()
method, like myTracker.getVelocity("y"). 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 a 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 (as well as time stamps) so that when it comes time to feed the
velocity into the 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 properties that you want
tracked like this:
var tracker:VelocityTracker = VelocityTracker.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 keeps writing over the previous
ones, so don't worry about memory buildup). This even works with properties that are function-based, 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 use the VelocityTracker's getVelocity() method to get the current velocity of a particular
property.
//first, start tracking "x" and "y":
var tracker:VelocityTracker = VelocityTracker.track(obj, "x,y");
//then, after at least 100ms, we can get the velocity:
var vx:Number = tracker.getVelocity("x");
var vy:Number = tracker.getVelocity("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:
//stop tracking only the "x" property:
VelocityTracker.untrack(obj, "x");
//stop tracking "x" and "y":
VelocityTracker.untrack(obj, "x,y");
//stop tracking all properties of obj:
VelocityTracker.untrack(obj);
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".
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"
| |
types:String (default = num)"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).
|
VelocityTracker — a VelocityTracker object that's responsible for doing the tracking.
|
See also
| untrack | () | method |
public static function untrack(target:Object, props:String = null):void
Stops tracking the velocity of certain properties (or all properties of an object), like ones initiated with
the track() method.
//starts tracking "x" and "y":
var tracker:VelocityTracker = VelocityTracker.track(obj, "x,y");
//stops tracking only the "x" property:
VelocityTracker.untrack(obj, "x");
//stops tracking "x" and "y":
VelocityTracker.untrack(obj, "x,y");
//stops tracking all properties of obj:
VelocityTracker.untrack(obj);
//or you can use the removeProp() method directly on the VelocityTracker instance to remove one at a time:
tracker.removeProp("x");
Parameters
target:Object — the target object whose properties should stop being tracked
| |
props:String (default = null)null, ALL properties of the target will stop being tracked.
|
See also