edu.umd.cs.jazz.animation
Class ZAnimation

java.lang.Object
  |
  +--edu.umd.cs.jazz.animation.ZAnimation

Direct Known Subclasses:

ZAudioAnimation, ZColorAnimation, ZStrokeAnimation, ZTransformAnimation

public abstract class ZAnimation

extends java.lang.Object

ZAnimation and its subclasses provide the central programming interface to the animation system. Most animations consist of a source property, a destination property and a target object that is normally something in the Jazz scene graph. The animation interpolates between its source and destination property over time, applying the intermediate values to its target. For a concrete look at this behavior see ZColorAnimation.

Each ZAnimation has a ZAlpha object that it uses to determine when it should start, when it should finish, and how it should interpolate between its source and destination values.

When creating most animations three decisions need to be made.

1. What object should this animation apply to? This determines the target of the animation.
2. What property on the target do i want to change. This will determine the ZAnimation subclass that you use, and its source and destination values. (if the property is a color then use ZColorAnimation)
3. How should this property be set over time, this determines the parameters used to set up the animations ZAlpha.

Once an animation has been constructed the method play must be called so that the animation gets scheduled with the current ZAnimationScheduler. Once the scheduler determines (by using the animations ZAlpha and ZNextFrameCondition) that the next frame of the animation should be animated it calls animateFrameForTime on the animation. In this method the animation performs all animation activities, finishing that method implementation by scheduling its next frame if it wishes to continue animating.

Here is a simple animation example. It uses a transform animation to animate a square across the screen.

 ZRectangle aRect = new ZRectangle(0, 0, 100, 100);
 ZVisualLeaf aLeaf = new ZVisualLeaf(aRect);

 // The animation will apply to the transform group decorating the aLeaf node.
 ZTransformGroup aTarget = aLeaf.editor().getTransformGroup();

 canvas.getLayer().addChild(aTarget);

 // Create a new ZAlpha that will run from the current time for 1.5 seconds.
 // This alpha will change linearly; see the ZAlpha class to learn how to create
 // slow in slow out animation effects.
 ZAlpha alpha = new ZAlpha(1, 1500);

 // Create the ZTransformAnimation with its source and destination values. Here
 // we choose to animate the target from its current transform, to the identity transform
 // translated by 300, 300.
 AffineTransform souceTransform = aTarget.getTransform();
 AffineTransform destinationTransform = AffineTransform.getTranslateInstance(300, 300);
 ZTransformAnimation aTransformAnimation = new ZTransformAnimation(souceTransform, destinationTransform);

 // Set the target of the animation.
 aTransformAnimation.setTransformTarget(aTarget);

 // Set the alpha value for the animation. This animation will start immediately,
 // and run for 1.5 seconds.
 aTransformAnimation.setAlpha(alpha);

 // Start the animation by registering it with the ZAnimationScheduler.
 aTransformAnimation.play();
 

Author:

Jesse Grosjean

See Also:

ZAlpha

ZAnimation

public ZAnimation()

Construct a new ZAnimation.

ZAnimation

public ZAnimation(ZAlpha aAlpha)

Construct a new ZAnimation.

Parameters:

aAlpha - the alpha parameter determines the animations start and finish time, and generates any alpha values needed by the animation to interpolate between values.

animateFrameForTime

protected void animateFrameForTime(long aTime)

Animate one frame of this animation at the specified time, and schedule a new frame to be animated if the alpha object that is scheduling this animation has not yet finished. This method is called by the ZAnimation scheduler.

ZAnimation subclasses should override this method and perform all animation code from with it.

animationRateByElapsedFrames

public void animationRateByElapsedFrames(long aFramesCount)

This method makes the animation schedule its frames by elapsed frames. For example this code would make the animation animate on every 5th frame. animation.animationRateByElapsedFrames(5).

Parameters:

aFramesCount - the number of frames to wait until the next frame of this animation is animated.

animationRateByElapsedTime

public void animationRateByElapsedTime(long aElapsedTime)

This method makes the animation schedule its frames by elapsed time. For example this code would make the animation animate one frame per seconds. animation.animationRateByElapsedTime(1000).

Parameters:

aElapsedTime - the amount of time to wait before animating the next frame of the animation, specified in milliseconds.

animationRateByNextFrame

public void animationRateByNextFrame()

Make it so that that this animation will be animated on every frame that the ZAnimationScheduler runs.

animationStarted

protected void animationStarted()

Template method that is called when the first frame of the animation is animated after play has been called.

animationStopped

protected void animationStopped()

Template method that is called when the animation is temporarily stopped with the stop method or when the animation finishes.

getAlpha

public ZAlpha getAlpha()

Return the alpha object used to determine the animations start and finish time, and to generate any alpha values that it needs when interpolating between values.

Returns:

the animations alpha object, the default value is null.

isStopped

public boolean isStopped()

Return true if the animation has been stopped. It can be restarted with the play method.

play

public void play()

Schedule this animation with the ZAnimationScheduler. Once an animation is constructed it is necessary to call this method to so that the animation is scheduled.

scheduleNextFrame

protected void scheduleNextFrame()

Schedule the next frame of the animation. This is normaly called as the last statement in animateFrameForTime. It creates a new ZNextFrameCondition and schedules this animation with that condition on the ZAnimationScheduler.

scheduleNextFrame

protected void scheduleNextFrame(ZNextFrameCondition aCondition)

Schedules this animation with the given condition with the ZAnimationScheduler.

setAlpha

public void setAlpha(ZAlpha aAlpha)

Set the alpha object used to determine the animations start and finish time, and to generate alpha values that it needs when interpolating between values.

Parameters:

aAlpha - the alpha

stop

public void stop()

Temporarily or permanently stop the animation. This will stop any animation frames that have been scheduled with the ZAnimationScheduler from playing. The animation can be restarted with play method.

setStartedRunnable

public void setStartedRunnable(java.lang.Runnable aRunnable)

Specify a Runnable that will be executed when the animation is started..

setStoppedRunnable

public void setStoppedRunnable(java.lang.Runnable aRunnable)

Specify a Runnable that will be executed when the animation is stopped..