Package diva.canvas

Class CanvasUtilities

  • public final class CanvasUtilities
extends java.lang.Object
    A collection of canvas utilities. These utilities perform useful functions related to the structural aspects of diva.canvas that do not properly belong in any one class. Some of them perform utility geometric functions that are not available in the Java 2D API, while others accept iterators over Figures or Shapes and compute a useful composite result.
    Version:
    $Id$
    Author:
    John Reekie
    Pt.AcceptedRating:
    Red

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static double EAST
      double representation of EAST: 0 degrees.
      static double NORTH
      double representation of NORTH: -90 degrees (-PI/2).
      static double NORTHEAST
      double representation of NORTHEAST: -45 degrees (PI/4).
      static double NORTHWEST
      double representation of NORTHWEST: -135 degrees (-PI*3/4).
      static double SOUTH
      double representation of SOUTH: 90 degrees (PI/2).
      static double SOUTHEAST
      double representation of SOUTHEAST: 45 degrees (PI/4).
      static double SOUTHWEST
      double representation of SOUTHWEST: 135 degrees (PI*3/4).
      static double WEST
      double representation of WEST: 180 degrees (PI).

    • Method Summary

      All Methods Static Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      static java.awt.Shape clone​(java.awt.Shape s)
      Deprecated.
      Use ShapeUtilities.cloneShape() instead
      static java.awt.geom.Rectangle2D computeCompositeBounds​(java.util.Iterator<Figure> i)
      Compute a composite bounding box.
      static java.awt.Shape computeCompositeShape​(java.util.Iterator<Figure> i)
      Compute a composite shape.
      static java.awt.geom.AffineTransform computeFitTransform​(java.awt.geom.RectangularShape r, java.awt.geom.RectangularShape s)
      Get the transform that will make the first rectangle change fit within the second, while preserving the shape.
      static java.awt.geom.Rectangle2D computeSiteBounds​(java.util.Iterator<Site> i)
      Compute the bounding box of a set of connectors.
      static java.awt.geom.AffineTransform computeTransform​(java.awt.geom.RectangularShape r, java.awt.geom.RectangularShape s)
      Get the transform that will make the first rectangle change into the second.
      static java.awt.geom.Point2D getCenterPoint​(Figure f)
      Return the point at the center of a figure.
      static java.awt.geom.Point2D getCenterPoint​(Figure f, TransformContext root)
      Return the point at the center of a figure, in the given transform context.
      static java.awt.geom.Point2D getCenterPoint​(java.awt.geom.Rectangle2D r)
      Return the point at the center of a Rectangle.
      static int getDirection​(double angle)
      Return the closest direction from SwingConstants, based on the given angle.
      static java.awt.geom.Point2D getLocation​(java.awt.geom.Rectangle2D r, int location)
      Get the point on the given rectangular shape indicated by the location flag.
      static double getNormal​(int direction)
      Return an angle in radians, given a direction from SwingConstants.
      static boolean isOrthogonal​(java.awt.geom.AffineTransform at)
      Return true if the given transform maps a rectangle to a rectangle.
      static double moduloAngle​(double angle)
      Return the angle between -PI and PI that corresponds to the given angle.
      static Figure pick​(java.util.Iterator i, java.awt.geom.Rectangle2D region)
      Return the first figure that is hit by the given region.
      static Figure pick​(java.util.Iterator i, java.awt.geom.Rectangle2D region, Filter filter)
      Return the first figure that is hit by the given region.
      static java.util.Iterator pickIter​(java.util.Iterator i, java.awt.geom.Rectangle2D region)
      Return an iterator over the figures hit by the given region.
      static int reverseDirection​(int direction)
      Reverse a direction flag.
      static java.awt.Shape transform​(java.awt.geom.RectangularShape r, java.awt.geom.AffineTransform at)
      Deprecated.
      Use diva.util.java2d.ShapeUtilities.transformRectangle() or diva.util.java2d.ShapeUtilities.transformRectangularShape()
      static java.awt.Shape transform​(java.awt.Shape s, java.awt.geom.AffineTransform at)
      Deprecated.
      Use ShapeUtilities.transformModify()
      static java.awt.geom.Point2D transformInto​(java.awt.geom.Point2D p, TransformContext local, TransformContext root)
      Deprecated.
      Use local.getTransform(root) instead.
      static void translate​(Figure f, double distance, int direction)
      Translate a figure the given distance in the direction given by the flag.
      static java.awt.geom.Point2D translate​(java.awt.geom.Point2D.Double p, double distance, int direction)
      Translate a point the given distance in the direction given by the flag.
      static java.awt.geom.Point2D translate​(java.awt.geom.Point2D.Float p, double distance, int direction)
      Translate a point the given distance in the direction given by the flag.
      static java.awt.geom.Point2D translate​(java.awt.geom.Point2D p, double distance, int direction)
      Translate a point the given distance in the direction given by the flag.
      static java.awt.Shape translate​(java.awt.Shape s, double x, double y)
      Deprecated.
      Use ShapeUtilities.translateModify()
      static void translateTo​(Figure f, double x, double y)
      Move a figure so that its origin is located at the given coordinates.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • WEST

        public static final double WEST
        double representation of WEST: 180 degrees (PI).
        See Also:
        Constant Field Values

      • NORTH

        public static final double NORTH
        double representation of NORTH: -90 degrees (-PI/2).
        See Also:
        Constant Field Values

      • EAST

        public static final double EAST
        double representation of EAST: 0 degrees.
        See Also:
        Constant Field Values

      • SOUTH

        public static final double SOUTH
        double representation of SOUTH: 90 degrees (PI/2).
        See Also:
        Constant Field Values

      • NORTHWEST

        public static final double NORTHWEST
        double representation of NORTHWEST: -135 degrees (-PI*3/4).
        See Also:
        Constant Field Values

      • NORTHEAST

        public static final double NORTHEAST
        double representation of NORTHEAST: -45 degrees (PI/4).
        See Also:
        Constant Field Values

      • SOUTHWEST

        public static final double SOUTHWEST
        double representation of SOUTHWEST: 135 degrees (PI*3/4).
        See Also:
        Constant Field Values

      • SOUTHEAST

        public static final double SOUTHEAST
        double representation of SOUTHEAST: 45 degrees (PI/4).
        See Also:
        Constant Field Values

    • Method Detail

      • clone

        @Deprecated
public static java.awt.Shape clone​(java.awt.Shape s)
        Deprecated.
        Use ShapeUtilities.cloneShape() instead
        Clone a shape. This method is needed because Shape by itself does not define clone(), although many (all?) shape instances do.
        Parameters:
        s - The shape.
        Returns:
        The clone

      • computeCompositeShape

        public static java.awt.Shape computeCompositeShape​(java.util.Iterator<Figure> i)
        Compute a composite shape. The iterator must contain figures, from which the shapes are obtained and joined into a more complex shape. If the iterator is empty, return a very small rectangle.
        Parameters:
        i - The iterator of Figures
        Returns:
        The composite shape

      • computeSiteBounds

        public static java.awt.geom.Rectangle2D computeSiteBounds​(java.util.Iterator<Site> i)
        Compute the bounding box of a set of connectors. The iterator must contain connectors.
        Parameters:
        i - the iterator of Sites
        Returns:
        The bounding box

      • computeCompositeBounds

        public static java.awt.geom.Rectangle2D computeCompositeBounds​(java.util.Iterator<Figure> i)
        Compute a composite bounding box. The iterator must contain figures, from which the bounding boxes are obtained and joined into a more complex shape. If the iterator is empty, return a very small rectangle.
        Parameters:
        i - The iterator of Figures.
        Returns:
        The bounding box

      • computeTransform

        public static java.awt.geom.AffineTransform computeTransform​(java.awt.geom.RectangularShape r,
                                                             java.awt.geom.RectangularShape s)
        Get the transform that will make the first rectangle change into the second.
        Parameters:
        r - The shape to be transformed.
        s - The resulting shape.
        Returns:
        The transformation

      • computeFitTransform

        public static java.awt.geom.AffineTransform computeFitTransform​(java.awt.geom.RectangularShape r,
                                                                java.awt.geom.RectangularShape s)
        Get the transform that will make the first rectangle change fit within the second, while preserving the shape.
        Parameters:
        r - The shape to be transformed.
        s - The resulting shape.
        Returns:
        The transformation

      • getCenterPoint

        public static java.awt.geom.Point2D getCenterPoint​(java.awt.geom.Rectangle2D r)
        Return the point at the center of a Rectangle.
        Parameters:
        r - The Rectangle.
        Returns:
        The point at the center.

      • getCenterPoint

        public static java.awt.geom.Point2D getCenterPoint​(Figure f)
        Return the point at the center of a figure. This is simple but so common it's worth having a method for it.
        Parameters:
        f - The figure.
        Returns:
        The point at the center.

      • getCenterPoint

        public static java.awt.geom.Point2D getCenterPoint​(Figure f,
                                                   TransformContext root)
        Return the point at the center of a figure, in the given transform context. This is simple but so common it's worth having a method for it.
        Parameters:
        f - The figure.
        root - The TransformContext.
        Returns:
        The point at the center.

      • getDirection

        public static int getDirection​(double angle)
        Return the closest direction from SwingConstants, based on the given angle. West corresponds to 0 degrees and south is PI/2.
        Parameters:
        angle - The angle
        Returns:
        The direction, see SwingConstants

      • getNormal

        public static double getNormal​(int direction)
        Return an angle in radians, given a direction from SwingConstants. West corresponds to 0 degrees and south is PI/2. The angle returned is between -PI and PI as per the normalizeAngle method.
        Parameters:
        direction - The direction, see SwingConstants.
        Returns:
        The angle of the normal in radians.

      • getLocation

        public static java.awt.geom.Point2D getLocation​(java.awt.geom.Rectangle2D r,
                                                int location)
        Get the point on the given rectangular shape indicated by the location flag. This flag must be one of those defined in javax.swing.Constants.
        Parameters:
        r - The give rectangle
        location - One of the directions (CENTER, NORTH etc.) defined in SwingConstants.
        Returns:
        The point.

      • isOrthogonal

        public static boolean isOrthogonal​(java.awt.geom.AffineTransform at)
        Return true if the given transform maps a rectangle to a rectangle. If this method returns true, then passing a rectangle to transform() is guaranteed to return a rectangle.
        Parameters:
        at - The AffineTransformation
        Returns:
        True if it is orthogonal.

      • moduloAngle

        public static double moduloAngle​(double angle)
        Return the angle between -PI and PI that corresponds to the given angle.
        Parameters:
        angle - The angle
        Returns:
        The modulo of the angle.

      • pick

        public static Figure pick​(java.util.Iterator i,
                          java.awt.geom.Rectangle2D region)
        Return the first figure that is hit by the given region. The figures tested are contained in the given iterator, which must contain only figures. And figure that is also a FigureContainer is descended into recursively; other figures are simply tested using their hit() method.
        Parameters:
        i - An iterator over figures
        region - A rectangle which represents the pick or hit region
        Returns:
        The topmost descendent under the pick region, or null there isn't one.

      • pick

        public static Figure pick​(java.util.Iterator i,
                          java.awt.geom.Rectangle2D region,
                          Filter filter)
        Return the first figure that is hit by the given region. The figures tested are contained in the given iterator, which must contain only figures. And figure that is also a FigureContainer is descended into recursively; other figures are simply tested using their hit() method.
        Parameters:
        i - An iterator over figures
        region - A rectangle which represents the pick or hit region
        filter - The filter that is called to accept the figure.
        Returns:
        The topmost descendent under the pick region, or null there isn't one.

      • pickIter

        public static java.util.Iterator pickIter​(java.util.Iterator i,
                                          java.awt.geom.Rectangle2D region)
        Return an iterator over the figures hit by the given region. The figures tested are contained in the given iterator, which must contain only figures. And figure that is also a FigureContainer is descended into recursively; other figures are simply tested using their hit() method. XXX how to do this?
        Parameters:
        i - An iterator over figures
        region - A rectangle which represents the pick or hit region
        Returns:
        An iterator over the hit figures.

      • reverseDirection

        public static int reverseDirection​(int direction)
        Reverse a direction flag. The flag must one of the eight compass directions defined in SwingConstants. Return the flag that represents the opposite direction.
        Parameters:
        direction - One of the directions from SwingContatn
        Returns:
        The opposite direction.

      • transform

        @Deprecated
public static java.awt.Shape transform​(java.awt.geom.RectangularShape r,
                                       java.awt.geom.AffineTransform at)
        Deprecated.
        Use diva.util.java2d.ShapeUtilities.transformRectangle() or diva.util.java2d.ShapeUtilities.transformRectangularShape()
        Transform a shape with the supplied transform. If the shape is an instance of RectangularShape, then the transformation will modify that shape and return it if it is possible to do so. Otherwise, AffineTransform.createTransformedShape() is used to create a new shape, which is then returned.
        Parameters:
        r - The rectangular shape
        at - The AffineTransform
        Returns:
        The shape after the transformation.

      • transform

        @Deprecated
public static java.awt.Shape transform​(java.awt.Shape s,
                                       java.awt.geom.AffineTransform at)
        Deprecated.
        Use ShapeUtilities.transformModify()
        Transform a shape with the supplied transform. As much as possible, this method attempts to preserve the type of the shape and to modify it directly if possible: if the shape of this figure is an instance of RectangularShape or Polyline, then the shape may be modified directly. Otherwise, a general transformation is used that creates and returns a new instance of GeneralPath.
        Parameters:
        s - The shape
        at - The AffineTransform
        Returns:
        The shape after the transformation.

      • transformInto

        @Deprecated
public static java.awt.geom.Point2D transformInto​(java.awt.geom.Point2D p,
                                                  TransformContext local,
                                                  TransformContext root)
        Deprecated.
        Use local.getTransform(root) instead.
        Transform a point from a local transform context into a root transform context. The root context must enclose the local one, otherwise this method goes into an infinite loop. You asked for it.
        Parameters:
        p - The point to be transformed
        local - The local context
        root - The root
        Returns:
        The transformed point

      • translate

        public static void translate​(Figure f,
                             double distance,
                             int direction)
        Translate a figure the given distance in the direction given by the flag. The flag must one of the eight compass directions defined in SwingConstants.
        Parameters:
        f - The figure.
        distance - The distance.
        direction - One of the eight compass directions defined in javax.swing.SwingConstants.

      • translate

        public static java.awt.geom.Point2D translate​(java.awt.geom.Point2D p,
                                              double distance,
                                              int direction)
        Translate a point the given distance in the direction given by the flag. The flag must one of the eight compass directions defined in SwingConstants. Return the same point, but modified.
        Parameters:
        p - The point to be translated as a Float or Double.
        distance - The distance.
        direction - One of the eight compass directions defined in javax.swing.SwingConstants.
        Returns:
        The translated point.

      • translate

        public static java.awt.geom.Point2D translate​(java.awt.geom.Point2D.Double p,
                                              double distance,
                                              int direction)
        Translate a point the given distance in the direction given by the flag. The flag must one of the eight compass directions defined in SwingConstants. Return the same point, but modified.
        Parameters:
        p - The point to be translated as a Double.
        distance - The distance.
        direction - One of the eight compass directions defined in javax.swing.SwingConstants.
        Returns:
        The translated point.

      • translate

        public static java.awt.geom.Point2D translate​(java.awt.geom.Point2D.Float p,
                                              double distance,
                                              int direction)
        Translate a point the given distance in the direction given by the flag. The flag must one of the eight compass directions defined in SwingConstants. Return the same point, but modified.
        Parameters:
        p - The point to be translated as a float.
        distance - The distance.
        direction - One of the eight compass directions defined in javax.swing.SwingConstants.
        Returns:
        The translated point.

      • translate

        @Deprecated
public static java.awt.Shape translate​(java.awt.Shape s,
                                       double x,
                                       double y)
        Deprecated.
        Use ShapeUtilities.translateModify()
        Translate a shape the given distance. If it is possible to do so, perform this translation efficiently, modifying and returning the passed shape. Otherwise use AffineTransform.createTransformedShape() to create a new translated shape, and return that.
        Parameters:
        s - The shape to translate.
        x - amount to translate.
        y - amount to translate.
        Returns:
        The transformed shape

      • translateTo

        public static void translateTo​(Figure f,
                               double x,
                               double y)
        Move a figure so that its origin is located at the given coordinates. If the figure is centered, the origin is the center of the figure. If it is not, then the origin is 0,0.
        Parameters:
        f - The figure to be moved.
        x - The new x location.
        y - The new y location.