com.jidesoft.animation
Class CustomAnimation

java.lang.Object
  com.jidesoft.animation.CustomAnimation

All Implemented Interfaces:

Serializable, Cloneable

public class CustomAnimation
extends Object
implements Serializable, Cloneable

A class implements custom animations.

Currently we support three kinds of animations - fly, zoom and fade - we call it effect. They all can be used during entrance and exit animation type.

There are a lot of options you can control how the animation looks like. Those options include speed, smoothness (how many frames. The more the smoother), and location.

In the case of fly effect animation, you also have options such as direction, start location, end location, function x and function y. Function x and function y here are just like function in the maths. Both functions together will define the path of the fly in or fly out.

In the case of fade effect animation, you only have the option of end location as it stays at the same location. However you do have a function to control the fade speed at different stage. For example, if you choose FUNC_POW_HALF, it will fade faster at the beginning and slower at the end. If you choose FUNC_POW2 or FUNC_POW3, it will be the opposite.

Please note, each component should have it's own CustomAnimation and should not share the same instance with other components. If you want the same setting of a CustomAnimation, you can call clone() method to clone one.

See Also:

Serialized Form

Nested Class Summary

static interface

CustomAnimation.Callback

Field Summary

static int	BOTTOM
static int	BOTTOM_LEFT
static int	BOTTOM_RIGHT
static int	CENTER
static int	EFFECT_FADE
static int	EFFECT_FLY
static int	EFFECT_ZOOM
static Function	FUNC_BOUNCE
static Function	FUNC_LINEAR
static Function	FUNC_LOG
static Function	FUNC_POW_HALF
static Function	FUNC_POW2
static Function	FUNC_POW3
static Function	FUNC_VIBRATE
static int	HORIZONTAL
static int	IN
static int	LEFT
static int	LEFT_DOWN
static int	LEFT_UP
static int	OUT
static int	RIGHT
static int	RIGHT_DOWN
static int	RIGHT_UP
static int	SMOOTHNESS_MEDIUM
static int	SMOOTHNESS_ROUGH
static int	SMOOTHNESS_SMOOTH
static int	SMOOTHNESS_VERY_ROUGH
static int	SMOOTHNESS_VERY_SMOOTH
static int	SPEED_FAST
static int	SPEED_MEDIUM
static int	SPEED_SLOW
static int	SPEED_VERY_FAST
static int	SPEED_VERY_SLOW
static int	TOP
static int	TOP_LEFT
static int	TOP_RIGHT
static int	TYPE_ENTRANCE
static int	TYPE_EXIT
static int	VERTICAL

Constructor Summary

CustomAnimation()
Creates a CustomAnimation.

CustomAnimation(int type, int effect, int smoothness, int speed)
Creates a CustomAnimation with several parameters.

Method Summary

void	addAnimatorListener(AnimatorListener listener) Adds an AnimatorListener to this CustomAnimation.
Object	clone() Clone the CustomAnimation.
protected void	customizeAnimator(Animator animator) Customizes the animator.
AnimatorListener	getAnimatorListener() Gets the animator listener.
AnimatorListener[]	getAnimatorListeners() Returns an array of all the AnimatorListeners added to this CustomAnimation with addAnimatorListener().
CustomAnimation.Callback	getCallback() Sets the call back.
int	getDirection() Gets the direction of the animation.
int	getEffect() Gets the effect of the animation.
Point	getEndLocation() Gets the end location of the animation.
Function	getFunctionFade() Sets the function for fading effect.
Function	getFunctionX() Gets the function used to calculate the x coord.
Function	getFunctionY() Gets the function used to calculate the y coord.
Function	getFunctionZoom() Gets the function for zooming effect.
int	getInitDelay() Gets the initial delay, in milliseconds.
protected double	getPercentFade(int step, int totalStep)
protected double	getPercentX(int step, int totalStep)
protected double	getPercentY(int step, int totalStep)
protected double	getPercentZoom(int step, int totalStep)
Image	getScreenImage() Gets the screen image.
int	getSecondaryDirection() Gets the secondary direction.
int	getSmoothness() Gets the smoothness of the animation.
int	getSpeed() Gets the speed.
Point	getStartLocation() Gets the start location of the animation.
int	getType() Gets the type of the animation.
Rectangle	getVisibleBounds() Gets the visible bounds.
boolean	isRunning() Checks if the animation is running.
void	removeAnimatorListener(AnimatorListener listener) Removes an AnimatorListener from this CustomAnimation.
void	setAnimatorListener(AnimatorListener animatorListener) Sets the animator listener.
void	setCallback(CustomAnimation.Callback callback) Callback which will be called when animation ends.
void	setDirection(int direction) Sets the direction of the animation.
void	setEffect(int effect) Sets the effect of animation.
void	setEndLocation(Point endLocation) Sets the end location of the animation.
void	setFunctionFade(Function functionFade) Sets the function for fading effect.
void	setFunctionX(Function functionX) Sets the function used to calculate the x coord.
void	setFunctionY(Function functionY) Sets the function used to calculate the x coord.
void	setFunctionZoom(Function functionZoom) Sets the function for zooming effect.
void	setInitDelay(int initDelay) Sets the initial delay.
void	setScreenImage(Image screenImage) Sets the screen image.
void	setSecondaryDirection(int secondaryDirection) Sets the secondary direction.
void	setSmoothness(int smoothness) Sets the smoothness.
void	setSpeed(int speed) Sets the speed.
void	setStartLocation(Point startLocation) Sets the start location of the animation.
void	setType(int type) Sets the type of the animation.
void	setVisibleBounds(Rectangle visibleBounds) Sets the visible bounds.
void	start(Component source) Starts the animation.
void	stop() Stops the animation.

Methods inherited from class java.lang.Object

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

Field Detail

TYPE_ENTRANCE

public static final int TYPE_ENTRANCE

See Also:

Constant Field Values

TYPE_EXIT

public static final int TYPE_EXIT

See Also:

Constant Field Values

EFFECT_FLY

public static final int EFFECT_FLY

See Also:

Constant Field Values

EFFECT_ZOOM

public static final int EFFECT_ZOOM

See Also:

Constant Field Values

EFFECT_FADE

public static final int EFFECT_FADE

See Also:

Constant Field Values

SMOOTHNESS_VERY_SMOOTH

public static final int SMOOTHNESS_VERY_SMOOTH

See Also:

Constant Field Values

SMOOTHNESS_SMOOTH

public static final int SMOOTHNESS_SMOOTH

See Also:

Constant Field Values

SMOOTHNESS_MEDIUM

public static final int SMOOTHNESS_MEDIUM

See Also:

Constant Field Values

SMOOTHNESS_ROUGH

public static final int SMOOTHNESS_ROUGH

See Also:

Constant Field Values

SMOOTHNESS_VERY_ROUGH

public static final int SMOOTHNESS_VERY_ROUGH

See Also:

Constant Field Values

SPEED_VERY_SLOW

public static final int SPEED_VERY_SLOW

See Also:

Constant Field Values

SPEED_SLOW

public static final int SPEED_SLOW

See Also:

Constant Field Values

SPEED_MEDIUM

public static final int SPEED_MEDIUM

See Also:

Constant Field Values

SPEED_FAST

public static final int SPEED_FAST

See Also:

Constant Field Values

SPEED_VERY_FAST

public static final int SPEED_VERY_FAST

See Also:

Constant Field Values

IN

public static final int IN

See Also:

Constant Field Values

OUT

public static final int OUT

See Also:

Constant Field Values

HORIZONTAL

public static final int HORIZONTAL

See Also:

Constant Field Values

VERTICAL

public static final int VERTICAL

See Also:

Constant Field Values

CENTER

public static final int CENTER

See Also:

Constant Field Values

BOTTOM

public static final int BOTTOM

See Also:

Constant Field Values

LEFT

public static final int LEFT

See Also:

Constant Field Values

RIGHT

public static final int RIGHT

See Also:

Constant Field Values

TOP

public static final int TOP

See Also:

Constant Field Values

BOTTOM_LEFT

public static final int BOTTOM_LEFT

See Also:

Constant Field Values

BOTTOM_RIGHT

public static final int BOTTOM_RIGHT

See Also:

Constant Field Values

TOP_LEFT

public static final int TOP_LEFT

See Also:

Constant Field Values

TOP_RIGHT

public static final int TOP_RIGHT

See Also:

Constant Field Values

LEFT_DOWN

public static final int LEFT_DOWN

See Also:

Constant Field Values

LEFT_UP

public static final int LEFT_UP

See Also:

Constant Field Values

RIGHT_DOWN

public static final int RIGHT_DOWN

See Also:

Constant Field Values

RIGHT_UP

public static final int RIGHT_UP

See Also:

Constant Field Values

FUNC_LINEAR

public static Function FUNC_LINEAR

FUNC_POW_HALF

public static Function FUNC_POW_HALF

FUNC_POW2

public static Function FUNC_POW2

FUNC_POW3

public static Function FUNC_POW3

FUNC_LOG

public static Function FUNC_LOG

FUNC_BOUNCE

public static Function FUNC_BOUNCE

FUNC_VIBRATE

public static Function FUNC_VIBRATE

Constructor Detail

CustomAnimation

public CustomAnimation()

Creates a CustomAnimation.

CustomAnimation

public CustomAnimation(int type,
                       int effect,
                       int smoothness,
                       int speed)

Creates a CustomAnimation with several parameters.

Parameters:

type - TYPE_ENTRANCE or TYPE_EXIT.

effect - EFFECT_FADE or EFFECT_FLY or EFFECT_ZOOM

smoothness - any positive integer. We also predefined a few values, SMOOTHNESS_VERY_ROUGH (5), SMOOTHNESS_ROUGH (10), SMOOTHNESS_MEDIUM (25), SMOOTHNESS_SMOOTH (50), and SMOOTHNESS_VERY_SMOOTH (100). The large the value is, the smoothier the animation.

speed - any positive integer. We also predefined a few values, SPEED_VERY_SLOW (200), SPEED_SLOW (100), SPEED_MEDIUM (50), SPEED_FAST (25), and SPEED_VERY_FAST (10). The large the value is, the slower the animation.

Method Detail

getType

public int getType()

Gets the type of the animation. There are only two valid types - TYPE_ENTRANCE and TYPE_EXIT.

Returns:

the type of the animation.

setType

public void setType(int type)

Sets the type of the animation. There are only two valid types - TYPE_ENTRANCE and TYPE_EXIT.

Parameters:

type - TYPE_ENTRANCE or TYPE_EXIT.

See Also:

getType()

getEffect

public int getEffect()

Gets the effect of the animation. Valid effects are EFFECT_FLY, EFFECT_FADE and EFFECT_ZOOM.

Returns:

the effect of the animation.

setEffect

public void setEffect(int effect)

Sets the effect of animation. Valid effects are EFFECT_FLY, EFFECT_FADE and EFFECT_ZOOM.

Parameters:

effect - EFFECT_FADE or EFFECT_FLY or EFFECT_ZOOM

getInitDelay

public int getInitDelay()

Gets the initial delay, in milliseconds. It will wait for the specified time before starting the animation.

Returns:

the initial delay, in milliseconds.

setInitDelay

public void setInitDelay(int initDelay)

Sets the initial delay.

Parameters:

initDelay - the initial delay, in milliseconds.

See Also:

getInitDelay()

getSmoothness

public int getSmoothness()

Gets the smoothness of the animation. We called in smoothness, it's actually the number of frames (or steps) during the animation.

Returns:

the smoothness of the animation.

setSmoothness

public void setSmoothness(int smoothness)

Sets the smoothness. It's an integer value. There are five predefined number you can use. They are SMOOTHNESS_VERY_SMOOTH, SMOOTHNESS_SMOOTH, SMOOTHNESS_MEDIUM,SMOOTHNESS_ROUGH and SMOOTHNESS_VERY_ROUGH. We recommend you to use those predefined values although you can use any positive integer value as parameter. We called it speed, but it's actually the number of milliseconds delay between two steps. So the smaller the number, the fast the animation.

Parameters:

smoothness - the smoothness.

getSpeed

public int getSpeed()

Gets the speed. We called it speed, but it's actually the number of milliseconds delay between two steps. So the smaller the number, the fast the animation.

Returns:

the speed

setSpeed

public void setSpeed(int speed)

Sets the speed. It's an integer value. There are five predefined number you can use. They are SPEED_VERY_FAST, SPEED_FAST, SPEED_MEDIUM,SPEED_SLOW and SPEED_VERY_SLOW. We recommend you to use those predefined values although you can use any positive integer value as parameter.

Parameters:

speed - the speed.

getDirection

public int getDirection()

Gets the direction of the animation. This is only used in FLY and ZOOM effect animation when the start location is not clear.

Returns:

the direction.

setDirection

public void setDirection(int direction)

Sets the direction of the animation. This is only used in FLY and ZOOM type of animation when the start location is not clear. For example, if you never call setStartLocation() but you set direction to BOTTOM for a FLY effect entrance animation, the animation will start from the bottom of the screen and fly to the location either set by setEndLocation() or set by showPopup(...) method vertically.

Parameters:

direction - the direction. The valid values are TOP, TOP_LEFT, LEFT, TOP_RIGHT, RIGHT, BOTTOM, BOTTOM_LEFT, and BOTTOM_RIGHT.

getSecondaryDirection

public int getSecondaryDirection()

Gets the secondary direction. This is not used right now. It is reserved for future usage because some animation effects we will add need it.

Returns:

the secondary direction.

setSecondaryDirection

public void setSecondaryDirection(int secondaryDirection)

Sets the secondary direction. This is not used right now. It is reserved for future usage because some animation effects we will add need it.

Parameters:

secondaryDirection - the secondary direction.

getStartLocation

public Point getStartLocation()

Gets the start location of the animation.

Returns:

the start location of the animation.

setStartLocation

public void setStartLocation(Point startLocation)

Sets the start location of the animation. In exit type animation, the start location, if never set, is defaulted to the current location.

Parameters:

startLocation - the start location.

getEndLocation

public Point getEndLocation()

Gets the end location of the animation.

Returns:

the end location.

setEndLocation

public void setEndLocation(Point endLocation)

Sets the end location of the animation. In entrnace type animation, the end location, if never set, is defaulted to the current location.

Parameters:

endLocation - the end location.

getVisibleBounds

public Rectangle getVisibleBounds()

Gets the visible bounds. This is only used when there is no the start and end location but have direction information. In order to calculate the location, we will use this bounds as the visible area.
For example, if the direction is BOTTOM in a fly entrance animation, we will calculate the start location based on the visible bounds so that it starts right right outside the visible bounds to get the fly-in effect.

Returns:

the visible bounds. By default it will use the screen bounds. If it's dual or more monitors system, it will use the main monitor screen bounds.

setVisibleBounds

public void setVisibleBounds(Rectangle visibleBounds)

Sets the visible bounds.

Parameters:

visibleBounds - the visible bounds of the screen.

start

public void start(Component source)

Starts the animation.

Parameters:

source - the component which will animate.

getAnimatorListener

public AnimatorListener getAnimatorListener()

Gets the animator listener. Usually it will return null unless you set it. If it's null, it will setup the default animator listener based on the effect and type.

Returns:

the animator listener.

setAnimatorListener

public void setAnimatorListener(AnimatorListener animatorListener)

Sets the animator listener. Usually you don't need to set it. It will setup the default animator listener based on the effect and type. If you decide to set it, you will have full control over how the animation works.

Parameters:

animatorListener - the animation listener.

addAnimatorListener

public void addAnimatorListener(AnimatorListener listener)

Adds an AnimatorListener to this CustomAnimation. Please use this method if you wish to receive notification that the animation is about to start or has just ended.

Parameters:

listener - the AnimatorListener to be added

removeAnimatorListener

public void removeAnimatorListener(AnimatorListener listener)

Removes an AnimatorListener from this CustomAnimation.

Parameters:

listener - the listener to be removed

getAnimatorListeners

public AnimatorListener[] getAnimatorListeners()

Returns an array of all the AnimatorListeners added to this CustomAnimation with addAnimatorListener().

Returns:

all of the AnimatorListeners added or an empty array if no listeners have been added

customizeAnimator

protected void customizeAnimator(Animator animator)

Customizes the animator. Based on the type and effect, this method will set an AnimatorListener to do the animation using Animator.addAnimatorListener(com.jidesoft.swing.AnimatorListener) method. If you have any new effect, you can override this method to provide your own AnimatorListener.

Parameters:

animator - the Animator.

stop

public void stop()

Stops the animation.

getPercentX

protected double getPercentX(int step,
                             int totalStep)

getPercentY

protected double getPercentY(int step,
                             int totalStep)

getPercentFade

protected double getPercentFade(int step,
                                int totalStep)

getPercentZoom

protected double getPercentZoom(int step,
                                int totalStep)

getScreenImage

public Image getScreenImage()

Gets the screen image.

Returns:

the screen image.

See Also:

setScreenImage(java.awt.Image)

setScreenImage

public void setScreenImage(Image screenImage)

Sets the screen image. This is really a hack than a feature. Because there is no way to display a transparent JWindow using Swing, we have to use a screenshot of current screen and paint it over the JWindow to get the transparent effect. So this method is used so that caller can set the screen image. If the future, if Swing ever supports transparent JWindow, we will be more than happy to get rid of this method.

Parameters:

screenImage - the screen image.

getCallback

public CustomAnimation.Callback getCallback()

Sets the call back.

Returns:

the call back.

setCallback

public void setCallback(CustomAnimation.Callback callback)

Callback which will be called when animation ends.

Parameters:

callback - the callback.

getFunctionX

public Function getFunctionX()

Gets the function used to calculate the x coord.

Returns:

the function used to calculate the x coord.

setFunctionX

public void setFunctionX(Function functionX)

Sets the function used to calculate the x coord. Together with functionY and the start/end locations, they will determine the exact track of a fly animation.

Here is an example. Say the animation will start at x coord 0 and end at x coord 100. To make it simple, let's assume there are 100 steps in this animation. If you use linear functionX, it will move steadily because in the linear function, calculate(step, totalStep) simply returns ((double) step) / totalStep. This means at step 1, move to x coord 1, at step 2, move to x coord 2 and so on. Now if you use pow2 function, it will move differently. Pow2 function returns Math.pow((double) step / totalStep, 2.0). If you calculate manually, you will find it moves slowly at the beginning and faster at the end. Pow 1/2 function on the other hand will be opposite. It will be faster at the beginning and slower at the end. Please note, this is just the functionX which controls the movement on x coord. If the y coord of start and end location are different, the y coord will change along with x coord change. Combining the both functionX and functionY, it's possible to achieve any moving track as you want from the starting location to end location.
Just to make it interesting, we pre-built FUNC_BOUNCE or FUNC_VIBRATE functions you can use to create a bouncing or vibrating effect.

Parameters:

functionX - the function for X direction.

getFunctionY

public Function getFunctionY()

Gets the function used to calculate the y coord.

Returns:

the function used to calculate the y coord.

See Also:

setFunctionY(Function), setFunctionX(Function)

setFunctionY

public void setFunctionY(Function functionY)

Sets the function used to calculate the x coord. Together with functionX and the start/end locations, they will determine the exact track of the fly animation.

Parameters:

functionY - the function for Y direction.

See Also:

getFunctionY(), setFunctionX(Function)

getFunctionFade

public Function getFunctionFade()

Sets the function for fading effect. Same as functionX and functionY which controls the movement along x and y coord, functionFade controls the transparency level of the fading effect.

Returns:

function for fading effect.

setFunctionFade

public void setFunctionFade(Function functionFade)

Sets the function for fading effect.

Parameters:

functionFade - the function for fading calculation.

getFunctionZoom

public Function getFunctionZoom()

Gets the function for zooming effect. Same as functionX and functionY which controls the movement along x and y coord, functionZoom controls the size changing of the zooming effect.

Returns:

the function for zooming effect.

setFunctionZoom

public void setFunctionZoom(Function functionZoom)

Sets the function for zooming effect.

Parameters:

functionZoom - the function for zooming calculation.

clone

public Object clone()

Clone the CustomAnimation. Since CustomAnimation cannot be shared among several components, it is recommended to clone a CustomAnimation when using it.

Overrides:

clone in class Object

Returns:

a cloned CustomAnimation.

isRunning

public boolean isRunning()

Checks if the animation is running.

Returns:

true if the animation is running.