package aurelienribon.tweenengine;
import aurelienribon.tweenengine.equations.Quad;
import java.util.HashMap;
import java.util.Map;
/**
* Core class of the Tween Engine. A Tween is basically an interpolation
* between two values of an object attribute. However, the main interest of a
* Tween is that you can apply an easing formula on this interpolation, in
* order to smooth the transitions or to achieve cool effects like springs or
* bounces.
*
*
* The Universal Tween Engine is called "universal" because it is able to apply
* interpolations on every attribute from every possible object. Therefore,
* every object in your application can be animated with cool effects: it does
* not matter if your application is a game, a desktop interface or even a
* console program! If it makes sense to animate something, then it can be
* animated through this engine.
*
*
* This class contains many static factory methods to create and instantiate
* new interpolations easily. The common way to create a Tween is by using one
* of these factories:
*
*
* - Tween.to(...)
* - Tween.from(...)
* - Tween.set(...)
* - Tween.call(...)
*
*
*
Example - firing a Tween
*
* The following example will move the target horizontal position from its
* current value to x=200 and y=300, during 500ms, but only after a delay of
* 1000ms. The animation will also be repeated 2 times (the starting position
* is registered at the end of the delay, so the animation will automatically
* restart from this registered position).
*
*
*
*
* Tween life-cycles can be automatically managed for you, thanks to the
* {@link TweenManager} class. If you choose to manage your tween when you start
* it, then you don't need to care about it anymore. Tweens are
* fire-and-forget: don't think about them anymore once you started
* them (if they are managed of course).
*
*
* You need to periodicaly update the tween engine, in order to compute the new
* values. If your tweens are managed, only update the manager; else you need
* to call {@link #update()} on your tweens periodically.
*
*
*
Example - setting up the engine
*
* The engine cannot directly change your objects attributes, since it doesn't
* know them. Therefore, you need to tell him how to get and set the different
* attributes of your objects: you need to implement the {@link
* TweenAccessor} interface for each object class you will animate. Once
* done, don't forget to register these implementations, using the static method
* {@link registerAccessor()}, when you start your application.
*
* @see TweenAccessor
* @see TweenManager
* @see TweenEquation
* @see Timeline
* @author Aurelien Ribon | http://www.aurelienribon.com/
*/
public final class Tween extends BaseTween {
// -------------------------------------------------------------------------
// Static -- misc
// -------------------------------------------------------------------------
/**
* Used as parameter in {@link #repeat(int, float)} and
* {@link #repeatYoyo(int, float)} methods.
*/
public static final int INFINITY = -1;
private static int combinedAttrsLimit = 3;
private static int waypointsLimit = 0;
/**
* Changes the limit for combined attributes. Defaults to 3 to reduce
* memory footprint.
*/
public static void setCombinedAttributesLimit(int limit) {
Tween.combinedAttrsLimit = limit;
}
/**
* Changes the limit of allowed waypoints for each tween. Defaults to 0 to
* reduce memory footprint.
*/
public static void setWaypointsLimit(int limit) {
Tween.waypointsLimit = limit;
}
/**
* Gets the version number of the library.
*/
public static String getVersion() {
return "6.3.3";
}
// -------------------------------------------------------------------------
// Static -- pool
// -------------------------------------------------------------------------
private static final Pool.Callback poolCallback = new Pool.Callback() {
@Override public void onPool(Tween obj) {obj.reset();}
@Override public void onUnPool(Tween obj) {obj.reset();}
};
private static final Pool pool = new Pool(20, poolCallback) {
@Override protected Tween create() {return new Tween();}
};
/**
* Used for debug purpose. Gets the current number of objects that are
* waiting in the Tween pool.
*/
public static int getPoolSize() {
return pool.size();
}
/**
* Increases the minimum capacity of the pool. Capacity defaults to 20.
*/
public static void ensurePoolCapacity(int minCapacity) {
pool.ensureCapacity(minCapacity);
}
// -------------------------------------------------------------------------
// Static -- tween accessors
// -------------------------------------------------------------------------
private static final Map, TweenAccessor>> registeredAccessors = new HashMap, TweenAccessor>>();
/**
* Registers an accessor with the class of an object. This accessor will be
* used by tweens applied to every objects implementing the registered
* class, or inheriting from it.
*
* @param someClass An object class.
* @param defaultAccessor The accessor that will be used to tween any
* object of class "someClass".
*/
public static void registerAccessor(Class> someClass, TweenAccessor> defaultAccessor) {
registeredAccessors.put(someClass, defaultAccessor);
}
/**
* Gets the registered TweenAccessor associated with the given object class.
*
* @param someClass An object class.
*/
public static TweenAccessor> getRegisteredAccessor(Class> someClass) {
return registeredAccessors.get(someClass);
}
// -------------------------------------------------------------------------
// Static -- factories
// -------------------------------------------------------------------------
/**
* Factory creating a new standard interpolation. This is the most common
* type of interpolation. The starting values are retrieved automatically
* after the delay (if any).
*
*
* You need to set the target values of the interpolation by using one
* of the target() methods. The interpolation will run from the
* starting values to these target values.
*
*
* The common use of Tweens is "fire-and-forget": you do not need to care
* for tweens once you added them to a TweenManager, they will be updated
* automatically, and cleaned once finished. Common call:
*
*
* Several options such as delay, repetitions and callbacks can be added to
* the tween.
*
* @param target The target object of the interpolation.
* @param tweenType The desired type of interpolation.
* @param duration The duration of the interpolation, in milliseconds.
* @return The generated Tween.
*/
public static Tween to(Object target, int tweenType, float duration) {
Tween tween = pool.get();
tween.setup(target, tweenType, duration);
tween.ease(Quad.INOUT);
tween.path(TweenPaths.catmullRom);
return tween;
}
/**
* Factory creating a new reversed interpolation. The ending values are
* retrieved automatically after the delay (if any).
*
*
* You need to set the starting values of the interpolation by using one
* of the target() methods. The interpolation will run from the
* starting values to these target values.
*
*
* The common use of Tweens is "fire-and-forget": you do not need to care
* for tweens once you added them to a TweenManager, they will be updated
* automatically, and cleaned once finished. Common call:
*
*
* Several options such as delay, repetitions and callbacks can be added to
* the tween.
*
* @param target The target object of the interpolation.
* @param tweenType The desired type of interpolation.
* @param duration The duration of the interpolation, in milliseconds.
* @return The generated Tween.
*/
public static Tween from(Object target, int tweenType, float duration) {
Tween tween = pool.get();
tween.setup(target, tweenType, duration);
tween.ease(Quad.INOUT);
tween.path(TweenPaths.catmullRom);
tween.isFrom = true;
return tween;
}
/**
* Factory creating a new instantaneous interpolation (thus this is not
* really an interpolation).
*
*
* You need to set the target values of the interpolation by using one
* of the target() methods. The interpolation will set the target
* attribute to these values after the delay (if any).
*
*
* The common use of Tweens is "fire-and-forget": you do not need to care
* for tweens once you added them to a TweenManager, they will be updated
* automatically, and cleaned once finished. Common call:
*
*
* Several options such as delay, repetitions and callbacks can be added to
* the tween.
*
* @param target The target object of the interpolation.
* @param tweenType The desired type of interpolation.
* @return The generated Tween.
*/
public static Tween set(Object target, int tweenType) {
Tween tween = pool.get();
tween.setup(target, tweenType, 0);
tween.ease(Quad.INOUT);
return tween;
}
/**
* Factory creating a new timer. The given callback will be triggered on
* each iteration start, after the delay.
*
*
* The common use of Tweens is "fire-and-forget": you do not need to care
* for tweens once you added them to a TweenManager, they will be updated
* automatically, and cleaned once finished. Common call:
*
*
* @param callback The callback that will be triggered on each iteration
* start.
* @return The generated Tween.
* @see TweenCallback
*/
public static Tween call(TweenCallback callback) {
Tween tween = pool.get();
tween.setup(null, -1, 0);
tween.setCallback(callback);
tween.setCallbackTriggers(TweenCallback.START);
return tween;
}
/**
* Convenience method to create an empty tween. Such object is only useful
* when placed inside animation sequences (see {@link Timeline}), in which
* it may act as a beacon, so you can set a callback on it in order to
* trigger some action at the right moment.
*
* @return The generated Tween.
* @see Timeline
*/
public static Tween mark() {
Tween tween = pool.get();
tween.setup(null, -1, 0);
return tween;
}
// -------------------------------------------------------------------------
// Attributes
// -------------------------------------------------------------------------
// Main
private Object target;
private Class> targetClass;
private TweenAccessor