universe.world
Class World<Msg extends java.io.Serializable>

java.lang.Object
  extended by universe.world.World<Msg>
Direct Known Subclasses:
FallingWorld, KeyMoveWorld, MousePointsWorld, RotatingLinesWorld, ShowKey

public abstract class World<Msg extends java.io.Serializable>
extends java.lang.Object

A Class representing a World and the related methods for drawing the world and handling various events connected to a Universe. The class is parameterized by the type of messages (which must extend Serializable) that are passed throughout the Universe.

In order to implement a functioning World you must extend this class, and implement an onDraw method. Other handler methods (tickRate, onTick, onMouse, onKey, onRelease, stopWhen, and lastScene) are optional, and can be overridden to add new functionality.

Most handler methods return a Package, which contains the updated World, and a possible message to the connected Universe. In order to interact with the Universe and other Worlds, implementations must override the onReceive method that handles messages from the Universe.

See also world.World for similar documentation on individual methods.

Extending World

Below is a simple example of a World that adds a new point at each mouse click. The world contains a Scene and a new Circle is placed for each "button-down" event received.
   
 import image.*;
 import universe.Package;
 import universe.world.*;
 
 // Mouse World/Universe point/click Test
 public class MousePointsWorld extends World<None>{
     public static void main(String[] s){
         new MousePointsWorld(new EmptyScene(400,400))
               .bigBang();
     }
     // The inner Scene
     Scene scene;
     // Create a new World with the given Scene
     MousePointsWorld(Scene scene){
         this.scene = scene;    
     }
     // Draw by returning the inner Scene
     public Scene onDraw(){ return this.scene; }
     // On a mouse click add a circle to the inner Scene
     public Package<None> onMouse(int x, int y, String me){
         if(!me.equals("button-down"))
             return new Package<None>(this);
         else
             return new Package<None>(
                     new MousePointsWorld(
                             this.scene.placeImage(new Circle(20, "solid","red")
                                       .overlay(new Circle(20, "outline", "blue")), x, y)));
     }
 }
 
After a few mouse clicks, the window will look something like this:


Field Summary
static double DEFAULT_TICK_RATE
          Default Tick rate for the world: ~33 frames per second
static java.lang.String KEY_ARROW_DOWN
          Key arrow-down event String
static java.lang.String KEY_ARROW_LEFT
          Key arrow-left event String
static java.lang.String KEY_ARROW_RIGHT
          Key arrow-right event String
static java.lang.String KEY_ARROW_UP
          Key arrow-up event String
static java.lang.String MOUSE_DOWN
          Mouse down (button-down) event String
static java.lang.String MOUSE_DRAG
          Mouse down & move (drag) event String
static java.lang.String MOUSE_ENTER
          Mouse window enter (enter) event String
static java.lang.String MOUSE_LEAVE
          Mouse window leave (leave) event String
static java.lang.String MOUSE_MOVE
          Mouse motion (move) event String
static java.lang.String MOUSE_UP
          Mouse up (button-up) event String
 
Constructor Summary
World()
           
 
Method Summary
 World<Msg> bigBang()
          Kick off the interaction/animation without connecting to the Universe.
 World<Msg> bigBang(java.lang.String server, java.lang.String name)
          Kick off the interaction/animation and connect to the given Universe server URL, under the given client name.
 Scene lastScene()
          Returns the Scene that should be displayed when the interaction/animation completes (stopWhen() returns true).
abstract  Scene onDraw()
          Return a visualization of this World as a Scene.
 Package<Msg> onKey(java.lang.String ke)
          Produce a Package, containing a (possibly) new World and a possible Message, when a key is pressed.
 Package<Msg> onMouse(int x, int y, java.lang.String me)
          Produce a Package, containing a (possibly) new World and a possible Message, when a mouse event is triggered.
 Package<Msg> onReceive(Msg msg)
          Produce a Package, containing a (possibly) new World and a possible Message, when a message from the universe is received.
 Package<Msg> onRelease(java.lang.String ke)
          Produce a Package, containing a (possibly) new World and a possible Message, when a key is released.
 Package<Msg> onTick()
          Produce a Package, containing a (possibly) new World and a possible Message, based on the Tick of the clock.
 boolean stopWhen()
          Determine if the World/interaction/animation should be stopped.
 double tickRate()
          Return the tick rate for this World in seconds.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_TICK_RATE

public static double DEFAULT_TICK_RATE
Default Tick rate for the world: ~33 frames per second


MOUSE_DOWN

public static java.lang.String MOUSE_DOWN
Mouse down (button-down) event String


MOUSE_UP

public static java.lang.String MOUSE_UP
Mouse up (button-up) event String


MOUSE_ENTER

public static java.lang.String MOUSE_ENTER
Mouse window enter (enter) event String


MOUSE_LEAVE

public static java.lang.String MOUSE_LEAVE
Mouse window leave (leave) event String


MOUSE_MOVE

public static java.lang.String MOUSE_MOVE
Mouse motion (move) event String


MOUSE_DRAG

public static java.lang.String MOUSE_DRAG
Mouse down & move (drag) event String


KEY_ARROW_UP

public static java.lang.String KEY_ARROW_UP
Key arrow-up event String


KEY_ARROW_DOWN

public static java.lang.String KEY_ARROW_DOWN
Key arrow-down event String


KEY_ARROW_LEFT

public static java.lang.String KEY_ARROW_LEFT
Key arrow-left event String


KEY_ARROW_RIGHT

public static java.lang.String KEY_ARROW_RIGHT
Key arrow-right event String

Constructor Detail

World

public World()
Method Detail

onDraw

public abstract Scene onDraw()
Return a visualization of this World as a Scene. See EmptyScene, Scene.placeImage(Image, int, int), and Scene.addLine(int, int, int, int, String) for documentation on constructing Scenes


tickRate

public double tickRate()
Return the tick rate for this World in seconds. For example, 0.5 means two ticks per second. The rate is only accessed when bigBang() is initially called and the window is created.


onTick

public Package<Msg> onTick()
Produce a Package, containing a (possibly) new World and a possible Message, based on the Tick of the clock. This method is called to get the next world on each clock tick.


onMouse

public Package<Msg> onMouse(int x,
                            int y,
                            java.lang.String me)
Produce a Package, containing a (possibly) new World and a possible Message, when a mouse event is triggered. x and y are the location of the event in the window, and event is a String that describes what kind of event occurred.

Possible Mouse Events

"button-down" : The user presses a mouse button in the World window
"button-up" : The user releases a mouse button in the World window
"move" : The user moves the mouse in the World window
"drag" : The user holds a mouse button and moves the mouse in the World window
"enter" : The user moves the mouse in-to the World window
"leave" : The user moves the mouse out-of the World window


onKey

public Package<Msg> onKey(java.lang.String ke)
Produce a Package, containing a (possibly) new World and a possible Message, when a key is pressed. The given event is a String that describes what key was pressed.

Special Keys

"up" : The user presses the up-arrow key
"down" : The user presses the down-arrow key
"left" : The user presses the left-arrow key
"right" : The user presses the right-arrow key
Other keys generate a single character String that represents the key pressed. For example, Pressing the B key on the keyboard generates "b" as an event. If the shift key is held while pressing B then "B" is generated.


onRelease

public Package<Msg> onRelease(java.lang.String ke)
Produce a Package, containing a (possibly) new World and a possible Message, when a key is released. The given event is a String that describes which key was released.

Special Keys

"up" : The user presses the up-arrow key
"down" : The user presses the down-arrow key
"left" : The user presses the left-arrow key
"right" : The user presses the right-arrow key
Other keys generate a single character String that represents the key released. For example, Pressing then releasing the B key on the keyboard generates "b" as an onKey event and again as an onRelease event. If the shift key is held while pressing/releasing B then "B" is generated.


onReceive

public Package<Msg> onReceive(Msg msg)
Produce a Package, containing a (possibly) new World and a possible Message, when a message from the universe is received.


stopWhen

public boolean stopWhen()
Determine if the World/interaction/animation should be stopped. Returning a value of true discontinues all events (mouse, key, ticks, messages) and causes lastScene() to be used to draw the final Scene.


lastScene

public Scene lastScene()
Returns the Scene that should be displayed when the interaction/animation completes (stopWhen() returns true).


bigBang

public World<Msg> bigBang(java.lang.String server,
                          java.lang.String name)
Kick off the interaction/animation and connect to the given Universe server URL, under the given client name. This method returns the final state of the world after the user closes the World window.


bigBang

public World<Msg> bigBang()
Kick off the interaction/animation without connecting to the Universe. This method returns the final state of the world after the user closes the World window. The Universe is not contacted, but the client is run locally