sim.portrayal
Class FieldPortrayal

java.lang.Object
  extended by sim.portrayal.FieldPortrayal
Direct Known Subclasses:
FieldPortrayal2D, FieldPortrayal3D

public abstract class FieldPortrayal
extends java.lang.Object

A FieldPortrayal is an object which knows how to portray some kind of Field.

This abstract version of FieldPortrayal provides some basic functionality that many FieldPortrayals may find handy. This functionality allows a FieldPortrayal to store Portrayal objects responsible for drawing various objects within the Field. For example, a SparseGrid2D holds a bunch of objects: the SparseGridPortrayal2D, which is a FieldPortrayal, lets you store Portrayal objects which know how to draw the various objects in the SparseGrid2D.

You can associate a Portrayal object with an object stored in the Field in several ways. First, you can specify one Portrayal object to be used for ALL objects stored in the field, using setPortrayalForAll. Second, you can specify a Portrayal object to be used for objects in a Field all belonging to the same class, using setPortrayalForClassOf. Third, you can specify a Portrayal for a specific object, using setPortrayalForObject.

You can get the desired Portrayal for an object by calling getPortrayalForObject. This method looks up the Portrayal for an object by going down the following checklist until a Portrayal is found (earlier checklist items take precedence over later ones):

  1. If there is a portrayalForAll, return it.
  2. If the object is null:
    1. Return the portrayalForNull if there is one
    2. If a portrayal is explicitly registered for null, return that portrayal.
    3. Return the defaultNullPortrayal.
  3. If the object is non-null:
    1. If the object implements the appropriate Portrayal interface, return the object itself as its own Portrayal.
    2. Return the portrayalForNonNull if there is one
    3. If a portrayal is explicitly registered for the object, return that portrayal. Portrayals may be registered for null as well.
    4. If a Portrayal is registered for the object's exact class (superclasses are ignored), return that portrayal.
    5. Return the portrayalForRemainder if there is one
    6. Return the default Portrayal object.

FieldPortrayals store Portrayal objects in WeakHashMaps. This means that if you register a Portrayal explicitly for an object, and then later the object is eliminated from your model, the FieldPortrayal will not hold onto the object or onto its Portrayal, but will allow them to garbage collect as well. Thus you don't have to worry about de-registering an object.

Some FieldPortrayals benefit (draw faster) if they know that their underlying field is immutable, that is, it never changes. Notably, most FieldPortrayal3Ds benefit, as well as various ValueGrid2DPortrayals.


Nested Class Summary
 class FieldPortrayal.CustomInspector
           
 
Field Summary
 java.util.WeakHashMap classPortrayals
           
protected  boolean dirtyField
          This flag is available for Fields to set and clear as they like: but its intended function is to be set during setField(field) to warn drawing that even though the field is immutable, it may have changed to another field and needs to be redrawn.
protected  java.lang.Object field
           
protected  boolean immutableField
           
 Portrayal portrayalForAll
           
 Portrayal portrayalForNonNull
           
 Portrayal portrayalForNull
           
 Portrayal portrayalForRemainder
           
 java.util.WeakHashMap portrayals
           
 
Constructor Summary
FieldPortrayal()
           
 
Method Summary
 Portrayal getDefaultNullPortrayal()
          Returns a default portrayal for null.
abstract  Portrayal getDefaultPortrayal()
          Should return a portrayal which can portray any object regardless of whether it's valid or not
 java.lang.Object getField()
          Returns the field.
 Inspector getInspector(LocationWrapper wrapper, GUIState state)
           
 java.lang.String getName(LocationWrapper wrapper)
           
 Portrayal getPortrayalForAll()
           
 Portrayal getPortrayalForNonNull()
           
 Portrayal getPortrayalForNull()
           
 Portrayal getPortrayalForObject(java.lang.Object obj)
          Returns the appropriate Portrayal.
 Portrayal getPortrayalForRemainder()
           
 java.lang.String getStatus(LocationWrapper wrapper)
           
 boolean isImmutableField()
          Returns true if the underlying field is assumed to be unchanging -- thus there's no reason to update once we're created.
abstract  void setField(java.lang.Object field)
          Sets the field.
 void setImmutableField(boolean val)
          Specifies that the underlying field is (or is not) to be assumed unchanging -- thus there's no reason to update once we're created.
 void setPortrayalForAll(Portrayal portrayal)
          Set the portrayal to null to remove it.
 void setPortrayalForClass(java.lang.Class cls, Portrayal portrayal)
          Sets a portrayal for a class -- objects must be of EXACTLY this class (not subclasses) to respond to this.
 void setPortrayalForNonNull(Portrayal portrayal)
          Set the portrayal to null to remove it.
 void setPortrayalForNull(Portrayal portrayal)
          Set the portrayal to null to remove it.
 void setPortrayalForObject(java.lang.Object obj, Portrayal portrayal)
          Sets a portrayal for a class -- objects must be equal(...) to the provided object here to respond to this.
 void setPortrayalForRemainder(Portrayal portrayal)
          Set the portrayal to null to remove it.
 boolean setSelected(LocationWrapper wrapper, boolean selected)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

portrayalForAll

public Portrayal portrayalForAll

portrayalForNull

public Portrayal portrayalForNull

portrayalForNonNull

public Portrayal portrayalForNonNull

portrayalForRemainder

public Portrayal portrayalForRemainder

portrayals

public java.util.WeakHashMap portrayals

classPortrayals

public java.util.WeakHashMap classPortrayals

field

protected java.lang.Object field

immutableField

protected boolean immutableField

dirtyField

protected boolean dirtyField
This flag is available for Fields to set and clear as they like: but its intended function is to be set during setField(field) to warn drawing that even though the field is immutable, it may have changed to another field and needs to be redrawn. Similarly, typically this flag is cleared after drawing. Initially true.

Constructor Detail

FieldPortrayal

public FieldPortrayal()
Method Detail

setPortrayalForAll

public void setPortrayalForAll(Portrayal portrayal)
Set the portrayal to null to remove it.


getPortrayalForAll

public Portrayal getPortrayalForAll()

setPortrayalForNull

public void setPortrayalForNull(Portrayal portrayal)
Set the portrayal to null to remove it.


getPortrayalForNull

public Portrayal getPortrayalForNull()

setPortrayalForNonNull

public void setPortrayalForNonNull(Portrayal portrayal)
Set the portrayal to null to remove it.


getPortrayalForNonNull

public Portrayal getPortrayalForNonNull()

setPortrayalForRemainder

public void setPortrayalForRemainder(Portrayal portrayal)
Set the portrayal to null to remove it.


getPortrayalForRemainder

public Portrayal getPortrayalForRemainder()

setPortrayalForClass

public void setPortrayalForClass(java.lang.Class cls,
                                 Portrayal portrayal)
Sets a portrayal for a class -- objects must be of EXACTLY this class (not subclasses) to respond to this. Set the portrayal to null to remove it for a given class.


setPortrayalForObject

public void setPortrayalForObject(java.lang.Object obj,
                                  Portrayal portrayal)
Sets a portrayal for a class -- objects must be equal(...) to the provided object here to respond to this. Set the portrayal to null to remove it for a given object.


getDefaultNullPortrayal

public Portrayal getDefaultNullPortrayal()
Returns a default portrayal for null. By default this is set to the same as getDefaultPortrayal(). Override this to provide a more interesting default portrayals for null.


getDefaultPortrayal

public abstract Portrayal getDefaultPortrayal()
Should return a portrayal which can portray any object regardless of whether it's valid or not


getPortrayalForObject

public Portrayal getPortrayalForObject(java.lang.Object obj)
Returns the appropriate Portrayal.


isImmutableField

public boolean isImmutableField()
Returns true if the underlying field is assumed to be unchanging -- thus there's no reason to update once we're created. Not all FieldPortrayals will care about whether or not a field is immutable.


setImmutableField

public void setImmutableField(boolean val)
Specifies that the underlying field is (or is not) to be assumed unchanging -- thus there's no reason to update once we're created. Not all FieldPortrayals will care about whether or not a field is immutable. Sets dirtyField to true.


getField

public java.lang.Object getField()
Returns the field.


setField

public abstract void setField(java.lang.Object field)
Sets the field. Also sets dirtyField = true. May throw an exception if the field is inappropriate.


getInspector

public Inspector getInspector(LocationWrapper wrapper,
                              GUIState state)

getName

public java.lang.String getName(LocationWrapper wrapper)

getStatus

public java.lang.String getStatus(LocationWrapper wrapper)

setSelected

public boolean setSelected(LocationWrapper wrapper,
                           boolean selected)