| Frames | No Frames |
1: /* Shape.java -- the classic Object-Oriented shape interface 2: Copyright (C) 1999, 2002, 2005, 2006, Free Software Foundation, Inc. 3: 4: This file is part of GNU Classpath. 5: 6: GNU Classpath is free software; you can redistribute it and/or modify 7: it under the terms of the GNU General Public License as published by 8: the Free Software Foundation; either version 2, or (at your option) 9: any later version. 10: 11: GNU Classpath is distributed in the hope that it will be useful, but 12: WITHOUT ANY WARRANTY; without even the implied warranty of 13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14: General Public License for more details. 15: 16: You should have received a copy of the GNU General Public License 17: along with GNU Classpath; see the file COPYING. If not, write to the 18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 19: 02110-1301 USA. 20: 21: Linking this library statically or dynamically with other modules is 22: making a combined work based on this library. Thus, the terms and 23: conditions of the GNU General Public License cover the whole 24: combination. 25: 26: As a special exception, the copyright holders of this library give you 27: permission to link this library with independent modules to produce an 28: executable, regardless of the license terms of these independent 29: modules, and to copy and distribute the resulting executable under 30: terms of your choice, provided that you also meet, for each linked 31: independent module, the terms and conditions of the license of that 32: module. An independent module is a module which is not derived from 33: or based on this library. If you modify this library, you may extend 34: this exception to your version of the library, but you are not 35: obligated to do so. If you do not wish to do so, delete this 36: exception statement from your version. */ 37: 38: 39: package java.awt; 40: 41: import java.awt.geom.AffineTransform; 42: import java.awt.geom.PathIterator; 43: import java.awt.geom.Point2D; 44: import java.awt.geom.Rectangle2D; 45: 46: /** 47: * This interface represents an abstract shape. The shape is described by 48: * a {@link PathIterator}, and has callbacks for determining bounding box, 49: * where points and rectangles lie in relation to the shape, and tracing 50: * the trajectory. 51: * 52: * <p>A point is inside if it is completely inside, or on the boundary and 53: * adjacent points in the increasing x or y direction are completely inside. 54: * Unclosed shapes are considered as implicitly closed when performing 55: * <code>contains</code> or <code>intersects</code>. 56: * 57: * @author Aaron M. Renn (arenn@urbanophile.com) 58: * @see PathIterator 59: * @see AffineTransform 60: * @see java.awt.geom.FlatteningPathIterator 61: * @see java.awt.geom.GeneralPath 62: * @since 1.0 63: * @status updated to 1.4 64: */ 65: public interface Shape 66: { 67: /** 68: * Returns a <code>Rectange</code> that bounds the shape. There is no 69: * guarantee that this is the minimum bounding box, particularly if 70: * the shape overflows the finite integer range of a bound. Generally, 71: * <code>getBounds2D</code> returns a tighter bound. 72: * 73: * @return the shape's bounding box 74: * @see #getBounds2D() 75: */ 76: Rectangle getBounds(); 77: 78: /** 79: * Returns a high precision bounding box of the shape. There is no guarantee 80: * that this is the minimum bounding box, but at least it never overflows. 81: * 82: * @return the shape's bounding box 83: * @see #getBounds() 84: * @since 1.2 85: */ 86: Rectangle2D getBounds2D(); 87: 88: /** 89: * Test if the coordinates lie in the shape. 90: * 91: * @param x the x coordinate 92: * @param y the y coordinate 93: * @return true if (x,y) lies inside the shape 94: * @since 1.2 95: */ 96: boolean contains(double x, double y); 97: 98: /** 99: * Test if the point lie in the shape. 100: * 101: * @param p the high-precision point 102: * @return true if p lies inside the shape 103: * @throws NullPointerException if p is null 104: * @since 1.2 105: */ 106: boolean contains(Point2D p); 107: 108: /** 109: * Test if a high-precision rectangle intersects the shape. This is true 110: * if any point in the rectangle is in the shape, with the caveat that the 111: * operation may include high probability estimates when the actual 112: * calculation is prohibitively expensive. The {@link java.awt.geom.Area} 113: * class can be used for more precise answers. 114: * 115: * @param x the x coordinate of the rectangle 116: * @param y the y coordinate of the rectangle 117: * @param w the width of the rectangle, undefined results if negative 118: * @param h the height of the rectangle, undefined results if negative 119: * @return true if the rectangle intersects this shape 120: * @see java.awt.geom.Area 121: * @since 1.2 122: */ 123: boolean intersects(double x, double y, double w, double h); 124: 125: /** 126: * Test if a high-precision rectangle intersects the shape. This is true 127: * if any point in the rectangle is in the shape, with the caveat that the 128: * operation may include high probability estimates when the actual 129: * calculation is prohibitively expensive. The {@link java.awt.geom.Area} 130: * class can be used for more precise answers. 131: * 132: * @param r the rectangle 133: * @return true if the rectangle intersects this shape 134: * @throws NullPointerException if r is null 135: * @see #intersects(double, double, double, double) 136: * @since 1.2 137: */ 138: boolean intersects(Rectangle2D r); 139: 140: /** 141: * Test if a high-precision rectangle lies completely in the shape. This is 142: * true if all points in the rectangle are in the shape, with the caveat 143: * that the operation may include high probability estimates when the actual 144: * calculation is prohibitively expensive. The {@link java.awt.geom.Area} 145: * class can be used for more precise answers. 146: * 147: * @param x the x coordinate of the rectangle 148: * @param y the y coordinate of the rectangle 149: * @param w the width of the rectangle, undefined results if negative 150: * @param h the height of the rectangle, undefined results if negative 151: * @return true if the rectangle is contained in this shape 152: * @see java.awt.geom.Area 153: * @since 1.2 154: */ 155: boolean contains(double x, double y, double w, double h); 156: 157: /** 158: * Test if a high-precision rectangle lies completely in the shape. This is 159: * true if all points in the rectangle are in the shape, with the caveat 160: * that the operation may include high probability estimates when the actual 161: * calculation is prohibitively expensive. The {@link java.awt.geom.Area} 162: * class can be used for more precise answers. 163: * 164: * @param r the rectangle 165: * @return true if the rectangle is contained in this shape 166: * @throws NullPointerException if r is null 167: * @see #contains(double, double, double, double) 168: * @since 1.2 169: */ 170: boolean contains(Rectangle2D r); 171: 172: /** 173: * Return an iterator along the shape boundary. If the optional transform 174: * is provided, the iterator is transformed accordingly. Each call returns 175: * a new object, independent from others in use. It is recommended, but 176: * not required, that the Shape isolate iterations from future changes to 177: * the boundary, and document this fact. 178: * 179: * @param transform an optional transform to apply to the 180: * iterator (<code>null</code> permitted). 181: * @return a new iterator over the boundary 182: * @since 1.2 183: */ 184: PathIterator getPathIterator(AffineTransform transform); 185: 186: /** 187: * Return an iterator along the flattened version of the shape boundary. 188: * Only SEG_MOVETO, SEG_LINETO, and SEG_CLOSE points are returned in the 189: * iterator. The flatness parameter controls how far points are allowed to 190: * differ from the real curve; although a limit on accuracy may cause this 191: * parameter to be enlarged if needed. 192: * 193: * <p>If the optional transform is provided, the iterator is transformed 194: * accordingly. Each call returns a new object, independent from others in 195: * use. It is recommended, but not required, that the Shape isolate 196: * iterations from future changes to the boundary, and document this fact. 197: * 198: * @param transform an optional transform to apply to the 199: * iterator (<code>null</code> permitted). 200: * @param flatness the maximum distance for deviation from the real boundary 201: * @return a new iterator over the boundary 202: * @since 1.2 203: */ 204: PathIterator getPathIterator(AffineTransform transform, double flatness); 205: }