sim.display
Class GUIState

java.lang.Object
  extended bysim.display.GUIState

public abstract class GUIState
extends java.lang.Object

A wrapper for SimState and Schedule which provides additional functionality for GUI objects. This wrapper extends the functionality of SimState and Schedule through encapsulation, NOT subclassing. Why? Because the general idea is that SimState, and *anything* which hangs off of it, should be serializable out to a checkpoint and not know or care about whether or not it's running under a GUI or running headless.

Displays and Controllers (such as Display2D and the Console) do not care about the SimState, and make precious few calls to the Schedule. Instead, they generally only work with you through the GUIState class.

GUIState has the same start() and finish() methods as SimState, and indeed the default forms of these methods just call start() and finish() on the underlying SimState. Additionally, GUIState has init(Controller) and quit() methods. The init(Controller) method sets up the GUIState to work in an environment controlled by the specified Controller. The quit() method is called to tell the GUIState to shut down and free any of its resources (perhaps the simulation document is being closed in the GUI, or the GUI is quitting).

GUIState also has two methods used by the Controller to specify things about it. In particular, getName() should return an intelligent name for the simulation, and getInfo() should return an HTML description of the simulation.

You can create a global inspector for your model (as opposed to the individual per-object inspectors created by various portrayals). This is done by overriding either getInspector() or getSimulationInspectedObject(). Additionally, override isInspectorVolatile() if your global inspector doesn't have to be constantly, and inefficiently, updated to reflect new model information (perhaps it's just for setting initial values etcc.)

GUIState has a wrapper step() method which in turn calls the Schedule's step(state) method. However, this wrapper provides a hook for objects such as displays to schedule themselves without using the Schedule. This hook is the scheduleImmediate(...) and scheduleImmediateRepeat(...) methods. There is also a reset() method which resets both the immediates and the underlying Schedule.

Last, GUIState has a wrapper function to make it convenient to read in a new SimState from a serialized file: readNewStateFromCheckpoint(). This function checks to see if the serialized file is valid for this simulation. To do this, it calls validSimState(), which is a hook that you should override to return TRUE if the provided state is a valid SimState for your simulation (usually this means that it's the right subclass of SimState for your purposes).

Generally speaking, if you have access to a GUIState, you should use GUIstate methods start(), finish(), step(), reset(), and readNewStateFromCheckpoint() instead of the underlying methods in the SimState and Controller. Otherwise, feel free to use the underlying methods (such as Schedule.time()).


Field Summary
protected  Steppable[] after
           
protected  int afterSize
           
protected  Steppable[] before
           
protected  int beforeSize
           
 Controller controller
          The controller for the GUIState.
protected  Steppable[] finish
           
protected  int finishSize
           
protected  Steppable[] start
           
protected  int startSize
           
 SimState state
          The underlying SimState
 
Constructor Summary
protected GUIState(SimState state)
          You may optionally override this constructor to call super(state) but you should be sure to override the no-argument GUIState() constructor as stipulated.
 
Method Summary
 void finish()
          Called either at the proper or a premature end to the simulation.
 java.lang.String getInfo()
          Returns an HTML string which gives descriptive information about the system.
 Inspector getInspector()
          Returns an Inspector which allows the user to manipulate global model features, or null if no such Inspector is desired.
 java.lang.String getName()
          Name of the simulation.
 java.lang.Object getSimulationInspectedObject()
          Returns an object with various property methods (getFoo(...), isFoo(...), setFoo(...)) whose properties will be accessible by the user.
protected  Steppable[] increaseSubsteps(Steppable[] substeps)
          Roughly doubles the array size, retaining the existing elements
 void init(Controller controller)
          Called to initialize (display) windows etc.
 boolean isInspectorVolatile()
          Returns true if the inspector (if any) provided in getInspector() or via getSimulationInspectedObject() should be updated at each time tick (as opposed to updated only when the window needs repainting).
 void load(SimState state)
          Called by the Console when the user is loading in a new state from a checkpoint.
 void quit()
          Called by the Console when the user is quitting the SimState.
 boolean readNewStateFromCheckpoint(java.io.File file)
          Loads a new SimState from the provided file.
 void reset(SimState state)
          Empties out the schedule and resets it to a pristine state BEFORE_SIMULATION.
protected  void resetQueues()
          Don't call this unless you know what you're doing.
 boolean scheduleAtExtreme(Steppable event, boolean atEnd)
          Schedules an item to occur when the user starts or stops the simulator, or when it stops on its own accord.
 boolean scheduleImmediate(boolean immediatelyAfter, Steppable event)
          Schedules an item to occur (in no particular order) immediately before or immediately after the schedule is stepped on the next time step (not including blank steps).
 Stoppable scheduleImmediateRepeat(boolean immediatelyAfter, Steppable event)
          Schedules an item to occur (in no particular order) immediately before or immediately after all future steps the Schedule takes (not including blank steps).
 void start()
          Called immediately prior to starting the simulation, or in-between simulation runs.
 boolean step()
          Returns FALSE if nothing was stepped -- the schedule is exhausted or time has run out.
 boolean validSimState(SimState state)
          This method should be set to return TRUE if state can be validly used -- mostly likely all you need to check is that it's the right class for this simulation.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

state

public SimState state
The underlying SimState


controller

public Controller controller
The controller for the GUIState. This field may be null if there is no controller or no controller YET


before

protected Steppable[] before

beforeSize

protected int beforeSize

after

protected Steppable[] after

afterSize

protected int afterSize

start

protected Steppable[] start

startSize

protected int startSize

finish

protected Steppable[] finish

finishSize

protected int finishSize
Constructor Detail

GUIState

protected GUIState(SimState state)
You may optionally override this constructor to call super(state) but you should be sure to override the no-argument GUIState() constructor as stipulated.

Method Detail

getName

public java.lang.String getName()
Name of the simulation. Override this to make a nicer name than "foo.bar.baz.Quux Simulation"


getInfo

public java.lang.String getInfo()
Returns an HTML string which gives descriptive information about the system. Override this as you see fit.


getInspector

public Inspector getInspector()
Returns an Inspector which allows the user to manipulate global model features, or null if no such Inspector is desired. The default returns an inspector which wraps around getSimulationInspectedObject(); if getSimulationInspectedObject() returns null, then getInspector() will return null also. Override this as you see fit.


getSimulationInspectedObject

public java.lang.Object getSimulationInspectedObject()
Returns an object with various property methods (getFoo(...), isFoo(...), setFoo(...)) whose properties will be accessible by the user. This gives you an easy way to allow the user to set certain global properties of your model from the GUI. If null is returned (the default), then nothing will be displayed to the user. One trick you should know about your object: it should be public, as well its property methods, and if it's anonymous, it should not introduce any property methods not defined in its superclass. Otherwise Java's reflection API can't access those methods -- they're considered private.


isInspectorVolatile

public boolean isInspectorVolatile()
Returns true if the inspector (if any) provided in getInspector() or via getSimulationInspectedObject() should be updated at each time tick (as opposed to updated only when the window needs repainting). This is important because constant repaints are expensive. By default, this method returns FALSE, which means that the inspector's updateInspector() method is called only when start() was called initially. You should override this to return TRUE if your inspector needs be updated on each schedule tick.


init

public void init(Controller controller)
Called to initialize (display) windows etc. You can use this to set up the windows, then register them with the Controller so it can manage hiding, showing, and moving them. The default version of this method simply calls this.controller=controller;


start

public void start()
Called immediately prior to starting the simulation, or in-between simulation runs. Ordinarily, you wouldn't need to override this hook.


finish

public void finish()
Called either at the proper or a premature end to the simulation. If the user quits the program, this function may not be called. Ordinarily, you wouldn't need to override this hook.


quit

public void quit()
Called by the Console when the user is quitting the SimState. A good place to stick stuff that you'd ordinarily put in a finalizer -- finalizers are tenuous at best. So here you'd put things like the code that closes the relevant display windows etc.


validSimState

public boolean validSimState(SimState state)
This method should be set to return TRUE if state can be validly used -- mostly likely all you need to check is that it's the right class for this simulation. The default returns TRUE if state is non-null and the same class as the current state; that's often sufficient.


load

public void load(SimState state)
Called by the Console when the user is loading in a new state from a checkpoint. The new state is passed in as an argument. The default version simply sets this.state to the new state. You should override this, calling super.load(state) first, to reset your portrayals etc. to reflect the new state. state.start() will NOT be called. Thus anything you handled in start() that needs to be reset to accommodate the new state should be handled here. We recommend that you call repaint() on any Display2Ds.


readNewStateFromCheckpoint

public boolean readNewStateFromCheckpoint(java.io.File file)
                                   throws java.io.IOException,
                                          java.lang.ClassNotFoundException,
                                          java.io.OptionalDataException,
                                          java.lang.ClassCastException,
                                          java.lang.Exception
Loads a new SimState from the provided file. Do not call this in an unthreadsafe situation -- it doesn't check. Returns false if the state was not valid. Returns various errors if bad things occurred trying to serialize in from the checkpoint. If false is returned or an error is thrown, the old SimState is retained.

Throws:
java.io.IOException
java.lang.ClassNotFoundException
java.io.OptionalDataException
java.lang.ClassCastException
java.lang.Exception

resetQueues

protected void resetQueues()
Don't call this unless you know what you're doing.


reset

public final void reset(SimState state)
Empties out the schedule and resets it to a pristine state BEFORE_SIMULATION. If you're using a GUIState, you should call this version instead of Schedule's version.


step

public boolean step()
Returns FALSE if nothing was stepped -- the schedule is exhausted or time has run out.


increaseSubsteps

protected Steppable[] increaseSubsteps(Steppable[] substeps)
Roughly doubles the array size, retaining the existing elements


scheduleImmediate

public boolean scheduleImmediate(boolean immediatelyAfter,
                                 Steppable event)
Schedules an item to occur (in no particular order) immediately before or immediately after the schedule is stepped on the next time step (not including blank steps). Pass in FALSE to indicate you want to be immediately BEFORE the next timestep; pass in TRUE if you want to be immediately AFTER the next time step (the more common situation). Returns false if the current time is AFTER_SIMULATION or if the event is null.

Why would you use this method? Primarily to get things scheduled which aren't stored in the Schedule itself, so it can be serialized out without them.


scheduleImmediateRepeat

public Stoppable scheduleImmediateRepeat(boolean immediatelyAfter,
                                         Steppable event)
Schedules an item to occur (in no particular order) immediately before or immediately after all future steps the Schedule takes (not including blank steps). Pass in FALSE to indicate you want to be immediately BEFORE the next timestep; pass in TRUE if you want to be immediately AFTER the next time step (the more common situation). Returns a Stoppable, or null if the current time is AFTER_SIMULATION or if the event is null.

Why would you use this method? Primarily to get things scheduled which aren't stored in the Schedule itself, so it can be serialized out without them.


scheduleAtExtreme

public boolean scheduleAtExtreme(Steppable event,
                                 boolean atEnd)
Schedules an item to occur when the user starts or stops the simulator, or when it stops on its own accord. If atEnd is TRUE, then the item is scheduled to occur when the finish() method is executed. If atEnd is FALSE, then the item is scheduled to occur when the start() method is executed.