Chapter 16. The java.awt.geom Package

AffineTransform	Java 1.2
java.awt.geom	cloneable serializable

An AffineTransform represents an arbitrary linear transformation of a point, vector, shape, or coordinate system by any combination of translation, rotation, scaling, flipping, and skewing. This is one of the most fundamental classes in Java 2D: the Java 2D rendering process uses an AffineTransform to convert from user coordinate space to the coordinate space of the physical device. In addition to this implicit use of AffineTransform, the class is often used explicitly in Java 2D programming.

The transformations specified by AffineTransform objects are quite general. But they are all linear: straight lines remain straight, and parallel lines remain parallel under any AffineTransform. Although it is possible to imagine more general, nonlinear, transformations, Java 2D works only with affine transformations. AffineTransform is not an implementation of some more general Transform interface.

Mathematically, an affine transformation is represented by a 2-by-3 matrix of six numbers. The AffineTransform class has constructors and methods that allow you to work with this matrix directly, but unless you remember your linear algebra, you typically use the higher-level methods of this class.

You can use a constructor to create an AffineTransform, but it is usually easier to use one of the static methods to create an AffineTransform suitable for rotation about the origin, rotation about an arbitrary point, scaling, shearing, or translation. Or, if you have an existing AffineTransform object that you want to reuse, you can use one of the setTo() methods to specify a rotation, scale, shear, or translation to replace the existing transform. Note that a flip transform is simply scaling by -1.0 in the X or Y dimension.

Often, however, you have an AffineTransform that you want to transform further. The rotate(), scale(), shear(), and translate() methods do this. Or, more generally, you can use concatenate() or preConcatenate() to transform one AffineTransform by another.

Once an AffineTransform object is set to the desired transformation, the transform() method can be used to transform points, or arrays of points, in the desired way. deltaTransform() transforms a point or array of points, leaving out any translation component of the transform. This is useful for transforming dimensions and position-independent vectors, rather than transforming absolute coordinates. inverseTransform() performs the inverse of the transformation specified by an AffineTransform. Finally, createTransformedShape() returns a java.awt.Shape that represents a transformed version of the specified Shape.

isIdentity() returns true if an AffineTransform is an identity transform--that is, if it performs no transform at all. getType() returns a value that provides basic information about the transform. The value returned is TYPE_IDENTITY, TYPE_GENERAL_TRANSFORM, or a bitmask of the remaining type constants.

Hierarchy: Object-->AffineTransform(Cloneable,Serializable)

Passed To: Too many methods to list.

Returned By: Font.getTransform(), Graphics2D.getTransform(), GraphicsConfiguration.{getDefaultTransform(), getNormalizingTransform()}, java.awt.font.FontRenderContext.getTransform(), java.awt.font.GlyphVector.getGlyphTransform(), java.awt.font.TransformAttribute.getTransform(), AffineTransform.{createInverse(), getRotateInstance(), getScaleInstance(), getShearInstance(), getTranslateInstance()}, java.awt.image.AffineTransformOp.getTransform(), java.awt.image.renderable.RenderContext.getTransform()

Arc2D	Java 1.2
java.awt.geom	cloneable shape

This abstract class is a java.awt.Shape that represents an arc. The arc is defined as a portion of an ellipse, where the ellipse is defined by a rectangle. The start and end points of the arc on that ellipse are defined by a start angle and an extent angle, measured in degrees counterclockwise from the positive X axis. Unless the ellipse is actually a perfect circle, the specified angles are not true angles: a line drawn from the center of the ellipse to the upper-right corner of the bounding rectangle is always considered to form a 45-degree angle with the X axis, regardless of the true angle it forms.

In addition to the coordinates of the rectangle and the angles that specify the start and end points of the arc, the shape of an Arc2D is also specified by its arcType property. If the type of the arc is specified as CHORD, the two end points are joined by a straight line. If the type is specified as PIE, each of the two end points is joined to the center of the ellipse, forming a wedge, or slice of pie. If the type is specified as OPEN, the end points are not joined and the resulting shape is an open curve that does not enclose a region.

Arc2D is an abstract class and cannot be instantiated. Arc2D.Float and Arc2D.Double are concrete subclasses that use float and double fields to store arc coordinates and angles.

Hierarchy: Object-->RectangularShape(Cloneable,Shape)-->Arc2D

Subclasses: Arc2D.Double, Arc2D.Float

Passed To: Arc2D.setArc()

Arc2D.Double	Java 1.2
java.awt.geom	cloneable shape

This class is a concrete implementation of Arc2D that uses double fields to store the coordinates and angles of the arc. For efficiency, these x, y, width, height, start, and extent fields are declared public and may be used directly by Java programs. See Arc2D for more information.

Arc2D.Float	Java 1.2
java.awt.geom	cloneable shape

This class is a concrete implementation of Arc2D that uses float fields to store the coordinates and angles of the arc. For efficiency, these x, y, width, height, start, and extent fields are declared public and may be used directly by Java programs. See Arc2D for more information.

Area	Java 1.2
java.awt.geom	cloneable shape

Area is an implementation of java.awt.Shape that represents an arbitrary enclosed area. The Area() constructor is passed an arbitrary Shape that defines the initial area. If this Shape object represents an open curve that does not enclose an area, the curve is automatically closed with a straight line between the end points. Once an Area object has been created, it can be combined with another Area object with the add(), subtract(), intersect(), and exclusiveOr() methods. For example, you can construct an Area object that represents a hexagon minus the intersection of two circles.

Hierarchy: Object-->Area(Cloneable,Shape)

Passed To: Area.{add(), equals(), exclusiveOr(), intersect(), subtract()}

Returned By: Area.createTransformedArea()

CubicCurve2D	Java 1.2
java.awt.geom	cloneable shape

This abstract class is a java.awt.Shape that represents a smooth cubic Bezier curve (or spline) between end points p1 (x1, y1) and p2 (x2, y2). The precise shape of the curve is defined by two control points, cp1 (ctrlx1, ctrly1) and cp2 (ctrlx2, ctrly2). Note that the curve does not pass through cp1 and cp2 but that it does remain inside the quadrilateral defined by p1, cp1, cp2, and p2.

CubicCurve2D does not itself enclose an area, so the contains() methods test whether a point or rectangle is within the area defined by the curve and the straight line between its end points.

CubicCurve2D is an abstract class and cannot be instantiated. CubicCurve2D.Float and CubicCurve2D.Double are concrete subclasses that use float and double fields to store the end points and control points. See also QuadCurve2D, which is a quadratic Bezier curve that uses only a single control point.

Hierarchy: Object-->CubicCurve2D(Cloneable,Shape)

Subclasses: CubicCurve2D.Double, CubicCurve2D.Float

Passed To: CubicCurve2D.{setCurve(), subdivide()}

CubicCurve2D.Double	Java 1.2
java.awt.geom	cloneable shape

This class is a concrete implementation of CubicCurve2D that uses double fields to store the end points and control points of the curve. The X and Y coordinates of these four points are stored in public fields and may be used directly by Java programs. See CubicCurve2D for more information.

CubicCurve2D.Float	Java 1.2
java.awt.geom	cloneable shape

This class is a concrete implementation of CubicCurve2D that uses float fields to store the end points and control points of the curve. The X and Y coordinates of these four points are stored in public fields and may be used directly by Java programs. See CubicCurve2D for more information.

Dimension2D	Java 1.2
java.awt.geom	cloneable

This class represents a two-dimensional size in terms of its width and height. The accessor methods defined by this class query and set the width and height using values of type double. Note, however, that this class is abstract and does not actually store a size itself. java.awt.Dimension is a concrete subclass that stores a width and height as integers.

Hierarchy: Object-->Dimension2D(Cloneable)

Subclasses: Dimension

Passed To: Arc2D.setArc(), Dimension2D.setSize(), RectangularShape.setFrame()

Ellipse2D	Java 1.2
java.awt.geom	cloneable shape

This abstract class is a java.awt.Shape that represents an ellipse (or a circle). Ellipse2D is a subclass of RectangularShape, and for this reason, the ellipse is defined by its bounding rectangle. The width and height of the bounding rectangle specify the length of the two axes of the ellipse. (If the width and height are equal, the ellipse is a circle.) The X and Y coordinates of the ellipse specify the upper-left corner of the bounding rectangle; note that this point actually falls outside of the ellipse. The setFrameFromCenter() method, inherited from RectangularShape, allows you to define the ellipse by specifying the center and one corner. Note that Ellipse2D can only represent ellipses whose axes are parallel to the X and Y axes of the coordinate system. In order to work with rotated ellipses, use the createTransformedShape() method of AffineTransform or some other transformation method.

Ellipse2D is an abstract class and cannot be instantiated. The concrete subclasses Ellipse2D.Double and Ellipse2D.Float represent ellipses using double and float fields to contain the rectangular coordinates.

Hierarchy: Object-->RectangularShape(Cloneable,Shape)-->Ellipse2D

Subclasses: Ellipse2D.Double, Ellipse2D.Float

Ellipse2D.Double	Java 1.2
java.awt.geom	cloneable shape

This class is a concrete implementation of Ellipse2D that uses double fields to store the coordinates of the bounding rectangle of the ellipse. These x, y, width, height fields are declared public and may be used directly by Java programs. See Ellipse2D for more information.

Ellipse2D.Float	Java 1.2
java.awt.geom	cloneable shape

This class is a concrete implementation of Ellipse2D that uses float fields to store the coordinates of the bounding rectangle of the ellipse. Note that these x, y, width, height fields are declared public and may be used directly by Java programs. See Ellipse2D for more information.

FlatteningPathIterator	Java 1.2
java.awt.geom

This class is a PathIterator that flattens the curves returned by another PathIterator, approximating them with straight-line segments that are easier to work with. The currentSegment() methods of FlatteningPathIterator are guaranteed never to return SEG_QUADTO or SEG_CUBICTO curve segments.

The flatness of a cubic or quadratic curve is the distance from the curve to its control points. Smaller distances imply flatter curves (i.e., curves that are closer to a straight line). The flatness argument to the FlatteningPathIterator() constructor specifies how flat a curve must be before it is approximated with a flat line. Smaller values of flatness result in increasingly accurate approximations of the curves.

When a FlatteningPathIterator encounters a curve that is not flat enough to approximate with a straight line, it subdivides the curve into two curves, each of which is flatter than the original curve. This process of subdivision continues recursively until the subdivided curves are flat enough to be approximated with line segments, up to the num ber of times specified by the limit argument. If limit is not specified, a default of 10 is used, which means that no curve is broken down into more than 1,024 separate line segments.

You should rarely need to use a FlatteningPathIterator explicitly in Java 2D programming. The two-argument version of the getPathIterator() method of Shape takes a flatness argument and returns a flattened path that does not contain any curves. Implementations of this method typically use FlatteningPathIterator internally.

Hierarchy: Object-->FlatteningPathIterator(PathIterator)

GeneralPath	Java 1.2
java.awt.geom	cloneable shape

This class represents an arbitrary path or shape that consists of any number of line segments and quadratic and cubic Bezier curves. After creating a GeneralPath object, you must define a current point by calling moveTo(). Once an initial current point is established, you can create the path by calling lineTo(), quadTo(), and curveTo(). These methods draw line segments, quadratic curves, and cubic curves from the current point to a new point (which becomes the new current point).

The shape defined by a GeneralPath need not be closed, although you may close it by calling the closePath() method, which appends a line segment between the current point and the initial point. Similarly, the path need not be continuous: you can call moveTo() at any time to change the current point without adding a connecting line or curve to the path. The append() method allows you to add a Shape or PathIterator to a GeneralPath, optionally connecting it to the current point with a straight line.

The GeneralPath() constructor allows you to specify an estimate of the number of path segments that will be added. Specifying an accurate estimate can increase efficiency. It also allows you to specify the winding rule to use for the path. A winding rule is used to determine what points are contained within a GeneralPath. The choice of winding rules matters only for those paths that intersect themselves. The two choices are WIND_EVEN_ODD and WIND_NON_ZERO.

Note the close correspondence between the path elements (lines, quadratic curves, and cubic curves) that may be appended to a GeneralPath and those that are enumerated by a PathIterator object.

Hierarchy: Object-->GeneralPath(Cloneable,Shape)

IllegalPathStateException	Java 1.2
java.awt.geom	serializable unchecked

Signals that a path is not in an appropriate state for some requested operation. This exception is thrown if you attempt to append a path segment to a GeneralPath before performing an initial moveTo().

Hierarchy: Object-->Throwable(Serializable)-->Exception-->RuntimeException-->IllegalPathStateException

Line2D	Java 1.2
java.awt.geom	cloneable shape

This abstract class is a java.awt.Shape that represents a line segment between two end points. Line2D defines various methods for computing the distance between a point and a line or line segment and for computing the position of a point relative to a line. Note, however, that the setLine() method for specifying the end points of the line segment is abstract. The concrete subclasses Line2D.Double and Line2D.Float use double and float fields to store the coordinates of the end points. They define the setLine() method and constructors that accept the line segment end points as arguments. Since a line does not contain an area, the contains() methods of Line2D and of its subclasses always return false.

Hierarchy: Object-->Line2D(Cloneable,Shape)

Subclasses: Line2D.Double, Line2D.Float

Passed To: Line2D.{intersectsLine(), setLine()}, Rectangle2D.intersectsLine()

Line2D.Double	Java 1.2
java.awt.geom	cloneable shape

This class is a concrete implementation of Line2D that uses double fields to store the end points of the line segment. These end points are stored in public fields and may be directly set and queried by programs. See Line2D for more information.

Line2D.Float	Java 1.2
java.awt.geom	cloneable shape

This class is a concrete implementation of Line2D that uses float fields to store the end points of the line segment. These end points are stored in public fields and may be directly set and queried by programs. See Line2D for more information.

NoninvertibleTransformException	Java 1.2
java.awt.geom	serializable checked

Thrown when the inverse of a noninvertible AffineTransform is required. An example of a noninvertible transformation is scaling the X dimension by a factor of 0. This maps all points onto a vertical line, leaving no information about transforming those points back to their original locations. This transform is noninvertible because division by zero is not possible.

Hierarchy: Object-->Throwable(Serializable)-->Exception-->NoninvertibleTransformException

Thrown By: AffineTransform.{createInverse(), inverseTransform()}

PathIterator	Java 1.2
java.awt.geom

This interface is the basic Java 2D mechanism for defining arbitrary shapes. The most important requirement of the java.awt.Shape interface is that every shape be able to return a PathIterator that traverses the outline of the shape. The information returned by a PathIterator is sufficient to allow the Java 2D rendering engine to stroke (draw) or fill arbitrarily complex shapes.

A PathIterator breaks a shape or path down into individual path segments. The currentSegment() method returns the current segment. The next() method moves the iterator on to the next segment, and isDone() returns true if there are no more segments left to iterate. getWindingRule() returns the winding rule for the shape--this value is used to determine which points are inside complex self-intersecting shapes. The two possible values are WIND_EVEN_ODD and WIND_NON_ZERO.

currentSegment() is the most important method of PathIterator. Its return value, one of the five integer constants whose names begin with SEG, specifies the type of the current segment. currentSegment() returns the coordinates of the current segment in the float or double array passed as an argument. This array must have at least six elements. The segment types and their meanings are as follows:

SEG_MOVETO

Defines a path starting point rather than an actual segment. The current point of the path is set to the X,Y point specified in the first two elements of the array. This is the first segment type of all paths. Paths may be disjoint, and may have more than one SEG_MOVETO segment.

SEG_LINETO

Defines a line between the current point and the X,Y end point stored in the first two elements of the array. The end point of the line segment becomes the new current point.

SEG_QUADTO

Defines a quadratic Bezier curve between the current point and an end point stored in the third and fourth elements of the array, using a control point stored in the first and second elements of the array. The end point of the curve becomes the current point.

SEG_CUBICTO

Defines a cubic Bezier curve between the current point and an end point stored in the fifth and sixth elements of the array, using two control points stored in the first through fourth elements of the array. The end point of the curve becomes the current point.

SEG_CLOSE

Specifies that the path should be closed by drawing a straight line from the current point back to the point specified by the most recent SEG_MOVETO segment. No values are stored in the array for this segment type.

Implementations: FlatteningPathIterator

Passed To: FlatteningPathIterator.FlatteningPathIterator(), GeneralPath.append()

Returned By: Too many methods to list.

Point2D	Java 1.2
java.awt.geom	cloneable

This abstract class represents a point in two-dimensional space. It has methods for getting and setting the X and Y coordinates of the point as double values and for computing the distance between points.

Point2D is abstract; it does not store actual coordinates and cannot be instantiated. You must use one of its concrete subclasses instead. Point2D.Double stores the coordinates of a point using double fields, while Point2D.Float stores the coordinates using float fields. Finally, java.awt.Point stores the coordinates using int fields.

Hierarchy: Object-->Point2D(Cloneable)

Subclasses: Point, Point2D.Double, Point2D.Float

Passed To: Too many methods to list.

Returned By: Too many methods to list.

Point2D.Double	Java 1.2
java.awt.geom	cloneable

This class is a concrete implementation of Point2D that stores the X and Y coordinates of a point using double fields. These fields are public and can be queried and set directly, without using accessor methods.

Point2D.Float	Java 1.2
java.awt.geom	cloneable

This class is a concrete implementation of Point2D that stores the X and Y coordinates of a point using float fields. These fields are public and can be queried and set directly, without using accessor methods.

QuadCurve2D	Java 1.2
java.awt.geom	cloneable shape

This abstract class is a java.awt.Shape that represents a smooth quadratic Bezier curve (or spline) between end points p1 (x1, y1) and p2 (x2, y2). The precise shape of the curve is defined by a control point, cp (ctrlx, ctrly). Note that the curve does not pass through cp but that it does remain inside the triangle defined by p1, cp, and p2.

QuadCurve2D does not itself enclose an area, so the contains() methods test whether a point or rectangle is within the area defined by the curve and the straight line between its end points.

QuadCurve2D is an abstract class and cannot be instantiated. QuadCurve2D.Float and QuadCurve2D.Double are concrete subclasses that use float and double fields to store the end points and control point. See also CubicCurve2D, which is a cubic Bezier curve that uses two control points.

Hierarchy: Object-->QuadCurve2D(Cloneable,Shape)

Subclasses: QuadCurve2D.Double, QuadCurve2D.Float

Passed To: QuadCurve2D.{setCurve(), subdivide()}

QuadCurve2D.Double	Java 1.2
java.awt.geom	cloneable shape

This class is a concrete implementation of QuadCurve2D that uses double fields to store the end points and control point of the curve. The X and Y coordinates of these three points are stored in public fields and may be used directly by Java programs. See QuadCurve2D for more information.

QuadCurve2D.Float	Java 1.2
java.awt.geom	cloneable shape

This class is a concrete implementation of QuadCurve2D that uses float fields to store the end points and control point of the curve. The X and Y coordinates of these three points are stored in public fields and may be used directly by Java programs. See QuadCurve2D for more information.

Rectangle2D	Java 1.2
java.awt.geom	cloneable shape

This abstract java.awt.Shape represents a rectangle specified by the location of its upper-left corner, its width, and its height. Various methods compute intersections and unions of rectangles, test whether a rectangle contains a point or contains another rectangle, and test whether a rectangle intersects a line or another rectangle. The outcode() method determines the spatial relationship between a point and a rectangle. The return value is the sum of the OUT_ constants that specify which edges of the rectangle a point is outside of. A value of 0 means that the point is inside the rectangle, of course. Other interesting methods include setFrameFromDiagonal() and setFrameFromCenter(), inherited from RectangularShape.

Rectangle2D is an abstract class that does not define any fields to store the size and position of the rectangle and cannot be instantiated. Choose a concrete subclass based on the type of data fields you desire: Rectangle2D.Double uses double fields, Rectangle2D.Float uses float fields, and java.awt.Rectangle uses int fields.

Hierarchy: Object-->RectangularShape(Cloneable,Shape)-->Rectangle2D

Subclasses: Rectangle, Rectangle2D.Double, Rectangle2D.Float

Passed To: Too many methods to list.

Returned By: Too many methods to list.

Rectangle2D.Double	Java 1.2
java.awt.geom	cloneable shape

This concrete subclass of Rectangle2D stores the position and size of the rectangle in fields of type double. These fields are declared public and can be set and queried directly without relying on accessor methods.

Rectangle2D.Float	Java 1.2
java.awt.geom	cloneable shape

This concrete subclass of Rectangle2D stores the position and size of the rectangle in fields of type float. These fields are declared public and can be set and queried directly without relying on accessor methods.

RectangularShape	Java 1.2
java.awt.geom	cloneable shape

This abstract class is the base class for several java.awt.Shape implementations that have a rectangular outline or bounding box. Its methods allow you to set and query the size and position of the bounding rectangle in several interesting ways.

Hierarchy: Object-->RectangularShape(Cloneable,Shape)

Subclasses: Arc2D, Ellipse2D, Rectangle2D, RoundRectangle2D

RoundRectangle2D	Java 1.2
java.awt.geom	cloneable shape

This abstract java.awt.Shape represents a rectangle with rounded corners, specified by the position of the upper-left corner (before rounding), the width and height of the rectangle, and the width and height of the arc used to round the corners. RoundRectangle2D is abstract and may not be instantiated. Use the concrete subclasses RoundRectangle2D.Double and RoundRectangle2D.Float, depending on the precision you desire for the rectangle coordinates and dimensions.

Hierarchy: Object-->RectangularShape(Cloneable,Shape)-->RoundRectangle2D

Subclasses: RoundRectangle2D.Double, RoundRectangle2D.Float

Passed To: RoundRectangle2D.setRoundRect(), RoundRectangle2D.Double.setRoundRect(), RoundRectangle2D.Float.setRoundRect()

RoundRectangle2D.Double	Java 1.2
java.awt.geom	cloneable shape

This concrete subclass of RoundRectangle2D stores the position and size of the rectangle and the size of the rounded corners in fields of type double. These fields are declared public and can be set and queried directly without relying on accessor methods.

RoundRectangle2D.Float	Java 1.2
java.awt.geom	cloneable shape

This concrete subclass of RoundRectangle2D stores the position and size of the rectangle and the size of the rounded corners in fields of type float. These fields are declared public and can be set and queried directly without relying on accessor methods.