/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* *
* JavaWorld Library, Copyright 2011 Bryan Chadwick *
* *
* FILE: ./universe/world/VoidWorld.java *
* *
* This file is part of JavaWorld. *
* *
* JavaWorld is free software: you can redistribute it and/or *
* modify it under the terms of the GNU General Public License *
* as published by the Free Software Foundation, either version *
* 3 of the License, or (at your option) any later version. *
* *
* JavaWorld is distributed in the hope that it will be useful, *
* but WITHOUT ANY WARRANTY; without even the implied warranty of *
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
* GNU General Public License for more details. *
* *
* You should have received a copy of the GNU General Public License *
* along with JavaWorld. If not, see . *
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
package universe.world;
import java.io.Serializable;
import universe.VoidPackage;
import universe.Package;
import image.Scene;
/** A Class representing an imperative World and the related methods
* for drawing the world and handling various events connected to a
* {@link universe.Universe Universe}. The class is parameterized by
* the type of messages (which must extend
* {@link java.io.Serializable Serializable}) that are passed
* throughout the Universe.
*
*
In order to implement a functioning World you must
* extend this class, and implement an {@link
* universe.world.VoidWorld#onDraw onDraw} method. Other handler
* methods ({@link universe.world.VoidWorld#tickRate tickRate},
* {@link universe.world.VoidWorld#onTick onTick}, {@link
* universe.world.VoidWorld#onMouse onMouse}, {@link
* universe.world.VoidWorld#onKey onKey}, {@link
* universe.world.VoidWorld#onRelease onRelease}, {@link
* universe.world.VoidWorld#stopWhen stopWhen}, and {@link
* universe.world.VoidWorld#lastScene lastScene}) are optional, and
* can be overridden to add new functionality.
*
* Most handler methods return a {@link universe.VoidPackage
* VoidPackage}, which contains a possible message to the connected
* Universe. In order to interact with the
* Universe and other VoidWorld/Worlds,
* implementations must override the {@link
* universe.world.VoidWorld#onReceive onReceive} method that handles
* messages from the Universe.
*
*
* See also {@link world.VoidWorld world.VoidWorld} for similar documentation on individual methods.
*
*
*/
public abstract class VoidWorld{
/** Default Tick rate for the world: ~33 frames per second */
public static double DEFAULT_TICK_RATE = BigBang.DEFAULT_TICK_RATE;
/** Mouse down (button-down) event String */
public static String MOUSE_DOWN = BigBang.MOUSE_DOWN;
/** Mouse up (button-up) event String */
public static String MOUSE_UP = BigBang.MOUSE_UP;
/** Mouse window enter (enter) event String */
public static String MOUSE_ENTER = BigBang.MOUSE_ENTER;
/** Mouse window leave (leave) event String */
public static String MOUSE_LEAVE = BigBang.MOUSE_LEAVE;
/** Mouse motion (move) event String */
public static String MOUSE_MOVE = BigBang.MOUSE_MOVE;
/** Mouse down & move (drag) event String */
public static String MOUSE_DRAG = BigBang.MOUSE_DRAG;
/** Key arrow-up event String */
public static String KEY_ARROW_UP = BigBang.KEY_ARROW_UP;
/** Key arrow-down event String */
public static String KEY_ARROW_DOWN = BigBang.KEY_ARROW_RIGHT;
/** Key arrow-left event String */
public static String KEY_ARROW_LEFT = BigBang.KEY_ARROW_LEFT;
/** Key arrow-right event String */
public static String KEY_ARROW_RIGHT = BigBang.KEY_ARROW_RIGHT;
/** Return a visualization of this VoidWorld as a {@link image.Scene Scene}.
* See {@link image.EmptyScene}, {@link image.Scene#placeImage(Image, int, int)}, and
* {@link image.Scene#addLine(int, int, int, int, String)} for documentation on
* constructing Scenes */
public abstract Scene onDraw();
/** Return the tick rate for this VoidWorld 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. */
public double tickRate(){ return DEFAULT_TICK_RATE; }
/** Change this VoidWorld based on the Tick of the clock. This
* method is called the update the VoidWorld on each clock
* tick. */
public VoidPackage onTick(){
return new VoidPackage();
}
/** Change this VoidWorld (and produce a VoidPackage
* possibly containing a 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 VoidWorld window |
* "button-up" : |
* The user releases a mouse button in the VoidWorld window |
* "move" : |
* The user moves the mouse in the VoidWorld window |
* "drag" : |
* The user holds a mouse button and moves the mouse in the VoidWorld window |
* "enter" : |
* The user moves the mouse in-to the VoidWorld window |
* "leave" : |
* The user moves the mouse out-of the VoidWorld window |
*
*
*/
public VoidPackage onMouse(int x, int y, String me){
return new VoidPackage();
}
/** Change this VoidWorld (and produce a VoidPackage
* possibly containing a message) when a key event is
* triggered. The given event is a String that
* describes which key was pressed.
*
*
* Special Key
*
* "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.
*
*/
public VoidPackage onKey(String ke){
return new VoidPackage();
}
/** Change this VoidWorld (and produce a VoidPackage
* possibly containing a 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.
*
*/
public VoidPackage onRelease(String ke){
return new VoidPackage();
}
/** Change this VoidWorld (and produce a VoidPackage
* possibly containing a message) when a message from the universe
* is received. */
public VoidPackage onReceive(Msg msg){
return new VoidPackage();
}
/** Determine if the World/interaction/animation should be
* stopped. Returning a value of true
* discontinues all events (mouse, key, ticks) and causes {@link
* universe.world.VoidWorld#lastScene} to be used to draw the final
* Scene. */
public boolean stopWhen(){ return false; }
/** Returns the Scene that should be displayed when the
* interaction/animation completes ({@link universe.world.VoidWorld#stopWhen}
* returns true). */
public Scene lastScene(){ return this.onDraw(); }
/** Wraps a VoidWorld in a regular World to simplify event/message/handling */
private class WorldWrap extends World{
public Scene onDraw(){ return VoidWorld.this.onDraw(); }
public double tickRate(){ return VoidWorld.this.tickRate(); }
public Package onTick()
{ return new Package(this, VoidWorld.this.onTick().getMsg()); }
public Package onMouse(int x, int y, String me)
{ return new Package(this, VoidWorld.this.onMouse(x,y,me).getMsg()); }
public Package onKey(String ke)
{ return new Package(this, VoidWorld.this.onKey(ke).getMsg()); }
public Package onRelease(String ke)
{ return new Package(this, VoidWorld.this.onRelease(ke).getMsg()); }
public Package onReceive(Msg msg)
{ return new Package(this, VoidWorld.this.onReceive(msg).getMsg()); }
public boolean stopWhen(){ return VoidWorld.this.stopWhen(); }
public Scene lastScene(){ return VoidWorld.this.lastScene(); }
public boolean equals(Object o){ return false; }
}
/** 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. */
public VoidWorld bigBang(String server, String name){
new WorldWrap().bigBang(server, name);
return this;
}
/** 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. */
public VoidWorld bigBang(){
new WorldWrap().bigBang();
return this;
}
}