diva.canvas

Class CanvasUtilities

java.lang.Object

diva.canvas.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 and 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

Modifier and Type	Method and 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.