/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * JavaWorld Library, Copyright 2011 Bryan Chadwick * * * * FILE: ./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 world; import image.Scene; /** * * * A Class representing an imperative World and the related methods * for drawing the world and handling various events. In order to * implement a functioning World you must extend this class, * and implement an {@link world.VoidWorld#onDraw onDraw} method. * Other handler methods ({@link world.VoidWorld#tickRate tickRate}, * {@link world.VoidWorld#onTick onTick}, {@link * world.VoidWorld#onMouse onMouse}, {@link world.VoidWorld#onKey * onKey}, {@link world.VoidWorld#onRelease onRelease}, {@link * world.VoidWorld#stopWhen stopWhen}, and {@link * world.VoidWorld#lastScene lastScene}) are optional, and can be * overridden to add new functionality.

See the individual * methods for detailed documentation.

* *

*

Extending VoidWorld

*
* Below is a simple example of a VoidWorld that adds a * new point at each mouse click. The world contains a {@link * image.Scene Scene} and a new {@link image.Circle Circle} is placed * for each "button-down" event received. * * 
   
 *        import image.*;
 *        import world.VoidWorld;
 *        
 *        public class MousePointsVoidWorld extends VoidWorld{
 *            // Simple Main Program
 *            public static void main(String[] args)
 *            { new MousePointsVoidWorld().bigBang(); }
 *            
 *            // The inner Scene
 *            Scene scene = new EmptyScene(200, 200);
 *        
 *            // Create a new World
 *            MousePointsVoidWorld(){}
 *            
 *            // Draw by returning the inner Scene
 *            public Scene onDraw(){ return this.scene; }
 *        
 *            // On a mouse click add a circle to the inner Scene
 *            public void onMouse(int x, int y, String me){
 *                if(me.equals("button-down")){
 *                    this.scene = this.scene.placeImage(
 *                                     new Circle(20, "solid", "red")
 *                                           .overlay(new Circle(20, "outline", "black")), x, y);
 *                }
 *            }
 *        }
 *
* * After a few mouse clicks, the window will look something like this:

* * *
*

*/ 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 to update the VoidWorld on each clock tick. */ public void onTick(){ } /** Change this VoidWorld 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 void onMouse(int x, int y, String event){ } /** Change this VoidWorld 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 void onKey(String event){ } /** Change this VoidWorld 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 void onRelease(String event){ } /** Determine if the World/interaction/animation should be * stopped. Returning a value of true * discontinues all events (mouse, key, ticks) and causes {@link * 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 world.VoidWorld#stopWhen} * returns true). */ public Scene lastScene(){ return this.onDraw(); } /** Kick off the interaction/animation. This method returns the final * state of the world after the user closes the World window. */ public VoidWorld bigBang(){ return (VoidWorld)new BigBang(this) .onDraw(new WorldDraw()) .onTick(new WorldTick(), tickRate()) .onMouse(new WorldMouse()) .onKey(new WorldKey()) .onRelease(new WorldRelease()) .stopWhen(new WorldStop()) .lastScene(new WorldLast()) .bigBang("VoidWorld"); } /** Wrapper for OnDraw callback */ private static class WorldDraw{ @SuppressWarnings("unused") Scene apply(VoidWorld w){ return w.onDraw(); } } /** Wrapper for OnTick callback */ private static class WorldTick{ @SuppressWarnings("unused") VoidWorld apply(VoidWorld w){ w.onTick(); return w; } } /** Wrapper for OnMouse callback */ private static class WorldMouse{ @SuppressWarnings("unused") VoidWorld apply(VoidWorld w, int x, int y, String me) { w.onMouse(x,y,me); return w; } } /** Wrapper for OnKey callback */ private static class WorldKey{ @SuppressWarnings("unused") VoidWorld apply(VoidWorld w, String ke){ w.onKey(ke); return w; } } /** Wrapper for OnKey callback */ private static class WorldRelease{ @SuppressWarnings("unused") VoidWorld apply(VoidWorld w, String ke){ w.onRelease(ke); return w; } } /** Wrapper for StopWhen callback */ private static class WorldStop{ @SuppressWarnings("unused") boolean apply(VoidWorld w){ return w.stopWhen(); } } /** Wrapper for LastScene callback */ private static class WorldLast{ @SuppressWarnings("unused") Scene apply(VoidWorld w){ return w.lastScene(); } } /** Make sure that changes are redrawn every time */ public boolean equals(Object o){ return false; } }