The Shape.java Java example source code
/*
* 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 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 PathIterator
* object that describes the trajectory path of the <code>Shape
* outline.
* <p>
* <a name="def_insideness">Definition of insideness:
* A point is considered to lie inside a
* <code>Shape if and only if:
* <ul>
* <li> it lies completely
* inside the<code>Shape boundary or
* <li>
* it lies exactly on the <code>Shape boundary and the
* space immediately adjacent to the
* point in the increasing <code>X direction is
* entirely inside the boundary <i>or
* <li>
* it lies exactly on a horizontal boundary segment <b>and the
* space immediately adjacent to the point in the
* increasing <code>Y direction is inside the boundary.
* </ul>
* <p>The contains and 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 Shape
* lies entirely within the indicated <code>Rectangle. The
* returned <code>Rectangle might also fail to completely
* enclose the <code>Shape if the 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/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 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 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/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/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; 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/awt/Shape.html#def_insideness">
* definition of insideness</a>.
* @param p the specified <code>Point2D to be tested
* @return <code>true if the specified 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 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 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 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 Shape
* entirely contains the specified rectangular area;
* <code>false otherwise or, if the Shape
* contains the rectangular area and the
* <code>intersects method returns 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 true and
* <li>
* the calculations to determine whether or not the
* <code>Shape entirely contains the 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 Shape
* entirely contains the <code>Rectangle2D;
* <code>false otherwise or, if the Shape
* contains the <code>Rectangle2D and the
* <code>intersects method returns 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);
}
Other Java examples (source code examples)
Here is a short list of links related to this Java Shape.java source code file:
The search page
Other Java source code examples at this package level
Click here to learn more about this project
