Back to index...

	/*
	* Copyright (c) 1996, 2013, 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</code> interface provides definitions for objects
	* that represent some form of geometric shape. The <code>Shape</code>
	* is described by a {@link PathIterator} object, which can express the
	* outline of the <code>Shape</code> as well as a rule for determining
	* how the outline divides the 2D plane into interior and exterior
	* points. Each <code>Shape</code> 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</code>, and retrieve a <code>PathIterator</code>
	* object that describes the trajectory path of the <code>Shape</code>
	* outline.
	* <p>
	* <a name="def_insideness"><b>Definition of insideness:</b></a>
	* A point is considered to lie inside a
	* <code>Shape</code> if and only if:
	* <ul>
	* <li> it lies completely
	* inside the<code>Shape</code> boundary <i>or</i>
	* <li>
	* it lies exactly on the <code>Shape</code> boundary <i>and</i> the
	* space immediately adjacent to the
	* point in the increasing <code>X</code> 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</code> direction is inside the boundary.
	* </ul>
	* <p>The <code>contains</code> and <code>intersects</code> methods
	* consider the interior of a <code>Shape</code> 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</code>. Note that there is no guarantee that the
	* returned <code>Rectangle</code> is the smallest bounding box that
	* encloses the <code>Shape</code>, only that the <code>Shape</code>
	* lies entirely within the indicated <code>Rectangle</code>. The
	* returned <code>Rectangle</code> might also fail to completely
	* enclose the <code>Shape</code> if the <code>Shape</code> overflows
	* the limited range of the integer data type. The
	* <code>getBounds2D</code> method generally returns a
	* tighter bounding box due to its greater flexibility in
	* representation.
	*
	* <p>
	* Note that the <a href="{@docRoot}/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</code> that completely encloses
	* the <code>Shape</code>.
	* @see #getBounds2D
	* @since 1.2
	*/
	public Rectangle getBounds();

	/**
	* Returns a high precision and more accurate bounding box of
	* the <code>Shape</code> than the <code>getBounds</code> method.
	* Note that there is no guarantee that the returned
	* {@link Rectangle2D} is the smallest bounding box that encloses
	* the <code>Shape</code>, only that the <code>Shape</code> lies
	* entirely within the indicated <code>Rectangle2D</code>. The
	* bounding box returned by this method is usually tighter than that
	* returned by the <code>getBounds</code> method and never fails due
	* to overflow problems since the return value can be an instance of
	* the <code>Rectangle2D</code> that uses double precision values to
	* store the dimensions.
	*
	* <p>
	* Note that the <a href="{@docRoot}/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</code> that is a
	* high-precision bounding box of the <code>Shape</code>.
	* @see #getBounds
	* @since 1.2
	*/
	public Rectangle2D getBounds2D();

	/**
	* Tests if the specified coordinates are inside the boundary of the
	* <code>Shape</code>, as described by the
	* <a href="{@docRoot}/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</code> if the specified coordinates are inside
	* the <code>Shape</code> boundary; <code>false</code>
	* 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</code>, as described by the
	* <a href="{@docRoot}/java/awt/Shape.html#def_insideness">
	* definition of insideness</a>.
	* @param p the specified <code>Point2D</code> to be tested
	* @return <code>true</code> if the specified <code>Point2D</code> is
	* inside the boundary of the <code>Shape</code>;
	* <code>false</code> otherwise.
	* @since 1.2
	*/
	public boolean contains(Point2D p);

	/**
	* Tests if the interior of the <code>Shape</code> intersects the
	* interior of a specified rectangular area.
	* The rectangular area is considered to intersect the <code>Shape</code>
	* if any point is contained in both the interior of the
	* <code>Shape</code> 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</code> 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</code> if the interior of the <code>Shape</code> 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</code> 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</code> intersects the
	* interior of a specified <code>Rectangle2D</code>.
	* 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</code> and the
	* <code>Shape</code> 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</code>
	* @return <code>true</code> if the interior of the <code>Shape</code> and
	* the interior of the specified <code>Rectangle2D</code>
	* intersect, or are both highly likely to intersect and intersection
	* calculations would be too expensive to perform; <code>false</code>
	* otherwise.
	* @see #intersects(double, double, double, double)
	* @since 1.2
	*/
	public boolean intersects(Rectangle2D r);

	/**
	* Tests if the interior of the <code>Shape</code> entirely contains
	* the specified rectangular area. All coordinates that lie inside
	* the rectangular area must lie within the <code>Shape</code> for the
	* entire rectangular area to be considered contained within the
	* <code>Shape</code>.
	* <p>
	* The {@code Shape.contains()} method allows a {@code Shape}
	* implementation to conservatively return {@code false} when:
	* <ul>
	* <li>
	* the <code>intersect</code> method returns <code>true</code> and
	* <li>
	* the calculations to determine whether or not the
	* <code>Shape</code> 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</code> if the interior of the <code>Shape</code>
	* entirely contains the specified rectangular area;
	* <code>false</code> otherwise or, if the <code>Shape</code>
	* contains the rectangular area and the
	* <code>intersects</code> method returns <code>true</code>
	* 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</code> entirely contains the
	* specified <code>Rectangle2D</code>.
	* The {@code Shape.contains()} method allows a {@code Shape}
	* implementation to conservatively return {@code false} when:
	* <ul>
	* <li>
	* the <code>intersect</code> method returns <code>true</code> and
	* <li>
	* the calculations to determine whether or not the
	* <code>Shape</code> entirely contains the <code>Rectangle2D</code>
	* 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</code>
	* @return <code>true</code> if the interior of the <code>Shape</code>
	* entirely contains the <code>Rectangle2D</code>;
	* <code>false</code> otherwise or, if the <code>Shape</code>
	* contains the <code>Rectangle2D</code> and the
	* <code>intersects</code> method returns <code>true</code>
	* 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</code> boundary and provides access to the geometry of the
	* <code>Shape</code> 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</code>
	* object that traverses the geometry of the <code>Shape</code> object
	* independently from any other <code>PathIterator</code> objects in use
	* at the same time.
	* <p>
	* It is recommended, but not guaranteed, that objects
	* implementing the <code>Shape</code> 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</code> to be applied to the
	* coordinates as they are returned in the iteration, or
	* <code>null</code> if untransformed coordinates are desired
	* @return a new <code>PathIterator</code> object, which independently
	* traverses the geometry of the <code>Shape</code>.
	* @since 1.2
	*/
	public PathIterator getPathIterator(AffineTransform at);

	/**
	* Returns an iterator object that iterates along the <code>Shape</code>
	* boundary and provides access to a flattened view of the
	* <code>Shape</code> outline geometry.
	* <p>
	* Only SEG_MOVETO, SEG_LINETO, and SEG_CLOSE point types are
	* returned by the iterator.
	* <p>
	* If an optional <code>AffineTransform</code> 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</code> 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</code>
	* object that traverses the <code>Shape</code> object geometry
	* independently from any other <code>PathIterator</code> objects in use at
	* the same time.
	* <p>
	* It is recommended, but not guaranteed, that objects
	* implementing the <code>Shape</code> 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</code> to be applied to the
	* coordinates as they are returned in the iteration, or
	* <code>null</code> 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</code> that independently traverses
	* a flattened view of the geometry of the <code>Shape</code>.
	* @since 1.2
	*/
	public PathIterator getPathIterator(AffineTransform at, double flatness);
	}

Back to index...