sim.display
Interface Controller

All Known Implementing Classes:
Console, SimpleController

public interface Controller

A Controller is the top-level object responsible for setting up and running the GUIState. More or less, the Controller calls the init, start, step, finish, and quit methods on the GUIState. The Controller also provides a window management facility. The controller allows the GUIState to register windows to appear in a list to the user and to be closed properly when the program is quit. The controller also manages a repository of current inspectors. Both of these facilities are optional. Subclasses are not required to implement all these methods; they can stub some out except for doChangeCode(...).


Method Summary
 void doChangeCode(java.lang.Runnable r)
          Deprecated.  
 java.util.ArrayList getAllFrames()
          Returns all registered frames.
 java.util.ArrayList getAllInspectors()
          Returns a list of all current inspectors.
 void refresh()
          Lazily updates and redraws all the displays and inspectors.
 boolean registerFrame(javax.swing.JFrame frame)
          Simulations can call this to add a frame to be listed in the "Display list" of the Controller.
 void registerInspector(Inspector inspector, Stoppable stopper)
          Registers an inspector to be refreshed as appropriate and stopped when the model is restarted.
 void setInspectors(Bag inspectors, Bag names)
          Replaces current inspectors with the ones provided.
 boolean unregisterAllFrames()
          Simulations can call this to clear out the "Display list" of the Controller.
 boolean unregisterFrame(javax.swing.JFrame frame)
          Simulations can call this to remove a frame from the "Display list" of the Controller.
 

Method Detail

doChangeCode

void doChangeCode(java.lang.Runnable r)
Deprecated. 

This method will interrupt the simulation (pause it), call your runnable, then continue (uninterrupt) the simulation. This allows you to guarantee a way to change the model from a separate thread -- for example, the Swing event thread -- in a synchronous, blocking fashion.

You have other options for updating the model from external threads. One option is to add a Steppable to GUIState's scheduleImmediate(...) queue. When the Steppable is stepped, it will be done so inside the model's thread. This is asynchronous (non-blocking), however.

Alternatively, you can synchronize on state.schedule and run your code. This is synchronous.


registerFrame

boolean registerFrame(javax.swing.JFrame frame)
Simulations can call this to add a frame to be listed in the "Display list" of the Controller. If the Controller does not have such a list, FALSE is returned.


unregisterFrame

boolean unregisterFrame(javax.swing.JFrame frame)
Simulations can call this to remove a frame from the "Display list" of the Controller. If the Controller does not have such a list, FALSE is returned.


unregisterAllFrames

boolean unregisterAllFrames()
Simulations can call this to clear out the "Display list" of the Controller. If the Controller does not have such a list, FALSE is returned.


getAllFrames

java.util.ArrayList getAllFrames()
Returns all registered frames.


refresh

void refresh()
Lazily updates and redraws all the displays and inspectors. Do not call this method from the model thread -- only from the Swing event thread. This is an expensive procedure and should not be done unless necessary. Typically it's done in response to some event (a button press etc.) rather than in the model itself.


setInspectors

void setInspectors(Bag inspectors,
                   Bag names)
Replaces current inspectors with the ones provided. The names bag should provide short, unique textual names appropriate for each inspector in the inspectors bag. Automatically registers the inspectors with registerInspector(...) as well.


registerInspector

void registerInspector(Inspector inspector,
                       Stoppable stopper)
Registers an inspector to be refreshed as appropriate and stopped when the model is restarted. Does not necessarily add the inspector to a list of inspectors like setInspectors(...) does.


getAllInspectors

java.util.ArrayList getAllInspectors()
Returns a list of all current inspectors. Some of these inspectors may be stored in the Controller itself, and others may have been dragged out into their own JFrames. You will need to distinguish between these two on your own. Note that some of these inspectors are stored as weak keys in the Controller, so holding onto this list will prevent them from getting garbage collected. As a result, you should only use this list for temporary scans.