Class FieldPortrayal
- Direct Known Subclasses:
FieldPortrayal2D
,FieldPortrayal3D
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.
The default version of the setField(...) method sets the field without checking to see if it's a valid field or not; you'll want to override this to check.
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):
- If there is a portrayalForAll, return it.
- If the object is null:
- Return the portrayalForNull if there is one
- If a portrayal is explicitly registered for null, return that portrayal.
- Return the defaultNullPortrayal.
- If the object is non-null:
- If we are using the "traditional" portrayal ordering, and the object implements the appropriate Portrayal interface, return the object itself as its own Portrayal.
- Return the portrayalForNonNull if there is one
- If a portrayal is explicitly registered for the object, return that portrayal. Portrayals may be registered for null as well.
- If a Portrayal is registered for the object's exact class (superclasses are ignored), return that portrayal.
- If we are using the "alternate" portrayal ordering, and the object implements the appropriate Portrayal interface, return the object itself as its own Portrayal.
- Return the portrayalForRemainder if there is one
- Return the default Portrayal object.
Note that when we decide to use objects themselves (if they are Portrayals) is determined by the portrayal ordering. The "default" (or "classic") version of this ordering uses objects themselves prior to looking up registered portrayals for them or for their classes. The "alternate" ordering instead looks up and uses registered portrayals first.
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.
-
Field Summary
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionboolean
Returns whether the alternate portrayal ordering is used.Returns a default portrayal for null.abstract Portrayal
Should return a portrayal which can portray any object regardless of whether it's valid or notgetField()
Returns the field.getInspector
(LocationWrapper wrapper, GUIState state) getName
(LocationWrapper wrapper) getObjectLocation
(Object object, GUIState gui) Returns the first location in the underlying field of the given object, if such a thing is reasonable.Returns the appropriate Portrayal.getStatus
(LocationWrapper wrapper) boolean
boolean
Returns true if the underlying field is assumed to be unchanging -- thus there's no reason to update once we're created.void
reset()
Deprecated.Use setDirtyField(true);void
setAlternatePortrayalOrdering
(boolean val) Sets whether the alternate portrayal ordering is used.void
setDirtyField
(boolean val) void
Sets the field, and sets the dirtyField flag to true.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
setObjectLocation
(Object obj, Object location, GUIState gui) Sets location in the underlying field of the given object, if such a thing is reasonable.void
setPortrayalForAll
(Portrayal portrayal) Set the portrayal to null to remove it.void
setPortrayalForClass
(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
(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) Selects or deselects all of the provided objects.void
setSelected
(Bag locationWrappers, boolean selected)
-
Field Details
-
portrayalForAll
-
portrayalForNull
-
portrayalForNonNull
-
portrayalForRemainder
-
portrayals
-
classPortrayals
-
field
-
immutableField
protected boolean immutableField
-
-
Constructor Details
-
FieldPortrayal
public FieldPortrayal()
-
-
Method Details
-
setAlternatePortrayalOrdering
public void setAlternatePortrayalOrdering(boolean val) Sets whether the alternate portrayal ordering is used. The default is false. -
getAlternatePortrayalOrdering
public boolean getAlternatePortrayalOrdering()Returns whether the alternate portrayal ordering is used. The default is false. -
setPortrayalForAll
Set the portrayal to null to remove it. -
getPortrayalForAll
-
setPortrayalForNull
Set the portrayal to null to remove it. -
getPortrayalForNull
-
setPortrayalForNonNull
Set the portrayal to null to remove it. -
getPortrayalForNonNull
-
setPortrayalForRemainder
Set the portrayal to null to remove it. -
getPortrayalForRemainder
-
setPortrayalForClass
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
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
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
Should return a portrayal which can portray any object regardless of whether it's valid or not -
getPortrayalForObject
Returns the appropriate Portrayal. -
setDirtyField
public void setDirtyField(boolean val) -
isDirtyField
public boolean isDirtyField() -
reset
public void reset()Deprecated.Use setDirtyField(true); -
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. Also sets dirtyField to true regardless. -
getField
Returns the field. -
setField
Sets the field, and sets the dirtyField flag to true. May throw an exception if the field is inappropriate. The default version just sets the field and sets the dirtyField flag. -
getInspector
-
getName
-
getStatus
-
setSelected
Selects or deselects all of the provided objects. -
setSelected
-
getObjectLocation
Returns the first location in the underlying field of the given object, if such a thing is reasonable. Largely used for getObjectPosition(...). If null is returned, then the portrayal is unable to determine the position of the field location. Optionally overridable. The default implementation returns null. -
setObjectLocation
Sets location in the underlying field of the given object, if such a thing is reasonable. Largely used for setObjectPosition(...), and in the Inspector's LocationWrapper via the Stable classes. Optionally overridable. The default implementation does nothing.
-