net.rim.device.api.animation
Class Animation

java.lang.Object
  extended by net.rim.device.api.animation.AbstractAnimation
      extended by net.rim.device.api.animation.Animation

public class Animation
extends AbstractAnimation

Defines a class that can animate values of an Animatable target property according to an AnimationKeyframeSequence over a specified period of time.

Binds an AnimationKeyframeSequence and Animatable object target and target property. This class is used to define how the values of a target property change over time based on the given sequence data.

Animation Setup

Creating an animation from simple 'from-to' single value data.

 // Create the animator
 Animator animator = new Animator(25);
 // Create the animatable target
 AnimatedScalar alpha = new AnimatedScalar(1.0f);
 // Create a fade-out animation. This animates the alpha value from 1.0 to 0.0.
 Animation animation = animator.addAnimationFromTo(alpha, AnimatedScalar.ANIMATION_PROPERTY_SCALAR, 1.0f, 0.0f, Animation.EASINGCURVE_LINEAR, 1000L);
 animation.setRepeatCount(1.0f);
 

Creating an animation from a simple 'to' vector of data.

 // Create the animator
 Animator animator = new Animator(25);
 // Create the animatable target
 AnimatedVector position = new AnimatedVector( new float[] { 0.0f, 0.0f }, 0 );
 // Create a translation animation on the target to animate the position vector 'to' position (100, 100)
 Animation animation = animator.addAnimationTo(position, AnimatedVector.ANIMATION_PROPERTY_VECTOR, new float[] { 100.0f, 100.0f }, 0, Animation.EASINGCURVE_LINEAR, 1000L);
 animation.setRepeatCount(1.0f);
 

Begin the Animation

 // Schedules the animation to begin with a 1 second delay.
 animation.begin(1000L);
 

Easing Curves

Pace can be controlled by the use of either an easing curve function or a cubic Bézier spline. In both cases, the domain represents the fraction of the duration passed, while the range represents the fraction of the distance travelled.

Easing Functions

If f(t) is an easing function and the “position” of an attribute of an animatable object changes from p1 to p2 during d time units (e.g., ms). Then at time t (0 <= t <= d), the attribute will be at position

(p2-p1) * f(t/d) + p1.

Here, “position” can be generalized to any numerical quantity.

There are four main categories of easing in/out functions:

The Animation API provides support for the following easing functions. Note that the picture in the second column of each row is the “normalized” graph of the corresponding easing function where the value of the domain is in the interval [0,1].


  EASINGCURVE_LINEAR
  Linear
  EASINGCURVE_QUADRATIC_IN
  Quadratic Ease-In
  EASINGCURVE_CUBIC_IN
  Cubic Ease-In
  EASINGCURVE_QUARTIC_IN
  Quartic Ease-In
  EASINGCURVE_QUINTIC_IN
  Quintic Ease-In
  EASINGCURVE_SINE_IN
  Sine Ease-In
  EASINGCURVE_EXPONENTIAL_IN
  Exponential Ease-In
  EASINGCURVE_CIRCULAR_IN
  Curve Ease-In
  EASINGCURVE_ELASTIC_IN
  Elastic Ease-In
  EASINGCURVE_OVERSHOOT_IN
  Overshoot Ease-In
  EASINGCURVE_BOUNCE_IN
  Bounce Ease-In
  EASINGCURVE_QUADRATIC_OUT
  Quadratic Ease-Out
  EASINGCURVE_CUBIC_OUT
  Cubic Ease-Out
  EASINGCURVE_QUARTIC_OUT
  Quartic Ease-Out
  EASINGCURVE_QUINTIC_OUT
  Quintic Ease-Out
  EASINGCURVE_SINE_OUT
  Sine Ease-Out
  EASINGCURVE_EXPONENTIAL_OUT
  Exponential Ease-Out
  EASINGCURVE_CIRCULAR_OUT
  Circular Ease-Out
  EASINGCURVE_ELASTIC_OUT
  Elastic Ease-Out
  EASINGCURVE_OVERSHOOT_OUT
  Overshoot Ease-Out
  EASINGCURVE_BOUNCE_OUT
  Bounce Ease-Out
  EASINGCURVE_QUADRATIC_INOUT
  Quadratic Ease-In-Out
  EASINGCURVE_CUBIC_INOUT
  Cubic Ease-In-Out
  EASINGCURVE_QUARTIC_INOUT
  Quartic Ease-In-Out
  EASINGCURVE_QUINTIC_INOUT
  Quintic Ease-In-Out
  EASINGCURVE_SINE_INOUT
  Sine Ease-In-Out
  EASINGCURVE_EXPONENTIAL_INOUT
  Exponential Ease-In-Out
  EASINGCURVE_CIRCULAR_INOUT
  Circular Ease-In-Out
  EASINGCURVE_ELASTIC_INOUT
  Elastic Ease-In-Out
  EASINGCURVE_OVERSHOOT_INOUT
  Overshoot Ease-In-Out
  EASINGCURVE_BOUNCE_INOUT
  Bounce Ease-In-Out
  EASINGCURVE_QUADRATIC_OUTIN
  Quadratic Ease-Out-In
  EASINGCURVE_CUBIC_OUTIN
  Cubic Ease-Out-In
  EASINGCURVE_QUARTIC_OUTIN
  Quartic Ease-Out-In
  EASINGCURVE_QUINTIC_OUTIN
  Quintic Ease-Out-In
  EASINGCURVE_SINE_OUTIN
  Sine Ease-Out-In
  EASINGCURVE_EXPONENTIAL_OUTIN
  Exponential Ease-Out-In
  EASINGCURVE_CIRCULAR_OUTIN
  Circular Ease-Out-In
  EASINGCURVE_ELASTIC_OUTIN
  Elastic Ease-Out-In
  EASINGCURVE_OVERSHOOT_OUTIN
  Overshoot Ease-Out-In
  EASINGCURVE_BOUNCE_OUTIN
  Bounce Ease-Out-In

With discrete interpolation (EASINGCURVE_DISCRETE), the easing function jumps from one value to the next without interpolation. Let v_i be the value at time t_i for 0 <= i <= n. Then for all t in [ t_i, t_(i+1) ),   i = 0, ..., n-1, the easing function is defined as

f(t) = v_i,  and f(t_n) = v_n.

As an example, for the following table:

  i     0     1     2     3     4     5  
  t_i     0     5     10     15     20     25  
  v_i     0     1     2     4     8     15  

the graph for the easing function using discrete interpolation has the following form:


In general, an easing function can be represented by a piecewise univariate function. In the cubic case, for example, the easing functions are:

The velocity at each time fraction can be easily computed, and is shown in the following table:

t EASINGCURVE_CUBIC_IN EASINGCURVE_CUBIC_OUT EASINGCURVE_CUBIC_INOUT EASINGCURVE_CUBIC_OUTIN
0.0 0.00 3.00 0.00 3.00
0.1 0.03 2.43 0.12 1.92
0.2 0.12 1.92 0.48 1.08
0.3 0.27 1.47 1.08 0.48
0.4 0.48 1.08 1.92 0.12
0.5 0.75 0.75 3.00 0.00
0.6 1.08 0.48 1.92 0.12
0.7 1.47 0.27 1.08 0.48
0.8 1.92 0.12 0.48 1.08
0.9 2.43 0.03 0.12 1.92
1.0 3.00 0.00 0.00 3.00

Observe that the above figures agree with the types of the four easing functions (in terms of acceleration/deceleration). The following picture shows the location of a ball moving along a line parallel to the horizontal axis. The start and end positions are 50 and 200, respectively. The duration is 10ms. The pace is controlled using the four cubic easing functions.


Cubic Bézier Splines

In using the EASINGCURVE_SPLINE curve type, a user elects to use a custom easing curve definition from the keyspline data that can be specified using:

AnimationKeyframeSequence#setKeysplines(float[])

This methods allows a user to specify 2 (x,y) control points per keyframe as an array.

With cubic Bézier splines, one can control the acceleration/deceleration during each time interval by providing the two control points.

Each of the following diagrams illustrate the effect of the control points for a single interval. The title [x_1, y_1, x_2, y_2] means the two control points (x_1, y_1) and (x_2, y_2) are used. The horizontal axis can be thought of as the input value for the unit progress of interpolation within the interval, i.e., the pace with which interpolation proceeds along the given interval. The vertical axis is the resulting value for the unit progress.

The following diagram shows the locations of four balls, each of which moves along a line parallel to the horizontal axis. The start and end positions are 50 and 200, respectively. The duration is 10ms. The paces are controlled by the four sets of control points whose effects are illustrated in the diagrams above.


Since:
BlackBerry API 6.0.0

Field Summary
static int EASINGCURVE_BOUNCE_IN
           
static int EASINGCURVE_BOUNCE_INOUT
           
static int EASINGCURVE_BOUNCE_OUT
           
static int EASINGCURVE_BOUNCE_OUTIN
           
static int EASINGCURVE_CIRCULAR_IN
           
static int EASINGCURVE_CIRCULAR_INOUT
           
static int EASINGCURVE_CIRCULAR_OUT
           
static int EASINGCURVE_CIRCULAR_OUTIN
           
static int EASINGCURVE_CUBIC_IN
           
static int EASINGCURVE_CUBIC_INOUT
           
static int EASINGCURVE_CUBIC_OUT
           
static int EASINGCURVE_CUBIC_OUTIN
           
static int EASINGCURVE_DISCRETE
           
static int EASINGCURVE_ELASTIC_IN
           
static int EASINGCURVE_ELASTIC_INOUT
           
static int EASINGCURVE_ELASTIC_OUT
           
static int EASINGCURVE_ELASTIC_OUTIN
           
static int EASINGCURVE_EXPONENTIAL_IN
           
static int EASINGCURVE_EXPONENTIAL_INOUT
           
static int EASINGCURVE_EXPONENTIAL_OUT
           
static int EASINGCURVE_EXPONENTIAL_OUTIN
           
static int EASINGCURVE_LINEAR
           
static int EASINGCURVE_OVERSHOOT_IN
           
static int EASINGCURVE_OVERSHOOT_INOUT
           
static int EASINGCURVE_OVERSHOOT_OUT
           
static int EASINGCURVE_OVERSHOOT_OUTIN
           
static int EASINGCURVE_QUADRATIC_IN
           
static int EASINGCURVE_QUADRATIC_INOUT
           
static int EASINGCURVE_QUADRATIC_OUT
           
static int EASINGCURVE_QUADRATIC_OUTIN
           
static int EASINGCURVE_QUARTIC_IN
           
static int EASINGCURVE_QUARTIC_INOUT
           
static int EASINGCURVE_QUARTIC_OUT
           
static int EASINGCURVE_QUARTIC_OUTIN
           
static int EASINGCURVE_QUINTIC_IN
           
static int EASINGCURVE_QUINTIC_INOUT
           
static int EASINGCURVE_QUINTIC_OUT
           
static int EASINGCURVE_QUINTIC_OUTIN
           
static int EASINGCURVE_SINE_IN
           
static int EASINGCURVE_SINE_INOUT
           
static int EASINGCURVE_SINE_OUT
           
static int EASINGCURVE_SINE_OUTIN
           
static int EASINGCURVE_SPLINE
           
static float REPEAT_COUNT_INDEFINITE
          Indefinite repeat count.
static long REPEAT_DURATION_INDEFINITE
          Indefinite repeat duration.
static int RESTART_RULE_ALWAYS
          Restart rule defining that the Animation can be started at any time.
static int RESTART_RULE_NEVER
          Restart rule defining that the Animation cannot be restarted.
static int RESTART_RULE_WHEN_NOT_ACTIVE
          Restart rule defining that the Animation can only be restarted when it is not active.
 
Method Summary
 void begin(long beginDelay)
          Schedules the animation to begin after the specified delay.
 void bind(Animatable target, int property, AnimationKeyframeSequence sequence)
          Binds an Animatable target's property and AnimationKeyframeSequence to the animation.
 boolean canRestart()
          Determines if the animation can be restarted.
 void end(long endDelay)
          Schedules the animation to end after the specified delay.
 long getDuration()
          Gets the duration of the animation.
 int getEasingCurve()
          Gets the easing curve that will be used to interpolate the animation's sequence data.
 long getElapsedTime()
          Returns the elapsed time for the animation.
 long getRemainingTime()
          Returns the amount of time remaining in the animation.
 float getRepeatCount()
          Gets the number of times the animation will repeat.
 long getRepeatDuration()
          Gets the total duration to repeat the animation for.
 int getRestartRule()
          Gets the restart rule being applied on the animation.
 AnimationKeyframeSequence getSequence()
          Gets the AnimationKeyframeSequence bound to the animation.
 Animatable getTarget()
          Gets the target Animatable object bound to the animation.
 int getTargetProperty()
          Gets the target property on the Animatable bound to the animation.
 boolean isAdditive()
          Gets whether the animation is additive.
 boolean isCumulative()
          Gets whether the animation is cumulative.
 boolean isFillFreeze()
          Gets the fill freeze mode for the animation.
 boolean isRestartToggleReverse()
          Gets if the animation automatically toggle the animation in reverse each time it is restarted.
 void setAdditive(boolean additive)
          Sets whether the animation is additive.
 void setCumulative(boolean cumulative)
          Sets whether the animation is cumulative.
 void setDuration(long duration)
          Sets the duration of the animation.
 void setEasingCurve(int easingCurve)
          Sets the easing curve that will be used to interpolate the animations's sequence data.
 void setFillFreeze(boolean freeze)
          Sets the fill freeze mode for the animation.
 void setRepeatCount(float count)
          Sets the number of times to repeat the animation.
 void setRepeatDuration(long repeatDur)
          Sets the total duration to repeat the animation for.
 void setRestartRule(int restartRule)
          Sets the restart rule to apply on the animation.
 void setRestartToggleReverse(boolean restartToggleReverse)
          Sets whether to automatically toggle the animation in reverse each time it is restarted.
 
Methods inherited from class net.rim.device.api.animation.AbstractAnimation
addBeginTrigger, addEndTrigger, getAnimator, getBeginTrigger, getEndTrigger, getListener, getName, getSpeed, hasBeginTriggers, hasEndTriggers, isStarted, removeAllBeginTriggers, removeAllEndTriggers, removeBeginTrigger, removeEndTrigger, setListener, setName, setSpeed
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Field Detail

RESTART_RULE_ALWAYS

public static final int RESTART_RULE_ALWAYS
Restart rule defining that the Animation can be started at any time.

This is the default restart rule.

See Also:
Animation.setRestartRule(int), Animation.getRestartRule(), Constant Field Values
Since:
BlackBerry API 6.0.0

RESTART_RULE_WHEN_NOT_ACTIVE

public static final int RESTART_RULE_WHEN_NOT_ACTIVE
Restart rule defining that the Animation can only be restarted when it is not active.

See Also:
Animation.setRestartRule(int), Animation.getRestartRule(), Constant Field Values
Since:
BlackBerry API 6.0.0

RESTART_RULE_NEVER

public static final int RESTART_RULE_NEVER
Restart rule defining that the Animation cannot be restarted.

See Also:
Animation.setRestartRule(int), Animation.getRestartRule(), Constant Field Values
Since:
BlackBerry API 6.0.0

REPEAT_DURATION_INDEFINITE

public static final long REPEAT_DURATION_INDEFINITE
Indefinite repeat duration. Used to specify the Animation will repeat indefintely until stopped.

See Also:
Animation.setRepeatDuration(long), Animation.getRepeatDuration(), Constant Field Values
Since:
BlackBerry API 6.0.0

REPEAT_COUNT_INDEFINITE

public static final float REPEAT_COUNT_INDEFINITE
Indefinite repeat count. Used to specify the Animation will repeat indefinitely until stopped.

See Also:
Animation.setRepeatCount(float), Animation.getRepeatCount(), Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_SPLINE

public static final int EASINGCURVE_SPLINE
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_DISCRETE

public static final int EASINGCURVE_DISCRETE
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_LINEAR

public static final int EASINGCURVE_LINEAR
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_QUADRATIC_IN

public static final int EASINGCURVE_QUADRATIC_IN
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_CUBIC_IN

public static final int EASINGCURVE_CUBIC_IN
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_QUARTIC_IN

public static final int EASINGCURVE_QUARTIC_IN
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_QUINTIC_IN

public static final int EASINGCURVE_QUINTIC_IN
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_SINE_IN

public static final int EASINGCURVE_SINE_IN
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_EXPONENTIAL_IN

public static final int EASINGCURVE_EXPONENTIAL_IN
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_CIRCULAR_IN

public static final int EASINGCURVE_CIRCULAR_IN
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_ELASTIC_IN

public static final int EASINGCURVE_ELASTIC_IN
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_OVERSHOOT_IN

public static final int EASINGCURVE_OVERSHOOT_IN
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_BOUNCE_IN

public static final int EASINGCURVE_BOUNCE_IN
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_QUADRATIC_OUT

public static final int EASINGCURVE_QUADRATIC_OUT
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_CUBIC_OUT

public static final int EASINGCURVE_CUBIC_OUT
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_QUARTIC_OUT

public static final int EASINGCURVE_QUARTIC_OUT
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_QUINTIC_OUT

public static final int EASINGCURVE_QUINTIC_OUT
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_SINE_OUT

public static final int EASINGCURVE_SINE_OUT
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_EXPONENTIAL_OUT

public static final int EASINGCURVE_EXPONENTIAL_OUT
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_CIRCULAR_OUT

public static final int EASINGCURVE_CIRCULAR_OUT
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_ELASTIC_OUT

public static final int EASINGCURVE_ELASTIC_OUT
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_OVERSHOOT_OUT

public static final int EASINGCURVE_OVERSHOOT_OUT
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_BOUNCE_OUT

public static final int EASINGCURVE_BOUNCE_OUT
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_QUADRATIC_INOUT

public static final int EASINGCURVE_QUADRATIC_INOUT
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_CUBIC_INOUT

public static final int EASINGCURVE_CUBIC_INOUT
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_QUARTIC_INOUT

public static final int EASINGCURVE_QUARTIC_INOUT
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_QUINTIC_INOUT

public static final int EASINGCURVE_QUINTIC_INOUT
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_SINE_INOUT

public static final int EASINGCURVE_SINE_INOUT
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_EXPONENTIAL_INOUT

public static final int EASINGCURVE_EXPONENTIAL_INOUT
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_CIRCULAR_INOUT

public static final int EASINGCURVE_CIRCULAR_INOUT
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_ELASTIC_INOUT

public static final int EASINGCURVE_ELASTIC_INOUT
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_OVERSHOOT_INOUT

public static final int EASINGCURVE_OVERSHOOT_INOUT
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_BOUNCE_INOUT

public static final int EASINGCURVE_BOUNCE_INOUT
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_QUADRATIC_OUTIN

public static final int EASINGCURVE_QUADRATIC_OUTIN
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_CUBIC_OUTIN

public static final int EASINGCURVE_CUBIC_OUTIN
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_QUARTIC_OUTIN

public static final int EASINGCURVE_QUARTIC_OUTIN
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_QUINTIC_OUTIN

public static final int EASINGCURVE_QUINTIC_OUTIN
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_SINE_OUTIN

public static final int EASINGCURVE_SINE_OUTIN
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_EXPONENTIAL_OUTIN

public static final int EASINGCURVE_EXPONENTIAL_OUTIN
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_CIRCULAR_OUTIN

public static final int EASINGCURVE_CIRCULAR_OUTIN
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_ELASTIC_OUTIN

public static final int EASINGCURVE_ELASTIC_OUTIN
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_OVERSHOOT_OUTIN

public static final int EASINGCURVE_OVERSHOOT_OUTIN
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

EASINGCURVE_BOUNCE_OUTIN

public static final int EASINGCURVE_BOUNCE_OUTIN
See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0


Method Detail

getTarget

public Animatable getTarget()
Gets the target Animatable object bound to the animation.

Returns:
The target Animatable.
See Also:
Animatable
Since:
BlackBerry API 6.0.0

getTargetProperty

public int getTargetProperty()
Gets the target property on the Animatable bound to the animation.

Returns:
The target property.
Since:
BlackBerry API 6.0.0

begin

public void begin(long beginDelay)
Description copied from class: AbstractAnimation
Schedules the animation to begin after the specified delay.

If a negative value is passed in for beginDelay the animation will start partway through with that magnitude of time elapsed into the animation's total duration. For example, calling begin(800) on an animation with a duration of 500 ms and a repeat count of 2 would start the animation 80% through, at 300 ms into the second iteration of the animation.

Specified by:
begin in class AbstractAnimation
Parameters:
beginDelay - The delay before the animation begins.
See Also:
AbstractAnimation.begin(long)
Since:
BlackBerry API 6.0.0

end

public void end(long endDelay)
Description copied from class: AbstractAnimation
Schedules the animation to end after the specified delay.

Specified by:
end in class AbstractAnimation
Parameters:
endDelay - The delay before the animation ends.
See Also:
AbstractAnimation.end(long)
Since:
BlackBerry API 6.0.0

bind

public void bind(Animatable target,
                 int property,
                 AnimationKeyframeSequence sequence)
Binds an Animatable target's property and AnimationKeyframeSequence to the animation.

This method re-targets an Animation to a given Animatable target property and AnimationKeyframeSequence.

Parameters:
target - The Animatable to apply the animation values to.
property - The property of the Animatable to be animated.
sequence - AnimationKeyframeSequence data to bind on the animation.
Throws:
IllegalArgumentException - if the target is null.
IllegalArgumentException - if the sequence is null.
IllegalArgumentException - if the property component count of property defined on the Animatable is less than 1 or greater than AnimationKeyframeSequence.PROPERTY_COUNT_MAX.
IllegalArgumentException - if the property component count of the property defined on the Animatable is not equal to the property component count of the sequence.
IllegalStateException - if the Animation is currently running.
See Also:
Animatable, AnimationKeyframeSequence
Since:
BlackBerry API 6.0.0

getDuration

public long getDuration()
Gets the duration of the animation.

Returns:
The duration.
Since:
BlackBerry API 6.0.0

setDuration

public void setDuration(long duration)
Sets the duration of the animation.

Parameters:
duration - the duration.
Throws:
IllegalArgumentException - if the duration <= 0.
IllegalStateException - if the animation is currently running.
Since:
BlackBerry API 6.0.0

isAdditive

public boolean isAdditive()
Gets whether the animation is additive.

Specifies whether the animation will add to the underlying value of the target property and other lower priority animations. Animation priority is based on when they were started on the Animator. Animations started later have higher priority. The default is false.

Returns:
true if the animation is additive; false if the animation is not additive.
See Also:
Animation.setAdditive(boolean)
Since:
BlackBerry API 6.0.0

setAdditive

public void setAdditive(boolean additive)
Sets whether the animation is additive.

Specifies whether the animation will add to the underlying value of the target property and other lower priority animations. Animation priority is based on when they were started on the Animator. Animations started later have higher priority. The default is false.

Parameters:
additive - If true the animation is additive; If false the animation is not additive.
Throws:
IllegalStateException - if the Animation is currently running.
See Also:
Animation.isAdditive()
Since:
BlackBerry API 6.0.0

isCumulative

public boolean isCumulative()
Gets whether the animation is cumulative.

The default value is false.

Returns:
true if the animation values are to be accumulated across iterations; false if the animation values are not be accumulated across iterations.
See Also:
Animation.setCumulative(boolean)
Since:
BlackBerry API 6.0.0

setCumulative

public void setCumulative(boolean cumulative)
Sets whether the animation is cumulative.

Specifies whether each repeat iteration builds upon the the last value of the previous iteration. The default value is false.

Parameters:
cumulative - if true the animation values will be accumulated across iterations; if false the animation values are not accumulated across iterations.
Throws:
IllegalStateException - if the animation is currently running.
See Also:
Animation.isCumulative()
Since:
BlackBerry API 6.0.0

getSequence

public AnimationKeyframeSequence getSequence()
Gets the AnimationKeyframeSequence bound to the animation.

Returns:
The AnimationKeyframeSequence bound to the animation.
Since:
BlackBerry API 6.0.0

isFillFreeze

public boolean isFillFreeze()
Gets the fill freeze mode for the animation.

Returns whether the animation will hold its final value once completed or if it will reset to its original value. The default is true.

Returns:
true if the animation will freeze once complete; false if the animation will reset to its original values once complete.
Since:
BlackBerry API 6.0.0

setFillFreeze

public void setFillFreeze(boolean freeze)
Sets the fill freeze mode for the animation.

Sets whether the animation will hold its final value once completed or if it will reset to its original values. The default is true.

Parameters:
freeze - if true the animation will freeze once complete; if false the animation will revert to its original values once complete.
Throws:
IllegalStateException - if the animation is currently running.
Since:
BlackBerry API 6.0.0

getRepeatCount

public float getRepeatCount()
Gets the number of times the animation will repeat.

The default is 1.0f.

Returns:
The repeat count set on the animation.
Since:
BlackBerry API 6.0.0

setRepeatCount

public void setRepeatCount(float count)
Sets the number of times to repeat the animation.

The default is 1.0f.

Parameters:
count - The repeat count to set on the animation.
Throws:
IllegalArgumentException - if count <= 0.
IllegalStateException - if the animation is currently running.
See Also:
Animation.REPEAT_COUNT_INDEFINITE
Since:
BlackBerry API 6.0.0

getRepeatDuration

public long getRepeatDuration()
Gets the total duration to repeat the animation for.

Returns:
The repeat duration (in millis).
Since:
BlackBerry API 6.0.0

setRepeatDuration

public void setRepeatDuration(long repeatDur)
Sets the total duration to repeat the animation for.

Parameters:
repeatDur - The total duration to repeat for.
Throws:
IllegalArgumentException - when repeatDur <= 0.
IllegalStateException - if the animation is currently running.
See Also:
Animation.REPEAT_DURATION_INDEFINITE
Since:
BlackBerry API 6.0.0

getElapsedTime

public long getElapsedTime()
Returns the elapsed time for the animation.

If the animation is stopped, this will return 0.

Returns:
The elapsed time of the animation.
Since:
BlackBerry API 6.0.0

getRemainingTime

public long getRemainingTime()
Returns the amount of time remaining in the animation.

If the animation is not running this will return 0. If the speed on the Animation is set to zero, this will return 0.

Returns:
The amount of time remaining in the animation.
Since:
BlackBerry API 6.0.0

getRestartRule

public int getRestartRule()
Gets the restart rule being applied on the animation.

The restart rule will be one of Animation.RESTART_RULE_ALWAYS, Animation.RESTART_RULE_WHEN_NOT_ACTIVE, Animation.RESTART_RULE_NEVER. The default is Animation.RESTART_RULE_ALWAYS.

Returns:
The restart rule.
See Also:
Animation.RESTART_RULE_ALWAYS, Animation.RESTART_RULE_WHEN_NOT_ACTIVE, Animation.RESTART_RULE_NEVER
Since:
BlackBerry API 6.0.0

setRestartRule

public void setRestartRule(int restartRule)
Sets the restart rule to apply on the animation.

The restart rule can be one of Animation.RESTART_RULE_ALWAYS, Animation.RESTART_RULE_WHEN_NOT_ACTIVE, Animation.RESTART_RULE_NEVER. The default is Animation.RESTART_RULE_ALWAYS.

Parameters:
restartRule - The restart rule.
Throws:
IllegalArgumentException - when the restart rule is not one of Animation.RESTART_RULE_ALWAYS, Animation.RESTART_RULE_WHEN_NOT_ACTIVE, or Animation.RESTART_RULE_NEVER.
IllegalStateException - if the animation is currently running.
See Also:
Animation.RESTART_RULE_ALWAYS, Animation.RESTART_RULE_WHEN_NOT_ACTIVE, Animation.RESTART_RULE_NEVER
Since:
BlackBerry API 6.0.0

canRestart

public boolean canRestart()
Determines if the animation can be restarted.

The animation can only restart if the restart rule is set to Animation.RESTART_RULE_ALWAYS, or if the restart rule is Animation.RESTART_RULE_WHEN_NOT_ACTIVE and the animation is not animating, or if the restart rule is Animation.RESTART_RULE_NEVER and the animation has never been run. The default is Animation.RESTART_RULE_ALWAYS.

Returns:
true if the animation can be restarted; false if the animation cannot be restarted.
Since:
BlackBerry API 6.0.0

setRestartToggleReverse

public void setRestartToggleReverse(boolean restartToggleReverse)
Sets whether to automatically toggle the animation in reverse each time it is restarted.

The default is false.

Parameters:
restartToggleReverse - true if the animation automatically toggle the animation between forward and reverse each time it is restarted; false if not.
Since:
BlackBerry API 6.0.0

isRestartToggleReverse

public boolean isRestartToggleReverse()
Gets if the animation automatically toggle the animation in reverse each time it is restarted.

The default is false.

Returns:
true if the animation automatically toggle the animation between forward and reverse each time it is restarted; false if not.
Since:
BlackBerry API 6.0.0

setEasingCurve

public void setEasingCurve(int easingCurve)
Sets the easing curve that will be used to interpolate the animations's sequence data.

Must be one of the defined easing curve constants.

Parameters:
easingCurve - The easing curve to use during interpolation.
Throws:
IllegalArgumentException - if easingCurve is not one of the defined easing curve constants.
Since:
BlackBerry API 6.0.0

getEasingCurve

public int getEasingCurve()
Gets the easing curve that will be used to interpolate the animation's sequence data.

Returns:
the easing curve being used during interpolation.
Since:
BlackBerry API 6.0.0





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.