Home » openjdk-7 » java » awt » [javadoc | source]

    1   /*
    2    * Copyright (c) 1996, 2006, Oracle and/or its affiliates. All rights reserved.
    3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
    4    *
    5    * This code is free software; you can redistribute it and/or modify it
    6    * under the terms of the GNU General Public License version 2 only, as
    7    * published by the Free Software Foundation.  Oracle designates this
    8    * particular file as subject to the "Classpath" exception as provided
    9    * by Oracle in the LICENSE file that accompanied this code.
   10    *
   11    * This code is distributed in the hope that it will be useful, but WITHOUT
   12    * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   13    * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   14    * version 2 for more details (a copy is included in the LICENSE file that
   15    * accompanied this code).
   16    *
   17    * You should have received a copy of the GNU General Public License version
   18    * 2 along with this work; if not, write to the Free Software Foundation,
   19    * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   20    *
   21    * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
   22    * or visit www.oracle.com if you need additional information or have any
   23    * questions.
   24    */
   25   
   26   package java.awt;
   27   
   28   import java.awt.geom.AffineTransform;
   29   import java.awt.geom.PathIterator;
   30   import java.awt.geom.Point2D;
   31   import java.awt.geom.Rectangle2D;
   32   
   33   /**
   34    * The <code>Shape</code> interface provides definitions for objects
   35    * that represent some form of geometric shape.  The <code>Shape</code>
   36    * is described by a {@link PathIterator} object, which can express the
   37    * outline of the <code>Shape</code> as well as a rule for determining
   38    * how the outline divides the 2D plane into interior and exterior
   39    * points.  Each <code>Shape</code> object provides callbacks to get the
   40    * bounding box of the geometry, determine whether points or
   41    * rectangles lie partly or entirely within the interior
   42    * of the <code>Shape</code>, and retrieve a <code>PathIterator</code>
   43    * object that describes the trajectory path of the <code>Shape</code>
   44    * outline.
   45    * <p>
   46    * <a name="def_insideness"><b>Definition of insideness:</b></a>
   47    * A point is considered to lie inside a
   48    * <code>Shape</code> if and only if:
   49    * <ul>
   50    * <li> it lies completely
   51    * inside the<code>Shape</code> boundary <i>or</i>
   52    * <li>
   53    * it lies exactly on the <code>Shape</code> boundary <i>and</i> the
   54    * space immediately adjacent to the
   55    * point in the increasing <code>X</code> direction is
   56    * entirely inside the boundary <i>or</i>
   57    * <li>
   58    * it lies exactly on a horizontal boundary segment <b>and</b> the
   59    * space immediately adjacent to the point in the
   60    * increasing <code>Y</code> direction is inside the boundary.
   61    * </ul>
   62    * <p>The <code>contains</code> and <code>intersects</code> methods
   63    * consider the interior of a <code>Shape</code> to be the area it
   64    * encloses as if it were filled.  This means that these methods
   65    * consider
   66    * unclosed shapes to be implicitly closed for the purpose of
   67    * determining if a shape contains or intersects a rectangle or if a
   68    * shape contains a point.
   69    *
   70    * @see java.awt.geom.PathIterator
   71    * @see java.awt.geom.AffineTransform
   72    * @see java.awt.geom.FlatteningPathIterator
   73    * @see java.awt.geom.GeneralPath
   74    *
   75    * @author Jim Graham
   76    * @since 1.2
   77    */
   78   public interface Shape {
   79       /**
   80        * Returns an integer {@link Rectangle} that completely encloses the
   81        * <code>Shape</code>.  Note that there is no guarantee that the
   82        * returned <code>Rectangle</code> is the smallest bounding box that
   83        * encloses the <code>Shape</code>, only that the <code>Shape</code>
   84        * lies entirely within the indicated  <code>Rectangle</code>.  The
   85        * returned <code>Rectangle</code> might also fail to completely
   86        * enclose the <code>Shape</code> if the <code>Shape</code> overflows
   87        * the limited range of the integer data type.  The
   88        * <code>getBounds2D</code> method generally returns a
   89        * tighter bounding box due to its greater flexibility in
   90        * representation.
   91        *
   92        * <p>
   93        * Note that the <a href="{@docRoot}/java/awt/Shape.html#def_insideness">
   94        * definition of insideness</a> can lead to situations where points
   95        * on the defining outline of the {@code shape} may not be considered
   96        * contained in the returned {@code bounds} object, but only in cases
   97        * where those points are also not considered contained in the original
   98        * {@code shape}.
   99        * </p>
  100        * <p>
  101        * If a {@code point} is inside the {@code shape} according to the
  102        * {@link #contains(double x, double y) contains(point)} method, then
  103        * it must be inside the returned {@code Rectangle} bounds object
  104        * according to the {@link #contains(double x, double y) contains(point)}
  105        * method of the {@code bounds}. Specifically:
  106        * </p>
  107        * <p>
  108        *  {@code shape.contains(x,y)} requires {@code bounds.contains(x,y)}
  109        * </p>
  110        * <p>
  111        * If a {@code point} is not inside the {@code shape}, then it might
  112        * still be contained in the {@code bounds} object:
  113        * </p>
  114        * <p>
  115        *  {@code bounds.contains(x,y)} does not imply {@code shape.contains(x,y)}
  116        * </p>
  117        * @return an integer <code>Rectangle</code> that completely encloses
  118        *                 the <code>Shape</code>.
  119        * @see #getBounds2D
  120        * @since 1.2
  121        */
  122       public Rectangle getBounds();
  123   
  124       /**
  125        * Returns a high precision and more accurate bounding box of
  126        * the <code>Shape</code> than the <code>getBounds</code> method.
  127        * Note that there is no guarantee that the returned
  128        * {@link Rectangle2D} is the smallest bounding box that encloses
  129        * the <code>Shape</code>, only that the <code>Shape</code> lies
  130        * entirely within the indicated <code>Rectangle2D</code>.  The
  131        * bounding box returned by this method is usually tighter than that
  132        * returned by the <code>getBounds</code> method and never fails due
  133        * to overflow problems since the return value can be an instance of
  134        * the <code>Rectangle2D</code> that uses double precision values to
  135        * store the dimensions.
  136        *
  137        * <p>
  138        * Note that the <a href="{@docRoot}/java/awt/Shape.html#def_insideness">
  139        * definition of insideness</a> can lead to situations where points
  140        * on the defining outline of the {@code shape} may not be considered
  141        * contained in the returned {@code bounds} object, but only in cases
  142        * where those points are also not considered contained in the original
  143        * {@code shape}.
  144        * </p>
  145        * <p>
  146        * If a {@code point} is inside the {@code shape} according to the
  147        * {@link #contains(Point2D p) contains(point)} method, then it must
  148        * be inside the returned {@code Rectangle2D} bounds object according
  149        * to the {@link #contains(Point2D p) contains(point)} method of the
  150        * {@code bounds}. Specifically:
  151        * </p>
  152        * <p>
  153        *  {@code shape.contains(p)} requires {@code bounds.contains(p)}
  154        * </p>
  155        * <p>
  156        * If a {@code point} is not inside the {@code shape}, then it might
  157        * still be contained in the {@code bounds} object:
  158        * </p>
  159        * <p>
  160        *  {@code bounds.contains(p)} does not imply {@code shape.contains(p)}
  161        * </p>
  162        * @return an instance of <code>Rectangle2D</code> that is a
  163        *                 high-precision bounding box of the <code>Shape</code>.
  164        * @see #getBounds
  165        * @since 1.2
  166        */
  167       public Rectangle2D getBounds2D();
  168   
  169       /**
  170        * Tests if the specified coordinates are inside the boundary of the
  171        * <code>Shape</code>, as described by the
  172        * <a href="{@docRoot}/java/awt/Shape.html#def_insideness">
  173        * definition of insideness</a>.
  174        * @param x the specified X coordinate to be tested
  175        * @param y the specified Y coordinate to be tested
  176        * @return <code>true</code> if the specified coordinates are inside
  177        *         the <code>Shape</code> boundary; <code>false</code>
  178        *         otherwise.
  179        * @since 1.2
  180        */
  181       public boolean contains(double x, double y);
  182   
  183       /**
  184        * Tests if a specified {@link Point2D} is inside the boundary
  185        * of the <code>Shape</code>, as described by the
  186        * <a href="{@docRoot}/java/awt/Shape.html#def_insideness">
  187        * definition of insideness</a>.
  188        * @param p the specified <code>Point2D</code> to be tested
  189        * @return <code>true</code> if the specified <code>Point2D</code> is
  190        *          inside the boundary of the <code>Shape</code>;
  191        *          <code>false</code> otherwise.
  192        * @since 1.2
  193        */
  194       public boolean contains(Point2D p);
  195   
  196       /**
  197        * Tests if the interior of the <code>Shape</code> intersects the
  198        * interior of a specified rectangular area.
  199        * The rectangular area is considered to intersect the <code>Shape</code>
  200        * if any point is contained in both the interior of the
  201        * <code>Shape</code> and the specified rectangular area.
  202        * <p>
  203        * The {@code Shape.intersects()} method allows a {@code Shape}
  204        * implementation to conservatively return {@code true} when:
  205        * <ul>
  206        * <li>
  207        * there is a high probability that the rectangular area and the
  208        * <code>Shape</code> intersect, but
  209        * <li>
  210        * the calculations to accurately determine this intersection
  211        * are prohibitively expensive.
  212        * </ul>
  213        * This means that for some {@code Shapes} this method might
  214        * return {@code true} even though the rectangular area does not
  215        * intersect the {@code Shape}.
  216        * The {@link java.awt.geom.Area Area} class performs
  217        * more accurate computations of geometric intersection than most
  218        * {@code Shape} objects and therefore can be used if a more precise
  219        * answer is required.
  220        *
  221        * @param x the X coordinate of the upper-left corner
  222        *          of the specified rectangular area
  223        * @param y the Y coordinate of the upper-left corner
  224        *          of the specified rectangular area
  225        * @param w the width of the specified rectangular area
  226        * @param h the height of the specified rectangular area
  227        * @return <code>true</code> if the interior of the <code>Shape</code> and
  228        *          the interior of the rectangular area intersect, or are
  229        *          both highly likely to intersect and intersection calculations
  230        *          would be too expensive to perform; <code>false</code> otherwise.
  231        * @see java.awt.geom.Area
  232        * @since 1.2
  233        */
  234       public boolean intersects(double x, double y, double w, double h);
  235   
  236       /**
  237        * Tests if the interior of the <code>Shape</code> intersects the
  238        * interior of a specified <code>Rectangle2D</code>.
  239        * The {@code Shape.intersects()} method allows a {@code Shape}
  240        * implementation to conservatively return {@code true} when:
  241        * <ul>
  242        * <li>
  243        * there is a high probability that the <code>Rectangle2D</code> and the
  244        * <code>Shape</code> intersect, but
  245        * <li>
  246        * the calculations to accurately determine this intersection
  247        * are prohibitively expensive.
  248        * </ul>
  249        * This means that for some {@code Shapes} this method might
  250        * return {@code true} even though the {@code Rectangle2D} does not
  251        * intersect the {@code Shape}.
  252        * The {@link java.awt.geom.Area Area} class performs
  253        * more accurate computations of geometric intersection than most
  254        * {@code Shape} objects and therefore can be used if a more precise
  255        * answer is required.
  256        *
  257        * @param r the specified <code>Rectangle2D</code>
  258        * @return <code>true</code> if the interior of the <code>Shape</code> and
  259        *          the interior of the specified <code>Rectangle2D</code>
  260        *          intersect, or are both highly likely to intersect and intersection
  261        *          calculations would be too expensive to perform; <code>false</code>
  262        *          otherwise.
  263        * @see #intersects(double, double, double, double)
  264        * @since 1.2
  265        */
  266       public boolean intersects(Rectangle2D r);
  267   
  268       /**
  269        * Tests if the interior of the <code>Shape</code> entirely contains
  270        * the specified rectangular area.  All coordinates that lie inside
  271        * the rectangular area must lie within the <code>Shape</code> for the
  272        * entire rectanglar area to be considered contained within the
  273        * <code>Shape</code>.
  274        * <p>
  275        * The {@code Shape.contains()} method allows a {@code Shape}
  276        * implementation to conservatively return {@code false} when:
  277        * <ul>
  278        * <li>
  279        * the <code>intersect</code> method returns <code>true</code> and
  280        * <li>
  281        * the calculations to determine whether or not the
  282        * <code>Shape</code> entirely contains the rectangular area are
  283        * prohibitively expensive.
  284        * </ul>
  285        * This means that for some {@code Shapes} this method might
  286        * return {@code false} even though the {@code Shape} contains
  287        * the rectangular area.
  288        * The {@link java.awt.geom.Area Area} class performs
  289        * more accurate geometric computations than most
  290        * {@code Shape} objects and therefore can be used if a more precise
  291        * answer is required.
  292        *
  293        * @param x the X coordinate of the upper-left corner
  294        *          of the specified rectangular area
  295        * @param y the Y coordinate of the upper-left corner
  296        *          of the specified rectangular area
  297        * @param w the width of the specified rectangular area
  298        * @param h the height of the specified rectangular area
  299        * @return <code>true</code> if the interior of the <code>Shape</code>
  300        *          entirely contains the specified rectangular area;
  301        *          <code>false</code> otherwise or, if the <code>Shape</code>
  302        *          contains the rectangular area and the
  303        *          <code>intersects</code> method returns <code>true</code>
  304        *          and the containment calculations would be too expensive to
  305        *          perform.
  306        * @see java.awt.geom.Area
  307        * @see #intersects
  308        * @since 1.2
  309        */
  310       public boolean contains(double x, double y, double w, double h);
  311   
  312       /**
  313        * Tests if the interior of the <code>Shape</code> entirely contains the
  314        * specified <code>Rectangle2D</code>.
  315        * The {@code Shape.contains()} method allows a {@code Shape}
  316        * implementation to conservatively return {@code false} when:
  317        * <ul>
  318        * <li>
  319        * the <code>intersect</code> method returns <code>true</code> and
  320        * <li>
  321        * the calculations to determine whether or not the
  322        * <code>Shape</code> entirely contains the <code>Rectangle2D</code>
  323        * are prohibitively expensive.
  324        * </ul>
  325        * This means that for some {@code Shapes} this method might
  326        * return {@code false} even though the {@code Shape} contains
  327        * the {@code Rectangle2D}.
  328        * The {@link java.awt.geom.Area Area} class performs
  329        * more accurate geometric computations than most
  330        * {@code Shape} objects and therefore can be used if a more precise
  331        * answer is required.
  332        *
  333        * @param r The specified <code>Rectangle2D</code>
  334        * @return <code>true</code> if the interior of the <code>Shape</code>
  335        *          entirely contains the <code>Rectangle2D</code>;
  336        *          <code>false</code> otherwise or, if the <code>Shape</code>
  337        *          contains the <code>Rectangle2D</code> and the
  338        *          <code>intersects</code> method returns <code>true</code>
  339        *          and the containment calculations would be too expensive to
  340        *          perform.
  341        * @see #contains(double, double, double, double)
  342        * @since 1.2
  343        */
  344       public boolean contains(Rectangle2D r);
  345   
  346       /**
  347        * Returns an iterator object that iterates along the
  348        * <code>Shape</code> boundary and provides access to the geometry of the
  349        * <code>Shape</code> outline.  If an optional {@link AffineTransform}
  350        * is specified, the coordinates returned in the iteration are
  351        * transformed accordingly.
  352        * <p>
  353        * Each call to this method returns a fresh <code>PathIterator</code>
  354        * object that traverses the geometry of the <code>Shape</code> object
  355        * independently from any other <code>PathIterator</code> objects in use
  356        * at the same time.
  357        * <p>
  358        * It is recommended, but not guaranteed, that objects
  359        * implementing the <code>Shape</code> interface isolate iterations
  360        * that are in process from any changes that might occur to the original
  361        * object's geometry during such iterations.
  362        *
  363        * @param at an optional <code>AffineTransform</code> to be applied to the
  364        *          coordinates as they are returned in the iteration, or
  365        *          <code>null</code> if untransformed coordinates are desired
  366        * @return a new <code>PathIterator</code> object, which independently
  367        *          traverses the geometry of the <code>Shape</code>.
  368        * @since 1.2
  369        */
  370       public PathIterator getPathIterator(AffineTransform at);
  371   
  372       /**
  373        * Returns an iterator object that iterates along the <code>Shape</code>
  374        * boundary and provides access to a flattened view of the
  375        * <code>Shape</code> outline geometry.
  376        * <p>
  377        * Only SEG_MOVETO, SEG_LINETO, and SEG_CLOSE point types are
  378        * returned by the iterator.
  379        * <p>
  380        * If an optional <code>AffineTransform</code> is specified,
  381        * the coordinates returned in the iteration are transformed
  382        * accordingly.
  383        * <p>
  384        * The amount of subdivision of the curved segments is controlled
  385        * by the <code>flatness</code> parameter, which specifies the
  386        * maximum distance that any point on the unflattened transformed
  387        * curve can deviate from the returned flattened path segments.
  388        * Note that a limit on the accuracy of the flattened path might be
  389        * silently imposed, causing very small flattening parameters to be
  390        * treated as larger values.  This limit, if there is one, is
  391        * defined by the particular implementation that is used.
  392        * <p>
  393        * Each call to this method returns a fresh <code>PathIterator</code>
  394        * object that traverses the <code>Shape</code> object geometry
  395        * independently from any other <code>PathIterator</code> objects in use at
  396        * the same time.
  397        * <p>
  398        * It is recommended, but not guaranteed, that objects
  399        * implementing the <code>Shape</code> interface isolate iterations
  400        * that are in process from any changes that might occur to the original
  401        * object's geometry during such iterations.
  402        *
  403        * @param at an optional <code>AffineTransform</code> to be applied to the
  404        *          coordinates as they are returned in the iteration, or
  405        *          <code>null</code> if untransformed coordinates are desired
  406        * @param flatness the maximum distance that the line segments used to
  407        *          approximate the curved segments are allowed to deviate
  408        *          from any point on the original curve
  409        * @return a new <code>PathIterator</code> that independently traverses
  410        *         a flattened view of the geometry of the  <code>Shape</code>.
  411        * @since 1.2
  412        */
  413       public PathIterator getPathIterator(AffineTransform at, double flatness);
  414   }

Home » openjdk-7 » java » awt » [javadoc | source]