CanvasUtilities (Starlink-UK API)

java.lang.Object
- diva.canvas.CanvasUtilities

```
public final class CanvasUtilities
extends 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:

$Revision: 1.27 $

Author:

John Reekie

Method Summary

All Methods Static Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`static Shape`	`clone(Shape s)` Deprecated. Use ShapeUtilities.cloneShape() instead
`static Rectangle2D`	`computeCompositeBounds(Iterator i)` Compute a composite bounding box.
`static Shape`	`computeCompositeShape(Iterator i)` Compute a composite shape.
`static AffineTransform`	`computeFitTransform(RectangularShape r, RectangularShape s)` Get the transform that will make the first rectangle change fit within the second, while preserving the shape.
`static Rectangle2D`	`computeSiteBounds(Iterator i)` Compute the bounding box of a set of connectors.
`static AffineTransform`	`computeTransform(RectangularShape r, RectangularShape s)` Get the transform that will make the first rectangle change into the second.
`static Point2D`	`getCenterPoint(Figure f)` Return the point at the center of a figure.
`static Point2D`	`getCenterPoint(Figure f, TransformContext root)` Return the point at the center of a figure, in the given transform context.
`static Point2D`	`getCenterPoint(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 Point2D`	`getLocation(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(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(Iterator i, Rectangle2D region)` Return the first figure that is hit by the given region.
`static Figure`	`pick(Iterator i, Rectangle2D region, Filter filter)` Return the first figure that is hit by the given region.
`static Iterator`	`pickIter(Iterator i, Rectangle2D region)` Return an iterator over the figures hit by the given region.
`static int`	`reverseDirection(int direction)` Reverse a direction flag.
`static Shape`	`transform(RectangularShape r, AffineTransform at)` Deprecated. Use diva.util.java2d.ShapeUtilities.transformRectangle() or diva.util.java2d.ShapeUtilities.transformRectangularShape()
`static Shape`	`transform(Shape s, AffineTransform at)` Deprecated. Use ShapeUtilities.transformModify()
`static Point2D`	`transformInto(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 Point2D`	`translate(Point2D.Double p, double distance, int direction)` Translate a point the given distance in the direction given by the flag.
`static Point2D`	`translate(Point2D.Float p, double distance, int direction)` Translate a point the given distance in the direction given by the flag.
`static Point2D`	`translate(Point2D p, double distance, int direction)` Translate a point the given distance in the direction given by the flag.
`static Shape`	`translate(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

- Method Detail
  - clone
```
public static Shape clone(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.
  - computeCompositeShape
```
public static Shape computeCompositeShape(Iterator 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.
  - computeSiteBounds
```
public static Rectangle2D computeSiteBounds(Iterator i)
```
    Compute the bounding box of a set of connectors. The iterator must contain connectors.
  - computeCompositeBounds
```
public static Rectangle2D computeCompositeBounds(Iterator 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.
  - computeTransform
```
public static AffineTransform computeTransform(RectangularShape r,
                                               RectangularShape s)
```
    Get the transform that will make the first rectangle change into the second.
  - computeFitTransform
```
public static AffineTransform computeFitTransform(RectangularShape r,
                                                  RectangularShape s)
```
    Get the transform that will make the first rectangle change fit within the second, while preserving the shape.
  - getCenterPoint
```
public static Point2D getCenterPoint(Rectangle2D r)
```
    Return the point at the center of a Rectangle.
  - getCenterPoint
```
public static 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.
  - getCenterPoint
```
public static 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.
  - 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.
  - 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.
  - getLocation
```
public static Point2D getLocation(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.
  - isOrthogonal
```
public static boolean isOrthogonal(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.
  - moduloAngle
```
public static double moduloAngle(double angle)
```
    Return the angle between -PI and PI that corresponds to the given angle.
  - pick
```
public static Figure pick(Iterator i,
                          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(Iterator i,
                          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
    
    Returns:
    
    The topmost descendent under the pick region, or null there isn't one.
  - pickIter
```
public static Iterator pickIter(Iterator i,
                                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.
  - transform
```
public static Shape transform(RectangularShape r,
                              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.
  - transform
```
public static Shape transform(Shape s,
                              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.
  - transformInto
```
public static Point2D transformInto(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.
  - 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.
  - translate
```
public static Point2D translate(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.
  - translate
```
public static Point2D translate(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.
  - translate
```
public static Point2D translate(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.
  - translate
```
public static Shape translate(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.
  - translateTo
```
public static void translateTo(Figure f,
                               double x,
                               double y)
```
    Move a figure so that its origin is located at the given coordinates.

Class CanvasUtilities

Method Summary

Methods inherited from class java.lang.Object

Method Detail

clone

computeCompositeShape

computeSiteBounds

computeCompositeBounds

computeTransform

computeFitTransform

getCenterPoint

getCenterPoint

getCenterPoint

getDirection

getNormal

getLocation

isOrthogonal

moduloAngle

pick

pick

pickIter

reverseDirection

transform

transform

transformInto

translate

translate

translate

translate

translate

translateTo