|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectsim.display.GUIState
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().
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. |
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()
By default returns a non-volatile Inspector r which wraps around getSimulationInspectedObject(); if getSimulationInspectedObject() returns null, then getInspector() will return null also. |
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()
Deprecated. |
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 |
scheduleAtEnd(Steppable event)
Schedules an item to occur when the user stops the simulator (when the stop() method is executed), when it stops on its own accord, or when the user has load()ed another simulation to replace it. |
boolean |
scheduleAtExtreme(Steppable event,
boolean atEnd)
Deprecated. use scheduleAtStart and scheduleAtEnd instead |
boolean |
scheduleAtStart(Steppable event)
Schedules an item to occur when the user starts the simulator (when the start() method is executed) or loads one (when load() is executed). |
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()
|
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 |
public SimState state
public Controller controller
protected Steppable[] before
protected int beforeSize
protected Steppable[] after
protected int afterSize
Constructor Detail |
protected GUIState(SimState state)
super(state)
but you should
be sure to override the no-argument GUIState() constructor as stipulated.
Method Detail |
public java.lang.String getName()
public java.lang.String getInfo()
public Inspector getInspector()
public java.lang.Object getSimulationInspectedObject()
public boolean isInspectorVolatile()
public void init(Controller controller)
public void start()
public void finish()
public void quit()
public boolean validSimState(SimState state)
public void load(SimState state)
public boolean readNewStateFromCheckpoint(java.io.File file) throws java.io.IOException, java.lang.ClassNotFoundException, java.io.OptionalDataException, java.lang.ClassCastException, java.lang.Exception
java.io.IOException
java.lang.ClassNotFoundException
java.io.OptionalDataException
java.lang.ClassCastException
java.lang.Exception
protected void resetQueues()
public final void reset(SimState state)
public boolean step()
protected Steppable[] increaseSubsteps(Steppable[] substeps)
public boolean scheduleImmediate(boolean immediatelyAfter, Steppable event)
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.
public Stoppable scheduleImmediateRepeat(boolean immediatelyAfter, Steppable event)
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.
public boolean scheduleAtExtreme(Steppable event, boolean atEnd)
public boolean scheduleAtStart(Steppable event)
public boolean scheduleAtEnd(Steppable event)
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |