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}. Note that there is no guarantee that the
82 * returned {@code Rectangle} is the smallest bounding box that
83 * encloses the {@code Shape}, only that the {@code Shape}
84 * lies entirely within the indicated {@code Rectangle}. The
85 * returned {@code Rectangle} might also fail to completely
86 * enclose the {@code Shape} if the {@code Shape} overflows
87 * the limited range of the integer data type. The
88 * {@code getBounds2D} 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>
118 * the {@code Shape}.
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} than the {@code getBounds} 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}, only that the {@code Shape} lies
130 * entirely within the indicated {@code Rectangle2D}. The
131 * bounding box returned by this method is usually tighter than that
132 * returned by the {@code getBounds} method and never fails due
133 * to overflow problems since the return value can be an instance of
134 * the {@code Rectangle2D} 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} that is a
163 * high-precision bounding box of the {@code Shape}.
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}, 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} if the specified coordinates are inside
177 * the {@code Shape} boundary; {@code false}
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}, 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} to be tested
189 * @return {@code true} if the specified {@code Point2D} is
190 * inside the boundary of the {@code Shape};
191 * {@code false} otherwise.
192 * @since 1.2
193 */
194 public boolean contains(Point2D p);
195
196 /**
197 * Tests if the interior of the {@code Shape} intersects the
198 * interior of a specified rectangular area.
199 * The rectangular area is considered to intersect the {@code Shape}
200 * if any point is contained in both the interior of the
201 * {@code Shape} 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>
|
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}. Note that there is no guarantee that the
82 * returned {@code Rectangle} is the smallest bounding box that
83 * encloses the {@code Shape}, only that the {@code Shape}
84 * lies entirely within the indicated {@code Rectangle}. The
85 * returned {@code Rectangle} might also fail to completely
86 * enclose the {@code Shape} if the {@code Shape} overflows
87 * the limited range of the integer data type. The
88 * {@code getBounds2D} method generally returns a
89 * tighter bounding box due to its greater flexibility in
90 * representation.
91 *
92 * <p>
93 * Note that the
94 * <a href="{@docRoot}/java.desktop/java/awt/Shape.html#def_insideness">
95 * definition of insideness</a> can lead to situations where points
96 * on the defining outline of the {@code shape} may not be considered
97 * contained in the returned {@code bounds} object, but only in cases
98 * where those points are also not considered contained in the original
99 * {@code shape}.
100 * </p>
101 * <p>
102 * If a {@code point} is inside the {@code shape} according to the
103 * {@link #contains(double x, double y) contains(point)} method, then
104 * it must be inside the returned {@code Rectangle} bounds object
105 * according to the {@link #contains(double x, double y) contains(point)}
106 * method of the {@code bounds}. Specifically:
107 * </p>
108 * <p>
109 * {@code shape.contains(x,y)} requires {@code bounds.contains(x,y)}
110 * </p>
111 * <p>
112 * If a {@code point} is not inside the {@code shape}, then it might
113 * still be contained in the {@code bounds} object:
114 * </p>
119 * the {@code Shape}.
120 * @see #getBounds2D
121 * @since 1.2
122 */
123 public Rectangle getBounds();
124
125 /**
126 * Returns a high precision and more accurate bounding box of
127 * the {@code Shape} than the {@code getBounds} method.
128 * Note that there is no guarantee that the returned
129 * {@link Rectangle2D} is the smallest bounding box that encloses
130 * the {@code Shape}, only that the {@code Shape} lies
131 * entirely within the indicated {@code Rectangle2D}. The
132 * bounding box returned by this method is usually tighter than that
133 * returned by the {@code getBounds} method and never fails due
134 * to overflow problems since the return value can be an instance of
135 * the {@code Rectangle2D} that uses double precision values to
136 * store the dimensions.
137 *
138 * <p>
139 * Note that the
140 * <a href="{@docRoot}/java.desktop/java/awt/Shape.html#def_insideness">
141 * definition of insideness</a> can lead to situations where points
142 * on the defining outline of the {@code shape} may not be considered
143 * contained in the returned {@code bounds} object, but only in cases
144 * where those points are also not considered contained in the original
145 * {@code shape}.
146 * </p>
147 * <p>
148 * If a {@code point} is inside the {@code shape} according to the
149 * {@link #contains(Point2D p) contains(point)} method, then it must
150 * be inside the returned {@code Rectangle2D} bounds object according
151 * to the {@link #contains(Point2D p) contains(point)} method of the
152 * {@code bounds}. Specifically:
153 * </p>
154 * <p>
155 * {@code shape.contains(p)} requires {@code bounds.contains(p)}
156 * </p>
157 * <p>
158 * If a {@code point} is not inside the {@code shape}, then it might
159 * still be contained in the {@code bounds} object:
160 * </p>
161 * <p>
162 * {@code bounds.contains(p)} does not imply {@code shape.contains(p)}
163 * </p>
164 * @return an instance of {@code Rectangle2D} that is a
165 * high-precision bounding box of the {@code Shape}.
166 * @see #getBounds
167 * @since 1.2
168 */
169 public Rectangle2D getBounds2D();
170
171 /**
172 * Tests if the specified coordinates are inside the boundary of the
173 * {@code Shape}, as described by the
174 * <a href="{@docRoot}/java.desktop/java/awt/Shape.html#def_insideness">
175 * definition of insideness</a>.
176 * @param x the specified X coordinate to be tested
177 * @param y the specified Y coordinate to be tested
178 * @return {@code true} if the specified coordinates are inside
179 * the {@code Shape} boundary; {@code false}
180 * otherwise.
181 * @since 1.2
182 */
183 public boolean contains(double x, double y);
184
185 /**
186 * Tests if a specified {@link Point2D} is inside the boundary
187 * of the {@code Shape}, as described by the
188 * <a href="{@docRoot}/java.desktop/java/awt/Shape.html#def_insideness">
189 * definition of insideness</a>.
190 * @param p the specified {@code Point2D} to be tested
191 * @return {@code true} if the specified {@code Point2D} is
192 * inside the boundary of the {@code Shape};
193 * {@code false} otherwise.
194 * @since 1.2
195 */
196 public boolean contains(Point2D p);
197
198 /**
199 * Tests if the interior of the {@code Shape} intersects the
200 * interior of a specified rectangular area.
201 * The rectangular area is considered to intersect the {@code Shape}
202 * if any point is contained in both the interior of the
203 * {@code Shape} and the specified rectangular area.
204 * <p>
205 * The {@code Shape.intersects()} method allows a {@code Shape}
206 * implementation to conservatively return {@code true} when:
207 * <ul>
208 * <li>
|