1 /*
2 * Copyright (c) 1995, 2021, 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 package java.awt;
26
27 import java.io.*;
28 import java.lang.*;
29 import java.util.*;
30 import java.awt.image.ImageObserver;
31 import java.text.AttributedCharacterIterator;
32
33 /**
34 * The {@code Graphics} class is the abstract base class for
35 * all graphics contexts that allow an application to draw onto
36 * components that are realized on various devices, as well as
37 * onto off-screen images.
38 * <p>
39 * A {@code Graphics} object encapsulates state information needed
40 * for the basic rendering operations that Java supports. This
41 * state information includes the following properties:
42 *
43 * <ul>
44 * <li>The {@code Component} object on which to draw.
45 * <li>A translation origin for rendering and clipping coordinates.
46 * <li>The current clip.
47 * <li>The current color.
48 * <li>The current font.
49 * <li>The current logical pixel operation function (XOR or Paint).
50 * <li>The current XOR alternation color
51 * (see {@link Graphics#setXORMode}).
52 * </ul>
53 * <p>
54 * Coordinates are infinitely thin and lie between the pixels of the
55 * output device.
56 * Operations that draw the outline of a figure operate by traversing
57 * an infinitely thin path between pixels with a pixel-sized pen that hangs
58 * down and to the right of the anchor point on the path.
59 * Operations that fill a figure operate by filling the interior
60 * of that infinitely thin path.
61 * Operations that render horizontal text render the ascending
62 * portion of character glyphs entirely above the baseline coordinate.
63 * <p>
64 * The graphics pen hangs down and to the right from the path it traverses.
65 * This has the following implications:
66 * <ul>
67 * <li>If you draw a figure that covers a given rectangle, that
68 * figure occupies one extra row of pixels on the right and bottom edges
69 * as compared to filling a figure that is bounded by that same rectangle.
70 * <li>If you draw a horizontal line along the same <i>y</i> coordinate as
71 * the baseline of a line of text, that line is drawn entirely below
72 * the text, except for any descenders.
73 * </ul><p>
74 * All coordinates that appear as arguments to the methods of this
75 * {@code Graphics} object are considered relative to the
76 * translation origin of this {@code Graphics} object prior to
77 * the invocation of the method.
78 * <p>
79 * All rendering operations modify only pixels which lie within the
80 * area bounded by the current clip, which is specified by a {@link Shape}
81 * in user space and is controlled by the program using the
82 * {@code Graphics} object. This <i>user clip</i>
83 * is transformed into device space and combined with the
84 * <i>device clip</i>, which is defined by the visibility of windows and
85 * device extents. The combination of the user clip and device clip
86 * defines the <i>composite clip</i>, which determines the final clipping
87 * region. The user clip cannot be modified by the rendering
88 * system to reflect the resulting composite clip. The user clip can only
89 * be changed through the {@code setClip} or {@code clipRect}
90 * methods.
91 * All drawing or writing is done in the current color,
92 * using the current paint mode, and in the current font.
93 *
94 * @author Sami Shaio
95 * @author Arthur van Hoff
96 * @see java.awt.Component
97 * @see java.awt.Graphics#clipRect(int, int, int, int)
98 * @see java.awt.Graphics#setColor(java.awt.Color)
99 * @see java.awt.Graphics#setPaintMode()
100 * @see java.awt.Graphics#setXORMode(java.awt.Color)
101 * @see java.awt.Graphics#setFont(java.awt.Font)
102 * @since 1.0
103 */
104 public abstract class Graphics {
105
106 /**
107 * Constructs a new {@code Graphics} object.
108 * This constructor is the default constructor for a graphics
109 * context.
110 * <p>
111 * Since {@code Graphics} is an abstract class, applications
112 * cannot call this constructor directly. Graphics contexts are
113 * obtained from other graphics contexts or are created by calling
114 * {@code getGraphics} on a component.
115 * @see java.awt.Graphics#create()
116 * @see java.awt.Component#getGraphics
117 */
118 protected Graphics() {
119 }
120
121 /**
122 * Creates a new {@code Graphics} object that is
123 * a copy of this {@code Graphics} object.
124 * @return a new graphics context that is a copy of
125 * this graphics context.
126 */
127 public abstract Graphics create();
128
129 /**
130 * Creates a new {@code Graphics} object based on this
131 * {@code Graphics} object, but with a new translation and clip area.
132 * The new {@code Graphics} object has its origin
133 * translated to the specified point (<i>x</i>, <i>y</i>).
134 * Its clip area is determined by the intersection of the original
135 * clip area with the specified rectangle. The arguments are all
136 * interpreted in the coordinate system of the original
137 * {@code Graphics} object. The new graphics context is
138 * identical to the original, except in two respects:
139 *
140 * <ul>
141 * <li>
142 * The new graphics context is translated by (<i>x</i>, <i>y</i>).
143 * That is to say, the point ({@code 0}, {@code 0}) in the
144 * new graphics context is the same as (<i>x</i>, <i>y</i>) in
145 * the original graphics context.
146 * <li>
147 * The new graphics context has an additional clipping rectangle, in
148 * addition to whatever (translated) clipping rectangle it inherited
149 * from the original graphics context. The origin of the new clipping
150 * rectangle is at ({@code 0}, {@code 0}), and its size
151 * is specified by the {@code width} and {@code height}
152 * arguments.
153 * </ul>
154 *
155 * @param x the <i>x</i> coordinate.
156 * @param y the <i>y</i> coordinate.
157 * @param width the width of the clipping rectangle.
158 * @param height the height of the clipping rectangle.
159 * @return a new graphics context.
160 * @see java.awt.Graphics#translate
161 * @see java.awt.Graphics#clipRect
162 */
163 public Graphics create(int x, int y, int width, int height) {
164 Graphics g = create();
165 if (g == null) return null;
166 g.translate(x, y);
167 g.clipRect(0, 0, width, height);
168 return g;
169 }
170
171 /**
172 * Translates the origin of the graphics context to the point
173 * (<i>x</i>, <i>y</i>) in the current coordinate system.
174 * Modifies this graphics context so that its new origin corresponds
175 * to the point (<i>x</i>, <i>y</i>) in this graphics context's
176 * original coordinate system. All coordinates used in subsequent
177 * rendering operations on this graphics context will be relative
178 * to this new origin.
179 * @param x the <i>x</i> coordinate.
180 * @param y the <i>y</i> coordinate.
181 */
182 public abstract void translate(int x, int y);
183
184 /**
185 * Gets this graphics context's current color.
186 * @return this graphics context's current color.
187 * @see java.awt.Color
188 * @see java.awt.Graphics#setColor(Color)
189 */
190 public abstract Color getColor();
191
192 /**
193 * Sets this graphics context's current color to the specified
194 * color. All subsequent graphics operations using this graphics
195 * context use this specified color.
196 * A null argument is silently ignored.
197 * @param c the new rendering color.
198 * @see java.awt.Color
199 * @see java.awt.Graphics#getColor
200 */
201 public abstract void setColor(Color c);
202
203 /**
204 * Sets the paint mode of this graphics context to overwrite the
205 * destination with this graphics context's current color.
206 * This sets the logical pixel operation function to the paint or
207 * overwrite mode. All subsequent rendering operations will
208 * overwrite the destination with the current color.
209 */
210 public abstract void setPaintMode();
211
212 /**
213 * Sets the paint mode of this graphics context to alternate between
214 * this graphics context's current color and the new specified color.
215 * This specifies that logical pixel operations are performed in the
216 * XOR mode, which alternates pixels between the current color and
217 * a specified XOR color.
218 * <p>
219 * When drawing operations are performed, pixels which are the
220 * current color are changed to the specified color, and vice versa.
221 * <p>
222 * Pixels that are of colors other than those two colors are changed
223 * in an unpredictable but reversible manner; if the same figure is
224 * drawn twice, then all pixels are restored to their original values.
225 * @param c1 the XOR alternation color
226 */
227 public abstract void setXORMode(Color c1);
228
229 /**
230 * Gets the current font.
231 * @return this graphics context's current font.
232 * @see java.awt.Font
233 * @see java.awt.Graphics#setFont(Font)
234 */
235 public abstract Font getFont();
236
237 /**
238 * Sets this graphics context's font to the specified font.
239 * All subsequent text operations using this graphics context
240 * use this font. A null argument is silently ignored.
241 * @param font the font.
242 * @see java.awt.Graphics#getFont
243 * @see java.awt.Graphics#drawString(java.lang.String, int, int)
244 * @see java.awt.Graphics#drawBytes(byte[], int, int, int, int)
245 * @see java.awt.Graphics#drawChars(char[], int, int, int, int)
246 */
247 public abstract void setFont(Font font);
248
249 /**
250 * Gets the font metrics of the current font.
251 * @return the font metrics of this graphics
252 * context's current font.
253 * @see java.awt.Graphics#getFont
254 * @see java.awt.FontMetrics
255 * @see java.awt.Graphics#getFontMetrics(Font)
256 */
257 public FontMetrics getFontMetrics() {
258 return getFontMetrics(getFont());
259 }
260
261 /**
262 * Gets the font metrics for the specified font.
263 * @return the font metrics for the specified font.
264 * @param f the specified font
265 * @see java.awt.Graphics#getFont
266 * @see java.awt.FontMetrics
267 * @see java.awt.Graphics#getFontMetrics()
268 */
269 public abstract FontMetrics getFontMetrics(Font f);
270
271
272 /**
273 * Returns the bounding rectangle of the current clipping area.
274 * This method refers to the user clip, which is independent of the
275 * clipping associated with device bounds and window visibility.
276 * If no clip has previously been set, or if the clip has been
277 * cleared using {@code setClip(null)}, this method returns
278 * {@code null}.
279 * The coordinates in the rectangle are relative to the coordinate
280 * system origin of this graphics context.
281 * @return the bounding rectangle of the current clipping area,
282 * or {@code null} if no clip is set.
283 * @see java.awt.Graphics#getClip
284 * @see java.awt.Graphics#clipRect
285 * @see java.awt.Graphics#setClip(int, int, int, int)
286 * @see java.awt.Graphics#setClip(Shape)
287 * @since 1.1
288 */
289 public abstract Rectangle getClipBounds();
290
291 /**
292 * Intersects the current clip with the specified rectangle.
293 * The resulting clipping area is the intersection of the current
294 * clipping area and the specified rectangle. If there is no
295 * current clipping area, either because the clip has never been
296 * set, or the clip has been cleared using {@code setClip(null)},
297 * the specified rectangle becomes the new clip.
298 * This method sets the user clip, which is independent of the
299 * clipping associated with device bounds and window visibility.
300 * This method can only be used to make the current clip smaller.
301 * To set the current clip larger, use any of the setClip methods.
302 * Rendering operations have no effect outside of the clipping area.
303 * @param x the x coordinate of the rectangle to intersect the clip with
304 * @param y the y coordinate of the rectangle to intersect the clip with
305 * @param width the width of the rectangle to intersect the clip with
306 * @param height the height of the rectangle to intersect the clip with
307 * @see #setClip(int, int, int, int)
308 * @see #setClip(Shape)
309 */
310 public abstract void clipRect(int x, int y, int width, int height);
311
312 /**
313 * Sets the current clip to the rectangle specified by the given
314 * coordinates. This method sets the user clip, which is
315 * independent of the clipping associated with device bounds
316 * and window visibility.
317 * Rendering operations have no effect outside of the clipping area.
318 * @param x the <i>x</i> coordinate of the new clip rectangle.
319 * @param y the <i>y</i> coordinate of the new clip rectangle.
320 * @param width the width of the new clip rectangle.
321 * @param height the height of the new clip rectangle.
322 * @see java.awt.Graphics#clipRect
323 * @see java.awt.Graphics#setClip(Shape)
324 * @see java.awt.Graphics#getClip
325 * @since 1.1
326 */
327 public abstract void setClip(int x, int y, int width, int height);
328
329 /**
330 * Gets the current clipping area.
331 * This method returns the user clip, which is independent of the
332 * clipping associated with device bounds and window visibility.
333 * If no clip has previously been set, or if the clip has been
334 * cleared using {@code setClip(null)}, this method returns
335 * {@code null}.
336 * @return a {@code Shape} object representing the
337 * current clipping area, or {@code null} if
338 * no clip is set.
339 * @see java.awt.Graphics#getClipBounds
340 * @see java.awt.Graphics#clipRect
341 * @see java.awt.Graphics#setClip(int, int, int, int)
342 * @see java.awt.Graphics#setClip(Shape)
343 * @since 1.1
344 */
345 public abstract Shape getClip();
346
347 /**
348 * Sets the current clipping area to an arbitrary clip shape.
349 * Not all objects that implement the {@code Shape}
350 * interface can be used to set the clip. The only
351 * {@code Shape} objects that are guaranteed to be
352 * supported are {@code Shape} objects that are
353 * obtained via the {@code getClip} method and via
354 * {@code Rectangle} objects. This method sets the
355 * user clip, which is independent of the clipping associated
356 * with device bounds and window visibility.
357 * @param clip the {@code Shape} to use to set the clip.
358 * Passing {@code null} clears the current {@code clip}.
359 * @see java.awt.Graphics#getClip()
360 * @see java.awt.Graphics#clipRect
361 * @see java.awt.Graphics#setClip(int, int, int, int)
362 * @since 1.1
363 */
364 public abstract void setClip(Shape clip);
365
366 /**
367 * Copies an area of the component by a distance specified by
368 * {@code dx} and {@code dy}. From the point specified
369 * by {@code x} and {@code y}, this method
370 * copies downwards and to the right. To copy an area of the
371 * component to the left or upwards, specify a negative value for
372 * {@code dx} or {@code dy}.
373 * If a portion of the source rectangle lies outside the bounds
374 * of the component, or is obscured by another window or component,
375 * {@code copyArea} will be unable to copy the associated
376 * pixels. The area that is omitted can be refreshed by calling
377 * the component's {@code paint} method.
378 * @param x the <i>x</i> coordinate of the source rectangle.
379 * @param y the <i>y</i> coordinate of the source rectangle.
380 * @param width the width of the source rectangle.
381 * @param height the height of the source rectangle.
382 * @param dx the horizontal distance to copy the pixels.
383 * @param dy the vertical distance to copy the pixels.
384 */
385 public abstract void copyArea(int x, int y, int width, int height,
386 int dx, int dy);
387
388 /**
389 * Draws a line, using the current color, between the points
390 * <code>(x1, y1)</code> and <code>(x2, y2)</code>
391 * in this graphics context's coordinate system.
392 * @param x1 the first point's <i>x</i> coordinate.
393 * @param y1 the first point's <i>y</i> coordinate.
394 * @param x2 the second point's <i>x</i> coordinate.
395 * @param y2 the second point's <i>y</i> coordinate.
396 */
397 public abstract void drawLine(int x1, int y1, int x2, int y2);
398
399 /**
400 * Fills the specified rectangle.
401 * The left and right edges of the rectangle are at
402 * {@code x} and <code>x + width - 1</code>.
403 * The top and bottom edges are at
404 * {@code y} and <code>y + height - 1</code>.
405 * The resulting rectangle covers an area
406 * {@code width} pixels wide by
407 * {@code height} pixels tall.
408 * The rectangle is filled using the graphics context's current color.
409 * @param x the <i>x</i> coordinate
410 * of the rectangle to be filled.
411 * @param y the <i>y</i> coordinate
412 * of the rectangle to be filled.
413 * @param width the width of the rectangle to be filled.
414 * @param height the height of the rectangle to be filled.
415 * @see java.awt.Graphics#clearRect
416 * @see java.awt.Graphics#drawRect
417 */
418 public abstract void fillRect(int x, int y, int width, int height);
419
420 /**
421 * Draws the outline of the specified rectangle.
422 * The left and right edges of the rectangle are at
423 * {@code x} and <code>x + width</code>.
424 * The top and bottom edges are at
425 * {@code y} and <code>y + height</code>.
426 * The rectangle is drawn using the graphics context's current color.
427 * @param x the <i>x</i> coordinate
428 * of the rectangle to be drawn.
429 * @param y the <i>y</i> coordinate
430 * of the rectangle to be drawn.
431 * @param width the width of the rectangle to be drawn.
432 * @param height the height of the rectangle to be drawn.
433 * @see java.awt.Graphics#fillRect
434 * @see java.awt.Graphics#clearRect
435 */
436 public void drawRect(int x, int y, int width, int height) {
437 if ((width < 0) || (height < 0)) {
438 return;
439 }
440
441 if (height == 0 || width == 0) {
442 drawLine(x, y, x + width, y + height);
443 } else {
444 drawLine(x, y, x + width - 1, y);
445 drawLine(x + width, y, x + width, y + height - 1);
446 drawLine(x + width, y + height, x + 1, y + height);
447 drawLine(x, y + height, x, y + 1);
448 }
449 }
450
451 /**
452 * Clears the specified rectangle by filling it with the background
453 * color of the current drawing surface. This operation does not
454 * use the current paint mode.
455 * <p>
456 * Beginning with Java 1.1, the background color
457 * of offscreen images may be system dependent. Applications should
458 * use {@code setColor} followed by {@code fillRect} to
459 * ensure that an offscreen image is cleared to a specific color.
460 * @param x the <i>x</i> coordinate of the rectangle to clear.
461 * @param y the <i>y</i> coordinate of the rectangle to clear.
462 * @param width the width of the rectangle to clear.
463 * @param height the height of the rectangle to clear.
464 * @see java.awt.Graphics#fillRect(int, int, int, int)
465 * @see java.awt.Graphics#drawRect
466 * @see java.awt.Graphics#setColor(java.awt.Color)
467 * @see java.awt.Graphics#setPaintMode
468 * @see java.awt.Graphics#setXORMode(java.awt.Color)
469 */
470 public abstract void clearRect(int x, int y, int width, int height);
471
472 /**
473 * Draws an outlined round-cornered rectangle using this graphics
474 * context's current color. The left and right edges of the rectangle
475 * are at {@code x} and <code>x + width</code>,
476 * respectively. The top and bottom edges of the rectangle are at
477 * {@code y} and <code>y + height</code>.
478 * @param x the <i>x</i> coordinate of the rectangle to be drawn.
479 * @param y the <i>y</i> coordinate of the rectangle to be drawn.
480 * @param width the width of the rectangle to be drawn.
481 * @param height the height of the rectangle to be drawn.
482 * @param arcWidth the horizontal diameter of the arc
483 * at the four corners.
484 * @param arcHeight the vertical diameter of the arc
485 * at the four corners.
486 * @see java.awt.Graphics#fillRoundRect
487 */
488 public abstract void drawRoundRect(int x, int y, int width, int height,
489 int arcWidth, int arcHeight);
490
491 /**
492 * Fills the specified rounded corner rectangle with the current color.
493 * The left and right edges of the rectangle
494 * are at {@code x} and <code>x + width - 1</code>,
495 * respectively. The top and bottom edges of the rectangle are at
496 * {@code y} and <code>y + height - 1</code>.
497 * @param x the <i>x</i> coordinate of the rectangle to be filled.
498 * @param y the <i>y</i> coordinate of the rectangle to be filled.
499 * @param width the width of the rectangle to be filled.
500 * @param height the height of the rectangle to be filled.
501 * @param arcWidth the horizontal diameter
502 * of the arc at the four corners.
503 * @param arcHeight the vertical diameter
504 * of the arc at the four corners.
505 * @see java.awt.Graphics#drawRoundRect
506 */
507 public abstract void fillRoundRect(int x, int y, int width, int height,
508 int arcWidth, int arcHeight);
509
510 /**
511 * Draws a 3-D highlighted outline of the specified rectangle.
512 * The edges of the rectangle are highlighted so that they
513 * appear to be beveled and lit from the upper left corner.
514 * <p>
515 * The colors used for the highlighting effect are determined
516 * based on the current color.
517 * The resulting rectangle covers an area that is
518 * <code>width + 1</code> pixels wide
519 * by <code>height + 1</code> pixels tall.
520 * @param x the <i>x</i> coordinate of the rectangle to be drawn.
521 * @param y the <i>y</i> coordinate of the rectangle to be drawn.
522 * @param width the width of the rectangle to be drawn.
523 * @param height the height of the rectangle to be drawn.
524 * @param raised a boolean that determines whether the rectangle
525 * appears to be raised above the surface
526 * or sunk into the surface.
527 * @see java.awt.Graphics#fill3DRect
528 */
529 public void draw3DRect(int x, int y, int width, int height,
530 boolean raised) {
531 Color c = getColor();
532 Color brighter = c.brighter();
533 Color darker = c.darker();
534
535 setColor(raised ? brighter : darker);
536 drawLine(x, y, x, y + height);
537 drawLine(x + 1, y, x + width - 1, y);
538 setColor(raised ? darker : brighter);
539 drawLine(x + 1, y + height, x + width, y + height);
540 drawLine(x + width, y, x + width, y + height - 1);
541 setColor(c);
542 }
543
544 /**
545 * Paints a 3-D highlighted rectangle filled with the current color.
546 * The edges of the rectangle will be highlighted so that it appears
547 * as if the edges were beveled and lit from the upper left corner.
548 * The colors used for the highlighting effect will be determined from
549 * the current color.
550 * @param x the <i>x</i> coordinate of the rectangle to be filled.
551 * @param y the <i>y</i> coordinate of the rectangle to be filled.
552 * @param width the width of the rectangle to be filled.
553 * @param height the height of the rectangle to be filled.
554 * @param raised a boolean value that determines whether the
555 * rectangle appears to be raised above the surface
556 * or etched into the surface.
557 * @see java.awt.Graphics#draw3DRect
558 */
559 public void fill3DRect(int x, int y, int width, int height,
560 boolean raised) {
561 Color c = getColor();
562 Color brighter = c.brighter();
563 Color darker = c.darker();
564
565 if (!raised) {
566 setColor(darker);
567 }
568 fillRect(x+1, y+1, width-2, height-2);
569 setColor(raised ? brighter : darker);
570 drawLine(x, y, x, y + height - 1);
571 drawLine(x + 1, y, x + width - 2, y);
572 setColor(raised ? darker : brighter);
573 drawLine(x + 1, y + height - 1, x + width - 1, y + height - 1);
574 drawLine(x + width - 1, y, x + width - 1, y + height - 2);
575 setColor(c);
576 }
577
578 /**
579 * Draws the outline of an oval.
580 * The result is a circle or ellipse that fits within the
581 * rectangle specified by the {@code x}, {@code y},
582 * {@code width}, and {@code height} arguments.
583 * <p>
584 * The oval covers an area that is
585 * <code>width + 1</code> pixels wide
586 * and <code>height + 1</code> pixels tall.
587 * @param x the <i>x</i> coordinate of the upper left
588 * corner of the oval to be drawn.
589 * @param y the <i>y</i> coordinate of the upper left
590 * corner of the oval to be drawn.
591 * @param width the width of the oval to be drawn.
592 * @param height the height of the oval to be drawn.
593 * @see java.awt.Graphics#fillOval
594 */
595 public abstract void drawOval(int x, int y, int width, int height);
596
597 /**
598 * Fills an oval bounded by the specified rectangle with the
599 * current color.
600 * @param x the <i>x</i> coordinate of the upper left corner
601 * of the oval to be filled.
602 * @param y the <i>y</i> coordinate of the upper left corner
603 * of the oval to be filled.
604 * @param width the width of the oval to be filled.
605 * @param height the height of the oval to be filled.
606 * @see java.awt.Graphics#drawOval
607 */
608 public abstract void fillOval(int x, int y, int width, int height);
609
610 /**
611 * Draws the outline of a circular or elliptical arc
612 * covering the specified rectangle.
613 * <p>
614 * The resulting arc begins at {@code startAngle} and extends
615 * for {@code arcAngle} degrees, using the current color.
616 * Angles are interpreted such that 0 degrees
617 * is at the 3 o'clock position.
618 * A positive value indicates a counter-clockwise rotation
619 * while a negative value indicates a clockwise rotation.
620 * <p>
621 * The center of the arc is the center of the rectangle whose origin
622 * is (<i>x</i>, <i>y</i>) and whose size is specified by the
623 * {@code width} and {@code height} arguments.
624 * <p>
625 * The resulting arc covers an area
626 * <code>width + 1</code> pixels wide
627 * by <code>height + 1</code> pixels tall.
628 * <p>
629 * The angles are specified relative to the non-square extents of
630 * the bounding rectangle such that 45 degrees always falls on the
631 * line from the center of the ellipse to the upper right corner of
632 * the bounding rectangle. As a result, if the bounding rectangle is
633 * noticeably longer in one axis than the other, the angles to the
634 * start and end of the arc segment will be skewed farther along the
635 * longer axis of the bounds.
636 * @param x the <i>x</i> coordinate of the
637 * upper-left corner of the arc to be drawn.
638 * @param y the <i>y</i> coordinate of the
639 * upper-left corner of the arc to be drawn.
640 * @param width the width of the arc to be drawn.
641 * @param height the height of the arc to be drawn.
642 * @param startAngle the beginning angle.
643 * @param arcAngle the angular extent of the arc,
644 * relative to the start angle.
645 * @see java.awt.Graphics#fillArc
646 */
647 public abstract void drawArc(int x, int y, int width, int height,
648 int startAngle, int arcAngle);
649
650 /**
651 * Fills a circular or elliptical arc covering the specified rectangle.
652 * <p>
653 * The resulting arc begins at {@code startAngle} and extends
654 * for {@code arcAngle} degrees.
655 * Angles are interpreted such that 0 degrees
656 * is at the 3 o'clock position.
657 * A positive value indicates a counter-clockwise rotation
658 * while a negative value indicates a clockwise rotation.
659 * <p>
660 * The center of the arc is the center of the rectangle whose origin
661 * is (<i>x</i>, <i>y</i>) and whose size is specified by the
662 * {@code width} and {@code height} arguments.
663 * <p>
664 * The resulting arc covers an area
665 * <code>width + 1</code> pixels wide
666 * by <code>height + 1</code> pixels tall.
667 * <p>
668 * The angles are specified relative to the non-square extents of
669 * the bounding rectangle such that 45 degrees always falls on the
670 * line from the center of the ellipse to the upper right corner of
671 * the bounding rectangle. As a result, if the bounding rectangle is
672 * noticeably longer in one axis than the other, the angles to the
673 * start and end of the arc segment will be skewed farther along the
674 * longer axis of the bounds.
675 * @param x the <i>x</i> coordinate of the
676 * upper-left corner of the arc to be filled.
677 * @param y the <i>y</i> coordinate of the
678 * upper-left corner of the arc to be filled.
679 * @param width the width of the arc to be filled.
680 * @param height the height of the arc to be filled.
681 * @param startAngle the beginning angle.
682 * @param arcAngle the angular extent of the arc,
683 * relative to the start angle.
684 * @see java.awt.Graphics#drawArc
685 */
686 public abstract void fillArc(int x, int y, int width, int height,
687 int startAngle, int arcAngle);
688
689 /**
690 * Draws a sequence of connected lines defined by
691 * arrays of <i>x</i> and <i>y</i> coordinates.
692 * Each pair of (<i>x</i>, <i>y</i>) coordinates defines a point.
693 * The figure is not closed if the first point
694 * differs from the last point.
695 * @param xPoints an array of <i>x</i> points
696 * @param yPoints an array of <i>y</i> points
697 * @param nPoints the total number of points
698 * @see java.awt.Graphics#drawPolygon(int[], int[], int)
699 * @since 1.1
700 */
701 public abstract void drawPolyline(int[] xPoints, int[] yPoints,
702 int nPoints);
703
704 /**
705 * Draws a closed polygon defined by
706 * arrays of <i>x</i> and <i>y</i> coordinates.
707 * Each pair of (<i>x</i>, <i>y</i>) coordinates defines a point.
708 * <p>
709 * This method draws the polygon defined by {@code nPoint} line
710 * segments, where the first <code>nPoint - 1</code>
711 * line segments are line segments from
712 * <code>(xPoints[i - 1], yPoints[i - 1])</code>
713 * to <code>(xPoints[i], yPoints[i])</code>, for
714 * 1 ≤ <i>i</i> ≤ {@code nPoints}.
715 * The figure is automatically closed by drawing a line connecting
716 * the final point to the first point, if those points are different.
717 * @param xPoints a an array of {@code x} coordinates.
718 * @param yPoints a an array of {@code y} coordinates.
719 * @param nPoints a the total number of points.
720 * @see java.awt.Graphics#fillPolygon
721 * @see java.awt.Graphics#drawPolyline
722 */
723 public abstract void drawPolygon(int[] xPoints, int[] yPoints,
724 int nPoints);
725
726 /**
727 * Draws the outline of a polygon defined by the specified
728 * {@code Polygon} object.
729 * @param p the polygon to draw.
730 * @see java.awt.Graphics#fillPolygon
731 * @see java.awt.Graphics#drawPolyline
732 */
733 public void drawPolygon(Polygon p) {
734 drawPolygon(p.xpoints, p.ypoints, p.npoints);
735 }
736
737 /**
738 * Fills a closed polygon defined by
739 * arrays of <i>x</i> and <i>y</i> coordinates.
740 * <p>
741 * This method draws the polygon defined by {@code nPoint} line
742 * segments, where the first <code>nPoint - 1</code>
743 * line segments are line segments from
744 * <code>(xPoints[i - 1], yPoints[i - 1])</code>
745 * to <code>(xPoints[i], yPoints[i])</code>, for
746 * 1 ≤ <i>i</i> ≤ {@code nPoints}.
747 * The figure is automatically closed by drawing a line connecting
748 * the final point to the first point, if those points are different.
749 * <p>
750 * The area inside the polygon is defined using an
751 * even-odd fill rule, also known as the alternating rule.
752 * @param xPoints a an array of {@code x} coordinates.
753 * @param yPoints a an array of {@code y} coordinates.
754 * @param nPoints a the total number of points.
755 * @see java.awt.Graphics#drawPolygon(int[], int[], int)
756 */
757 public abstract void fillPolygon(int[] xPoints, int[] yPoints,
758 int nPoints);
759
760 /**
761 * Fills the polygon defined by the specified Polygon object with
762 * the graphics context's current color.
763 * <p>
764 * The area inside the polygon is defined using an
765 * even-odd fill rule, also known as the alternating rule.
766 * @param p the polygon to fill.
767 * @see java.awt.Graphics#drawPolygon(int[], int[], int)
768 */
769 public void fillPolygon(Polygon p) {
770 fillPolygon(p.xpoints, p.ypoints, p.npoints);
771 }
772
773 /**
774 * Draws the text given by the specified string, using this
775 * graphics context's current font and color. The baseline of the
776 * leftmost character is at position (<i>x</i>, <i>y</i>) in this
777 * graphics context's coordinate system.
778 * @param str the string to be drawn.
779 * @param x the <i>x</i> coordinate.
780 * @param y the <i>y</i> coordinate.
781 * @throws NullPointerException if {@code str} is {@code null}.
782 * @see java.awt.Graphics#drawBytes
783 * @see java.awt.Graphics#drawChars
784 */
785 public abstract void drawString(String str, int x, int y);
786
787 /**
788 * Renders the text of the specified iterator applying its attributes
789 * in accordance with the specification of the
790 * {@link java.awt.font.TextAttribute TextAttribute} class.
791 * <p>
792 * The baseline of the leftmost character is at position
793 * (<i>x</i>, <i>y</i>) in this graphics context's coordinate system.
794 * @param iterator the iterator whose text is to be drawn
795 * @param x the <i>x</i> coordinate.
796 * @param y the <i>y</i> coordinate.
797 * @throws NullPointerException if {@code iterator} is
798 * {@code null}.
799 * @see java.awt.Graphics#drawBytes
800 * @see java.awt.Graphics#drawChars
801 */
802 public abstract void drawString(AttributedCharacterIterator iterator,
803 int x, int y);
804
805 /**
806 * Draws the text given by the specified character array, using this
807 * graphics context's current font and color. The baseline of the
808 * first character is at position (<i>x</i>, <i>y</i>) in this
809 * graphics context's coordinate system.
810 * @param data the array of characters to be drawn
811 * @param offset the start offset in the data
812 * @param length the number of characters to be drawn
813 * @param x the <i>x</i> coordinate of the baseline of the text
814 * @param y the <i>y</i> coordinate of the baseline of the text
815 * @throws NullPointerException if {@code data} is {@code null}.
816 * @throws IndexOutOfBoundsException if {@code offset} or
817 * {@code length} is less than zero, or
818 * {@code offset+length} is greater than the length of the
819 * {@code data} array.
820 * @see java.awt.Graphics#drawBytes
821 * @see java.awt.Graphics#drawString
822 */
823 public void drawChars(char[] data, int offset, int length, int x, int y) {
824 drawString(new String(data, offset, length), x, y);
825 }
826
827 /**
828 * Draws the text given by the specified byte array, using this
829 * graphics context's current font and color. The baseline of the
830 * first character is at position (<i>x</i>, <i>y</i>) in this
831 * graphics context's coordinate system.
832 * <p>
833 * Use of this method is not recommended as each byte is interpreted
834 * as a Unicode code point in the range 0 to 255, and so can only be
835 * used to draw Latin characters in that range.
836 * @param data the data to be drawn
837 * @param offset the start offset in the data
838 * @param length the number of bytes that are drawn
839 * @param x the <i>x</i> coordinate of the baseline of the text
840 * @param y the <i>y</i> coordinate of the baseline of the text
841 * @throws NullPointerException if {@code data} is {@code null}.
842 * @throws IndexOutOfBoundsException if {@code offset} or
843 * {@code length} is less than zero, or {@code offset+length}
844 * is greater than the length of the {@code data} array.
845 * @see java.awt.Graphics#drawChars
846 * @see java.awt.Graphics#drawString
847 */
848 @SuppressWarnings("deprecation")
849 public void drawBytes(byte[] data, int offset, int length, int x, int y) {
850 drawString(new String(data, 0, offset, length), x, y);
851 }
852
853 /**
854 * Draws as much of the specified image as is currently available.
855 * The image is drawn with its top-left corner at
856 * (<i>x</i>, <i>y</i>) in this graphics context's coordinate
857 * space. Transparent pixels in the image do not affect whatever
858 * pixels are already there.
859 * <p>
860 * This method returns immediately in all cases, even if the
861 * complete image has not yet been loaded, and it has not been dithered
862 * and converted for the current output device.
863 * <p>
864 * If the image has completely loaded and its pixels are
865 * no longer being changed, then
866 * {@code drawImage} returns {@code true}.
867 * Otherwise, {@code drawImage} returns {@code false}
868 * and as more of
869 * the image becomes available
870 * or it is time to draw another frame of animation,
871 * the process that loads the image notifies
872 * the specified image observer.
873 * @param img the specified image to be drawn. This method does
874 * nothing if {@code img} is null.
875 * @param x the <i>x</i> coordinate.
876 * @param y the <i>y</i> coordinate.
877 * @param observer object to be notified as more of
878 * the image is converted.
879 * @return {@code false} if the image pixels are still changing;
880 * {@code true} otherwise.
881 * @see java.awt.Image
882 * @see java.awt.image.ImageObserver
883 * @see java.awt.image.ImageObserver#imageUpdate(java.awt.Image, int, int, int, int, int)
884 */
885 public abstract boolean drawImage(Image img, int x, int y,
886 ImageObserver observer);
887
888 /**
889 * Draws as much of the specified image as has already been scaled
890 * to fit inside the specified rectangle.
891 * <p>
892 * The image is drawn inside the specified rectangle of this
893 * graphics context's coordinate space, and is scaled if
894 * necessary. Transparent pixels do not affect whatever pixels
895 * are already there.
896 * <p>
897 * This method returns immediately in all cases, even if the
898 * entire image has not yet been scaled, dithered, and converted
899 * for the current output device.
900 * If the current output representation is not yet complete, then
901 * {@code drawImage} returns {@code false}. As more of
902 * the image becomes available, the process that loads the image notifies
903 * the image observer by calling its {@code imageUpdate} method.
904 * <p>
905 * A scaled version of an image will not necessarily be
906 * available immediately just because an unscaled version of the
907 * image has been constructed for this output device. Each size of
908 * the image may be cached separately and generated from the original
909 * data in a separate image production sequence.
910 * @param img the specified image to be drawn. This method does
911 * nothing if {@code img} is null.
912 * @param x the <i>x</i> coordinate.
913 * @param y the <i>y</i> coordinate.
914 * @param width the width of the rectangle.
915 * @param height the height of the rectangle.
916 * @param observer object to be notified as more of
917 * the image is converted.
918 * @return {@code false} if the image pixels are still changing;
919 * {@code true} otherwise.
920 * @see java.awt.Image
921 * @see java.awt.image.ImageObserver
922 * @see java.awt.image.ImageObserver#imageUpdate(java.awt.Image, int, int, int, int, int)
923 */
924 public abstract boolean drawImage(Image img, int x, int y,
925 int width, int height,
926 ImageObserver observer);
927
928 /**
929 * Draws as much of the specified image as is currently available.
930 * The image is drawn with its top-left corner at
931 * (<i>x</i>, <i>y</i>) in this graphics context's coordinate
932 * space. Transparent pixels are drawn in the specified
933 * background color.
934 * <p>
935 * This operation is equivalent to filling a rectangle of the
936 * width and height of the specified image with the given color and then
937 * drawing the image on top of it, but possibly more efficient.
938 * <p>
939 * This method returns immediately in all cases, even if the
940 * complete image has not yet been loaded, and it has not been dithered
941 * and converted for the current output device.
942 * <p>
943 * If the image has completely loaded and its pixels are
944 * no longer being changed, then
945 * {@code drawImage} returns {@code true}.
946 * Otherwise, {@code drawImage} returns {@code false}
947 * and as more of
948 * the image becomes available
949 * or it is time to draw another frame of animation,
950 * the process that loads the image notifies
951 * the specified image observer.
952 * @param img the specified image to be drawn. This method does
953 * nothing if {@code img} is null.
954 * @param x the <i>x</i> coordinate.
955 * @param y the <i>y</i> coordinate.
956 * @param bgcolor the background color to paint under the
957 * non-opaque portions of the image.
958 * @param observer object to be notified as more of
959 * the image is converted.
960 * @return {@code false} if the image pixels are still changing;
961 * {@code true} otherwise.
962 * @see java.awt.Image
963 * @see java.awt.image.ImageObserver
964 * @see java.awt.image.ImageObserver#imageUpdate(java.awt.Image, int, int, int, int, int)
965 */
966 public abstract boolean drawImage(Image img, int x, int y,
967 Color bgcolor,
968 ImageObserver observer);
969
970 /**
971 * Draws as much of the specified image as has already been scaled
972 * to fit inside the specified rectangle.
973 * <p>
974 * The image is drawn inside the specified rectangle of this
975 * graphics context's coordinate space, and is scaled if
976 * necessary. Transparent pixels are drawn in the specified
977 * background color.
978 * This operation is equivalent to filling a rectangle of the
979 * width and height of the specified image with the given color and then
980 * drawing the image on top of it, but possibly more efficient.
981 * <p>
982 * This method returns immediately in all cases, even if the
983 * entire image has not yet been scaled, dithered, and converted
984 * for the current output device.
985 * If the current output representation is not yet complete then
986 * {@code drawImage} returns {@code false}. As more of
987 * the image becomes available, the process that loads the image notifies
988 * the specified image observer.
989 * <p>
990 * A scaled version of an image will not necessarily be
991 * available immediately just because an unscaled version of the
992 * image has been constructed for this output device. Each size of
993 * the image may be cached separately and generated from the original
994 * data in a separate image production sequence.
995 * @param img the specified image to be drawn. This method does
996 * nothing if {@code img} is null.
997 * @param x the <i>x</i> coordinate.
998 * @param y the <i>y</i> coordinate.
999 * @param width the width of the rectangle.
1000 * @param height the height of the rectangle.
1001 * @param bgcolor the background color to paint under the
1002 * non-opaque portions of the image.
1003 * @param observer object to be notified as more of
1004 * the image is converted.
1005 * @return {@code false} if the image pixels are still changing;
1006 * {@code true} otherwise.
1007 * @see java.awt.Image
1008 * @see java.awt.image.ImageObserver
1009 * @see java.awt.image.ImageObserver#imageUpdate(java.awt.Image, int, int, int, int, int)
1010 */
1011 public abstract boolean drawImage(Image img, int x, int y,
1012 int width, int height,
1013 Color bgcolor,
1014 ImageObserver observer);
1015
1016 /**
1017 * Draws as much of the specified area of the specified image as is
1018 * currently available, scaling it on the fly to fit inside the
1019 * specified area of the destination drawable surface. Transparent pixels
1020 * do not affect whatever pixels are already there.
1021 * <p>
1022 * This method returns immediately in all cases, even if the
1023 * image area to be drawn has not yet been scaled, dithered, and converted
1024 * for the current output device.
1025 * If the current output representation is not yet complete then
1026 * {@code drawImage} returns {@code false}. As more of
1027 * the image becomes available, the process that loads the image notifies
1028 * the specified image observer.
1029 * <p>
1030 * This method always uses the unscaled version of the image
1031 * to render the scaled rectangle and performs the required
1032 * scaling on the fly. It does not use a cached, scaled version
1033 * of the image for this operation. Scaling of the image from source
1034 * to destination is performed such that the first coordinate
1035 * of the source rectangle is mapped to the first coordinate of
1036 * the destination rectangle, and the second source coordinate is
1037 * mapped to the second destination coordinate. The subimage is
1038 * scaled and flipped as needed to preserve those mappings.
1039 * @param img the specified image to be drawn. This method does
1040 * nothing if {@code img} is null.
1041 * @param dx1 the <i>x</i> coordinate of the first corner of the
1042 * destination rectangle.
1043 * @param dy1 the <i>y</i> coordinate of the first corner of the
1044 * destination rectangle.
1045 * @param dx2 the <i>x</i> coordinate of the second corner of the
1046 * destination rectangle.
1047 * @param dy2 the <i>y</i> coordinate of the second corner of the
1048 * destination rectangle.
1049 * @param sx1 the <i>x</i> coordinate of the first corner of the
1050 * source rectangle.
1051 * @param sy1 the <i>y</i> coordinate of the first corner of the
1052 * source rectangle.
1053 * @param sx2 the <i>x</i> coordinate of the second corner of the
1054 * source rectangle.
1055 * @param sy2 the <i>y</i> coordinate of the second corner of the
1056 * source rectangle.
1057 * @param observer object to be notified as more of the image is
1058 * scaled and converted.
1059 * @return {@code false} if the image pixels are still changing;
1060 * {@code true} otherwise.
1061 * @see java.awt.Image
1062 * @see java.awt.image.ImageObserver
1063 * @see java.awt.image.ImageObserver#imageUpdate(java.awt.Image, int, int, int, int, int)
1064 * @since 1.1
1065 */
1066 public abstract boolean drawImage(Image img,
1067 int dx1, int dy1, int dx2, int dy2,
1068 int sx1, int sy1, int sx2, int sy2,
1069 ImageObserver observer);
1070
1071 /**
1072 * Draws as much of the specified area of the specified image as is
1073 * currently available, scaling it on the fly to fit inside the
1074 * specified area of the destination drawable surface.
1075 * <p>
1076 * Transparent pixels are drawn in the specified background color.
1077 * This operation is equivalent to filling a rectangle of the
1078 * width and height of the specified image with the given color and then
1079 * drawing the image on top of it, but possibly more efficient.
1080 * <p>
1081 * This method returns immediately in all cases, even if the
1082 * image area to be drawn has not yet been scaled, dithered, and converted
1083 * for the current output device.
1084 * If the current output representation is not yet complete then
1085 * {@code drawImage} returns {@code false}. As more of
1086 * the image becomes available, the process that loads the image notifies
1087 * the specified image observer.
1088 * <p>
1089 * This method always uses the unscaled version of the image
1090 * to render the scaled rectangle and performs the required
1091 * scaling on the fly. It does not use a cached, scaled version
1092 * of the image for this operation. Scaling of the image from source
1093 * to destination is performed such that the first coordinate
1094 * of the source rectangle is mapped to the first coordinate of
1095 * the destination rectangle, and the second source coordinate is
1096 * mapped to the second destination coordinate. The subimage is
1097 * scaled and flipped as needed to preserve those mappings.
1098 * @param img the specified image to be drawn. This method does
1099 * nothing if {@code img} is null.
1100 * @param dx1 the <i>x</i> coordinate of the first corner of the
1101 * destination rectangle.
1102 * @param dy1 the <i>y</i> coordinate of the first corner of the
1103 * destination rectangle.
1104 * @param dx2 the <i>x</i> coordinate of the second corner of the
1105 * destination rectangle.
1106 * @param dy2 the <i>y</i> coordinate of the second corner of the
1107 * destination rectangle.
1108 * @param sx1 the <i>x</i> coordinate of the first corner of the
1109 * source rectangle.
1110 * @param sy1 the <i>y</i> coordinate of the first corner of the
1111 * source rectangle.
1112 * @param sx2 the <i>x</i> coordinate of the second corner of the
1113 * source rectangle.
1114 * @param sy2 the <i>y</i> coordinate of the second corner of the
1115 * source rectangle.
1116 * @param bgcolor the background color to paint under the
1117 * non-opaque portions of the image.
1118 * @param observer object to be notified as more of the image is
1119 * scaled and converted.
1120 * @return {@code false} if the image pixels are still changing;
1121 * {@code true} otherwise.
1122 * @see java.awt.Image
1123 * @see java.awt.image.ImageObserver
1124 * @see java.awt.image.ImageObserver#imageUpdate(java.awt.Image, int, int, int, int, int)
1125 * @since 1.1
1126 */
1127 public abstract boolean drawImage(Image img,
1128 int dx1, int dy1, int dx2, int dy2,
1129 int sx1, int sy1, int sx2, int sy2,
1130 Color bgcolor,
1131 ImageObserver observer);
1132
1133 /**
1134 * Disposes of this graphics context and releases
1135 * any system resources that it is using.
1136 * A {@code Graphics} object cannot be used after
1137 * {@code dispose} has been called.
1138 * <p>
1139 * When a Java program runs, a large number of {@code Graphics}
1140 * objects can be created within a short time frame.
1141 * Although the finalization process of the garbage collector
1142 * also disposes of the same system resources, it is preferable
1143 * to manually free the associated resources by calling this
1144 * method rather than to rely on a finalization process which
1145 * may not run to completion for a long period of time.
1146 * <p>
1147 * Graphics objects which are provided as arguments to the
1148 * {@code paint} and {@code update} methods
1149 * of components are automatically released by the system when
1150 * those methods return. For efficiency, programmers should
1151 * call {@code dispose} when finished using
1152 * a {@code Graphics} object only if it was created
1153 * directly from a component or another {@code Graphics} object.
1154 * @see java.awt.Graphics#finalize
1155 * @see java.awt.Component#paint
1156 * @see java.awt.Component#update
1157 * @see java.awt.Component#getGraphics
1158 * @see java.awt.Graphics#create
1159 */
1160 public abstract void dispose();
1161
1162 /**
1163 * Disposes of this graphics context once it is no longer referenced.
1164 *
1165 * @deprecated Finalization has been deprecated for removal. See
1166 * {@link java.lang.Object#finalize} for background information and details
1167 * about migration options.
1168 *
1169 * @see #dispose
1170 */
1171 @Deprecated(since="9", forRemoval=true)
1172 @SuppressWarnings("removal")
1173 public void finalize() {
1174 dispose();
1175 }
1176
1177 /**
1178 * Returns a {@code String} object representing this
1179 * {@code Graphics} object's value.
1180 * @return a string representation of this graphics context.
1181 */
1182 public String toString() {
1183 return getClass().getName() + "[font=" + getFont() + ",color=" + getColor() + "]";
1184 }
1185
1186 /**
1187 * Returns the bounding rectangle of the current clipping area.
1188 * @return the bounding rectangle of the current clipping area
1189 * or {@code null} if no clip is set.
1190 * @deprecated As of JDK version 1.1,
1191 * replaced by {@code getClipBounds()}.
1192 */
1193 @Deprecated
1194 public Rectangle getClipRect() {
1195 return getClipBounds();
1196 }
1197
1198 /**
1199 * Returns true if the specified rectangular area might intersect
1200 * the current clipping area.
1201 * The coordinates of the specified rectangular area are in the
1202 * user coordinate space and are relative to the coordinate
1203 * system origin of this graphics context.
1204 * This method may use an algorithm that calculates a result quickly
1205 * but which sometimes might return true even if the specified
1206 * rectangular area does not intersect the clipping area.
1207 * The specific algorithm employed may thus trade off accuracy for
1208 * speed, but it will never return false unless it can guarantee
1209 * that the specified rectangular area does not intersect the
1210 * current clipping area.
1211 * The clipping area used by this method can represent the
1212 * intersection of the user clip as specified through the clip
1213 * methods of this graphics context as well as the clipping
1214 * associated with the device or image bounds and window visibility.
1215 *
1216 * @param x the x coordinate of the rectangle to test against the clip
1217 * @param y the y coordinate of the rectangle to test against the clip
1218 * @param width the width of the rectangle to test against the clip
1219 * @param height the height of the rectangle to test against the clip
1220 * @return {@code true} if the specified rectangle intersects
1221 * the bounds of the current clip; {@code false}
1222 * otherwise.
1223 */
1224 public boolean hitClip(int x, int y, int width, int height) {
1225 // Note, this implementation is not very efficient.
1226 // Subclasses should override this method and calculate
1227 // the results more directly.
1228 Rectangle clipRect = getClipBounds();
1229 if (clipRect == null) {
1230 return true;
1231 }
1232 return clipRect.intersects(x, y, width, height);
1233 }
1234
1235 /**
1236 * Returns the bounding rectangle of the current clipping area.
1237 * The coordinates in the rectangle are relative to the coordinate
1238 * system origin of this graphics context. This method differs
1239 * from {@link #getClipBounds() getClipBounds} in that an existing
1240 * rectangle is used instead of allocating a new one.
1241 * This method refers to the user clip, which is independent of the
1242 * clipping associated with device bounds and window visibility.
1243 * If no clip has previously been set, or if the clip has been
1244 * cleared using {@code setClip(null)}, this method returns the
1245 * specified {@code Rectangle}.
1246 * @param r the rectangle where the current clipping area is
1247 * copied to. Any current values in this rectangle are
1248 * overwritten.
1249 * @return the bounding rectangle of the current clipping area.
1250 */
1251 public Rectangle getClipBounds(Rectangle r) {
1252 // Note, this implementation is not very efficient.
1253 // Subclasses should override this method and avoid
1254 // the allocation overhead of getClipBounds().
1255 Rectangle clipRect = getClipBounds();
1256 if (clipRect != null) {
1257 r.x = clipRect.x;
1258 r.y = clipRect.y;
1259 r.width = clipRect.width;
1260 r.height = clipRect.height;
1261 } else if (r == null) {
1262 throw new NullPointerException("null rectangle parameter");
1263 }
1264 return r;
1265 }
1266 }