/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 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; } }