Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## sim.portrayal.simple
Class TrailedPortrayal2D

    java.lang.Object
      sim.portrayal.SimplePortrayal2D
          sim.portrayal.simple.TrailedPortrayal2D

All Implemented Interfaces:
  java.io.Serializable, Portrayal, Portrayal2D

    public class TrailedPortrayal2D

extends SimplePortrayal2D

TrailedPortrayal2D is a special SimplePortrayal wrapper which enables you to draw "trails" or "mouse tails" that drag behind objects and show where the've recently been. Unlike other "wrapper" style SimplePortrayals, like CircledPortrayal2D or LabelledPortrayal2D, TrailedPortrayal2D generally requires its own separate FieldPortrayal in which to draw the trails properly.

Let's say you have a 2D field called "field" (we strongly suggest only using trails in SparseGrid2D or in Continuous2D because of the costs involved in other spaces). That field is presently being portrayed by a FieldPortrayal2D called, say, "fieldPortrayal". fieldPortrayal2D is presently using a SimplePortrayal2D (we'll call it "simple") to draw those objects. It's possible for the objects to draw themselves if you like. fieldPortrayal is presently attached to a Display2D called "display".

To add trails, what you'll do is create a second FieldPortrayal2D, identical to fieldPortrayal, and which portrays the same field. Let's call this one trailfieldportrayal. Attach trailfieldportrayal to the display immediately *before* fieldPortrayal is attached, so it's drawn immediately before and thus the objects in fieldPortrayal get drawn on top of the trails.

Next you'll need to specify the SimplePortrayal2D for trailfieldportrayal. To do this, you'll use a TrailPortrayal2D wrapped around a child SimplePortrayal2D, specifically, the same kind of SimplePortrayal2D as "simple" was. In fact you can use "simple" itself if you like. If your objects portray themselves, pass in null as the child portrayal instead. This child portrayal won't be drawn and won't be inspected: it exists solely to enable the TrailPortrayal2D to determine whether an object has been SELECTED and if it should start drawing the trail. That is, it's used for hit testing.

It's important that you provide a SEPARATE TrailPortrayal2D for EVERY SINGLE object in trailfieldportrayal. That is, you register it using FieldPortrayal.setPortrayalForObject rather than FieldPortrayal.setPortrayalForAll or some-such. This is because TrailPortrayal2D only maintains one trail at a time, so if you select another object, the previous trail appears to be attached to that other object (which is wrong). If you use separate TrailPortrayal2Ds, each will manage the trail for the various objects in the field (which is right, but memory expensive and a bit slow).

Alternatively you can provide a single TrailPortrayal2D via FieldPortrayal.setPortrayalForAll but set growTrailOnlyWhenSelected to FALSE. This will cause the TrailPortrayal2D to *begin* growing the trail each time a new object is selected. It uses a lot less memory and is faster but may not produce the effect you desire.

You can also cause all the TrailPortrayal2Ds to draw trails regardless of selection: just set onlyShowTrailWhenSelected to FALSE (and make sure you have separate TrailPortrayal2Ds for each object in the field). This is a rare need.

To draw the actual trail segements, TrailPortrayal2D relies on a SECOND subsidiary SimplePortrayal2D called "trail". You can either provide your own custom SimplePortrayal2D or use the default one, which draws half-thick line segments of different colors. Either way, this "trail" SimplePortrayal2D will be passed a TrailedPortrayal2D.TrailDrawInfo2D, which is a special version of DrawInfo2D which contains the previous point and also a value from 0.0 to 1.0 indicating how far back in time the segement is supposed to be -- you can use that to figure out what color to draw with, for example.

To handle big jumps (particularly toroidal wrap-arounds) elegantly, TrailedPortrayal2D has a maximumJump percentage. For a jump to be drawn, it must be LESS than this percentage of the total width or height of the underlying field.

See Also:
  Serialized Form

Nested Class Summary
`static class` | `TrailedPortrayal2D.TrailDrawInfo2D` A special version of DrawInfo2D which adds additional information useful for drawing your own trails.

Field Summary
`SimplePortrayal2D` | `child` The Child portrayal of this portrayal: a SimplePortrayal2D used solely for determining hit testing.
`double` | `maximumJump`
`SimplePortrayal2D` | `trail` The SimplePortrayal2D used to draw line segments in the trail.

Fields inherited from class sim.portrayal.SimplePortrayal2D
`TYPE_HIT_OBJECT, TYPE_SELECTED_OBJECT`

Constructor Summary
`TrailedPortrayal2D(GUIState state, SimplePortrayal2D child, FieldPortrayal2D fieldPortrayal, double length)` Creates a TrailedPortrayal2D for a given child portrayal, field portrayal for the trail, length in time, using a default trail portrayal with default settings.
`TrailedPortrayal2D(GUIState state, SimplePortrayal2D child, FieldPortrayal2D fieldPortrayal, double length, java.awt.Color minColor, java.awt.Color maxColor)` Creates a TrailedPortrayal2D for a given child portrayal, field portrayal for the trail, length in time, using a default trail portrayal going from minColor to maxColor through time.
`TrailedPortrayal2D(GUIState state, SimplePortrayal2D child, FieldPortrayal2D fieldPortrayal, SimplePortrayal2D trail, double length)` Creates a TrailedPortrayal2D for a given child portrayal, field portrayal for the trail, trail portrayal, and length in time.

Method Summary
`void` | `draw(java.lang.Object object, java.awt.Graphics2D graphics, DrawInfo2D info)` Draw a the given object with an origin at (info.draw.x, info.draw.y), and with the coordinate system scaled by so that 1 unit is in the x and y directions are equal to info.draw.width and info.draw.height respectively in pixels.
`boolean` | `getGrowTrailOnlyWhenSelected()` Returns whether or not to grow the trail only after the objet has been selected, and delete it when the object has been deselected.
`Inspector` | `getInspector(LocationWrapper wrapper, GUIState state)` Provide an inspector for an object.
`double` | `getLength()` Returns the length of the trail in TIME.
`double` | `getMaximumJump()` Returns the maximum percentage of either the width or height of the field that can be jumped between two successive object locations before it's considered to be a huge leap and that segment won't be drawn.
`java.lang.String` | `getName(LocationWrapper wrapper)` Returns a static, one-line name for the given object that is useful for a human to distinguish it from other objects.
`boolean` | `getOnlyShowTrailWhenSelected()` Returns whether or not to draw the trail only when the object has been selected (or not).
`boolean` | `hitObject(java.lang.Object object, DrawInfo2D range)` Return true if the given object, when drawn, intersects with a provided rectangle, for hit testing purposes.
`void` | `setGrowTrailOnlyWhenSelected(boolean val)` Set this to grow the trail only after the objet has been selected, and delete it when the object has been deselected.
`void` | `setLength(double val)` Sets the length of the trail in TIME.
`void` | `setMaximumJump(double val)` Sets the maximum percentage of either the width or height of the field that can be jumped between two successive object locations before it's considered to be a huge leap and that segment won't be drawn.
`void` | `setOnlyShowTrailWhenSelected(boolean val)` Set this to draw the trail only when the object has been selected (or not).
`boolean` | `setSelected(LocationWrapper wrapper, boolean selected)` Change the portrayal state to reflect the fact that you've been selected or not selected.

Methods inherited from class sim.portrayal.SimplePortrayal2D
`getStatus, handleMouseEvent`

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

Field Detail

### child

    public SimplePortrayal2D child

  The Child portrayal of this portrayal: a SimplePortrayal2D used solely for determining hit testing.

### trail

    public SimplePortrayal2D trail

  The SimplePortrayal2D used to draw line segments in the trail.

### maximumJump

    public double maximumJump

Constructor Detail

### TrailedPortrayal2D

    public TrailedPortrayal2D(GUIState state,
                              SimplePortrayal2D child,
                              FieldPortrayal2D fieldPortrayal,
                              SimplePortrayal2D trail,
                              double length)

  Creates a TrailedPortrayal2D for a given child portrayal, field portrayal for the trail, trail portrayal, and length in time.

### TrailedPortrayal2D

    public TrailedPortrayal2D(GUIState state,
                              SimplePortrayal2D child,
                              FieldPortrayal2D fieldPortrayal,
                              double length,
                              java.awt.Color minColor,
                              java.awt.Color maxColor)

  Creates a TrailedPortrayal2D for a given child portrayal, field portrayal for the trail, length in time, using a default trail portrayal going from minColor to maxColor through time.

### TrailedPortrayal2D

    public TrailedPortrayal2D(GUIState state,
                              SimplePortrayal2D child,
                              FieldPortrayal2D fieldPortrayal,
                              double length)

  Creates a TrailedPortrayal2D for a given child portrayal, field portrayal for the trail, length in time, using a default trail portrayal with default settings.

Method Detail

### setGrowTrailOnlyWhenSelected

    public void setGrowTrailOnlyWhenSelected(boolean val)

  Set this to grow the trail only after the objet has been selected, and delete it when the object has been deselected. By default this is FALSE. If you set this to TRUE, you can use the same TrailedPortrayal2D repeatedly for all objects in your field rather than providing separate ones for separate objects; furthermore only one trail will exist at a time, reducing memory costs.

### getGrowTrailOnlyWhenSelected

    public boolean getGrowTrailOnlyWhenSelected()

  Returns whether or not to grow the trail only after the objet has been selected, and delete it when the object has been deselected. By default this is FALSE. If you set this to TRUE, you can use the same TrailedPortrayal2D repeatedly for all objects in your field rather than providing separate ones for separate objects; furthermore only one trail will exist at a time, reducing memory costs.

### setOnlyShowTrailWhenSelected

    public void setOnlyShowTrailWhenSelected(boolean val)

  Set this to draw the trail only when the object has been selected (or not). By default this is TRUE.

### getOnlyShowTrailWhenSelected

    public boolean getOnlyShowTrailWhenSelected()

  Returns whether or not to draw the trail only when the object has been selected (or not). By default this is TRUE.

### setLength

    public void setLength(double val)

  Sets the length of the trail in TIME. If an object was at a location further back than the length, the segment for that location won't be drawn any more.

### getLength

    public double getLength()

  Returns the length of the trail in TIME. If an object was at a location further back than the length, the segment for that location won't be drawn any more.

### setMaximumJump

    public void setMaximumJump(double val)

  Sets the maximum percentage of either the width or height of the field that can be jumped between two successive object locations before it's considered to be a huge leap and that segment won't be drawn. Huge leaps usually happen because of toroidal wrap-around. By default the value is 0.75. If you'd like all jumps to be drawn regardless of their size, set this to 1.0.

### getMaximumJump

    public double getMaximumJump()

  Returns the maximum percentage of either the width or height of the field that can be jumped between two successive object locations before it's considered to be a huge leap and that segment won't be drawn. Huge leaps usually happen because of toroidal wrap-around. By default the value is 0.75. If you'd like all jumps to be drawn regardless of their size, set this to 1.0.

### draw

    public void draw(java.lang.Object object,
                     java.awt.Graphics2D graphics,
                     DrawInfo2D info)

  Description copied from interface: `Portrayal2D`
  Draw a the given object with an origin at (info.draw.x, info.draw.y), and with the coordinate system scaled by so that 1 unit is in the x and y directions are equal to info.draw.width and info.draw.height respectively in pixels. The rectangle given by info.clip specifies the only region in which it is necessary to draw. If info.precise is true, try to draw using real-valued high-resolution drawing rather than faster integer drawing. It is possible that object is null. The location of the object in the field may (and may not) be stored in info.location. The form of that location varies depending on the kind of field used.

  Specified by:
    `draw` in interface `Portrayal2D`
  Overrides:
    `draw` in class `SimplePortrayal2D`

### hitObject

    public boolean hitObject(java.lang.Object object,
                             DrawInfo2D range)

  Description copied from class: `SimplePortrayal2D`
  Return true if the given object, when drawn, intersects with a provided rectangle, for hit testing purposes. The object is drawn with an origin at (info.draw.x, info.draw.y), and with the coordinate system scaled by so that 1 unit is in the x and y directions are equal to info.draw.width and info.draw.height respectively in pixels. The rectangle given by info.clip specifies the region to do hit testing in; often this region is actually of 0 width or height, which might represent a single point. It is possible that object is null. The location of the object in the field may (and may not) be stored in info.location. The form of that location varies depending on the kind of field used.

  Overrides:
    `hitObject` in class `SimplePortrayal2D`

### setSelected

    public boolean setSelected(LocationWrapper wrapper,
                               boolean selected)

  Description copied from interface: `Portrayal`
  Change the portrayal state to reflect the fact that you've been selected or not selected. Always return true, except if you've received a setSelected(true) and in fact do not wish to be selectable, in which case return false in that sole situation.

  Specified by:
    `setSelected` in interface `Portrayal`
  Overrides:
    `setSelected` in class `SimplePortrayal2D`

### getInspector

    public Inspector getInspector(LocationWrapper wrapper,
                                  GUIState state)

  Description copied from interface: `Portrayal`
  Provide an inspector for an object.

  Specified by:
    `getInspector` in interface `Portrayal`
  Overrides:
    `getInspector` in class `SimplePortrayal2D`

### getName

    public java.lang.String getName(LocationWrapper wrapper)

  Description copied from interface: `Portrayal`
  Returns a static, one-line name for the given object that is useful for a human to distinguish it from other objects. A simple default would be just to return "" + object.

  Specified by:
    `getName` in interface `Portrayal`
  Overrides:
    `getName` in class `SimplePortrayal2D`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD