net.rim.device.api.animation
Class AnimationGroup

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

Direct Known Subclasses:

Animator

public class AnimationGroup
extends AbstractAnimation

A collection class that groups together a set of animations. The class lets you schedule and control the animations as a group.

Creating an AnimationGroup

 AnimationGroup group = animator.addAnimationGroup();
 

Adding an AnimationGroup to an AnimationGroup

 AnimationGroup subGroup = group.addAnimationGroup();
 

Adding an Animation to an AnimationGroup

 Animation animation = subGroup.addAnimationFromBy(animatable, MyAnimatable.PROPERTY_XY, new float[] {50f, 75f}, 0, new float[] {75f, 100f}, 0, Animation.EASINGCURVE_ELASTIC_OUT, 1000L); 
 

Starting an AnimationGroup

 group.begin(0L);
 

Since:

BlackBerry API 6.0.0

Method Summary
Animation	addAnimation(Animatable target, int property, int keyframeCount, float[] keyTimes, int keyTimesOffset, float[] keyValues, int keyValuesOffset, int easingCurve, long duration) Creates and adds an animation on the given animatable target property generated with the the given set of key values and key times to the group.
Animation	addAnimation(Animatable target, int property, AnimationKeyframeSequence sequence, long duration) Creates and adds an animation that is bound to the supplied animatable target, property, and AnimationKeyframeSequence to the group.
Animation	addAnimationBy(Animatable target, int property, float byValue, int easingCurve, long duration) Creates and adds a relative By animation on the given animatable target property consisting of two key frames to the group.
Animation	addAnimationBy(Animatable target, int property, float[] byValue, int byOffset, int easingCurve, long duration) Creates and adds a relative By animation on the given animatable target property consisting of two keyframes to the group.
Animation	addAnimationFromBy(Animatable target, int property, float fromValue, float byValue, int easingCurve, long duration) Creates and adds a From-By animation on the given animatable target property consisting of two keyframes to the group.
Animation	addAnimationFromBy(Animatable target, int property, float[] fromValue, int fromOffset, float[] byValue, int byOffset, int easingCurve, long duration) Creates and adds a From-By animation on the given animatable target property consisting of two keyframes to the group.
Animation	addAnimationFromTo(Animatable target, int property, float fromValue, float toValue, int easingCurve, long duration) Creates and adds a From-To animation on the given animatable target property consisting of two keyframes to the group.
Animation	addAnimationFromTo(Animatable target, int property, float[] fromValue, int fromOffset, float[] toValue, int toOffset, int easingCurve, long duration) Creates and adds a From-To animation on the given animatable target property consisting of two keyframes to the group.
AnimationGroup	addAnimationGroup() Creates and adds an AnimationGroup to the group.
Animation	addAnimationTo(Animatable target, int property, float toValue, int easingCurve, long duration) Creates and adds a relative To animation on the given animatable target property consisting of two key frames to the group.
Animation	addAnimationTo(Animatable target, int property, float[] toValue, int toOffset, int easingCurve, long duration) Creates and adds a relative To animation on the given animatable target property consisting of two keyframes to the group.
void	begin(long beginDelay) Schedules the animation to begin after the specified delay.
void	end(long endDelay) Schedules the animation to end after the specified delay.
AbstractAnimation	findAnimation(String name) Finds the first animation with the specified name.
boolean	findAnimation(AbstractAnimation animation) Determines if the given animation belongs to the group.
void	removeAllAnimations() Removes all animations from the group.
boolean	removeAnimation(AbstractAnimation animation) Removes an animation from the group.
void	setSpeed(float speed) Sets the speed factor of the animation.

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

Method Detail

addAnimationFromTo

public Animation addAnimationFromTo(Animatable target,
                                    int property,
                                    float fromValue,
                                    float toValue,
                                    int easingCurve,
                                    long duration)

Creates and adds a From-To animation on the given animatable target property consisting of two keyframes to the group.

It is assumed the given animatable target property has a component size of 1.

Parameters:

target - The Animatable to apply the animation values to.

property - The property of the Animatable to be animated.

duration - The duration of the animation in milliseconds.

fromValue - The value the animation will animate from.

toValue - The value the animation will animate to.

easingCurve - The easing curve to be used to interpolate through the sequence data.

Returns:

An Animation object.

Throws:

IllegalArgumentException - if target is null.

IllegalArgumentException - if easingCurve is not a valid curve type.

IllegalArgumentException - if duration <= 0.

IllegalArgumentException - if the property component size of property is not equal to 1.

Since:

BlackBerry API 6.0.0

addAnimationFromBy

public Animation addAnimationFromBy(Animatable target,
                                    int property,
                                    float fromValue,
                                    float byValue,
                                    int easingCurve,
                                    long duration)

Creates and adds a From-By animation on the given animatable target property consisting of two keyframes to the group.

It is assumed the given animatable target property has a component size of 1.

Parameters:

target - The Animatable to apply the animation values to.

property - The property of the Animatable to be animated.

fromValue - The value the animation will animate from.

byValue - The value the animation will animate by.

easingCurve - The easing curve to be used to interpolate through the sequence data.

duration - The duration for the animation in milliseconds.

Returns:

An Animation object.

Throws:

IllegalArgumentException - if target is null.

IllegalArgumentException - if easingCurve is not a valid curve type.

IllegalArgumentException - if duration <= 0.

IllegalArgumentException - if the property component size of property is not equal to 1.

Since:

BlackBerry API 6.0.0

addAnimationTo

public Animation addAnimationTo(Animatable target,
                                int property,
                                float toValue,
                                int easingCurve,
                                long duration)

Creates and adds a relative To animation on the given animatable target property consisting of two key frames to the group.

It is assumed the given animatable target property has a component size of 1.

Parameters:

target - Animatable to apply the animation values to.

property - Property of the Animatable to be animated.

toValue - The value the animation will animate to.

easingCurve - The easing curve to be used to interpolate through the sequence data.

duration - The duration for the animation in milliseconds.

Returns:

An Animation object.

Throws:

IllegalArgumentException - if target is null.

IllegalArgumentException - if easingCurve is not a valid curve type.

IllegalArgumentException - if duration <= 0.

IllegalArgumentException - if the property component size of property is not equal to 1.

Since:

BlackBerry API 6.0.0

addAnimationBy

public Animation addAnimationBy(Animatable target,
                                int property,
                                float byValue,
                                int easingCurve,
                                long duration)

Creates and adds a relative By animation on the given animatable target property consisting of two key frames to the group.

It is assumed the given animatable target property has a component size of 1.

Parameters:

target - The Animatable to apply the animation values to.

property - The property of the Animatable to be animated.

byValue - The value the animation will animate by.

easingCurve - The easing curve to be used to interpolate through the sequence data.

duration - The duration for the animation in milliseconds.

Returns:

An Animation object.

Throws:

IllegalArgumentException - if target is null.

IllegalArgumentException - if easingCurve is not a valid curve type.

IllegalArgumentException - if duration <= 0.

IllegalArgumentException - if the property component size of property is not equal to 1.

Since:

BlackBerry API 6.0.0

addAnimationFromTo

public Animation addAnimationFromTo(Animatable target,
                                    int property,
                                    float[] fromValue,
                                    int fromOffset,
                                    float[] toValue,
                                    int toOffset,
                                    int easingCurve,
                                    long duration)

Creates and adds a From-To animation on the given animatable target property consisting of two keyframes to the group.

Parameters:

target - The Animatable to apply the animation values to.

property - The property of the Animatable to be animated.

fromValue - An array of values the animation will animate from.

fromOffset - The offset into the fromValue array.

toValue - An array of values the animation will animate to.

toOffset - The offset into the toValue array.

easingCurve - The easing curve to be used to interpolate through the sequence data.

duration - The duration for the animation in milliseconds.

Returns:

An Animation object.

Throws:

IllegalArgumentException - if target is null.

IllegalArgumentException - if fromValue is null.

IllegalArgumentException - if fromOffset < 0.

IllegalArgumentException - if fromValue.length < fromOffset + the property component count defined for the given property.

IllegalArgumentException - if toValue is null.

IllegalArgumentException - if toOffset < 0.

IllegalArgumentException - if toValue.length < toOffset + the property component count defined for the given property.

IllegalArgumentException - if easingCurve is not a valid curve type.

IllegalArgumentException - if duration <= 0.

IllegalArgumentException - if the property component count defined the given target property is less than 1 or greater than AnimationKeyframeSequence.PROPERTY_COUNT_MAX.

Since:

BlackBerry API 6.0.0

addAnimationFromBy

public Animation addAnimationFromBy(Animatable target,
                                    int property,
                                    float[] fromValue,
                                    int fromOffset,
                                    float[] byValue,
                                    int byOffset,
                                    int easingCurve,
                                    long duration)

Creates and adds a From-By animation on the given animatable target property consisting of two keyframes to the group.

Parameters:

target - The Animatable to apply the animation values to.

property - The property of the Animatable to be animated.

fromValue - An array of values the animation will animate from.

fromOffset - Offset into the fromValue array.

byValue - An array of values the animation will animate by.

byOffset - Offset into the toValue array.

easingCurve - The easing curve to be used to interpolate through the sequence data.

duration - The duration for the animation in milliseconds.

Returns:

An Animation object.

Throws:

IllegalArgumentException - if target is null.

IllegalArgumentException - if fromValue is null.

IllegalArgumentException - if fromOffset < 0.

IllegalArgumentException - if fromValue.length < fromOffset + the property component count defined for the given property.

IllegalArgumentException - if byValue is null.

IllegalArgumentException - if byOffset < 0.

IllegalArgumentException - if byValue.length < byOffset + the property component count defined for the given property.

IllegalArgumentException - if easingCurve is not a valid curve type.

IllegalArgumentException - if duration <= 0.

IllegalArgumentException - if the property component count defined the given target property is less than 1 or greater than AnimationKeyframeSequence.PROPERTY_COUNT_MAX.

Since:

BlackBerry API 6.0.0

addAnimationTo

public Animation addAnimationTo(Animatable target,
                                int property,
                                float[] toValue,
                                int toOffset,
                                int easingCurve,
                                long duration)

Creates and adds a relative To animation on the given animatable target property consisting of two keyframes to the group.

Parameters:

target - The Animatable to apply the animation values to.

property - The property of the Animatable to be animated.

toValue - An array of values the animation will animate to.

toOffset - Offset into the toValue array.

easingCurve - The easing curve to be used to interpolate through the sequence data.

duration - The duration for the animation in milliseconds.

Returns:

An Animation object.

Throws:

IllegalArgumentException - if target is null.

IllegalArgumentException - if toValue is null.

IllegalArgumentException - if toOffset < 0.

IllegalArgumentException - if toValue.length < toOffset + the property component count defined for the given property.

IllegalArgumentException - if easingCurve is not a valid curve type.

IllegalArgumentException - if duration <= 0.

IllegalArgumentException - if the property component count defined the given target property is less than 1 or greater than AnimationKeyframeSequence.PROPERTY_COUNT_MAX.

Since:

BlackBerry API 6.0.0

addAnimationBy

public Animation addAnimationBy(Animatable target,
                                int property,
                                float[] byValue,
                                int byOffset,
                                int easingCurve,
                                long duration)

Creates and adds a relative By animation on the given animatable target property consisting of two keyframes to the group.

Parameters:

target - The Animatable to apply the animation values to.

property - The property of the Animatable to be animated.

byValue - An array of values the animation will animate by.

byOffset - Offset into the toValue array.

easingCurve - The easing curve to be used to interpolate through the sequence data.

duration - The duration for the animation in milliseconds.

Returns:

An Animation object.

Throws:

IllegalArgumentException - if target is null.

IllegalArgumentException - if byValue is null.

IllegalArgumentException - if byOffset < 0.

IllegalArgumentException - if byValue.length < byOffset + the property component count defined for the given property.

IllegalArgumentException - if easingCurve is not a valid curve type.

IllegalArgumentException - if duration <= 0.

IllegalArgumentException - if the property component count defined the given target property is less than 1 or greater than AnimationKeyframeSequence.PROPERTY_COUNT_MAX.

Since:

BlackBerry API 6.0.0

addAnimation

public Animation addAnimation(Animatable target,
                              int property,
                              int keyframeCount,
                              float[] keyTimes,
                              int keyTimesOffset,
                              float[] keyValues,
                              int keyValuesOffset,
                              int easingCurve,
                              long duration)

Creates and adds an animation on the given animatable target property generated with the the given set of key values and key times to the group.

Parameters:

target - The Animatable property to apply the animation values to.

property - The property of the Animatable to be animated.

keyframeCount - The number of keyframes for the sequence data.

keyTimes - An array of key times

keyTimesOffset - The offset into the keyTimes array.

keyValues - An array of key values

keyValuesOffset - The offset into the keyValues array.

easingCurve - The easing curve to be used to interpolate through the sequence data.

duration - The duration for the animation in milliseconds.

Returns:

An Animation object.

Throws:

IllegalArgumentException - if target is null.

IllegalArgumentException - if keyframeCount < 2.

IllegalArgumentException - if the property component count defined for the given property is less than 1 or greater than AnimationKeyframeSequence.PROPERTY_COUNT_MAX.

IllegalArgumentException - if keyTimes is null.

IllegalArgumentException - if keyTimesOffset < 0.

IllegalArgumentException - if keyTimes.length < keyTimesOffset + keyframeCount.

IllegalArgumentException - if keyValues is null.

IllegalArgumentException - if keyValuesOffset < 0.

IllegalArgumentException - if keyValues.length < keyValuesOffset + keyframeCount * the property component count defined for the given property.

IllegalArgumentException - if easingCurve is not a valid curve type.

IllegalArgumentException - if duration <= 0.

Since:

BlackBerry API 6.0.0

addAnimation

public Animation addAnimation(Animatable target,
                              int property,
                              AnimationKeyframeSequence sequence,
                              long duration)

Creates and adds an animation that is bound to the supplied animatable target, property, and AnimationKeyframeSequence to the group.

Parameters:

target - The Animatable the animation will apply the animation values to.

property - The property of the Animatable to be animated.

sequence - AnimationKeyframeSequence data to bind on the animation.

duration - The duration for the animation in milliseconds.

Returns:

An Animation object.

Throws:

IllegalArgumentException - if target is null.

IllegalArgumentException - if sequence is null.

IllegalArgumentException - if duration <= 0.

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.

Since:

BlackBerry API 6.0.0

addAnimationGroup

public AnimationGroup addAnimationGroup()

Creates and adds an AnimationGroup to the group.

Returns:

AnimationGroup instance.

Since:

BlackBerry API 6.0.0

removeAnimation

public boolean removeAnimation(AbstractAnimation animation)

Removes an animation from the group.

Parameters:

animation - The animation to remove from the set.

Throws:

IllegalArgumentException - If animation is null.

Since:

BlackBerry API 6.0.0

removeAllAnimations

public void removeAllAnimations()

Removes all animations from the group.

Since:

BlackBerry API 6.0.0

findAnimation

public boolean findAnimation(AbstractAnimation animation)

Determines if the given animation belongs to the group.

Parameters:

animation - the animation to search for.

Returns:

true if animation belongs to the group; false if animation does not belong to the group.

Throws:

IllegalArgumentException - if animation is null.

Since:

BlackBerry API 6.0.0

findAnimation

public AbstractAnimation findAnimation(String name)

Finds the first animation with the specified name.

Parameters:

name - The name of the animation to find.

Returns:

The first animation found with the specified name or null if no animation is found with the specified name.

Throws:

IllegalArgumentException - if the name is null.

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(-500) on an animation with a duration of 1000 ms would cause the animation to start halfway through, and it would only run for 500 ms.

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

setSpeed

public void setSpeed(float speed)

Description copied from class: AbstractAnimation

Sets the speed factor of the animation. Elapsed time is multiplied by this factor to speed up or slow down the animation. The default value is 1.0f.

Overrides:

setSpeed in class AbstractAnimation

Parameters:

speed - The speed factor.

See Also:

AbstractAnimation.setSpeed(float)

Since:

BlackBerry API 6.0.0