javalib.funworld
Class Animation<Model>

java.lang.Object
  javalib.funworld.World
      javalib.funworld.Animation<Model>

All Implemented Interfaces:

Drawable

public abstract class Animation<Model>
extends World

An easy-to-use class for model/view GUI programs. The Animation class maintains the model as an instance variable and updates it at each event. To use it,

1. Decide what type the "model" (i.e. the internal information that changes while the program runs) should be. Some common choices:
   • WorldImage (for an animation that does purely graphical operations at each event)
   • Integer (for an animation whose current state can be described by a single integer, and whose changes are arithmetic operations)
   • String (for an animation whose current state can be described by a string, and whose changes are string operations)
   • Posn (for an animation whose current state consists of an (x,y) coordinate pair, and which might change either or both coordinates in response to events)
   • A user-defined class (if you need to keep track of more information than the above choices give you)
2. Define a subclass of Animation<your model type>. For example, if you were using an Integer model, you could write

   import javalib.funworld.*;
     class MyAnimation extends Animation<Integer>
     {
         // constructors and methods will go here
     }

3. Add a constructor that takes in the specified type and calls super on it, e.g.

       public MyAnimation (Integer initial)
         {
             super(initial);
             // maybe do other stuff here
         }

   Alternatively, if your animation should always start with the same initial value, you can write a constructor that takes in nothing, e.g.

       public MyAnimation ()
         {
             super(0);
             // maybe do other stuff here
         }

4. Add event-handlers as necessary. For example, if you wanted to add 1 to the integer model at every clock tick, you could write

       public Integer gotTick (Integer old)
         {
             return old + 1;
         }

   Of course, these methods should have test cases in an accompanying TestMyAnimation class.
5. One event handler you'll always need is makeImage, which is how the animation library decides what to show in the animation window. For example, if you wanted to display a blue disk whose radius was the integer model, you could write

       public WorldImage makeImage (Integer current)
         {
             return AImage.makeCircle(current, new Blue(), Mode.FILLED);
         }
     

6. Once all the event handlers pass all their test cases, you can try running the whole animation with code like

   new MyAnimation(5).bigBang (300, 200, 0.5);

   which creates a MyAnimation object with initial model 5 and runs it in a 300x200 window, with the clock ticking every 0.5 second.

Version:

March 5, 2013

Author:

Stephen Bloch

Field Summary

Fields inherited from class javalib.funworld.World

lastWorld, mytime, stopTimer, theCanvas

Constructor Summary

Animation(Model newModel)
Constructor for Animation.

Method Summary

boolean	bigBang() Start an animation, with default size and no timer.
boolean	bigBang(double time) Start an animation, with default size and a specified timer interval.
boolean	bigBang(int width, int height) Start an animation, with specified size and no timer.
boolean	bigBang(int width, int height, double time) Start an animation, with specified size and timer interval.
World	endOfWorld(String s) End the animation now.
int	getCurrentHeight() Get the current height of the animation window (which may have been adjusted by the user).
int	getCurrentWidth() Get the current width of the animation window (which may have been adjusted by the user).
double	getElapsedTime() Get elapsed time so far.
int	getHeight() Get the initially-specified height.
Model	getModel() Get the current model.
int	getTickCount() Get number of ticks so far.
int	getWidth() Get the initially-specified width.
Model	gotKeyEvent(Model oldModel, String s) Produce the new model after a keyboard event.
Model	gotMouseClicked(Model oldModel, Posn mouse) Produce the new model after a mouse-click event.
Model	gotMouseDragged(Model oldModel, Posn mouse) Produce the new model after a mouse-drag event.
Model	gotMouseEntered(Model oldModel, Posn mouse) Produce the new model after the mouse enters the window.
Model	gotMouseExited(Model oldModel, Posn mouse) Produce the new model after the mouse leaves the window.
Model	gotMouseMoved(Model oldModel, Posn mouse) Produce the new model after a mouse-move event.
Model	gotMousePressed(Model oldModel, Posn mouse) Produce the new model after the mouse is pressed (but not yet released).
Model	gotMouseReleased(Model oldModel, Posn mouse) Produce the new model after the mouse is released.
Model	gotTick(Model oldModel) Produce the new model after a tick event.
WorldImage	lastImage(String s) An alternative to makeImage that is called when the animation ends.
WorldImage	makeImage() A version of makeImage(Model) that defaults to using the current Model.
abstract WorldImage	makeImage(Model oldModel) Produce a WorldImage representation of the model; users subclassing Animation must override this.
World	onKeyEvent(String s) User shouldn't need to use or override this method, unless you're doing something with the World more complicated than just replacing the Model.
World	onMouseClicked(Posn mouse) User shouldn't need to use or override this method, unless you're doing something with the World more complicated than just replacing the Model.
World	onMouseDragged(Posn mouse) User shouldn't need to use or override this method, unless you're doing something with the World more complicated than just replacing the Model.
World	onMouseEntered(Posn mouse) User shouldn't need to use or override this method, unless you're doing something with the World more complicated than just replacing the Model.
World	onMouseExited(Posn mouse) User shouldn't need to use or override this method, unless you're doing something with the World more complicated than just replacing the Model.
World	onMouseMoved(Posn mouse) User shouldn't need to use or override this method, unless you're doing something with the World more complicated than just replacing the Model.
World	onMousePressed(Posn mouse) User shouldn't need to use or override this method, unless you're doing something with the World more complicated than just replacing the Model.
World	onMouseReleased(Posn mouse) User shouldn't need to use or override this method, unless you're doing something with the World more complicated than just replacing the Model.
World	onTick() User shouldn't need to use or override this method, unless you're doing something with the World more complicated than just replacing the Model.
WorldEnd	worldEnds() User shouldn't need to use or override this method.
WorldEnd	worldEnds(Model oldModel) Decide whether the animation should end yet, and if so, what the final window should look like.

Methods inherited from class javalib.funworld.World

drawWorld, processKeyEvent, processMouseClicked, processMouseDragged, processMouseEntered, processMouseExited, processMouseMoved, processMousePressed, processMouseReleased, processTick, stopWorld, testOnTick

Methods inherited from class java.lang.Object

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

Constructor Detail

Animation

public Animation(Model newModel)

Constructor for Animation. If you're subclassing Animation, you need to write a constructor that looks like

public MyKindOfAnimation (Model newModel)
 {
     super(newModel);
     // other initialization can go here
 }

Parameters:

newModel - the initial model for the Animation.

Method Detail

bigBang

public boolean bigBang()

Start an animation, with default size and no timer. You shouldn't need to override this, but you'll often want to call it.

Overrides:

bigBang in class World

Returns:

true

bigBang

public boolean bigBang(double time)

Start an animation, with default size and a specified timer interval. You shouldn't need to override this, but you'll often want to call it.

Overrides:

bigBang in class World

Parameters:

time - the timer interval in seconds

Returns:

true

bigBang

public boolean bigBang(int width,
                       int height)

Start an animation, with specified size and no timer. You shouldn't need to override this, but you'll often want to call it.

Overrides:

bigBang in class World

Parameters:

width - initial window width in pixels

height - initial window height in pixels

Returns:

true

bigBang

public boolean bigBang(int width,
                       int height,
                       double time)

Start an animation, with specified size and timer interval. You shouldn't need to override this, but you'll often want to call it.

Overrides:

bigBang in class World

Parameters:

width - initial window width in pixels

height - initial window height in pixels

time - the timer interval in seconds

Returns:

true

endOfWorld

public World endOfWorld(String s)

End the animation now. You shouldn't need to override this, but you'll often want to call it, typically from within an event handler. For example, if you wanted to end the animation when the user presses the "q" key, you could call this method from within gotKeyEvent.

Overrides:

endOfWorld in class World

Parameters:

message - a String to pass on to lastImage, e.g. "Congratulations! Final score 283."

Returns:

this world

getCurrentHeight

public int getCurrentHeight()

Get the current height of the animation window (which may have been adjusted by the user). You shouldn't need to override this, but you may want to call it.

Overrides:

getCurrentHeight in class World

Returns:

an int

getCurrentWidth

public int getCurrentWidth()

Get the current width of the animation window (which may have been adjusted by the user). You shouldn't need to override this, but you may want to call it.

Overrides:

getCurrentWidth in class World

Returns:

an int

getElapsedTime

public double getElapsedTime()

Get elapsed time so far. You shouldn't need to override this, but you may want to call it.

Overrides:

getElapsedTime in class World

Returns:

the number of seconds so far.

getHeight

public int getHeight()

Get the initially-specified height. You shouldn't need to override this, but you may want to call it.

Overrides:

getHeight in class World

Returns:

the height initially specified in the bigBang call, or if not specified, the height of the first image.

getModel

public Model getModel()

Get the current model. You shouldn't need to override this. You shouldn't need to call it often either, since all the gotWhatever methods are given the current model as an argument anyway, but you can call it if you want.

Returns:

the current Model.

getTickCount

public int getTickCount()

Get number of ticks so far. You shouldn't need to override this, but you may want to call it.

Overrides:

getTickCount in class World

Returns:

the number of ticks so far.

getWidth

public int getWidth()

Get the initially-specified width. You shouldn't need to override this, but you may want to call it.

Overrides:

getWidth in class World

Returns:

the width initially specified in the bigBang call, or if not specified, the width of the first image.

gotKeyEvent

public Model gotKeyEvent(Model oldModel,
                         String s)

Produce the new model after a keyboard event. Users subclassing Animation may override this; if they don't, the default handler makes no change.

Parameters:

oldModel - the current model

s - the key that was pressed
This will be either a single character (for letters, numbers, punctuation) or one of the following: "backspace", "tab", "newline", "escape", "page up", "page down", "end", "home", "left", "up", "right", "down", "delete", or "f1" through "f12"

Returns:

the new model

gotMouseClicked

public Model gotMouseClicked(Model oldModel,
                             Posn mouse)

Produce the new model after a mouse-click event. Users subclassing Animation may override this; if they don't, the default handler makes no change.

Parameters:

oldModel - the current model

mouse - the location of the mouse

Returns:

the new model

gotMouseDragged

public Model gotMouseDragged(Model oldModel,
                             Posn mouse)

Produce the new model after a mouse-drag event. Users subclassing Animation may override this; if they don't, the default handler makes no change.

Parameters:

oldModel - the current model

mouse - the location of the mouse

Returns:

the new model

gotMouseEntered

public Model gotMouseEntered(Model oldModel,
                             Posn mouse)

Produce the new model after the mouse enters the window. Users subclassing Animation may override this; if they don't, the default handler makes no change.

Parameters:

oldModel - the current model

mouse - the location of the mouse

Returns:

the new model

gotMouseExited

public Model gotMouseExited(Model oldModel,
                            Posn mouse)

Produce the new model after the mouse leaves the window. Users subclassing Animation may override this; if they don't, the default handler makes no change.

Parameters:

oldModel - the current model

mouse - the location of the mouse

Returns:

the new model

gotMouseMoved

public Model gotMouseMoved(Model oldModel,
                           Posn mouse)

Produce the new model after a mouse-move event. Users subclassing Animation may override this; if they don't, the default handler makes no change.

Parameters:

oldModel - the current model

mouse - the location of the mouse

Returns:

the new model

gotMousePressed

public Model gotMousePressed(Model oldModel,
                             Posn mouse)

Produce the new model after the mouse is pressed (but not yet released). Users subclassing Animation may override this; if they don't, the default handler makes no change.

Parameters:

oldModel - the current model

mouse - the location of the mouse

Returns:

the new model

gotMouseReleased

public Model gotMouseReleased(Model oldModel,
                              Posn mouse)

Produce the new model after the mouse is released. Users subclassing Animation may override this; if they don't, the default handler makes no change.

Parameters:

oldModel - the current model

mouse - the location of the mouse

Returns:

the new model

gotTick

public Model gotTick(Model oldModel)

Produce the new model after a tick event. Users subclassing Animation may override this; if they don't, the default handler makes no change.

Parameters:

oldModel - the current model

Returns:

the new model

lastImage

public WorldImage lastImage(String s)

An alternative to makeImage that is called when the animation ends. You'll often want to override this method in your Animation class; if you don't, it'll just call makeImage, ignoring the string.

Overrides:

lastImage in class World

Parameters:

s - a String that endOfWorld can use to communicate to lastImage

Returns:

the image that represents the last world to be drawn

makeImage

public WorldImage makeImage()

A version of makeImage(Model) that defaults to using the current Model. You probably don't need to override this, but you can call it if you want.

Specified by:

makeImage in interface Drawable

Specified by:

makeImage in class World

Returns:

the image that represents this world at this moment

See Also:

World.makeImage()

makeImage

public abstract WorldImage makeImage(Model oldModel)

Produce a WorldImage representation of the model; users subclassing Animation must override this.

Parameters:

oldModel - the current model

Returns:

a WorldImage based on the current model

Since:

Jan. 2, 2012

onKeyEvent

public World onKeyEvent(String s)

User shouldn't need to use or override this method, unless you're doing something with the World more complicated than just replacing the Model.

Overrides:

onKeyEvent in class World

Returns:

World that needs to have the canvas and the event handlers initialized

onMouseClicked

public World onMouseClicked(Posn mouse)

User shouldn't need to use or override this method, unless you're doing something with the World more complicated than just replacing the Model.

Overrides:

onMouseClicked in class World

Parameters:

mouse - the location of the mouse when clicked

Returns:

World after the mouse event

onMouseDragged

public World onMouseDragged(Posn mouse)

User shouldn't need to use or override this method, unless you're doing something with the World more complicated than just replacing the Model.

Overrides:

onMouseDragged in class World

Parameters:

mouse - the location of the mouse when moved

Returns:

World after the mouse event

onMouseEntered

public World onMouseEntered(Posn mouse)

User shouldn't need to use or override this method, unless you're doing something with the World more complicated than just replacing the Model.

Overrides:

onMouseEntered in class World

Parameters:

mouse - the location of the mouse when entered

Returns:

World after the mouse event

onMouseExited

public World onMouseExited(Posn mouse)

User shouldn't need to use or override this method, unless you're doing something with the World more complicated than just replacing the Model.

Overrides:

onMouseExited in class World

Parameters:

mouse - the location of the mouse when exited

Returns:

World after the mouse event

onMouseMoved

public World onMouseMoved(Posn mouse)

User shouldn't need to use or override this method, unless you're doing something with the World more complicated than just replacing the Model.

Overrides:

onMouseMoved in class World

Parameters:

mouse - the location of the mouse when moved

Returns:

World after the mouse event

onMousePressed

public World onMousePressed(Posn mouse)

User shouldn't need to use or override this method, unless you're doing something with the World more complicated than just replacing the Model.

Overrides:

onMousePressed in class World

Parameters:

mouse - the location of the mouse when pressed

Returns:

World after the mouse event

See Also:

World.onMousePressed()

onMouseReleased

public World onMouseReleased(Posn mouse)

User shouldn't need to use or override this method, unless you're doing something with the World more complicated than just replacing the Model.

Overrides:

onMouseReleased in class World

Parameters:

mouse - the location of the mouse when released

Returns:

World after the mouse event

See Also:

World.onMouseReleased()

onTick

public World onTick()

User shouldn't need to use or override this method, unless you're doing something with the World more complicated than just replacing the Model.

Overrides:

onTick in class World

Returns:

World that needs to have the canvas and the event handlers initialized

worldEnds

public WorldEnd worldEnds()

User shouldn't need to use or override this method.

Overrides:

worldEnds in class World

Returns:

pair (true, last image) or (false, any image)

worldEnds

public WorldEnd worldEnds(Model oldModel)

Decide whether the animation should end yet, and if so, what the final window should look like. This method is called automatically after every (tick, mouse, or key) event, so if you want to end the world as soon as the model has a particular property, worldEnds is the way to do it. You'll probably never call this method, except for unit-testing, but you may well want to override it. If you don't, the default handler says "no, don't end the world."

Parameters:

oldModel - the current model

Returns:

a WorldEnd object, which comprises a boolean, telling whether the animation should end, and a WorldImage to use as the final contents of the animation window.