Class PlacedAnimationObject2D

All Implemented Interfaces:
Graph.Graphic, NamedObjectOps
Direct Known Subclasses:
DirectedObject2D

public abstract class PlacedAnimationObject2D extends AnimationObject2D
Class representing two-dimensional objects with a position and orientation. The orientation is the angle between a vector parallel to a unit vector, that is parallel to the x axis, and a vector representing the direction in which an object is oriented. The orientation is represented by the angle between these two vectors. Positive angles are in the counterclockwise direction. The position is given in graph coordinate space, as defined by the Graph class, and a subclass-specific point called a reference point, at a fixed location relative to the object will be placed at that position.

Subclasses that are not abstract must have the Graph.Graphic method addTo implemented. This will typically contain code such as the following, which uses an affine transformation to handle the rotations and translations needed to draw the object:

    public void addTo(Graph graph, Graphics2D g2d, Graphics2D g2dGCS) {
       Color savedColor = g2d.getColor();
       try {
          AffineTransform af = getAddToTransform();
          g2d.setColor(Color.BLACK);
          Shape shape1 = ....;
          shape1 = new Path2D.Double(shape1, af);
          graph.draw(g2d, shape1);
          ...
       } finally {
          g2d.setColor(savedColor);
       }
    }
 
In this example, shape1 is created as if the object has been positioned at (0.0, 0.0) in graph coordinate space with no rotation. This shape is then used to create a Path2D.Double using the affine transform returned by getAddToTransform() to generate the shape for the current position and angle.

Reference points allow an object to be rotated about some other position than (0.0, 0.0) before placing it at some position (x, y). The point about which such a rotation may occur is called the reference point. The translation will be such that the reference point appears at (x, y) regardless of the rotation.

To draw an image, the procedure is slightly different. For example,

    public void addTo(Graph graph, Graphics2D g2d, Graphics2D g2dGCS) {
       try {
          AffineTransform af = getAddToTransform();
          ...
          Point2D pt = new Point2D(imageX, imageY);
          af.transform(pt,pt);
          double x = pt.getX();
          double y = pt.getY();
          graph.drawImage(g2d, image, x, y, RefPointName.CENTER, getAngle(),
                          imageScale, imageScale, true);
          ...
       } catch (IOException) {
         ...
       }
    }
 
where image is an image and (imageX, imageY) is the position in graph coordinate space at which the image should be drawn when the location is (0.0, 0.0) and the reference point for the object (not the image's internal reference point) is (0.0, 0.0). The argument RefPointName.CENTER in the call to drawImage causes the image to be centered on the point (x,y).

Subclasses that meaningfully support reference points will call the method setRefPointBounds with two arguments or the method setRefPointBounds with four arguments. These methods set a bounding box. Standard references point names exist for specifying various locations on or (in one case) within the bounding box. The bounding box must be set before any drawing is done. As a general rule, it should be set in a constructor.

See Also:
  • Constructor Details

    • PlacedAnimationObject2D

      public PlacedAnimationObject2D(Animation2D animation, String name, boolean intern)
      Constructor.
      Parameters:
      animation - the animation
      name - the name of the object; null for an automatically generated name
      intern - true if the object can be looked up by using the methods in Simulation; false otherwise.
      Throws:
      IllegalArgumentException - typically means a name is already in use
      See Also:
  • Method Details

    • setPosition

      public void setPosition(double x, double y, double angle)
      Set an object's position and orientation. Angles increase in the counterclockwise direction in graph coordinate space with an angle of zero corresponding to a subclass-specified direction, which will typically be one in which the object 'points' towards the positive x axis from position (0.0,0.0); The coordinates (x,y) are the coordinates of a subclass-specific reference point that is in a fixed location relative to the object.
      Parameters:
      x - the x coordinate in graph coordinate space
      y - the y coordinate in graph coordinate space
      angle - the angle giving the object's orientation in radians
    • setPosition

      public void setPosition(double x, double y)
      Set an object's position. The coordinates (x,y) are the coordinates of a subclass-specific reference point that is in a fixed location relative to the object.
      Parameters:
      x - the x coordinate in graph coordinate space
      y - the y coordinate in graph coordinate space
    • setAngle

      public void setAngle(double angle)
      Set an object's angle. Angles increase in the counterclockwise direction in graph coordinate space with an angle of zero corresponding to a subclass-specified direction, which will typically be one in which the object 'points' towards the positive x axis from position (0.0,0.0).
      Parameters:
      angle - the angle giving the object's orientation in radians
    • getAddToTransform

      public AffineTransform getAddToTransform()
      Get an affine transform that will allow an object to be drawn. The affine transformation will first translate the reference point to position (0.0, 0.0), then apply a rotation equal to the angle passed in the last call to setPosition(double,double,double) about position (0.0, 0.0), and finally translate position (0.0, 0.0) to the values of (x, y) provided in the last call to setPosition(double,double,double). This affine transformation allows the user to draw an object in graph-coordinate space at location (0.0, 0.0) as if the angle had the value 0.0. The object will then be rotated about the reference point and the reference point will be translated to the position (x, y).
      Returns:
      the affine transform
    • getX

      public double getX()
      Get the x position.
      Returns:
      the X position in graph coordinate space
    • getY

      public double getY()
      Get the Y position.
      Returns:
      the Y position in graph coordinate space
    • getAngle

      public double getAngle()
      Get the angle for the object's orientation.
      Returns:
      the angle in radians
    • getBBXMin

      public double getBBXMin()
      Get the minimum x value of the binding box. This is the bounding box's minimum value of x when the reference point's origin is at (0.0, 0.0) in graph coordinate space.
      Returns:
      the minimum x value in graph coordinate space units
    • getBBYMin

      public double getBBYMin()
      Get the minimum y value of the binding box. This is the bounding box's minimum value of y when the reference point's origin is at (0.0, 0.0) in graph coordinate space.
      Returns:
      the minimum y value in graph coordinate space units
    • getBBXMax

      public double getBBXMax()
      Get the maximum x value of the binding box. This is the bounding box's maximum value of x when the reference point's origin is at (0.0, 0.0) in graph coordinate space.
      Returns:
      the maximum x value in graph coordinate space units
    • getBBYMax

      public double getBBYMax()
      Get the maximum y value of the binding box. This is the bounding box's maximum value of y when the reference point's origin is at (0.0, 0.0) in graph coordinate space.
      Returns:
      the maximum y value in graph coordinate space units
    • getRefPointName

      public RefPointName getRefPointName()
      Get the name of a reference point.
      Returns:
      the reference point name, null if it is unnamed
    • getReferencePointX

      public double getReferencePointX()
      Get the X coordinate of the reference point. Drawing an object at its position in graph coordinate space is equivalent to drawing that object at position (0.0, 0.0) in graph coordinate space after a translation that puts the reference point at position (0.0, 0.0), and then translating the drawn object to its correct position. After that final translation, the reference point will appear at the location specified for the object. Any rotations will be about the reference point.
      Returns:
      the X coordinate of the reference point
    • getReferencePointY

      public double getReferencePointY()
      Get the Y component of the reference point. Drawing an object at its position in graph coordinate space is equivalent to drawing that object at position (0.0, 0.0) in graph coordinate space after a translation that puts the reference point at position (0.0, 0.0), and then translating the drawn object to its correct position. After that final translation, the reference point will appear at the location specified for the object. Any rotations will be about the reference point.
      Returns:
      the Y component of the reference point
    • setRefPointBounds

      protected void setRefPointBounds(double width, double height)
      Set the corners of an object's bounding box based on its height and width when the object is drawn at an angle of 0 degrees. The bounding box is that of the object when the object's position is (0.0, 0.0) in graph coordinate space with a null reference point. The arguments width and height refer to the dimensions of the bounding box in the x and y directions respectively. The point (0.0, 0.0) will be at the center of the bounding box. The reference point will be determined by the last reference-point name used (if null, the reference point will be at (0.0, 0.0)).
      Parameters:
      width - the width of the bounding box in graph coordinate space
      height - the height of the box in graph coordinate space
    • setRefPointBounds

      protected void setRefPointBounds(double xMin, double xMax, double yMin, double yMax)
      Set the lower and upper corners of the bounding box for the object when drawn at an angle of 0 degrees. The bounding box is that of the object when the object's position is (0.0, 0.0) in graph coordinate space with a null reference point. The reference point will be determined by the last reference-point name used (if null, the reference point will be at (0.0, 0.0)).
      Parameters:
      xMin - the minimum x coordinate of the bounding box in graph coordinate space
      xMax - the maximum x coordinate of the bounding box in graph coordinate space
      yMin - the minimum y coordinate of the bounding box in graph coordinate space
      yMax - the maximum y coordinate of the bounding box in graph coordinate space
    • setRefPointByName

      public void setRefPointByName(RefPointName loc)
      Set the reference point based on a name RefPointName is an enumeration with values UPPER_LEFT, UPPER_CENTER, UPPER_RIGHT, CENTER_LEFT, CENTER, CENTER_RIGHT, LOWER_LEFT, LOWER_CENTER, and LOWER_RIGHT. When the argument loc is null, if (0.0, 0.0) corresponds to one of the named locations, the reference point name will be set to a non-null value.

      This method calls SimObject.update(). Unless explicitly set, the reference point name is null.

      Parameters:
      loc - the name of the reference point; null for the default (position (0.0, 0.0))
    • setRefPoint

      public final void setRefPoint(Point2D point)
      Set the reference point by specifying a point.

      This method calls SimObject.update(). If the reference point was never explicitly set, its value will be (0.0, 0.0).

      Parameters:
      point - the point in graph coordinate space corresponding to the reference point
    • setRefPoint

      public void setRefPoint(double x, double y)
      Set the reference point by specifying its x and y coordinates. When the x and y match the coordinates for named reference points, a named reference point is used.

      This method calls SimObject.update(). If the reference point was never explicitly set, its value will be (0.0, 0.0).

      Parameters:
      x - the x coordinate in graph coordinate space
      y - the y coordinate in graph coordinate space
    • setRefPointByFraction

      public void setRefPointByFraction(double xf, double yf)
      Set the reference point based on fractions. the x coordinate of the reference point is xMin + xf * (xMax - xMin) and the y coordinate is yMin + yf * (yMax - yMin). The values 0.0, 0.5, and 1.0 are handled specially: when both xf and yf are set to 0.0, 0.5, or 1.0, a named reference point is used to maintain consistency.

      This method calls SimObject.update(). If the reference point was never explicitly set, its value will be (0.0, 0.0).

      Parameters:
      xf - the x fraction (0.0 to 1.0 inclusive)
      yf - the y fraction (0.0 to 1.0 inclusive)
    • printConfiguration

      public void printConfiguration(String iPrefix, String prefix, boolean printName, PrintWriter out)
      Print this simulation object's configuration. Documentation for the use of this method is provided by the documentation for the SimObject method SimObject.printConfiguration(String,String,boolean,PrintWriter).

      When the second argument has a value of true, the object name and class name will be printed in a standard format with its indentation provided by the iPrefix argument. In addition, the configuration that is printed includes the following items.

      Defined in AnimationObject2D:

      • the Z-order.
      • whether or not this object is visible.
      Defined in PlacedAnimationObject2D:
      • the reference-point name (if any).
      • the reference point location.
      • the reference point bounds (minimum and maximum X and Y values for the rectangle to which the reference point names refer).
      Overrides:
      printConfiguration in class AnimationObject2D
      Parameters:
      iPrefix - the prefix to use for an initial line when printName is true with null treated as an empty string
      prefix - a prefix string (typically whitespace) to put at the start of each line other than the initial line that is printed when printName is true
      printName - requests printing the name of an object
      out - the output print writer
    • printState

      public void printState(String iPrefix, String prefix, boolean printName, PrintWriter out)
      Print this simulation object's state. Documentation for the use of this method is provided by the documentation for the SimObject method SimObject.printState(String,String,boolean,PrintWriter).

      When the third argument has a value of true, the object name and class name will be printed in a standard format with its indentation provided by the iPrefix argument. In addition, the state that is printed includes the following items.

      Defined in PlacedAnimationObject2D:

      • the X coordinate of this object.
      • the Y coordinate of this object.
      • the angle for this object, measured counterclockwise.
      Overrides:
      printState in class AnimationObject2D
      Parameters:
      iPrefix - the prefix to use for an initial line when printName is true with null treated as an empty string
      prefix - a prefix string (typically whitespace) to put at the start of each line other than the initial line that is printed when printName is true
      printName - requests printing the name of an object
      out - the output print writer
    • clone

      protected Object clone() throws CloneNotSupportedException
      Creates and returns a copy of this object. This method will throw the exception CloneNotSupportedException if the object is interned.
      Overrides:
      clone in class Object
      Throws:
      CloneNotSupportedException - a clone could not be created
      See Also:
    • isInterned

      public boolean isInterned()
      Determine if an object is interned in a object namer's tables.
      Specified by:
      isInterned in interface NamedObjectOps
      Returns:
      true if the object is interned; false if not
    • getObjectNamer

      protected Simulation getObjectNamer()
      Get the object namer for a named object.
      Returns:
      the object namer for this named object
    • getName

      public final String getName()
      Get an object's name.
      Specified by:
      getName in interface NamedObjectOps
      Returns:
      the name of the object
    • canDelete

      public boolean canDelete()
      Determine if this named object can be deleted. A named object can be deleted if the method delete has not been called and if the object is not in a state that prevents the object from being deleted. Subclasses that override this method must call canDelete() for their superclasses and return false if the superclass' canDelete method returns false. The default method returns true if delete() has not been called and returned true.
      Specified by:
      canDelete in interface NamedObjectOps
      Returns:
      true if this object can be deleted; false otherwise
    • delete

      public final boolean delete()
      Delete an object. An object can only be deleted once. If this method returns true, the object (if interned) will have been removed from the object namer tables.

      The implementations provided by DefaultNamedObect and generated because of a @NamedObject annotation provide a protected method named onDelete. A subclass that overrides onDelete() must call the onDelete method of its superclass after it's onDelete method has been called and any cleanup actions performed. In some cases, this may happen at a later time (e.g., if a thread is used for some of the cleanup operations or if it is otherwise necessary to wait).

      Specified by:
      delete in interface NamedObjectOps
      Returns:
      true if the deletion request was accepted; false otherwise
    • isDeleted

      public final boolean isDeleted()
      Determine if an object has been deleted. An object is deleted if the method delete() has been called and returned true.
      Specified by:
      isDeleted in interface NamedObjectOps
      Returns:
      true if deleted; false otherwise
    • deletePending

      public final boolean deletePending()
      Determine if an object is being deleted. An deletion is pending if the method delete() has been called and returned true but the deletion has not been completed.
      Specified by:
      deletePending in interface NamedObjectOps
      Returns:
      true if deletion is pending; false otherwise