mirror of
https://github.com/openjdk/jdk.git
synced 2026-01-29 12:38:24 +00:00
417 lines
18 KiB
Java
417 lines
18 KiB
Java
/*
|
|
* Copyright (c) 1996, 2017, Oracle and/or its affiliates. All rights reserved.
|
|
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
|
|
*
|
|
* This code is free software; you can redistribute it and/or modify it
|
|
* under the terms of the GNU General Public License version 2 only, as
|
|
* published by the Free Software Foundation. Oracle designates this
|
|
* particular file as subject to the "Classpath" exception as provided
|
|
* by Oracle in the LICENSE file that accompanied this code.
|
|
*
|
|
* This code is distributed in the hope that it will be useful, but WITHOUT
|
|
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
|
|
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
|
|
* version 2 for more details (a copy is included in the LICENSE file that
|
|
* accompanied this code).
|
|
*
|
|
* You should have received a copy of the GNU General Public License version
|
|
* 2 along with this work; if not, write to the Free Software Foundation,
|
|
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
|
|
*
|
|
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
|
|
* or visit www.oracle.com if you need additional information or have any
|
|
* questions.
|
|
*/
|
|
|
|
package java.awt;
|
|
|
|
import java.awt.geom.AffineTransform;
|
|
import java.awt.geom.PathIterator;
|
|
import java.awt.geom.Point2D;
|
|
import java.awt.geom.Rectangle2D;
|
|
|
|
/**
|
|
* The {@code Shape} interface provides definitions for objects
|
|
* that represent some form of geometric shape. The {@code Shape}
|
|
* is described by a {@link PathIterator} object, which can express the
|
|
* outline of the {@code Shape} as well as a rule for determining
|
|
* how the outline divides the 2D plane into interior and exterior
|
|
* points. Each {@code Shape} object provides callbacks to get the
|
|
* bounding box of the geometry, determine whether points or
|
|
* rectangles lie partly or entirely within the interior
|
|
* of the {@code Shape}, and retrieve a {@code PathIterator}
|
|
* object that describes the trajectory path of the {@code Shape}
|
|
* outline.
|
|
* <p>
|
|
* <a id="def_insideness"><b>Definition of insideness:</b></a>
|
|
* A point is considered to lie inside a
|
|
* {@code Shape} if and only if:
|
|
* <ul>
|
|
* <li> it lies completely
|
|
* inside the {@code Shape} boundary <i>or</i>
|
|
* <li>
|
|
* it lies exactly on the {@code Shape} boundary <i>and</i> the
|
|
* space immediately adjacent to the
|
|
* point in the increasing {@code X} direction is
|
|
* entirely inside the boundary <i>or</i>
|
|
* <li>
|
|
* it lies exactly on a horizontal boundary segment <b>and</b> the
|
|
* space immediately adjacent to the point in the
|
|
* increasing {@code Y} direction is inside the boundary.
|
|
* </ul>
|
|
* <p>The {@code contains} and {@code intersects} methods
|
|
* consider the interior of a {@code Shape} to be the area it
|
|
* encloses as if it were filled. This means that these methods
|
|
* consider
|
|
* unclosed shapes to be implicitly closed for the purpose of
|
|
* determining if a shape contains or intersects a rectangle or if a
|
|
* shape contains a point.
|
|
*
|
|
* @see java.awt.geom.PathIterator
|
|
* @see java.awt.geom.AffineTransform
|
|
* @see java.awt.geom.FlatteningPathIterator
|
|
* @see java.awt.geom.GeneralPath
|
|
*
|
|
* @author Jim Graham
|
|
* @since 1.2
|
|
*/
|
|
public interface Shape {
|
|
/**
|
|
* Returns an integer {@link Rectangle} that completely encloses the
|
|
* {@code Shape}. Note that there is no guarantee that the
|
|
* returned {@code Rectangle} is the smallest bounding box that
|
|
* encloses the {@code Shape}, only that the {@code Shape}
|
|
* lies entirely within the indicated {@code Rectangle}. The
|
|
* returned {@code Rectangle} might also fail to completely
|
|
* enclose the {@code Shape} if the {@code Shape} overflows
|
|
* the limited range of the integer data type. The
|
|
* {@code getBounds2D} method generally returns a
|
|
* tighter bounding box due to its greater flexibility in
|
|
* representation.
|
|
*
|
|
* <p>
|
|
* Note that the
|
|
* <a href="{@docRoot}/java.desktop/java/awt/Shape.html#def_insideness">
|
|
* definition of insideness</a> can lead to situations where points
|
|
* on the defining outline of the {@code shape} may not be considered
|
|
* contained in the returned {@code bounds} object, but only in cases
|
|
* where those points are also not considered contained in the original
|
|
* {@code shape}.
|
|
* </p>
|
|
* <p>
|
|
* If a {@code point} is inside the {@code shape} according to the
|
|
* {@link #contains(double x, double y) contains(point)} method, then
|
|
* it must be inside the returned {@code Rectangle} bounds object
|
|
* according to the {@link #contains(double x, double y) contains(point)}
|
|
* method of the {@code bounds}. Specifically:
|
|
* </p>
|
|
* <p>
|
|
* {@code shape.contains(x,y)} requires {@code bounds.contains(x,y)}
|
|
* </p>
|
|
* <p>
|
|
* If a {@code point} is not inside the {@code shape}, then it might
|
|
* still be contained in the {@code bounds} object:
|
|
* </p>
|
|
* <p>
|
|
* {@code bounds.contains(x,y)} does not imply {@code shape.contains(x,y)}
|
|
* </p>
|
|
* @return an integer {@code Rectangle} that completely encloses
|
|
* the {@code Shape}.
|
|
* @see #getBounds2D
|
|
* @since 1.2
|
|
*/
|
|
public Rectangle getBounds();
|
|
|
|
/**
|
|
* Returns a high precision and more accurate bounding box of
|
|
* the {@code Shape} than the {@code getBounds} method.
|
|
* Note that there is no guarantee that the returned
|
|
* {@link Rectangle2D} is the smallest bounding box that encloses
|
|
* the {@code Shape}, only that the {@code Shape} lies
|
|
* entirely within the indicated {@code Rectangle2D}. The
|
|
* bounding box returned by this method is usually tighter than that
|
|
* returned by the {@code getBounds} method and never fails due
|
|
* to overflow problems since the return value can be an instance of
|
|
* the {@code Rectangle2D} that uses double precision values to
|
|
* store the dimensions.
|
|
*
|
|
* <p>
|
|
* Note that the
|
|
* <a href="{@docRoot}/java.desktop/java/awt/Shape.html#def_insideness">
|
|
* definition of insideness</a> can lead to situations where points
|
|
* on the defining outline of the {@code shape} may not be considered
|
|
* contained in the returned {@code bounds} object, but only in cases
|
|
* where those points are also not considered contained in the original
|
|
* {@code shape}.
|
|
* </p>
|
|
* <p>
|
|
* If a {@code point} is inside the {@code shape} according to the
|
|
* {@link #contains(Point2D p) contains(point)} method, then it must
|
|
* be inside the returned {@code Rectangle2D} bounds object according
|
|
* to the {@link #contains(Point2D p) contains(point)} method of the
|
|
* {@code bounds}. Specifically:
|
|
* </p>
|
|
* <p>
|
|
* {@code shape.contains(p)} requires {@code bounds.contains(p)}
|
|
* </p>
|
|
* <p>
|
|
* If a {@code point} is not inside the {@code shape}, then it might
|
|
* still be contained in the {@code bounds} object:
|
|
* </p>
|
|
* <p>
|
|
* {@code bounds.contains(p)} does not imply {@code shape.contains(p)}
|
|
* </p>
|
|
* @return an instance of {@code Rectangle2D} that is a
|
|
* high-precision bounding box of the {@code Shape}.
|
|
* @see #getBounds
|
|
* @since 1.2
|
|
*/
|
|
public Rectangle2D getBounds2D();
|
|
|
|
/**
|
|
* Tests if the specified coordinates are inside the boundary of the
|
|
* {@code Shape}, as described by the
|
|
* <a href="{@docRoot}/java.desktop/java/awt/Shape.html#def_insideness">
|
|
* definition of insideness</a>.
|
|
* @param x the specified X coordinate to be tested
|
|
* @param y the specified Y coordinate to be tested
|
|
* @return {@code true} if the specified coordinates are inside
|
|
* the {@code Shape} boundary; {@code false}
|
|
* otherwise.
|
|
* @since 1.2
|
|
*/
|
|
public boolean contains(double x, double y);
|
|
|
|
/**
|
|
* Tests if a specified {@link Point2D} is inside the boundary
|
|
* of the {@code Shape}, as described by the
|
|
* <a href="{@docRoot}/java.desktop/java/awt/Shape.html#def_insideness">
|
|
* definition of insideness</a>.
|
|
* @param p the specified {@code Point2D} to be tested
|
|
* @return {@code true} if the specified {@code Point2D} is
|
|
* inside the boundary of the {@code Shape};
|
|
* {@code false} otherwise.
|
|
* @since 1.2
|
|
*/
|
|
public boolean contains(Point2D p);
|
|
|
|
/**
|
|
* Tests if the interior of the {@code Shape} intersects the
|
|
* interior of a specified rectangular area.
|
|
* The rectangular area is considered to intersect the {@code Shape}
|
|
* if any point is contained in both the interior of the
|
|
* {@code Shape} and the specified rectangular area.
|
|
* <p>
|
|
* The {@code Shape.intersects()} method allows a {@code Shape}
|
|
* implementation to conservatively return {@code true} when:
|
|
* <ul>
|
|
* <li>
|
|
* there is a high probability that the rectangular area and the
|
|
* {@code Shape} intersect, but
|
|
* <li>
|
|
* the calculations to accurately determine this intersection
|
|
* are prohibitively expensive.
|
|
* </ul>
|
|
* This means that for some {@code Shapes} this method might
|
|
* return {@code true} even though the rectangular area does not
|
|
* intersect the {@code Shape}.
|
|
* The {@link java.awt.geom.Area Area} class performs
|
|
* more accurate computations of geometric intersection than most
|
|
* {@code Shape} objects and therefore can be used if a more precise
|
|
* answer is required.
|
|
*
|
|
* @param x the X coordinate of the upper-left corner
|
|
* of the specified rectangular area
|
|
* @param y the Y coordinate of the upper-left corner
|
|
* of the specified rectangular area
|
|
* @param w the width of the specified rectangular area
|
|
* @param h the height of the specified rectangular area
|
|
* @return {@code true} if the interior of the {@code Shape} and
|
|
* the interior of the rectangular area intersect, or are
|
|
* both highly likely to intersect and intersection calculations
|
|
* would be too expensive to perform; {@code false} otherwise.
|
|
* @see java.awt.geom.Area
|
|
* @since 1.2
|
|
*/
|
|
public boolean intersects(double x, double y, double w, double h);
|
|
|
|
/**
|
|
* Tests if the interior of the {@code Shape} intersects the
|
|
* interior of a specified {@code Rectangle2D}.
|
|
* The {@code Shape.intersects()} method allows a {@code Shape}
|
|
* implementation to conservatively return {@code true} when:
|
|
* <ul>
|
|
* <li>
|
|
* there is a high probability that the {@code Rectangle2D} and the
|
|
* {@code Shape} intersect, but
|
|
* <li>
|
|
* the calculations to accurately determine this intersection
|
|
* are prohibitively expensive.
|
|
* </ul>
|
|
* This means that for some {@code Shapes} this method might
|
|
* return {@code true} even though the {@code Rectangle2D} does not
|
|
* intersect the {@code Shape}.
|
|
* The {@link java.awt.geom.Area Area} class performs
|
|
* more accurate computations of geometric intersection than most
|
|
* {@code Shape} objects and therefore can be used if a more precise
|
|
* answer is required.
|
|
*
|
|
* @param r the specified {@code Rectangle2D}
|
|
* @return {@code true} if the interior of the {@code Shape} and
|
|
* the interior of the specified {@code Rectangle2D}
|
|
* intersect, or are both highly likely to intersect and intersection
|
|
* calculations would be too expensive to perform; {@code false}
|
|
* otherwise.
|
|
* @see #intersects(double, double, double, double)
|
|
* @since 1.2
|
|
*/
|
|
public boolean intersects(Rectangle2D r);
|
|
|
|
/**
|
|
* Tests if the interior of the {@code Shape} entirely contains
|
|
* the specified rectangular area. All coordinates that lie inside
|
|
* the rectangular area must lie within the {@code Shape} for the
|
|
* entire rectangular area to be considered contained within the
|
|
* {@code Shape}.
|
|
* <p>
|
|
* The {@code Shape.contains()} method allows a {@code Shape}
|
|
* implementation to conservatively return {@code false} when:
|
|
* <ul>
|
|
* <li>
|
|
* the {@code intersect} method returns {@code true} and
|
|
* <li>
|
|
* the calculations to determine whether or not the
|
|
* {@code Shape} entirely contains the rectangular area are
|
|
* prohibitively expensive.
|
|
* </ul>
|
|
* This means that for some {@code Shapes} this method might
|
|
* return {@code false} even though the {@code Shape} contains
|
|
* the rectangular area.
|
|
* The {@link java.awt.geom.Area Area} class performs
|
|
* more accurate geometric computations than most
|
|
* {@code Shape} objects and therefore can be used if a more precise
|
|
* answer is required.
|
|
*
|
|
* @param x the X coordinate of the upper-left corner
|
|
* of the specified rectangular area
|
|
* @param y the Y coordinate of the upper-left corner
|
|
* of the specified rectangular area
|
|
* @param w the width of the specified rectangular area
|
|
* @param h the height of the specified rectangular area
|
|
* @return {@code true} if the interior of the {@code Shape}
|
|
* entirely contains the specified rectangular area;
|
|
* {@code false} otherwise or, if the {@code Shape}
|
|
* contains the rectangular area and the
|
|
* {@code intersects} method returns {@code true}
|
|
* and the containment calculations would be too expensive to
|
|
* perform.
|
|
* @see java.awt.geom.Area
|
|
* @see #intersects
|
|
* @since 1.2
|
|
*/
|
|
public boolean contains(double x, double y, double w, double h);
|
|
|
|
/**
|
|
* Tests if the interior of the {@code Shape} entirely contains the
|
|
* specified {@code Rectangle2D}.
|
|
* The {@code Shape.contains()} method allows a {@code Shape}
|
|
* implementation to conservatively return {@code false} when:
|
|
* <ul>
|
|
* <li>
|
|
* the {@code intersect} method returns {@code true} and
|
|
* <li>
|
|
* the calculations to determine whether or not the
|
|
* {@code Shape} entirely contains the {@code Rectangle2D}
|
|
* are prohibitively expensive.
|
|
* </ul>
|
|
* This means that for some {@code Shapes} this method might
|
|
* return {@code false} even though the {@code Shape} contains
|
|
* the {@code Rectangle2D}.
|
|
* The {@link java.awt.geom.Area Area} class performs
|
|
* more accurate geometric computations than most
|
|
* {@code Shape} objects and therefore can be used if a more precise
|
|
* answer is required.
|
|
*
|
|
* @param r The specified {@code Rectangle2D}
|
|
* @return {@code true} if the interior of the {@code Shape}
|
|
* entirely contains the {@code Rectangle2D};
|
|
* {@code false} otherwise or, if the {@code Shape}
|
|
* contains the {@code Rectangle2D} and the
|
|
* {@code intersects} method returns {@code true}
|
|
* and the containment calculations would be too expensive to
|
|
* perform.
|
|
* @see #contains(double, double, double, double)
|
|
* @since 1.2
|
|
*/
|
|
public boolean contains(Rectangle2D r);
|
|
|
|
/**
|
|
* Returns an iterator object that iterates along the
|
|
* {@code Shape} boundary and provides access to the geometry of the
|
|
* {@code Shape} outline. If an optional {@link AffineTransform}
|
|
* is specified, the coordinates returned in the iteration are
|
|
* transformed accordingly.
|
|
* <p>
|
|
* Each call to this method returns a fresh {@code PathIterator}
|
|
* object that traverses the geometry of the {@code Shape} object
|
|
* independently from any other {@code PathIterator} objects in use
|
|
* at the same time.
|
|
* <p>
|
|
* It is recommended, but not guaranteed, that objects
|
|
* implementing the {@code Shape} interface isolate iterations
|
|
* that are in process from any changes that might occur to the original
|
|
* object's geometry during such iterations.
|
|
*
|
|
* @param at an optional {@code AffineTransform} to be applied to the
|
|
* coordinates as they are returned in the iteration, or
|
|
* {@code null} if untransformed coordinates are desired
|
|
* @return a new {@code PathIterator} object, which independently
|
|
* traverses the geometry of the {@code Shape}.
|
|
* @since 1.2
|
|
*/
|
|
public PathIterator getPathIterator(AffineTransform at);
|
|
|
|
/**
|
|
* Returns an iterator object that iterates along the {@code Shape}
|
|
* boundary and provides access to a flattened view of the
|
|
* {@code Shape} outline geometry.
|
|
* <p>
|
|
* Only SEG_MOVETO, SEG_LINETO, and SEG_CLOSE point types are
|
|
* returned by the iterator.
|
|
* <p>
|
|
* If an optional {@code AffineTransform} is specified,
|
|
* the coordinates returned in the iteration are transformed
|
|
* accordingly.
|
|
* <p>
|
|
* The amount of subdivision of the curved segments is controlled
|
|
* by the {@code flatness} parameter, which specifies the
|
|
* maximum distance that any point on the unflattened transformed
|
|
* curve can deviate from the returned flattened path segments.
|
|
* Note that a limit on the accuracy of the flattened path might be
|
|
* silently imposed, causing very small flattening parameters to be
|
|
* treated as larger values. This limit, if there is one, is
|
|
* defined by the particular implementation that is used.
|
|
* <p>
|
|
* Each call to this method returns a fresh {@code PathIterator}
|
|
* object that traverses the {@code Shape} object geometry
|
|
* independently from any other {@code PathIterator} objects in use at
|
|
* the same time.
|
|
* <p>
|
|
* It is recommended, but not guaranteed, that objects
|
|
* implementing the {@code Shape} interface isolate iterations
|
|
* that are in process from any changes that might occur to the original
|
|
* object's geometry during such iterations.
|
|
*
|
|
* @param at an optional {@code AffineTransform} to be applied to the
|
|
* coordinates as they are returned in the iteration, or
|
|
* {@code null} if untransformed coordinates are desired
|
|
* @param flatness the maximum distance that the line segments used to
|
|
* approximate the curved segments are allowed to deviate
|
|
* from any point on the original curve
|
|
* @return a new {@code PathIterator} that independently traverses
|
|
* a flattened view of the geometry of the {@code Shape}.
|
|
* @since 1.2
|
|
*/
|
|
public PathIterator getPathIterator(AffineTransform at, double flatness);
|
|
}
|