net.rim.device.api.animation
Class Animator

java.lang.Object
  net.rim.device.api.animation.AbstractAnimation
      net.rim.device.api.animation.AnimationGroup
          net.rim.device.api.animation.Animator

public final class Animator
extends AnimationGroup

Defines a top level AnimationGroup that controls updates of all animations in the group. All animations are created from this root group.

NOTE: You should only create one instance of the Animator class per application or framework. The Animator class is designed to efficiently manage multiple animations. In most cases, creating multiple instances of the Animator class in your application or framework is unnecessary and is likely to result in poor performance and wasted resources.

Creating an Automatically Updated Animator

Setting a target frame rate greater than zero on the Animator enables throttled updates. The updates to all animations in the group are processed on the event dispatch thread. The Animator updates animations at the specified frame rate. If there are no animations to process, the Animator stops updating and enters the idle state until more animations are scheduled.

 // Create the Animator
 int frameRate = 30;
 Animator animator = new Animator(frameRate);
 

Creating a User Updated Animator

Setting a target frame rate on the Animator that is less than or equal to zero disables throttled updates. If you are rendering content on a seperate thread, you should set the target frame rate to 0 and directly update the Animator from within the thread you are rendering on. There is an AnimatorListener interface for listening to when the Animator transitions between the processing state and the idle state. You can implement this interface to get notifications that signal you to call update().

 public void initialize() 
 {
     ...
     // Create the Animator, setting the frame rate to zero to specify a non-throttled animation
     Animator animator = new Animator(0);
     ...
 }
 
 ...
 
 public void update()
 {
     // Because the Animator is non-throttled, we have to call update() to update the animation values.
     animator.update();
 }
 

Adding an Animation to the Animator

 // Create the Animator
 Animator animator = new Animator(30);
 // Create a to-animation to animate our target's property to the value 100.0f.
 Animation animation = animator.addAnimationTo(_target, MyTargetAnimatable.PROPERTY_1, 100.0f, Animation.EASINGCURVE_EXPONENTIAL_OUT, 1000L);
 
 

Starting all Animations on the Animator

If no TimeSource is provided to the Animator constructor, the TimeSource is created automatically and started. If you specify a TimeSource using Animator.Animator(int,TimeSource) you must start the TimeSource for the Animator to process animations.

 // Create the animator.
 Animator animator = new Animator(30);
 ... 
 AnimatedScalar alpha = new Scalar(1.0f);
 AnimatedScalar scale = new Scalar(100.0f);
 ...
 // Add animations on the animator
 Animation fadeIn = animator.addAnimationFromTo(alpha, AnimatedScalar.ANIMATION_PROPERTY_SCALAR, 0.0f, 1.0f, Animation.EASINGCURVE_LINEAR, 1000L);
 Animation scaleOut = animator.addAnimationFromTo(alpha, AnimatedScalar.ANIMATION_PROPERTY_SCALAR, 100, 0, Animation.EASINGCURVE_LINEAR, 1000L);
 
 // Start all the animations with no delay.
 animator.begin(0L);
 
 

When animations are suspended automatically to save power

To save power, the Animator suspends an application's animations if the application is sent to the background or if the device's backlight times out. Animations resume when the application returns to the foreground or when the backlight turns back on. While animations are suspended, the Animator's timer continues. To stop the timer when the application is sent to the background, you have to override Application.deactivate() and pause the Animator's TimeSource. To stop the timer when the device's backlight times out, you have to implement the SystemListener2 interface and pause the Animator's timer in your implementation of SystemListener2.backlightStateChange(boolean) when on is false.

Pausing the time source

 animator.getTimeSource().pause();
 

To restart the timer when the application is sent back to the foreground, you have to override Application.activate() and start the Animator's TimeSource. To restart the timer when the device's backlight turns on, you have to implement the SystemListener2 interface and start the Animator's timer in your implementation of SystemListener2.backlightStateChange(boolean) when on is true.

Resuming the time source

 animator.getTimeSource().start();
 

Since:

BlackBerry API 6.0.0

Constructor Summary

Animator(int targetFrameRate)
Class constructor.

Animator(int targetFrameRate, TimeSource timeSource)
Class constructor.

Method Summary
AnimatorListener	getAnimatorListener() Gets the AnimatorListener.
int	getCurrentFrameRate() Gets the actual frame rate in frames per second.
int	getTargetFrameRate() Gets the target frame rate for the Animator.
TimeSource	getTimeSource() Gets the TimeSource.
boolean	isProcessing() Indicates if the Animator is currently processing any scheduled animations.
void	reset() Resets the Animator.
void	setAnimatorListener(AnimatorListener listener) Sets the AnimatorListener.
void	setTargetFrameRate(int framesPerSecond) Sets the target frame rate for the Animator.
void	update() Updates all running animations and animations pending to begin and end.

Methods inherited from class net.rim.device.api.animation.AnimationGroup

addAnimation, addAnimation, addAnimationBy, addAnimationBy, addAnimationFromBy, addAnimationFromBy, addAnimationFromTo, addAnimationFromTo, addAnimationGroup, addAnimationTo, addAnimationTo, begin, end, findAnimation, findAnimation, removeAllAnimations, removeAnimation, setSpeed

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

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Animator

public Animator(int targetFrameRate)

Class constructor.

Creates an Animator object that throttles update() calls at the specified frame rate. If a frame rate of zero is specified, automatic updates are disabled and you must call update() on the Animator.

This constructor creates a TimeSource and starts it automatically.

Parameters:

targetFrameRate - The number of frames per second the Animator should process. If targetFrameRate <= 0 the frame rate is not throttled.

Since:

BlackBerry API 6.0.0

Animator

public Animator(int targetFrameRate,
                TimeSource timeSource)

Class constructor.

Creates an Animator object that throttles update() calls at the specified frame rate. If a frame rate of zero is specified, automatic updates are disabled and you must call update() on the Animator.

You must start the TimeSource you provide to this constructor for the animator to play animations.

Parameters:

targetFrameRate - The number of frames per second the Animator should process. If targetFrameRate <= 0 the frame rate is not throttled.

timeSource - The TimeSource that the Animator will use to process time.

Throws:

IllegalArgumentException - if timeSource is null.

See Also:

TimeSource

Since:

BlackBerry API 6.0.0

Method Detail

getTimeSource

public TimeSource getTimeSource()

Gets the TimeSource.

Note: Calling TimeSource.stop() will reset the Animator by stopping any running animations and removing any scheduled animations.

Returns:

The TimeSource used by this Animator.

See Also:

TimeSource

Since:

BlackBerry API 6.0.0

getAnimatorListener

public AnimatorListener getAnimatorListener()

Gets the AnimatorListener.

You can use the AnimatorListener to listen for Animator state changes between the processing state and the idle state.

Returns:

the AnimatorListener or null if none is set.

See Also:

AnimatorListener

Since:

BlackBerry API 6.0.0

setAnimatorListener

public void setAnimatorListener(AnimatorListener listener)

Sets the AnimatorListener.

The AnimatorListener is used to listen for Animator state changes between the processing state and the idle state.

Parameters:

listener - The listener to be set or null to remove a listener.

See Also:

AnimatorListener

Since:

BlackBerry API 6.0.0

update

public void update()

Updates all running animations and animations pending to begin and end. You only have to call this method if the Animator is non-throttled.

Since:

BlackBerry API 6.0.0

reset

public void reset()

Resets the Animator.

Stops the TimeSource, ends any running animations and removes any scheduled animations.

Note: Animations can persist in processing or scheduling queues after you exit your application. As a result, your instance of the Animator class may not be garbage collected. A good practice is to call reset() before exiting your application to ensure that animations associated with your instance of the Animator class are removed from any queues. This will ensure that your Animator instance is garbage collected soon after the application exits.

Since:

BlackBerry API 6.0.0

getCurrentFrameRate

public int getCurrentFrameRate()

Gets the actual frame rate in frames per second.

Returns 0 if the Animator is non-throttled.

Returns:

The actual frame rate of the Animator.

Since:

BlackBerry API 6.0.0

getTargetFrameRate

public int getTargetFrameRate()

Gets the target frame rate for the Animator.

Returns:

The target frames per second.

Since:

BlackBerry API 6.0.0

setTargetFrameRate

public void setTargetFrameRate(int framesPerSecond)

Sets the target frame rate for the Animator.

Parameters:

framesPerSecond - The targetted number of frames per second to update the animations. If framesPerSecond <= 0 the frame rate is not throttled.

Since:

BlackBerry API 6.0.0

isProcessing

public boolean isProcessing()

Indicates if the Animator is currently processing any scheduled animations.

You should not poll this method. Instead, implement AnimatorListener which receives callbacks when the Animator's state switches between processing and idle.

Returns:

true if processing, false if idling.

See Also:

AnimatorListener

Since:

BlackBerry API 6.0.0