Documentation Contents

Chapter    3

Geometries

The Java 2D API provides several classes that define common geometric objects, such as points, lines, curves, and rectangles. These new geometry classes are part of the java.awt.geom package. For backward compatibility, the geometry classes that existed in previous versions of the JDK, such as Rectangle, Point, and Polygon, remain in the java.awt package.

The Java 2D API geometries such as GeneralPath, Arc2D, and Rectangle2D implement the Shape interface defined in java.awt. Shape provides a common protocol for describing and inspecting geometric path objects. A new interface, PathIterator, defines methods for retrieving elements from a geometry.

Using the geometry classes, you can easily define and manipulate virtually any two-dimensional object.

3.1 Interfaces and Classes

The following tables list the key geometry interfaces and classes. Most of these interfaces and classes are part of the java.awt.geom package. Some, like Shape, are part of the java.awt package, primarily to maintain backward compatibility with earlier versions of the JDK.

3.2 Geometry Concepts

A Shape is an instance of any class that implements the Shape interface, such as GeneralPath or Rectangle2D.Float. A Shape’s contour (outline) is referred to as its path.

When a Shape is drawn, the pen style defined by the Stroke object in the Graphics2D context is applied to the Shape’s path. When a Shape is filled, the Paint in the Graphics2D context is applied to the area within its path. For more information, see “Rendering with Graphics2D”.

A Shape’s path can be also used to define a clipping path. A clipping path determines what pixels are rendered—only those pixels that lie within the area defined by the clipping path are rendered. The clipping path is part of the Graphics2D context. For more information, see “Setting the Clipping Path”.

A GeneralPath is a shape that can be used to represent any two-dimensional object that can be constructed from lines and quadratic or cubic curves. For convenience, java.awt.geom provides additional implementations of the Shape interface that represent common geometric objects such as rectangles, ellipses, arcs, and curves. The Java 2D API also provides a special type of shape that supports constructive area geometry.

3.2.1 Constructive Area Geometry

Constructive Area Geometry (CAG) is the process of creating new geometric objects by performing boolean operations on existing objects. In the Java 2D API, a special type of Shape called an Area supports boolean operations. You can construct an Area from any Shape.

Areas support the following Boolean operations:

• Union
• Intersection
• Subtraction
• Exclusive OR (XOR)

These operations are illustrated in Figure 3-1.

3.2.2 Bounds and Hit Testing

A bounding box is a rectangle that fully encloses a shape’s geometry. Bounding boxes are used to determine whether or not an object has been selected or “hit” by the user.

The Shape interface defines two methods for retrieving a shape’s bounding box, getBounds and getBounds2D. The getBounds2D method returns a Rectangle2D instead of a Rectangle, providing a higher-precision description of the shape’s bounding box.

Shape also provides methods for determining whether or not:

• A specified point lies within the bounds of the shape (contains)
• A specified rectangle lies totally within the bounds of the shape (contains)
• A specified rectangle intersects the shape (intersects)

3.3 Combining Areas to Create New Shapes

Areas can be used to quickly construct complex Shapes from simple shapes such as circles and squares. To create a new complex Shape by combining Areas:

• Using Shapes, construct the Areas to be combined.
• Call the appropriate Boolean operators: add, subtract, intersect, exclusiveOr.

For example, CAG could be used to create a pear like that shown in Figure 3-2.

The body of the pear is constructed by performing a union operation on two overlapping Areas: a circle and an oval. The leaves are each created by performing an intersection on two overlapping circles and then joined into a single Shape through a union operation. Overlapping circles are also used to construct the stem through two subtraction operations.

3.4 Creating a Custom Shape

You can implement the Shape interface to create a class that defines a new type of shape. It doesn’t matter how you represent the shape internally, as long as you can implement the Shape interface methods. The Shape must be able to generate a path that specifies its contour.

For example, you could create a simple implementation of Shape that represents polygons as arrays of points. Once the polygon is built, it could be passed to draw, setClip, or any other method that expects a Shape object as an argument.

The PolygonPath class must implement the Shape interface methods:

• contains
• getBounds
• getBounds2D
• getPathIterator
• intersects

---

Copyright © 1993, 2022, Oracle and/or its affiliates. All rights reserved.

Contact Us