objectdraw
Class Animation

java.lang.Object
  extended by objectdraw.ObjectDrawObject
      extended by objectdraw.ObjectDrawShape
          extended by objectdraw.Animation
All Implemented Interfaces:
objectdraw.Dependent, DrawableInterface

public class Animation
extends objectdraw.ObjectDrawShape

Animation is similar to VisibleImage, but rather than simply displaying an unchanging image, it displays an animation. After playing through the animation, which typically takes only a few seconds, it automatically removes itself from the canvas.

Displaying an animation is a simple as creating an Animation object, then telling it to start. WHen creating the object, you can choose one of the constants in this class to specify the type of animation, and you can also specify an object to center the animation around. So, for example, if player is a VisibleImage representing the player, this code would display a shower of gold sparks cascading down in front of him:

new Animation(Animation.SPARKS, player).start();

It is also possible to have the animation display text labels that appear over an object and move upwards and fade out as the animation runs. These labels should be set before starting the animation. So, for example, this code would make "Heal!" appear over the player as the "sparks" animation is running:

Animation animation = new Animation(Animation.SPARKS, player);
animation.label(player, "Heal!");
animation.start();


You can add as many labels as you wish to an animation in this same way.

Currently, Animation only contains animation types I produced while designing an RPG project for an introductory Java course. If you have ideas for animation you would like to see added, send a detailed description to my email address below.

Author:
Russell Zahniser (russell@zahniser.net)

Field Summary
static objectdraw.Animation.AnimationType BURST
          Animation type that shows green particles collecting around the center of the target and then bursting outward.
static objectdraw.Animation.AnimationType DUSTY
          Animation type that outlines the target in dark clouds of dust
static objectdraw.Animation.AnimationType FROSTY
          Animation type that covers the target in white layers of frost.
static objectdraw.Animation.AnimationType GLOW
          Animation type that halos the target in green spots, which then shoot off upward.
static objectdraw.Animation.AnimationType GOLD_SHOWER
          Animation type that shows a shower of golden sparks falling in front of the target.
static objectdraw.Animation.AnimationType ICE_STORM
          Animation type that shows large hailstones falling around its target.
static objectdraw.Animation.AnimationType LIGHTNING
          Animation type that shows purple lightning striking its target, followed by a white explosion.
static objectdraw.Animation.AnimationType METEOR
          Animation type that shows a single meteor moving from one object to strike another.
static objectdraw.Animation.AnimationType METEORS
          Animation type that surrounds the player with a cloud of orbiting meteors, which can be fired one by one at other targets.
static objectdraw.Animation.AnimationType SHIELD
          Animation type that shows a rotating sphere of green particles forming around its target.
static objectdraw.Animation.AnimationType SLASH_LEFT
          Animation type that shows a sword slash, moving from right to left, which leaves behind it a trail of blood that then drips down to the floor.
static objectdraw.Animation.AnimationType SLASH_RIGHT
          Animation type that shows a sword slash, moving from left to right, which leaves behind it a trail of blood that then drips down to the floor.
static objectdraw.Animation.AnimationType SMOKE_BOMB
          Animation type that shows a cloud of smoke erupting around its target.
static objectdraw.Animation.AnimationType SPARKLY
          Animation type that outlines the target with bright yellow sparks.
static objectdraw.Animation.AnimationType SPARKS
          Animation type that shows sparks rising up from the base of the target, as if it had stepped on hot coals.
static objectdraw.Animation.AnimationType SPLIT
          Animation type that shows a vertical line of blue arcs forming at the middle of the target and then splitting out to the two sides.
static objectdraw.Animation.AnimationType SWARM
          Animation type that shows an angry swarm of black particles gathering on its target.
static objectdraw.Animation.AnimationType SWIRL
          Animation type that shows a swirl of pink particles wrapping upwards around its target.
static objectdraw.Animation.AnimationType TREASURE
          Animation type that shows gold glittering in a open treasure chest, then gradually fading away.
 
Constructor Summary
Animation(objectdraw.Animation.AnimationType type, DrawableInterface object)
          Create an animation.
 
Method Summary
 void addSpecialRegion(DrawableInterface object)
          Mark the region enclosed by the given object to have some special behavior.
 void addToCanvas(DrawingCanvas c)
          Place this object on the specified canvas.
 void cancel()
          Cancel this animation.
static void cancelAll()
          Cancel every animation that is currently running.
 boolean contains(Location point)
          Return true if the given location is inside this object, false otherwise.
 Animation fireOne(DrawableInterface object)
          Split off another animation targeting the given object.
 DrawingCanvas getCanvas()
          Return the canvas that this object is on.
 Color getColor()
          Return the color that this animation's labels are drawn with.
 int getCount()
          Get this animation's count.
 double getDoubleX()
          Get this object's x coordinate, in double precision.
 double getDoubleY()
          Get this object's y coordinate, in double precision.
 Location getLocation()
          Get this object's location.
 int getX()
          Get this object's x coordinate.
 int getY()
          Get this object's y coordinate.
 void hide()
          Make this object invisible.
 boolean isHidden()
          Return true if this object has been rendered invisible with a call to its hide() method, false if it is still being drawn.
 void label(DrawableInterface object, String label)
          Produce a label that will appear in front of the given object, move upwards, and then fade out.
 void label(DrawableInterface object, String label, int dt)
          Produce a label that will appear in front of the given object, move upwards, and then fade out.
 void move(double dx, double dy)
          Shift (translate) this object left or right by an amount dx, and up or down by an amount dy.
 void moveTo(double x, double y)
          Move the center of this animation to the given (code>x, y).
 void moveTo(Location point)
          Move the center of this animation to the given location.
 void removeFromCanvas()
          Remove this object from its canvas.
 void sendBackward()
          Move this object one step backward in the draw order, causing it to be drawn underneath the objects that are in front of it.
 void sendForward()
          Move this object one step forward in the draw order, causing it to be drawn on top of the objects that are behind it.
 void sendToBack()
          Move this object to the very back of the draw order, causing it to be drawn underneath all the other objects.
 void sendToFront()
          Move this object to the very front of the draw order, causing it to be drawn on top of all the other objects.
 void setAttached(boolean attached)
          Set whether this animation moves along with the object it decorates.
static void setAttachedByDefault(boolean attached)
          Set whether animations are, by default, attached to the object they decorate.
 void setColor(Color c)
          Change the color that this animation's labels are drawn with.
 void setCount(int n)
          Set this animation's count.
static void setDefaultLabelColor(Color color)
          Set the default color for animation labels to appear in.
 void show()
          Make an object visible again after it had been hidden.
 void start()
          Start (or restart) this animation.
 String toString()
          Return a string describing how this object might be constructed.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

BURST

public static final objectdraw.Animation.AnimationType BURST
Animation type that shows green particles collecting around the center of the target and then bursting outward.


DUSTY

public static final objectdraw.Animation.AnimationType DUSTY
Animation type that outlines the target in dark clouds of dust


FROSTY

public static final objectdraw.Animation.AnimationType FROSTY
Animation type that covers the target in white layers of frost.


GLOW

public static final objectdraw.Animation.AnimationType GLOW
Animation type that halos the target in green spots, which then shoot off upward.


GOLD_SHOWER

public static final objectdraw.Animation.AnimationType GOLD_SHOWER
Animation type that shows a shower of golden sparks falling in front of the target.


ICE_STORM

public static final objectdraw.Animation.AnimationType ICE_STORM
Animation type that shows large hailstones falling around its target. The hailstones, upon hitting the ground, shatter into smaller pieces. It is also possible for hailstones to turn into steam when they hit the ground; to accomplish this, call addSpecialRegion() for each object within whose bounds steam ought to be produced.


LIGHTNING

public static final objectdraw.Animation.AnimationType LIGHTNING
Animation type that shows purple lightning striking its target, followed by a white explosion.


METEOR

public static final objectdraw.Animation.AnimationType METEOR
Animation type that shows a single meteor moving from one object to strike another. The source object is the one passed to the constructor of Asteroid; the destination object should be set with addSpecialRegion(). This is also the animation type used for the meteors fired by a METEORS animation.


METEORS

public static final objectdraw.Animation.AnimationType METEORS
Animation type that surrounds the player with a cloud of orbiting meteors, which can be fired one by one at other targets. By default, six meteors will be shown; you can change this number by calling setCount() at any time before you start() the animation. Calling fireOne() on an animation of this type will separate out a single meteor into a new animation, which you can then start as you would any other animation. This will also decrease the count by one. So, you can tell when all the meteors have been fired, because getCount() will return 0.


SHIELD

public static final objectdraw.Animation.AnimationType SHIELD
Animation type that shows a rotating sphere of green particles forming around its target.


SLASH_LEFT

public static final objectdraw.Animation.AnimationType SLASH_LEFT
Animation type that shows a sword slash, moving from right to left, which leaves behind it a trail of blood that then drips down to the floor.


SLASH_RIGHT

public static final objectdraw.Animation.AnimationType SLASH_RIGHT
Animation type that shows a sword slash, moving from left to right, which leaves behind it a trail of blood that then drips down to the floor.


SMOKE_BOMB

public static final objectdraw.Animation.AnimationType SMOKE_BOMB
Animation type that shows a cloud of smoke erupting around its target.


SPARKLY

public static final objectdraw.Animation.AnimationType SPARKLY
Animation type that outlines the target with bright yellow sparks.


SPARKS

public static final objectdraw.Animation.AnimationType SPARKS
Animation type that shows sparks rising up from the base of the target, as if it had stepped on hot coals.


SPLIT

public static final objectdraw.Animation.AnimationType SPLIT
Animation type that shows a vertical line of blue arcs forming at the middle of the target and then splitting out to the two sides.


SWARM

public static final objectdraw.Animation.AnimationType SWARM
Animation type that shows an angry swarm of black particles gathering on its target.


SWIRL

public static final objectdraw.Animation.AnimationType SWIRL
Animation type that shows a swirl of pink particles wrapping upwards around its target.


TREASURE

public static final objectdraw.Animation.AnimationType TREASURE
Animation type that shows gold glittering in a open treasure chest, then gradually fading away. This animation is designed to work only with one particular open treasure chest image.

Constructor Detail

Animation

public Animation(objectdraw.Animation.AnimationType type,
                 DrawableInterface object)
Create an animation.

Parameters:
type - Type of animation. This will be one of the constants, like Animation.SPARKS, that are defined in this class.
object - Target of the animation. The animation will be centered around this object.
Method Detail

addSpecialRegion

public void addSpecialRegion(DrawableInterface object)
Mark the region enclosed by the given object to have some special behavior.

Parameters:
object - Objects whose bounding rectangle will be marked.

addToCanvas

public void addToCanvas(DrawingCanvas c)
Place this object on the specified canvas. The object will be removed from its current canvas, if it is on a canvas that is not the one it is being moved to. The object will be at the front of the canvas, as if it had just been drawn. If the given canvas is null the object is simply removed from its current canvas.

Specified by:
addToCanvas in interface DrawableInterface
Overrides:
addToCanvas in class objectdraw.ObjectDrawShape
Parameters:
c - DrawingCanvas to place this object on

cancel

public void cancel()
Cancel this animation.


cancelAll

public static void cancelAll()
Cancel every animation that is currently running.


contains

public boolean contains(Location point)
Return true if the given location is inside this object, false otherwise. Because Lines and FramedArcs have no "inside", a point is considered to be contained in one of them as long as it is within a few pixels of the line.

Parameters:
point - Location to test
Returns:
whether the given location is inside this shape

fireOne

public Animation fireOne(DrawableInterface object)
Split off another animation targeting the given object. This only works for certain animation types, such as METEORS, that have several pieces that can be targeted separately.

The returned animation will need to be start()'ed just as any other newly created animation would. It can have labels or special regions added to it first, like any other animation.

This method reduces the count of this animation by one, and if the count gets to zero, the animation is stopped and removed from the canvas.

Parameters:
object - Target of the new animation
Returns:
newly created animation

getCanvas

public DrawingCanvas getCanvas()
Return the canvas that this object is on. If it has been removed from its canvas, this method will return null.

Specified by:
getCanvas in interface DrawableInterface
Overrides:
getCanvas in class objectdraw.ObjectDrawShape
Returns:
the DrawingCanvas that this object is on.

getColor

public Color getColor()
Return the color that this animation's labels are drawn with.

Specified by:
getColor in interface DrawableInterface
Overrides:
getColor in class objectdraw.ObjectDrawShape
Returns:
the Color that this animation's labels are drawn with

getCount

public int getCount()
Get this animation's count. This is a number that has meaning only for animations like METEORS that consist of several discreet pieces. The count will be 1 unless you set it to something else.

Returns:
The number of pieces in this animation.

getDoubleX

public double getDoubleX()
Get this object's x coordinate, in double precision.

Returns:
this object's x coordinate, in double precision

getDoubleY

public double getDoubleY()
Get this object's y coordinate, in double precision.

Returns:
this object's y coordinate, in double precision

getLocation

public Location getLocation()
Get this object's location. Translating this Location object will have the same effect as moving the object. So, the following two lines of code are equivalent:

object.move(10, 20);
object.getLocation().translate(10, 20);


If you want to create a Location offset by some amount from the Location of this object, without actually moving this object, use the offset() method in Location, which creates a new Location.

Returns:
the Location of this object.

getX

public int getX()
Get this object's x coordinate.

Returns:
this object's x coordinate

getY

public int getY()
Get this object's y coordinate.

Returns:
this object's y coordinate

hide

public void hide()
Make this object invisible. It stays in position on its canvas; it is simply not drawn. This method has no effect if the object was already hidden.

Specified by:
hide in interface DrawableInterface
Overrides:
hide in class objectdraw.ObjectDrawShape

isHidden

public boolean isHidden()
Return true if this object has been rendered invisible with a call to its hide() method, false if it is still being drawn.

Specified by:
isHidden in interface DrawableInterface
Overrides:
isHidden in class objectdraw.ObjectDrawShape
Returns:
whether this object is hidden

label

public void label(DrawableInterface object,
                  String label)
Produce a label that will appear in front of the given object, move upwards, and then fade out.

Parameters:
object - Object to label
label - Text to display

label

public void label(DrawableInterface object,
                  String label,
                  int dt)
Produce a label that will appear in front of the given object, move upwards, and then fade out.

Parameters:
object - Object to label
label - Text to display
dt - Number of frames to wait, before the start of the animation, before displaying the label.

move

public void move(double dx,
                 double dy)
Shift (translate) this object left or right by an amount dx, and up or down by an amount dy. A negative dx indicates a shift to the left; a negative dy indicates a shift up. If this animation is attached to its target, the target will move with it.

Specified by:
move in interface DrawableInterface
Overrides:
move in class objectdraw.ObjectDrawShape
Parameters:
dx - amount of x translation
dy - amount of y translation
See Also:
setAttached(boolean)

moveTo

public void moveTo(double x,
                   double y)
Move the center of this animation to the given (code>x, y). If this animation is attached to its target, the target will move with it.

Specified by:
moveTo in interface DrawableInterface
Overrides:
moveTo in class objectdraw.ObjectDrawShape
Parameters:
x - x coordinate to move to
y - y coordinate to move to
See Also:
setAttached(boolean)

moveTo

public void moveTo(Location point)
Move the center of this animation to the given location. If this animation is attached to its target, the target will move with it.

Specified by:
moveTo in interface DrawableInterface
Overrides:
moveTo in class objectdraw.ObjectDrawShape
Parameters:
point - Location to move to
See Also:
setAttached(boolean)

removeFromCanvas

public void removeFromCanvas()
Remove this object from its canvas.

Specified by:
removeFromCanvas in interface DrawableInterface
Overrides:
removeFromCanvas in class objectdraw.ObjectDrawShape

sendBackward

public void sendBackward()
Move this object one step backward in the draw order, causing it to be drawn underneath the objects that are in front of it.

Specified by:
sendBackward in interface DrawableInterface
Overrides:
sendBackward in class objectdraw.ObjectDrawShape

sendForward

public void sendForward()
Move this object one step forward in the draw order, causing it to be drawn on top of the objects that are behind it.

Specified by:
sendForward in interface DrawableInterface
Overrides:
sendForward in class objectdraw.ObjectDrawShape

sendToBack

public void sendToBack()
Move this object to the very back of the draw order, causing it to be drawn underneath all the other objects.

Specified by:
sendToBack in interface DrawableInterface
Overrides:
sendToBack in class objectdraw.ObjectDrawShape

sendToFront

public void sendToFront()
Move this object to the very front of the draw order, causing it to be drawn on top of all the other objects.

Specified by:
sendToFront in interface DrawableInterface
Overrides:
sendToFront in class objectdraw.ObjectDrawShape

setAttached

public void setAttached(boolean attached)
Set whether this animation moves along with the object it decorates. If this is set to false, you can move the animation or its target and have them appear in separate places.

Parameters:
attached -

setAttachedByDefault

public static void setAttachedByDefault(boolean attached)
Set whether animations are, by default, attached to the object they decorate. If true, moving that object will cause the animation to move with it.

Parameters:
attached - Whether animations are attached to their target by default

setColor

public void setColor(Color c)
Change the color that this animation's labels are drawn with.

Specified by:
setColor in interface DrawableInterface
Overrides:
setColor in class objectdraw.ObjectDrawShape
Parameters:
c - new Color for this animation's labels

setCount

public void setCount(int n)
Set this animation's count. This is a number that has meaning only for animations like METEORS that consist of several discreet pieces. The count will be 1 unless you set it to something else. This method must be called before start() to have the proper effect. The count is automatically reduced by fireOne(), and the animation is automatically removed from the canvas when the count gets to zero.

Parameters:
n - The number of pieces in this animation.

setDefaultLabelColor

public static void setDefaultLabelColor(Color color)
Set the default color for animation labels to appear in. You can set the color used by a particular Animation using its setColor(), but this method is convenient if you want all your animations to have the same color and that color isn't black.

Parameters:
color - Default color for labels

show

public void show()
Make an object visible again after it had been hidden. This method has no effect if the object was already visible.

Specified by:
show in interface DrawableInterface
Overrides:
show in class objectdraw.ObjectDrawShape

start

public void start()
Start (or restart) this animation. You should be sure to set the count, labels, and any special regions before calling this method if you want them to appear correctly. If the animation is restarted before it has finished, it will jump back to the start of the animation without completing the sequence it was in.

See Also:
setCount(int), label(DrawableInterface, String), addSpecialRegion(DrawableInterface)

toString

public String toString()
Return a string describing how this object might be constructed.

Overrides:
toString in class objectdraw.ObjectDrawObject