edu.cmu.hcii.calo.view.animation.Animation Class Reference

Collaboration diagram for edu.cmu.hcii.calo.view.animation.Animation:

Collaboration graph
[legend]
List of all members.

Detailed Description

Represents an animation, a smooth change in some set of numeric values.

Animations are created by the AnimationManager. Animations can be used to animate individual scalar values, arbitrary arrays of these values, or the special cases of Points and Rectangles (modeled using Point2D and Rectangle2D). All of these are modeled to double precision. You can therefore use Animations to animate changes in size, position, bounds, color, or anything else you can represent with numbers. When you call start() on an Animation, you must pass an AnimationListener that will be notified when that Animation changes by calls to the AnimationListener.animationDidUpdate(Animation) method. This method will be called as frequently as possible throughout the duration of the Animation, and will be called at least once when the animation is complete. You can implement this method to do whatever is required with the current value of the Animation's modeled state, such as setting the size of a component to the current Rectangle or setting the color from an array of three scalar values representing red, green, and blue.

Author:
Brian Ellis


Public Types

enum  AnimationCurve
 Represents the mathematical equation used to determine how the animation progresses. More...
enum  AnimationType
 Represents the type of Animation, defined by the sort of thing that is being animated. More...

Public Member Functions

AnimationCurve getAnimationCurve ()
 Gets the animation curve for this animation.
AnimationType getAnimationType ()
 Gets the type of this animation.
Point2D getCurrentPoint ()
 Returns the current value of the Point that is being animated.
Rectangle2D getCurrentRectangle ()
 Returns the current value of the Rectangle that is being animated.
double getCurrentValue () throws IllegalStateException
 Returns the current value of the single scalar that is being animated.
double[] getCurrentValues ()
 Returns the current value of the array of scalars that is being animated.
double getDuration ()
 Gets the duration of this Animation.
AnimationListener getListener ()
 Gets the AnimationListener for this Animation.
Object getObjectData ()
 Gets the arbitrary object associated with this Animation, if one has been set.
double getProgress ()
 Gets the progress of this animation as a floating-point number in (0, 1].
Calendar getStartTime ()
 Gets the time at which this animation was begun.
boolean isComplete ()
 Returns true if this Animation is complete, and false otherwise.
void setObjectData (Object objectData)
 Associates an arbitrary object with this Animation which can later be retrieved using getObjectData().
void start (AnimationListener l)
 Starts this animation immediately.

Package Functions

 Animation (double initialValue, double finalValue, AnimationCurve curve, double duration)
 Constructs an Animation designed to animate a single scalar value.
 Animation (double[] initialValues, double[] finalValues, AnimationCurve curve, double duration)
 Constructs an Animation designed to animate an arbitrary list of scalar values.
 Animation (Point2D initialPoint, Point2D finalPoint, AnimationCurve curve, double duration)
 Constructs an Animation designed to animate a point (or a size, or any other two-element pair for that matter).
 Animation (Rectangle2D initialRect, Rectangle2D finalRect, AnimationCurve curve, double duration)
 Constructs an Animation designed to animate a rectangle (or any other four-element tuple).
void setComplete (boolean complete)
 Marks this Animation as complete.
void setTimer (AnimationTimer t)
 Sets the timer associated with this Animation.

Private Member Functions

double getInterpolatedValue (double initialValue, double finalValue, double weight)
 Returns an interpolated value for the given initial and final values, based on the current Animation's curve and the progress (which is passed in as weight so that you can ask about progress values other than the current one).

Private Attributes

Calendar startTime
 The point in time at which this animation was started.
double duration = 1.0
 How long (in seconds) this animation should take.
AnimationType animationType
 The type of this animation.
AnimationCurve animationCurve
 The curve for this animation.
double[] initialState
 The initial state of this animation, which is always represented as an array of doubles.
double[] finalState
 The final state of this animation, which is always represented as an array of doubles.
AnimationTimer timer
 The timer assigned to this animation, if any.
AnimationListener listener
 The listener for this animation.
boolean isComplete = false
 Whether this animation is complete.
Object objectData
 The arbitrary object data associated with this Animation, if any.


Member Enumeration Documentation

enum edu::cmu::hcii::calo::view::animation::Animation::AnimationCurve

Represents the mathematical equation used to determine how the animation progresses.

Author:
Brian Ellis

enum edu::cmu::hcii::calo::view::animation::Animation::AnimationType

Represents the type of Animation, defined by the sort of thing that is being animated.

Author:
Brian Ellis


Constructor & Destructor Documentation

edu.cmu.hcii.calo.view.animation.Animation.Animation ( double  initialValue,
double  finalValue,
AnimationCurve  curve,
double  duration 
) [package]

Constructs an Animation designed to animate a single scalar value.

Note:
External classes should use the AnimationManager to create Animations, which is why this constructor is package protected.
Parameters:
initialValue the initial value of this scalar
finalValue the final value of this scalar
curve the AnimationCurve to use for this Animation
duration the intended duration of this Animation

edu.cmu.hcii.calo.view.animation.Animation.Animation ( double[]  initialValues,
double[]  finalValues,
AnimationCurve  curve,
double  duration 
) [package]

Constructs an Animation designed to animate an arbitrary list of scalar values.

Note:
External classes should use the AnimationManager to create Animations, which is why this constructor is package protected.
Parameters:
initialValues the initial values of the array
finalValues the final values of the array
curve the AnimationCurve to use for this Animation
duration the intended duration of this Animation

edu.cmu.hcii.calo.view.animation.Animation.Animation ( Point2D  initialPoint,
Point2D  finalPoint,
AnimationCurve  curve,
double  duration 
) [package]

Constructs an Animation designed to animate a point (or a size, or any other two-element pair for that matter).

Note:
External classes should use the AnimationManager to create Animations, which is why this constructor is package protected.
Parameters:
initialPoint the initial Point
finalPoint the final Point
curve the AnimationCurve to use for this Animation
duration the intended duration of this Animation

edu.cmu.hcii.calo.view.animation.Animation.Animation ( Rectangle2D  initialRect,
Rectangle2D  finalRect,
AnimationCurve  curve,
double  duration 
) [package]

Constructs an Animation designed to animate a rectangle (or any other four-element tuple).

Note:
External classes should use the AnimationManager to create Animations, which is why this constructor is package protected.
Parameters:
initialRect the initial Rectangle
finalRect the final Rectangle
curve the AnimationCurve to use for this Animation
duration the intended duration of this Animation


Member Function Documentation

AnimationCurve edu.cmu.hcii.calo.view.animation.Animation.getAnimationCurve (  ) 

Gets the animation curve for this animation.

Returns:
the animation curve

AnimationType edu.cmu.hcii.calo.view.animation.Animation.getAnimationType (  ) 

Gets the type of this animation.

Returns:
the animation type

Point2D edu.cmu.hcii.calo.view.animation.Animation.getCurrentPoint (  ) 

Returns the current value of the Point that is being animated.

Returns:
the current value of the Point
Exceptions:
IllegalStateException if this Animation is not currently animating a Point.

Rectangle2D edu.cmu.hcii.calo.view.animation.Animation.getCurrentRectangle (  ) 

Returns the current value of the Rectangle that is being animated.

Returns:
the current value of the Rectangle
Exceptions:
IllegalStateException if this Animation is not currently animating a Rectangle.

double edu.cmu.hcii.calo.view.animation.Animation.getCurrentValue (  )  throws IllegalStateException

Returns the current value of the single scalar that is being animated.

Returns:
the current value of the scalar
Exceptions:
IllegalStateException if this Animation is not currently animating a single scalar value.

double [] edu.cmu.hcii.calo.view.animation.Animation.getCurrentValues (  ) 

Returns the current value of the array of scalars that is being animated.

Returns:
the current value of the scalar array
Exceptions:
IllegalStateException if this Animation is not currently animating an array of scalar values.

double edu.cmu.hcii.calo.view.animation.Animation.getDuration (  ) 

Gets the duration of this Animation.

Note that this means the full duration even if the Animation has been started, and not just the time from now until the end of the animation.

Note:
The AnimationManager will attempt to honor this duration on a best-effort basis. As with much computer timing, the actual animation may take a slightly longer time than this value to fully complete. The Animation will, however, never take less time than this to go from start to finish.
Returns:
the duration of this Animation

double edu.cmu.hcii.calo.view.animation.Animation.getInterpolatedValue ( double  initialValue,
double  finalValue,
double  weight 
) [private]

Returns an interpolated value for the given initial and final values, based on the current Animation's curve and the progress (which is passed in as weight so that you can ask about progress values other than the current one).

If animating more than one value (e.g., a rectangle or an array of scalars), call this method once for each value you want to animate.

Parameters:
initialValue the initial value of this particular scalar
finalValue the final value of this particular scalar
weight the point along the line between these two values that should be interpolated, expressed as a number between 0 and 1 (usually the same as the progress value)
Returns:

AnimationListener edu.cmu.hcii.calo.view.animation.Animation.getListener (  ) 

Gets the AnimationListener for this Animation.

Returns:
the AnimationListener for this Animation

Object edu.cmu.hcii.calo.view.animation.Animation.getObjectData (  ) 

Gets the arbitrary object associated with this Animation, if one has been set.

Returns:
this Animation's object data, or null if none has been set

double edu.cmu.hcii.calo.view.animation.Animation.getProgress (  ) 

Gets the progress of this animation as a floating-point number in (0, 1].

0 indicates that the animation has not yet started, and 1 indicates that it is complete. The animation's progress will be greater than zero when the AnimationListener's animationDidUpdate() method is called for the first time. The AnimationListener's animationDidUpdate() method is guaranteed to be called at least once when this Animation's progress is exactly 1.0. Also, this Animation's isComplete() method will return true if and only if this method returns 1.0.

Note:
The progress of the animation is not the same as the value of the scalar that is being animated, so be careful not to confuse these two cases. The progress is always a single number between 0 and 1.
Returns:
the progress of this Animation

Calendar edu.cmu.hcii.calo.view.animation.Animation.getStartTime (  ) 

Gets the time at which this animation was begun.

Returns null if the animation has not yet been started.

Returns:
the start time of this Animation

boolean edu.cmu.hcii.calo.view.animation.Animation.isComplete (  ) 

Returns true if this Animation is complete, and false otherwise.

If this method returns true, the getProgress() method is guaranteed to return 1.0.

Returns:
true if the Animation is complete, false otherwise.

void edu.cmu.hcii.calo.view.animation.Animation.setComplete ( boolean  complete  )  [package]

Marks this Animation as complete.

This method does not, however, stop the timer associated with the event. When an event is marked as complete, calls to getProgress() will always return 1.0. If a formerly complete event is marked incomplete, the getProgress() method will return whatever it last returned before the Animation was marked as complete.

Parameters:
complete Whether or not this Animation is complete.

void edu.cmu.hcii.calo.view.animation.Animation.setObjectData ( Object  objectData  ) 

Associates an arbitrary object with this Animation which can later be retrieved using getObjectData().

This allows you to avoid conditional logic in your AnimationListener's update method if you just want to map an animation to, for example, the object it is animating. This object is not used in any way by the Animation class; it is provided totally for your convenience.

Parameters:
objectData the arbitrary object to associate with this Animation

void edu.cmu.hcii.calo.view.animation.Animation.setTimer ( AnimationTimer  t  )  [package]

Sets the timer associated with this Animation.

This method only exists to ensure that the timer will not be garbage collected before this Animation has completed, and does not actually start the timer or associate it with the Animation in any other way.

Parameters:
t the timer associated with this Animation

void edu.cmu.hcii.calo.view.animation.Animation.start ( AnimationListener  l  ) 

Starts this animation immediately.

Parameters:
l the AnimationListener that will be notified with a call to AnimationListener.animationDidUpdate(Animation) when this Animation updates.


Member Data Documentation

Calendar edu.cmu.hcii.calo.view.animation.Animation.startTime [private]

The point in time at which this animation was started.

double edu.cmu.hcii.calo.view.animation.Animation.duration = 1.0 [private]

How long (in seconds) this animation should take.

AnimationType edu.cmu.hcii.calo.view.animation.Animation.animationType [private]

The type of this animation.

AnimationCurve edu.cmu.hcii.calo.view.animation.Animation.animationCurve [private]

The curve for this animation.

double [] edu.cmu.hcii.calo.view.animation.Animation.initialState [private]

The initial state of this animation, which is always represented as an array of doubles.

double [] edu.cmu.hcii.calo.view.animation.Animation.finalState [private]

The final state of this animation, which is always represented as an array of doubles.

AnimationTimer edu.cmu.hcii.calo.view.animation.Animation.timer [private]

The timer assigned to this animation, if any.

This field exists solely to ensure that the timer doesn't get garbage collected before the animation it controls is finished.

AnimationListener edu.cmu.hcii.calo.view.animation.Animation.listener [private]

The listener for this animation.

For simplicity, there can only be one AnimationListener at a time for any given Animation.

boolean edu.cmu.hcii.calo.view.animation.Animation.isComplete = false [private]

Whether this animation is complete.

Object edu.cmu.hcii.calo.view.animation.Animation.objectData [private]

The arbitrary object data associated with this Animation, if any.


The documentation for this class was generated from the following file:
Generated on Mon Aug 13 15:06:23 2007 for CALO by  doxygen 1.5.2