com.sun.scenario.animation
Class Clip

java.lang.Object
  com.sun.scenario.animation.Animation
      com.sun.scenario.animation.Clip

public final class Clip
extends Animation

This class controls animations. Its constructors and various set methods control the parameters under which animations are run, and the other methods support starting and stopping the animation. The parameters of this class use the concepts of a "cycle" (the base animation) and an "envelope" that controls how the cycle is started, ended, and repeated.

Most of the methods here are simple getters/setters for the properties used by Clip. Typical animations will simply use one of the factory methods (depending on whether you are constructing a repeating animation), optionally call any of the set* methods to alter any of the other parameters, and then call start() to run the animation. For example, this animation will run for 1 second, calling your TimingTarget with timing events when the animation is started, running, and stopped:

  Clip clip = Clip.create(1000, property, startVal, endVal);
  clip.start();
 

The following variation will run a half-second animation 4 times, reversing direction each time:

  Clip clip = Clip.create(500, 4, property, startVal, endVal);
  clip.start();
 

More complex animations can be created through using the properties in Clip, such as interpolation. Animations involving multiple animations that run at preset scheduled times relative to each other can be collected into a Timeline object and started, stopped, and paused all at once.

Nested Class Summary

static class	Clip.Direction Direction is used to set the initial direction in which the animation starts.
static class	Clip.EndBehavior EndBehavior determines what happens at the end of the animation.
static class	Clip.RepeatBehavior RepeatBehavior determines how each successive cycle will flow.

Field Summary

static int

INDEFINITE Used to specify unending duration or repeatCount

Method Summary

void	addBeginAnimation(Animation beginAnim) Adds the specified Animation to start when this Clip reaches the begin() state.
void	addBeginAnimation(Animation beginAnim, long offset) Adds the specified Animation to start offset milliseconds after this Clip reaches the begin() state.
void	addEndAnimation(Animation endAnim) Adds the specified Animation to start when this Clip reaches the end() state.
void	addEndAnimation(Animation endAnim, long offset) Adds the specified Animation to start offset milliseconds after this Clip reaches the end() state.
void	addTarget(TimingTarget target) Adds a TimingTarget to the list of targets that get notified of each timingEvent.
java.lang.Iterable<Animation>	beginAnimations() Returns an iterable list of the Animation objects scheduled to start when this Clip reaches the begin() state.
java.lang.Iterable<? extends ScheduledAnimation>	beginEntries() Returns an iterable list of the scheduled animations that will start when this Clip reaches the begin() state.
void	cancel() This method is like the stop() method, only this one will not result in a calls to the end() method in all TimingTargets of this Animation; it simply cancels the Clip immediately.
static <T> Clip	create(long duration, float repeatCount, java.lang.Object target, java.lang.String property, T... keyValues) Returns a new Clip instance for the given duration, repeat count, and key values.
static <T> Clip	create(long duration, float repeatCount, Property<T> property, T... keyValues) Returns a new Clip instance for the given duration, repeat count, and key values.
static Clip	create(long duration, float repeatCount, TimingTarget target) Returns a new Clip instance that drives the given target over the specified duration and repeat count.
static <T> Clip	create(long duration, java.lang.Object target, java.lang.String property, T... keyValues) Returns a new Clip instance for the given duration and key values.
static <T> Clip	create(long duration, Property<T> property, T... keyValues) Returns a new Clip instance for the given duration and key values.
static Clip	create(long duration, TimingTarget target) Returns a new Clip instance that drives the given target over the specified duration.
java.lang.Iterable<Animation>	endAnimations() Returns an iterable list of the Animation objects scheduled to start when this Clip reaches the end() state.
java.lang.Iterable<? extends ScheduledAnimation>	endEntries() Returns an iterable list of the scheduled animations that will start when this Clip reaches the end() state.
Clip.Direction	getDirection() Returns the direction of this animation.
long	getDuration() Returns the duration of the animation.
Clip.EndBehavior	getEndBehavior() Returns the Clip.EndBehavior of the animation, either HOLD to retain the final value or RESET to take on the initial value.
Interpolator	getInterpolator() Returns the interpolator for the animation.
Clip.RepeatBehavior	getRepeatBehavior() Returns the Clip.RepeatBehavior of the animation.
float	getRepeatCount() Returns the number of times the animation cycle will repeat.
int	getResolution() Returns the current resolution of the animation.
boolean	isRunning() Returns whether this Clip object or any of its dependent Clips are currently running
void	pause() This method pauses a running animation.
void	removeBeginAnimation(Animation beginAnim) Removes the specified Animation from the list of Animations to be started when this Clip reaches the begin() state.
void	removeEndAnimation(Animation endAnim) Removes the target Animation from the list of Animations to be started when this Clip reaches the end() state.
void	removeTarget(TimingTarget target) Removes the specified TimingTarget from the list of targets that get notified of each timingEvent.
void	resume() This method resumes a paused animation.
void	setDirection(Clip.Direction direction) Sets the direction of this animation.
void	setDuration(long duration) Sets the duration for the animation
void	setEndBehavior(Clip.EndBehavior endBehavior) Sets the behavior at the end of the animation.
void	setInterpolator(Interpolator interpolator) Sets the interpolator for the animation cycle.
void	setRepeatBehavior(Clip.RepeatBehavior repeatBehavior) Sets the Clip.RepeatBehavior of the animation.
void	setRepeatCount(float repeatCount) Sets the number of times the animation cycle will repeat.
void	setResolution(int resolution) Sets the resolution of the animation
void	stop() This method is optional; animations will always stop on their own if Clip is provided with appropriate values for duration and repeatCount in the constructor.

Methods inherited from class com.sun.scenario.animation.Animation

animateTo, start

Methods inherited from class java.lang.Object

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

Field Detail

INDEFINITE

public static final int INDEFINITE

Used to specify unending duration or repeatCount

See Also:

setDuration(long), setRepeatCount(float), Constant Field Values

Method Detail

create

public static Clip create(long duration,
                          TimingTarget target)

Returns a new Clip instance that drives the given target over the specified duration.

Parameters:

duration - the duration of the animation, in milliseconds, or Clip.INDEFINITE

target - the target of the animation (e.g. a KeyFrames instance)

Returns:

a new Clip instance

create

public static <T> Clip create(long duration,
                              Property<T> property,
                              T... keyValues)

Returns a new Clip instance for the given duration and key values.

Parameters:

duration - the duration of the animation, in milliseconds, or Clip.INDEFINITE

property - the target property of the animation

keyValues - the set of key values in the animation

Returns:

a new Clip instance

create

public static <T> Clip create(long duration,
                              java.lang.Object target,
                              java.lang.String property,
                              T... keyValues)

Returns a new Clip instance for the given duration and key values.

This is a convenience method that is equivalent to calling:

     Clip.create(duration, new BeanProperty<T>(target, property), keyValues);
 

Parameters:

duration - the duration of the animation, in milliseconds, or Clip.INDEFINITE

target - the target object of the animation

property - the property on the target object to be animated

keyValues - the set of key values in the animation

Returns:

a new Clip instance

create

public static Clip create(long duration,
                          float repeatCount,
                          TimingTarget target)

Returns a new Clip instance that drives the given target over the specified duration and repeat count. The repeatCount may be INDEFINITE for animations that repeat indefinitely, but must otherwise be >= 0.

Parameters:

duration - the duration of the animation, in milliseconds, or Clip.INDEFINITE

repeatCount - the number of times to repeat the animation, or Clip.INDEFINITE

target - the target of the animation (e.g. a KeyFrames instance)

Returns:

a new Clip instance

Throws:

java.lang.IllegalArgumentException - if repeatCount is not INDEFINITE or >= 0

create

public static <T> Clip create(long duration,
                              float repeatCount,
                              Property<T> property,
                              T... keyValues)

Returns a new Clip instance for the given duration, repeat count, and key values. The repeatCount may be INDEFINITE for animations that repeat indefinitely, but must otherwise be >= 0.

Parameters:

duration - the duration of the animation, in milliseconds, or Clip.INDEFINITE

repeatCount - the number of times to repeat the animation, or Clip.INDEFINITE

property - the target property of the animation

keyValues - the set of key values in the animation

Returns:

a new Clip instance

Throws:

java.lang.IllegalArgumentException - if repeatCount is not INDEFINITE or >= 0

create

public static <T> Clip create(long duration,
                              float repeatCount,
                              java.lang.Object target,
                              java.lang.String property,
                              T... keyValues)

Returns a new Clip instance for the given duration, repeat count, and key values.

This is a convenience method that is equivalent to calling:

     Clip.create(duration, repeatCount, new BeanProperty<T>(target, property), keyValues);
 

The repeatCount may be INDEFINITE for animations that repeat indefinitely, but must otherwise be >= 0.

Parameters:

duration - the duration of the animation, in milliseconds, or Clip.INDEFINITE

repeatCount - the number of times to repeat the animation, or Clip.INDEFINITE

target - the target object of the animation

property - the property on the target object to be animated

keyValues - the set of key values in the animation

Returns:

a new Clip instance

Throws:

java.lang.IllegalArgumentException - if repeatCount is not INDEFINITE or >= 0

getDirection

public Clip.Direction getDirection()

Returns the direction of this animation.

Returns:

the direction of this animation

setDirection

public void setDirection(Clip.Direction direction)

Sets the direction of this animation. The default direction is FORWARD.

Parameters:

direction - the direction of this animation

getInterpolator

public Interpolator getInterpolator()

Returns the interpolator for the animation.

Returns:

interpolator that the initial animation cycle uses

setInterpolator

public void setInterpolator(Interpolator interpolator)

Sets the interpolator for the animation cycle. The default interpolator is Interpolators.getEasingInstance().

Parameters:

interpolator - the interpolation to use each animation cycle

Throws:

java.lang.IllegalStateException - if animation is already running; this parameter may only be changed prior to starting the animation or after the animation has ended

See Also:

isRunning()

addTarget

public void addTarget(TimingTarget target)

Adds a TimingTarget to the list of targets that get notified of each timingEvent. This can be done at any time before, during, or after the animation has started or completed; the new target will begin having its TimingTarget methods called as soon as it is added. If target is already on the list of targets in this Clip, it is not added again (there will be only one instance of any given target in any Clip's list of targets).

Parameters:

target - TimingTarget to be added to the list of targets that get notified by this Clip of all timing events. Target cannot be null.

removeTarget

public void removeTarget(TimingTarget target)

Removes the specified TimingTarget from the list of targets that get notified of each timingEvent. This can be done at any time before, during, or after the animation has started or completed; the target will cease having its TimingTarget methods called as soon as it is removed.

Parameters:

target - TimingTarget to be removed from the list of targets that get notified by this Clip of all timing events.

getResolution

public int getResolution()

Returns the current resolution of the animation. This helps determine the maximum frame rate at which the animation will run.

Returns:

the resolution, in milliseconds, of the timer

setResolution

public void setResolution(int resolution)

Sets the resolution of the animation

Parameters:

resolution - the amount of time between timing events of the animation, in milliseconds. Note that the actual resolution may vary, according to the resolution of the timer used by the framework as well as system load and configuration; this value should be seen more as a minimum resolution than a guaranteed resolution.

Throws:

java.lang.IllegalArgumentException - resolution must be >= 0

java.lang.IllegalStateException - if animation is already running; this parameter may only be changed prior to starting the animation or after the animation has ended

See Also:

isRunning()

getDuration

public long getDuration()

Returns the duration of the animation.

Returns:

the length of the animation, in milliseconds. A return value of -1 indicates an INDEFINITE duration.

setDuration

public void setDuration(long duration)

Sets the duration for the animation

Parameters:

duration - the length of the animation, in milliseconds. This value can also be INDEFINITE, meaning the animation will run until manually stopped.

Throws:

java.lang.IllegalStateException - if animation is already running; this parameter may only be changed prior to starting the animation or after the animation has ended

See Also:

isRunning(), stop()

getRepeatCount

public float getRepeatCount()

Returns the number of times the animation cycle will repeat.

Returns:

the number of times the animation cycle will repeat.

setRepeatCount

public void setRepeatCount(float repeatCount)

Sets the number of times the animation cycle will repeat. The default value is 1. This value may be INDEFINITE for animations that repeat indefinitely, but must otherwise be >= 0. The value may be fractional if the animation should stop at some fractional point. This parameter may only be changed prior to starting the animation or after the animation has ended.

Parameters:

repeatCount - Number of times the animation cycle will repeat.

Throws:

java.lang.IllegalArgumentException - if repeatCount is not INDEFINITE or >= 0

java.lang.IllegalStateException - if animation is already running

See Also:

isRunning()

getRepeatBehavior

public Clip.RepeatBehavior getRepeatBehavior()

Returns the Clip.RepeatBehavior of the animation. The default behavior is REVERSE, meaning that the animation will reverse direction at the end of each cycle.

Returns:

whether the animation will repeat in the same direction or will reverse direction each time.

setRepeatBehavior

public void setRepeatBehavior(Clip.RepeatBehavior repeatBehavior)

Sets the Clip.RepeatBehavior of the animation.

Parameters:

repeatBehavior - the behavior for each successive cycle in the animation. A null behavior is equivalent to specifying the default: REVERSE. The default behaviors is HOLD.

Throws:

java.lang.IllegalStateException - if animation is already running; this parameter may only be changed prior to starting the animation or after the animation has ended

See Also:

isRunning()

getEndBehavior

public Clip.EndBehavior getEndBehavior()

Returns the Clip.EndBehavior of the animation, either HOLD to retain the final value or RESET to take on the initial value. The default behavior is HOLD.

Returns:

the behavior at the end of the animation

setEndBehavior

public void setEndBehavior(Clip.EndBehavior endBehavior)

Sets the behavior at the end of the animation.

Parameters:

endBehavior - the behavior at the end of the animation, either HOLD or RESET. A null value is equivalent to the default value of HOLD.

Throws:

java.lang.IllegalStateException - if animation is already running; this parameter may only be changed prior to starting the animation or after the animation has ended

See Also:

isRunning()

addBeginAnimation

public void addBeginAnimation(Animation beginAnim)

Adds the specified Animation to start when this Clip reaches the begin() state. This is equivalent to calling addBeginAnimation(beginAnim, 0).

Parameters:

beginAnim - the target which should start based on the begin state of this Clip

See Also:

addBeginAnimation(Animation, long), beginAnimations()

addBeginAnimation

public void addBeginAnimation(Animation beginAnim,
                              long offset)

Adds the specified Animation to start offset milliseconds after this Clip reaches the begin() state.

Parameters:

beginAnim - the target which should be scheduled based on the begin state of this Clip

offset - the number of milliseconds after the begin event when target should start

See Also:

addBeginAnimation(Animation), beginEntries()

beginAnimations

public java.lang.Iterable<Animation> beginAnimations()

Returns an iterable list of the Animation objects scheduled to start when this Clip reaches the begin() state. The Animations are iterated directly from this Iterable without any information about scheduling offsets that may have been specified for them. Use beginEntries() to iterate the animations along with their scheduling offsets. The returned Iterable can be used directly in a foreach construct:

     for (Animation a : clip.beginAnimations()) {...}
 

Returns:

an Iterable useful for iterating the Animations

See Also:

beginEntries()

beginEntries

public java.lang.Iterable<? extends ScheduledAnimation> beginEntries()

Returns an iterable list of the scheduled animations that will start when this Clip reaches the begin() state. ScheduledAnimation instances are iterated from this Iterable so that both the animation and the time offset it is scheduled to start at can be retrieved. The Animation objects themselves can be iterated directly, without time offset information, using the beginAnimations() method. The returned Iterable can be used directly in a foreach construct:

     for (ScheduledAnimation sa : clip.beginEntries()) {
         Animation a = sa.getAnimation();
         long timeOffset = sa.getTime();
     }
 

Returns:

an Iterable useful for iterating the scheduled animations

See Also:

beginAnimations()

removeBeginAnimation

public void removeBeginAnimation(Animation beginAnim)

Removes the specified Animation from the list of Animations to be started when this Clip reaches the begin() state.

Parameters:

beginAnim - the target to be removed from the begin animations

addEndAnimation

public void addEndAnimation(Animation endAnim)

Adds the specified Animation to start when this Clip reaches the end() state. This is equivalent to calling addEndAnimation(endAnim, 0).

Parameters:

endAnim - the target which should start based on the end state of this Clip

See Also:

addEndAnimation(Animation, long), endAnimations()

addEndAnimation

public void addEndAnimation(Animation endAnim,
                            long offset)

Adds the specified Animation to start offset milliseconds after this Clip reaches the end() state.

Parameters:

endAnim - the target which should be scheduled based on the end state of this Clip

offset - the number of milliseconds after the end event when target should start

See Also:

addEndAnimation(Animation), endEntries()

endAnimations

public java.lang.Iterable<Animation> endAnimations()

Returns an iterable list of the Animation objects scheduled to start when this Clip reaches the end() state. The Animations are iterated directly from this Iterable without any information about scheduling offsets that may have been specified for them. Use endEntries() to iterate the animations along with their scheduling offsets. The returned Iterable can be used directly in a foreach construct:

     for (Animation a : clip.endAnimations()) {...}
 

Returns:

an Iterable useful for iterating the Animations

See Also:

endEntries()

endEntries

public java.lang.Iterable<? extends ScheduledAnimation> endEntries()

Returns an iterable list of the scheduled animations that will start when this Clip reaches the end() state. ScheduledAnimation instances are iterated from this Iterable so that both the animation and the time offset it is scheduled to start at can be retrieved. The Animation objects themselves can be iterated directly, without time offset information, using the endAnimations() method. The returned Iterable can be used directly in a foreach construct:

     for (ScheduledAnimation sa : clip.endEntries()) {
         Animation a = sa.getAnimation();
         long timeOffset = sa.getTime();
     }
 

Returns:

an Iterable useful for iterating the scheduled animations

See Also:

endAnimations()

removeEndAnimation

public void removeEndAnimation(Animation endAnim)

Removes the target Animation from the list of Animations to be started when this Clip reaches the end() state.

Parameters:

endAnim - the target to be removed from the end animations

isRunning

public boolean isRunning()

Returns whether this Clip object or any of its dependent Clips are currently running

Specified by:

isRunning in class Animation

stop

public void stop()

This method is optional; animations will always stop on their own if Clip is provided with appropriate values for duration and repeatCount in the constructor. But if the application wants to stop the timer mid-stream, this is the method to call. This call will result in calls to the end() method of all TimingTargets of this Clip.

Specified by:

stop in class Animation

See Also:

cancel()

cancel

public void cancel()

This method is like the stop() method, only this one will not result in a calls to the end() method in all TimingTargets of this Animation; it simply cancels the Clip immediately.

Specified by:

cancel in class Animation

See Also:

stop()

pause

public void pause()

This method pauses a running animation. No further events are sent to TimingTargets. A paused animation may be resumed by calling the resume() method. Pausing a non-running animation has no effect. REMIND: what about dependent clips if we are already stopped?

Specified by:

pause in class Animation

See Also:

resume(), isRunning()

resume

public void resume()

This method resumes a paused animation. Resuming an animation that is not paused has no effect.

Specified by:

resume in class Animation

See Also:

pause()