## org.ascape.model.event
Class DefaultScapeListener

    java.lang.Object
      org.ascape.model.event.DefaultScapeListener

All Implemented Interfaces:
  java.io.Serializable, java.lang.Cloneable, java.util.EventListener, ScapeListener, HasName

Direct Known Subclasses:
  ModelScapeView, ModelWrapperScapeListener, NonGraphicView, Query, RuntimeEnvironment, ScapeListenerDelegate, ScapeTransitionListener

    public abstract class DefaultScapeListener

extends java.lang.Object
implements ScapeListener, java.io.Serializable

A listener to an agent scape. When a scape is updated, it is the listener's responsility to update itself, and then inform the scape that updating is finished, so that the scape can continue iterating through its rules. DefaultScapeListener provides a good reference implementation of the listener contract. By default, this is assumed to be a nongrphic view. Overide isGraphic to return true if you are implementing a graphic view.

Since:
  1.0
Version:
  2.9.1
Author:
  Miles Parker
See Also:
  Serialized Form

Field Summary
`protected boolean` `listeningToScape` Is this scape view delegate currently listening to a scape? Seperated from wether scape is null, becuase we want to be able to save old scape.
`protected java.lang.String` `name` The name of the view.
`Scape` `scape` The scape being listened to.

Constructor Summary
`DefaultScapeListener()` Constructs a default listener.
`DefaultScapeListener(java.lang.String name)` Constructs a default listener.

Method Summary
`java.lang.Object` `clone()` Clones this object.
`void` `environmentQuiting(ScapeEvent scapeEvent)` Method called as the scape is about to be closed.
`java.lang.String` `getName()` Returns a name for the view as defined by set name.
`Scape` `getScape()` Returns the scape the listner is listening to.
`boolean` `isGraphic()` Is this a grpahic view? By default, returns false.
`boolean` `isLifeOfScape()` Returns true (default) if the listener is intended to be used only for the current scape; typical of all but control related listeners.
`boolean` `isNotifyScapeAutomatically()` Should the scape be notified automatically? Default is true.
`void` `notifyScapeUpdated()` Calls the observed scape and notifies it that the view has finished updating its state.
`void` `scapeAdded(ScapeEvent scapeEvent)` Add the view to the scape, registering it as a listener, and ensuring that it hasn't been added to any other scapes.
`void` `scapeClosing(ScapeEvent scapeEvent)` Method called as the scape is about to be closed.
`void` `scapeDeserialized(ScapeEvent scapeEvent)` Method called immediatly after a model is deserialized.
`void` `scapeInitialized(ScapeEvent scapeEvent)` Called immediatly after the scape is initialized.
`void` `scapeIterated(ScapeEvent scapeEvent)` Called immediatly after scape is iterated.
`void` `scapeNotification(ScapeEvent scapeEvent)` Notifies the delegating view that something has happened on the scape.
`void` `scapeRemoved(ScapeEvent scapeEvent)` Notifies the listener that the scape has removed it.
`void` `scapeSetup(ScapeEvent scapeEvent)` Method called when the scape is ready for setup.
`void` `scapeStarted(ScapeEvent scapeEvent)` Called immediatly after the scape is started.
`void` `scapeStopped(ScapeEvent scapeEvent)` Called immediatly after the scape is stopped.
`void` `setName(java.lang.String name)` Sets the name of this view.
`void` `setNotifyScapeAutomatically(boolean notifyScapeAutomatically)` Sets wether the scape is notified automatically.
`java.lang.String` `toString()` Returns a short description of this view.

Methods inherited from class java.lang.Object
`equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Field Detail

### scape

    public Scape scape

  The scape being listened to.

### listeningToScape

    protected boolean listeningToScape

  Is this scape view delegate currently listening to a scape? Seperated from wether scape is null, becuase we want to be able to save old scape.

### name

    protected java.lang.String name

  The name of the view.

Constructor Detail

### DefaultScapeListener

    public DefaultScapeListener()

  Constructs a default listener.

### DefaultScapeListener

    public DefaultScapeListener(java.lang.String name)

  Constructs a default listener.

  Parameters:
    `name` - a user relevant name for this view

Method Detail

### scapeInitialized

    public void scapeInitialized(ScapeEvent scapeEvent)

  Called immediatly after the scape is initialized.

  Specified by:
    `scapeInitialized` in interface `ScapeListener`
  Parameters:
    `scapeEvent` - the scape event

### scapeStarted

    public void scapeStarted(ScapeEvent scapeEvent)

  Called immediatly after the scape is started.

  Specified by:
    `scapeStarted` in interface `ScapeListener`
  Parameters:
    `scapeEvent` - the scape event

### scapeStopped

    public void scapeStopped(ScapeEvent scapeEvent)

  Called immediatly after the scape is stopped.

  Specified by:
    `scapeStopped` in interface `ScapeListener`
  Parameters:
    `scapeEvent` - the scape event

### scapeIterated

    public void scapeIterated(ScapeEvent scapeEvent)

  Called immediatly after scape is iterated.

  Specified by:
    `scapeIterated` in interface `ScapeListener`
  Parameters:
    `scapeEvent` - the scape event

### scapeSetup

    public void scapeSetup(ScapeEvent scapeEvent)

  Method called when the scape is ready for setup. That is, the scape has been created (or it has just finished its previous run) but it has not yet been initialized. This is an appropriate place to change model paramters, persent user's with options, etc.

  Specified by:
    `scapeSetup` in interface `ScapeListener`
  Parameters:
    `scapeEvent` - the scape event

### scapeClosing

    public void scapeClosing(ScapeEvent scapeEvent)

  Method called as the scape is about to be closed. Allows any final view cleanup.

  Specified by:
    `scapeClosing` in interface `ScapeListener`
  Parameters:
    `scapeEvent` - the scape event

### environmentQuiting

    public void environmentQuiting(ScapeEvent scapeEvent)

  Method called as the scape is about to be closed. Allows any final view cleanup.

  Specified by:
    `environmentQuiting` in interface `ScapeListener`
  Parameters:
    `scapeEvent` - the scape event

### scapeDeserialized

    public void scapeDeserialized(ScapeEvent scapeEvent)

  Method called immediatly after a model is deserialized.

  Specified by:
    `scapeDeserialized` in interface `ScapeListener`
  Parameters:
    `scapeEvent` - the scape event

### scapeAdded

    public void scapeAdded(ScapeEvent scapeEvent)
                    throws java.util.TooManyListenersException

  Add the view to the scape, registering it as a listener, and ensuring that it hasn't been added to any other scapes.

  Specified by:
    `scapeAdded` in interface `ScapeListener`
  Parameters:
    `scapeEvent` - the event for this scape to make this view the observer of
  Throws:
    `java.util.TooManyListenersException` - the too many listeners exception
    `java.util.TooManyListenersException` - on attempt to add a scape when one is allready added

### scapeRemoved

    public void scapeRemoved(ScapeEvent scapeEvent)

  Notifies the listener that the scape has removed it. The scape event event must be from the scape that this listener is listening to.

  Specified by:
    `scapeRemoved` in interface `ScapeListener`
  Parameters:
    `scapeEvent` - the scape removed notification event
  See Also:
    `scapeAdded`

### scapeNotification

    public void scapeNotification(ScapeEvent scapeEvent)

  Notifies the delegating view that something has happened on the scape. Calls the scapeIterated, setup, started, stoped, closing, or onDeserialized methods as appropriate. Calls notifyScapeUpdated, so you will need to overide this method if you do not want to notify the scape immediatly upon the scape... methods returning.

  Specified by:
    `scapeNotification` in interface `ScapeListener`
  Parameters:
    `scapeEvent` - a scape event update

### notifyScapeUpdated

    public void notifyScapeUpdated()

  Calls the observed scape and notifies it that the view has finished updating its state. This method must be called after receiving any scapeNotification event or the model will stall.

### isGraphic

    public boolean isGraphic()

  Is this a grpahic view? By default, returns false. Overide to return true if this is a graphic view.

  Specified by:
    `isGraphic` in interface `ScapeListener`
  Returns:
    true, if is graphic

### isLifeOfScape

    public boolean isLifeOfScape()

  Returns true (default) if the listener is intended to be used only for the current scape; typical of all but control related listeners.

  Specified by:
    `isLifeOfScape` in interface `ScapeListener`
  Returns:
    true, if is life of scape

### getScape

    public Scape getScape()

  Returns the scape the listner is listening to.

  Specified by:
    `getScape` in interface `ScapeListener`
  Returns:
    the scape

### isNotifyScapeAutomatically

    public boolean isNotifyScapeAutomatically()

  Should the scape be notified automatically? Default is true.

  Returns:
    true, if is notify scape automatically

### setNotifyScapeAutomatically

    public void setNotifyScapeAutomatically(boolean notifyScapeAutomatically)

  Sets wether the scape is notified automatically. That is, when the listener methods finish, should the scape be notified? Normally this should be true - anytime everything needed to update from the current scape state is known when the methods exit. But in some cases the sacape should not continue iterating until something else happens. The most obvious example is in a graphics view, where we need to be sure that the actual graphics are updated before the scape moves on. But other cases where you might want to wait might also happen; for example, you may want to wait for some other state to change first, you may need to wait for a process (like a database write) to occur in another thread, etc.

  Parameters:
    `notifyScapeAutomatically` - true to send a respond update event back immediatly, false to wait

### getName

    public java.lang.String getName()

  Returns a name for the view as defined by set name.

  Specified by:
    `getName` in interface `HasName`
  Returns:
    the name

### setName

    public final void setName(java.lang.String name)

  Sets the name of this view.

  Parameters:
    `name` - a user relevant name for this view

### clone

    public java.lang.Object clone()

  Clones this object.

  Specified by:
    `clone` in interface `ScapeListener`
  Overrides:
    `clone` in class `java.lang.Object`
  Returns:
    the object

### toString

    public java.lang.String toString()

  Returns a short description of this view. Sames as name unless overridden.

  Overrides:
    `toString` in class `java.lang.Object`
  Returns:
    the string