KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > awt > Graphics


1 /*
2  * @(#)Graphics.java 1.69 04/05/18
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */

7 package java.awt;
8
9 import java.io.*;
10 import java.lang.*;
11 import java.util.*;
12 import java.awt.image.ImageObserver JavaDoc;
13 import java.text.AttributedCharacterIterator JavaDoc;
14
15 /**
16  * The <code>Graphics</code> class is the abstract base class for
17  * all graphics contexts that allow an application to draw onto
18  * components that are realized on various devices, as well as
19  * onto off-screen images.
20  * <p>
21  * A <code>Graphics</code> object encapsulates state information needed
22  * for the basic rendering operations that Java supports. This
23  * state information includes the following properties:
24  * <p>
25  * <ul>
26  * <li>The <code>Component</code> object on which to draw.
27  * <li>A translation origin for rendering and clipping coordinates.
28  * <li>The current clip.
29  * <li>The current color.
30  * <li>The current font.
31  * <li>The current logical pixel operation function (XOR or Paint).
32  * <li>The current XOR alternation color
33  * (see {@link Graphics#setXORMode}).
34  * </ul>
35  * <p>
36  * Coordinates are infinitely thin and lie between the pixels of the
37  * output device.
38  * Operations that draw the outline of a figure operate by traversing
39  * an infinitely thin path between pixels with a pixel-sized pen that hangs
40  * down and to the right of the anchor point on the path.
41  * Operations that fill a figure operate by filling the interior
42  * of that infinitely thin path.
43  * Operations that render horizontal text render the ascending
44  * portion of character glyphs entirely above the baseline coordinate.
45  * <p>
46  * The graphics pen hangs down and to the right from the path it traverses.
47  * This has the following implications:
48  * <p><ul>
49  * <li>If you draw a figure that covers a given rectangle, that
50  * figure occupies one extra row of pixels on the right and bottom edges
51  * as compared to filling a figure that is bounded by that same rectangle.
52  * <li>If you draw a horizontal line along the same <i>y</i> coordinate as
53  * the baseline of a line of text, that line is drawn entirely below
54  * the text, except for any descenders.
55  * </ul><p>
56  * All coordinates that appear as arguments to the methods of this
57  * <code>Graphics</code> object are considered relative to the
58  * translation origin of this <code>Graphics</code> object prior to
59  * the invocation of the method.
60  * <p>
61  * All rendering operations modify only pixels which lie within the
62  * area bounded by the current clip, which is specified by a {@link Shape}
63  * in user space and is controlled by the program using the
64  * <code>Graphics</code> object. This <i>user clip</i>
65  * is transformed into device space and combined with the
66  * <i>device clip</i>, which is defined by the visibility of windows and
67  * device extents. The combination of the user clip and device clip
68  * defines the <i>composite clip</i>, which determines the final clipping
69  * region. The user clip cannot be modified by the rendering
70  * system to reflect the resulting composite clip. The user clip can only
71  * be changed through the <code>setClip</code> or <code>clipRect</code>
72  * methods.
73  * All drawing or writing is done in the current color,
74  * using the current paint mode, and in the current font.
75  *
76  * @version 1.69, 05/18/04
77  * @author Sami Shaio
78  * @author Arthur van Hoff
79  * @see java.awt.Component
80  * @see java.awt.Graphics#clipRect(int, int, int, int)
81  * @see java.awt.Graphics#setColor(java.awt.Color)
82  * @see java.awt.Graphics#setPaintMode()
83  * @see java.awt.Graphics#setXORMode(java.awt.Color)
84  * @see java.awt.Graphics#setFont(java.awt.Font)
85  * @since JDK1.0
86  */

87 public abstract class Graphics {
88
89     /**
90      * Constructs a new <code>Graphics</code> object.
91      * This constructor is the default contructor for a graphics
92      * context.
93      * <p>
94      * Since <code>Graphics</code> is an abstract class, applications
95      * cannot call this constructor directly. Graphics contexts are
96      * obtained from other graphics contexts or are created by calling
97      * <code>getGraphics</code> on a component.
98      * @see java.awt.Graphics#create()
99      * @see java.awt.Component#getGraphics
100      */

101     protected Graphics() {
102     }
103
104     /**
105      * Creates a new <code>Graphics</code> object that is
106      * a copy of this <code>Graphics</code> object.
107      * @return a new graphics context that is a copy of
108      * this graphics context.
109      */

110     public abstract Graphics JavaDoc create();
111
112     /**
113      * Creates a new <code>Graphics</code> object based on this
114      * <code>Graphics</code> object, but with a new translation and clip area.
115      * The new <code>Graphics</code> object has its origin
116      * translated to the specified point (<i>x</i>,&nbsp;<i>y</i>).
117      * Its clip area is determined by the intersection of the original
118      * clip area with the specified rectangle. The arguments are all
119      * interpreted in the coordinate system of the original
120      * <code>Graphics</code> object. The new graphics context is
121      * identical to the original, except in two respects:
122      * <p>
123      * <ul>
124      * <li>
125      * The new graphics context is translated by (<i>x</i>,&nbsp;<i>y</i>).
126      * That is to say, the point (<code>0</code>,&nbsp;<code>0</code>) in the
127      * new graphics context is the same as (<i>x</i>,&nbsp;<i>y</i>) in
128      * the original graphics context.
129      * <li>
130      * The new graphics context has an additional clipping rectangle, in
131      * addition to whatever (translated) clipping rectangle it inherited
132      * from the original graphics context. The origin of the new clipping
133      * rectangle is at (<code>0</code>,&nbsp;<code>0</code>), and its size
134      * is specified by the <code>width</code> and <code>height</code>
135      * arguments.
136      * </ul>
137      * <p>
138      * @param x the <i>x</i> coordinate.
139      * @param y the <i>y</i> coordinate.
140      * @param width the width of the clipping rectangle.
141      * @param height the height of the clipping rectangle.
142      * @return a new graphics context.
143      * @see java.awt.Graphics#translate
144      * @see java.awt.Graphics#clipRect
145      */

146     public Graphics JavaDoc create(int x, int y, int width, int height) {
147     Graphics JavaDoc g = create();
148     if (g == null) return null;
149     g.translate(x, y);
150     g.clipRect(0, 0, width, height);
151     return g;
152     }
153
154     /**
155      * Translates the origin of the graphics context to the point
156      * (<i>x</i>,&nbsp;<i>y</i>) in the current coordinate system.
157      * Modifies this graphics context so that its new origin corresponds
158      * to the point (<i>x</i>,&nbsp;<i>y</i>) in this graphics context's
159      * original coordinate system. All coordinates used in subsequent
160      * rendering operations on this graphics context will be relative
161      * to this new origin.
162      * @param x the <i>x</i> coordinate.
163      * @param y the <i>y</i> coordinate.
164      */

165     public abstract void translate(int x, int y);
166
167     /**
168      * Gets this graphics context's current color.
169      * @return this graphics context's current color.
170      * @see java.awt.Color
171      * @see java.awt.Graphics#setColor(Color)
172      */

173     public abstract Color JavaDoc getColor();
174
175     /**
176      * Sets this graphics context's current color to the specified
177      * color. All subsequent graphics operations using this graphics
178      * context use this specified color.
179      * @param c the new rendering color.
180      * @see java.awt.Color
181      * @see java.awt.Graphics#getColor
182      */

183     public abstract void setColor(Color JavaDoc c);
184
185     /**
186      * Sets the paint mode of this graphics context to overwrite the
187      * destination with this graphics context's current color.
188      * This sets the logical pixel operation function to the paint or
189      * overwrite mode. All subsequent rendering operations will
190      * overwrite the destination with the current color.
191      */

192     public abstract void setPaintMode();
193
194     /**
195      * Sets the paint mode of this graphics context to alternate between
196      * this graphics context's current color and the new specified color.
197      * This specifies that logical pixel operations are performed in the
198      * XOR mode, which alternates pixels between the current color and
199      * a specified XOR color.
200      * <p>
201      * When drawing operations are performed, pixels which are the
202      * current color are changed to the specified color, and vice versa.
203      * <p>
204      * Pixels that are of colors other than those two colors are changed
205      * in an unpredictable but reversible manner; if the same figure is
206      * drawn twice, then all pixels are restored to their original values.
207      * @param c1 the XOR alternation color
208      */

209     public abstract void setXORMode(Color JavaDoc c1);
210
211     /**
212      * Gets the current font.
213      * @return this graphics context's current font.
214      * @see java.awt.Font
215      * @see java.awt.Graphics#setFont(Font)
216      */

217     public abstract Font JavaDoc getFont();
218
219     /**
220      * Sets this graphics context's font to the specified font.
221      * All subsequent text operations using this graphics context
222      * use this font.
223      * @param font the font.
224      * @see java.awt.Graphics#getFont
225      * @see java.awt.Graphics#drawString(java.lang.String, int, int)
226      * @see java.awt.Graphics#drawBytes(byte[], int, int, int, int)
227      * @see java.awt.Graphics#drawChars(char[], int, int, int, int)
228     */

229     public abstract void setFont(Font JavaDoc font);
230
231     /**
232      * Gets the font metrics of the current font.
233      * @return the font metrics of this graphics
234      * context's current font.
235      * @see java.awt.Graphics#getFont
236      * @see java.awt.FontMetrics
237      * @see java.awt.Graphics#getFontMetrics(Font)
238      */

239     public FontMetrics JavaDoc getFontMetrics() {
240     return getFontMetrics(getFont());
241     }
242
243     /**
244      * Gets the font metrics for the specified font.
245      * @return the font metrics for the specified font.
246      * @param f the specified font
247      * @see java.awt.Graphics#getFont
248      * @see java.awt.FontMetrics
249      * @see java.awt.Graphics#getFontMetrics()
250      */

251     public abstract FontMetrics JavaDoc getFontMetrics(Font JavaDoc f);
252
253
254     /**
255      * Returns the bounding rectangle of the current clipping area.
256      * This method refers to the user clip, which is independent of the
257      * clipping associated with device bounds and window visibility.
258      * If no clip has previously been set, or if the clip has been
259      * cleared using <code>setClip(null)</code>, this method returns
260      * <code>null</code>.
261      * The coordinates in the rectangle are relative to the coordinate
262      * system origin of this graphics context.
263      * @return the bounding rectangle of the current clipping area,
264      * or <code>null</code> if no clip is set.
265      * @see java.awt.Graphics#getClip
266      * @see java.awt.Graphics#clipRect
267      * @see java.awt.Graphics#setClip(int, int, int, int)
268      * @see java.awt.Graphics#setClip(Shape)
269      * @since JDK1.1
270      */

271     public abstract Rectangle JavaDoc getClipBounds();
272
273     /**
274      * Intersects the current clip with the specified rectangle.
275      * The resulting clipping area is the intersection of the current
276      * clipping area and the specified rectangle. If there is no
277      * current clipping area, either because the clip has never been
278      * set, or the clip has been cleared using <code>setClip(null)</code>,
279      * the specified rectangle becomes the new clip.
280      * This method sets the user clip, which is independent of the
281      * clipping associated with device bounds and window visibility.
282      * This method can only be used to make the current clip smaller.
283      * To set the current clip larger, use any of the setClip methods.
284      * Rendering operations have no effect outside of the clipping area.
285      * @param x the x coordinate of the rectangle to intersect the clip with
286      * @param y the y coordinate of the rectangle to intersect the clip with
287      * @param width the width of the rectangle to intersect the clip with
288      * @param height the height of the rectangle to intersect the clip with
289      * @see #setClip(int, int, int, int)
290      * @see #setClip(Shape)
291      */

292     public abstract void clipRect(int x, int y, int width, int height);
293
294     /**
295      * Sets the current clip to the rectangle specified by the given
296      * coordinates. This method sets the user clip, which is
297      * independent of the clipping associated with device bounds
298      * and window visibility.
299      * Rendering operations have no effect outside of the clipping area.
300      * @param x the <i>x</i> coordinate of the new clip rectangle.
301      * @param y the <i>y</i> coordinate of the new clip rectangle.
302      * @param width the width of the new clip rectangle.
303      * @param height the height of the new clip rectangle.
304      * @see java.awt.Graphics#clipRect
305      * @see java.awt.Graphics#setClip(Shape)
306      * @see java.awt.Graphics#getClip
307      * @since JDK1.1
308      */

309     public abstract void setClip(int x, int y, int width, int height);
310
311     /**
312      * Gets the current clipping area.
313      * This method returns the user clip, which is independent of the
314      * clipping associated with device bounds and window visibility.
315      * If no clip has previously been set, or if the clip has been
316      * cleared using <code>setClip(null)</code>, this method returns
317      * <code>null</code>.
318      * @return a <code>Shape</code> object representing the
319      * current clipping area, or <code>null</code> if
320      * no clip is set.
321      * @see java.awt.Graphics#getClipBounds
322      * @see java.awt.Graphics#clipRect
323      * @see java.awt.Graphics#setClip(int, int, int, int)
324      * @see java.awt.Graphics#setClip(Shape)
325      * @since JDK1.1
326      */

327     public abstract Shape JavaDoc getClip();
328
329     /**
330      * Sets the current clipping area to an arbitrary clip shape.
331      * Not all objects that implement the <code>Shape</code>
332      * interface can be used to set the clip. The only
333      * <code>Shape</code> objects that are guaranteed to be
334      * supported are <code>Shape</code> objects that are
335      * obtained via the <code>getClip</code> method and via
336      * <code>Rectangle</code> objects. This method sets the
337      * user clip, which is independent of the clipping associated
338      * with device bounds and window visibility.
339      * @param clip the <code>Shape</code> to use to set the clip
340      * @see java.awt.Graphics#getClip()
341      * @see java.awt.Graphics#clipRect
342      * @see java.awt.Graphics#setClip(int, int, int, int)
343      * @since JDK1.1
344      */

345     public abstract void setClip(Shape JavaDoc clip);
346
347     /**
348      * Copies an area of the component by a distance specified by
349      * <code>dx</code> and <code>dy</code>. From the point specified
350      * by <code>x</code> and <code>y</code>, this method
351      * copies downwards and to the right. To copy an area of the
352      * component to the left or upwards, specify a negative value for
353      * <code>dx</code> or <code>dy</code>.
354      * If a portion of the source rectangle lies outside the bounds
355      * of the component, or is obscured by another window or component,
356      * <code>copyArea</code> will be unable to copy the associated
357      * pixels. The area that is omitted can be refreshed by calling
358      * the component's <code>paint</code> method.
359      * @param x the <i>x</i> coordinate of the source rectangle.
360      * @param y the <i>y</i> coordinate of the source rectangle.
361      * @param width the width of the source rectangle.
362      * @param height the height of the source rectangle.
363      * @param dx the horizontal distance to copy the pixels.
364      * @param dy the vertical distance to copy the pixels.
365      */

366     public abstract void copyArea(int x, int y, int width, int height,
367                   int dx, int dy);
368
369     /**
370      * Draws a line, using the current color, between the points
371      * <code>(x1,&nbsp;y1)</code> and <code>(x2,&nbsp;y2)</code>
372      * in this graphics context's coordinate system.
373      * @param x1 the first point's <i>x</i> coordinate.
374      * @param y1 the first point's <i>y</i> coordinate.
375      * @param x2 the second point's <i>x</i> coordinate.
376      * @param y2 the second point's <i>y</i> coordinate.
377      */

378     public abstract void drawLine(int x1, int y1, int x2, int y2);
379
380     /**
381      * Fills the specified rectangle.
382      * The left and right edges of the rectangle are at
383      * <code>x</code> and <code>x&nbsp;+&nbsp;width&nbsp;-&nbsp;1</code>.
384      * The top and bottom edges are at
385      * <code>y</code> and <code>y&nbsp;+&nbsp;height&nbsp;-&nbsp;1</code>.
386      * The resulting rectangle covers an area
387      * <code>width</code> pixels wide by
388      * <code>height</code> pixels tall.
389      * The rectangle is filled using the graphics context's current color.
390      * @param x the <i>x</i> coordinate
391      * of the rectangle to be filled.
392      * @param y the <i>y</i> coordinate
393      * of the rectangle to be filled.
394      * @param width the width of the rectangle to be filled.
395      * @param height the height of the rectangle to be filled.
396      * @see java.awt.Graphics#clearRect
397      * @see java.awt.Graphics#drawRect
398      */

399     public abstract void fillRect(int x, int y, int width, int height);
400
401     /**
402      * Draws the outline of the specified rectangle.
403      * The left and right edges of the rectangle are at
404      * <code>x</code> and <code>x&nbsp;+&nbsp;width</code>.
405      * The top and bottom edges are at
406      * <code>y</code> and <code>y&nbsp;+&nbsp;height</code>.
407      * The rectangle is drawn using the graphics context's current color.
408      * @param x the <i>x</i> coordinate
409      * of the rectangle to be drawn.
410      * @param y the <i>y</i> coordinate
411      * of the rectangle to be drawn.
412      * @param width the width of the rectangle to be drawn.
413      * @param height the height of the rectangle to be drawn.
414      * @see java.awt.Graphics#fillRect
415      * @see java.awt.Graphics#clearRect
416      */

417     public void drawRect(int x, int y, int width, int height) {
418     if ((width < 0) || (height < 0)) {
419         return;
420     }
421
422     if (height == 0 || width == 0) {
423         drawLine(x, y, x + width, y + height);
424     } else {
425         drawLine(x, y, x + width - 1, y);
426         drawLine(x + width, y, x + width, y + height - 1);
427         drawLine(x + width, y + height, x + 1, y + height);
428         drawLine(x, y + height, x, y + 1);
429     }
430     }
431     
432     /**
433      * Clears the specified rectangle by filling it with the background
434      * color of the current drawing surface. This operation does not
435      * use the current paint mode.
436      * <p>
437      * Beginning with Java&nbsp;1.1, the background color
438      * of offscreen images may be system dependent. Applications should
439      * use <code>setColor</code> followed by <code>fillRect</code> to
440      * ensure that an offscreen image is cleared to a specific color.
441      * @param x the <i>x</i> coordinate of the rectangle to clear.
442      * @param y the <i>y</i> coordinate of the rectangle to clear.
443      * @param width the width of the rectangle to clear.
444      * @param height the height of the rectangle to clear.
445      * @see java.awt.Graphics#fillRect(int, int, int, int)
446      * @see java.awt.Graphics#drawRect
447      * @see java.awt.Graphics#setColor(java.awt.Color)
448      * @see java.awt.Graphics#setPaintMode
449      * @see java.awt.Graphics#setXORMode(java.awt.Color)
450      */

451     public abstract void clearRect(int x, int y, int width, int height);
452
453     /**
454      * Draws an outlined round-cornered rectangle using this graphics
455      * context's current color. The left and right edges of the rectangle
456      * are at <code>x</code> and <code>x&nbsp;+&nbsp;width</code>,
457      * respectively. The top and bottom edges of the rectangle are at
458      * <code>y</code> and <code>y&nbsp;+&nbsp;height</code>.
459      * @param x the <i>x</i> coordinate of the rectangle to be drawn.
460      * @param y the <i>y</i> coordinate of the rectangle to be drawn.
461      * @param width the width of the rectangle to be drawn.
462      * @param height the height of the rectangle to be drawn.
463      * @param arcWidth the horizontal diameter of the arc
464      * at the four corners.
465      * @param arcHeight the vertical diameter of the arc
466      * at the four corners.
467      * @see java.awt.Graphics#fillRoundRect
468      */

469     public abstract void drawRoundRect(int x, int y, int width, int height,
470                        int arcWidth, int arcHeight);
471
472     /**
473      * Fills the specified rounded corner rectangle with the current color.
474      * The left and right edges of the rectangle
475      * are at <code>x</code> and <code>x&nbsp;+&nbsp;width&nbsp;-&nbsp;1</code>,
476      * respectively. The top and bottom edges of the rectangle are at
477      * <code>y</code> and <code>y&nbsp;+&nbsp;height&nbsp;-&nbsp;1</code>.
478      * @param x the <i>x</i> coordinate of the rectangle to be filled.
479      * @param y the <i>y</i> coordinate of the rectangle to be filled.
480      * @param width the width of the rectangle to be filled.
481      * @param height the height of the rectangle to be filled.
482      * @param arcWidth the horizontal diameter
483      * of the arc at the four corners.
484      * @param arcHeight the vertical diameter
485      * of the arc at the four corners.
486      * @see java.awt.Graphics#drawRoundRect
487      */

488     public abstract void fillRoundRect(int x, int y, int width, int height,
489                        int arcWidth, int arcHeight);
490
491     /**
492      * Draws a 3-D highlighted outline of the specified rectangle.
493      * The edges of the rectangle are highlighted so that they
494      * appear to be beveled and lit from the upper left corner.
495      * <p>
496      * The colors used for the highlighting effect are determined
497      * based on the current color.
498      * The resulting rectangle covers an area that is
499      * <code>width&nbsp;+&nbsp;1</code> pixels wide
500      * by <code>height&nbsp;+&nbsp;1</code> pixels tall.
501      * @param x the <i>x</i> coordinate of the rectangle to be drawn.
502      * @param y the <i>y</i> coordinate of the rectangle to be drawn.
503      * @param width the width of the rectangle to be drawn.
504      * @param height the height of the rectangle to be drawn.
505      * @param raised a boolean that determines whether the rectangle
506      * appears to be raised above the surface
507      * or sunk into the surface.
508      * @see java.awt.Graphics#fill3DRect
509      */

510     public void draw3DRect(int x, int y, int width, int height,
511                boolean raised) {
512     Color JavaDoc c = getColor();
513     Color JavaDoc brighter = c.brighter();
514     Color JavaDoc darker = c.darker();
515
516     setColor(raised ? brighter : darker);
517     drawLine(x, y, x, y + height);
518     drawLine(x + 1, y, x + width - 1, y);
519     setColor(raised ? darker : brighter);
520     drawLine(x + 1, y + height, x + width, y + height);
521     drawLine(x + width, y, x + width, y + height - 1);
522     setColor(c);
523     }
524
525     /**
526      * Paints a 3-D highlighted rectangle filled with the current color.
527      * The edges of the rectangle will be highlighted so that it appears
528      * as if the edges were beveled and lit from the upper left corner.
529      * The colors used for the highlighting effect will be determined from
530      * the current color.
531      * @param x the <i>x</i> coordinate of the rectangle to be filled.
532      * @param y the <i>y</i> coordinate of the rectangle to be filled.
533      * @param width the width of the rectangle to be filled.
534      * @param height the height of the rectangle to be filled.
535      * @param raised a boolean value that determines whether the
536      * rectangle appears to be raised above the surface
537      * or etched into the surface.
538      * @see java.awt.Graphics#draw3DRect
539      */

540     public void fill3DRect(int x, int y, int width, int height,
541                boolean raised) {
542     Color JavaDoc c = getColor();
543     Color JavaDoc brighter = c.brighter();
544     Color JavaDoc darker = c.darker();
545
546     if (!raised) {
547         setColor(darker);
548     }
549     fillRect(x+1, y+1, width-2, height-2);
550     setColor(raised ? brighter : darker);
551     drawLine(x, y, x, y + height - 1);
552     drawLine(x + 1, y, x + width - 2, y);
553     setColor(raised ? darker : brighter);
554     drawLine(x + 1, y + height - 1, x + width - 1, y + height - 1);
555     drawLine(x + width - 1, y, x + width - 1, y + height - 2);
556     setColor(c);
557     }
558
559     /**
560      * Draws the outline of an oval.
561      * The result is a circle or ellipse that fits within the
562      * rectangle specified by the <code>x</code>, <code>y</code>,
563      * <code>width</code>, and <code>height</code> arguments.
564      * <p>
565      * The oval covers an area that is
566      * <code>width&nbsp;+&nbsp;1</code> pixels wide
567      * and <code>height&nbsp;+&nbsp;1</code> pixels tall.
568      * @param x the <i>x</i> coordinate of the upper left
569      * corner of the oval to be drawn.
570      * @param y the <i>y</i> coordinate of the upper left
571      * corner of the oval to be drawn.
572      * @param width the width of the oval to be drawn.
573      * @param height the height of the oval to be drawn.
574      * @see java.awt.Graphics#fillOval
575      */

576     public abstract void drawOval(int x, int y, int width, int height);
577
578     /**
579      * Fills an oval bounded by the specified rectangle with the
580      * current color.
581      * @param x the <i>x</i> coordinate of the upper left corner
582      * of the oval to be filled.
583      * @param y the <i>y</i> coordinate of the upper left corner
584      * of the oval to be filled.
585      * @param width the width of the oval to be filled.
586      * @param height the height of the oval to be filled.
587      * @see java.awt.Graphics#drawOval
588      */

589     public abstract void fillOval(int x, int y, int width, int height);
590
591     /**
592      * Draws the outline of a circular or elliptical arc
593      * covering the specified rectangle.
594      * <p>
595      * The resulting arc begins at <code>startAngle</code> and extends
596      * for <code>arcAngle</code> degrees, using the current color.
597      * Angles are interpreted such that 0&nbsp;degrees
598      * is at the 3&nbsp;o'clock position.
599      * A positive value indicates a counter-clockwise rotation
600      * while a negative value indicates a clockwise rotation.
601      * <p>
602      * The center of the arc is the center of the rectangle whose origin
603      * is (<i>x</i>,&nbsp;<i>y</i>) and whose size is specified by the
604      * <code>width</code> and <code>height</code> arguments.
605      * <p>
606      * The resulting arc covers an area
607      * <code>width&nbsp;+&nbsp;1</code> pixels wide
608      * by <code>height&nbsp;+&nbsp;1</code> pixels tall.
609      * <p>
610      * The angles are specified relative to the non-square extents of
611      * the bounding rectangle such that 45 degrees always falls on the
612      * line from the center of the ellipse to the upper right corner of
613      * the bounding rectangle. As a result, if the bounding rectangle is
614      * noticeably longer in one axis than the other, the angles to the
615      * start and end of the arc segment will be skewed farther along the
616      * longer axis of the bounds.
617      * @param x the <i>x</i> coordinate of the
618      * upper-left corner of the arc to be drawn.
619      * @param y the <i>y</i> coordinate of the
620      * upper-left corner of the arc to be drawn.
621      * @param width the width of the arc to be drawn.
622      * @param height the height of the arc to be drawn.
623      * @param startAngle the beginning angle.
624      * @param arcAngle the angular extent of the arc,
625      * relative to the start angle.
626      * @see java.awt.Graphics#fillArc
627      */

628     public abstract void drawArc(int x, int y, int width, int height,
629                  int startAngle, int arcAngle);
630
631     /**
632      * Fills a circular or elliptical arc covering the specified rectangle.
633      * <p>
634      * The resulting arc begins at <code>startAngle</code> and extends
635      * for <code>arcAngle</code> degrees.
636      * Angles are interpreted such that 0&nbsp;degrees
637      * is at the 3&nbsp;o'clock position.
638      * A positive value indicates a counter-clockwise rotation
639      * while a negative value indicates a clockwise rotation.
640      * <p>
641      * The center of the arc is the center of the rectangle whose origin
642      * is (<i>x</i>,&nbsp;<i>y</i>) and whose size is specified by the
643      * <code>width</code> and <code>height</code> arguments.
644      * <p>
645      * The resulting arc covers an area
646      * <code>width&nbsp;+&nbsp;1</code> pixels wide
647      * by <code>height&nbsp;+&nbsp;1</code> pixels tall.
648      * <p>
649      * The angles are specified relative to the non-square extents of
650      * the bounding rectangle such that 45 degrees always falls on the
651      * line from the center of the ellipse to the upper right corner of
652      * the bounding rectangle. As a result, if the bounding rectangle is
653      * noticeably longer in one axis than the other, the angles to the
654      * start and end of the arc segment will be skewed farther along the
655      * longer axis of the bounds.
656      * @param x the <i>x</i> coordinate of the
657      * upper-left corner of the arc to be filled.
658      * @param y the <i>y</i> coordinate of the
659      * upper-left corner of the arc to be filled.
660      * @param width the width of the arc to be filled.
661      * @param height the height of the arc to be filled.
662      * @param startAngle the beginning angle.
663      * @param arcAngle the angular extent of the arc,
664      * relative to the start angle.
665      * @see java.awt.Graphics#drawArc
666      */

667     public abstract void fillArc(int x, int y, int width, int height,
668                  int startAngle, int arcAngle);
669
670     /**
671      * Draws a sequence of connected lines defined by
672      * arrays of <i>x</i> and <i>y</i> coordinates.
673      * Each pair of (<i>x</i>,&nbsp;<i>y</i>) coordinates defines a point.
674      * The figure is not closed if the first point
675      * differs from the last point.
676      * @param xPoints an array of <i>x</i> points
677      * @param yPoints an array of <i>y</i> points
678      * @param nPoints the total number of points
679      * @see java.awt.Graphics#drawPolygon(int[], int[], int)
680      * @since JDK1.1
681      */

682     public abstract void drawPolyline(int xPoints[], int yPoints[],
683                       int nPoints);
684
685     /**
686      * Draws a closed polygon defined by
687      * arrays of <i>x</i> and <i>y</i> coordinates.
688      * Each pair of (<i>x</i>,&nbsp;<i>y</i>) coordinates defines a point.
689      * <p>
690      * This method draws the polygon defined by <code>nPoint</code> line
691      * segments, where the first <code>nPoint&nbsp;-&nbsp;1</code>
692      * line segments are line segments from
693      * <code>(xPoints[i&nbsp;-&nbsp;1],&nbsp;yPoints[i&nbsp;-&nbsp;1])</code>
694      * to <code>(xPoints[i],&nbsp;yPoints[i])</code>, for
695      * 1&nbsp;&le;&nbsp;<i>i</i>&nbsp;&le;&nbsp;<code>nPoints</code>.
696      * The figure is automatically closed by drawing a line connecting
697      * the final point to the first point, if those points are different.
698      * @param xPoints a an array of <code>x</code> coordinates.
699      * @param yPoints a an array of <code>y</code> coordinates.
700      * @param nPoints a the total number of points.
701      * @see java.awt.Graphics#fillPolygon
702      * @see java.awt.Graphics#drawPolyline
703      */

704     public abstract void drawPolygon(int xPoints[], int yPoints[],
705                      int nPoints);
706
707     /**
708      * Draws the outline of a polygon defined by the specified
709      * <code>Polygon</code> object.
710      * @param p the polygon to draw.
711      * @see java.awt.Graphics#fillPolygon
712      * @see java.awt.Graphics#drawPolyline
713      */

714     public void drawPolygon(Polygon JavaDoc p) {
715     drawPolygon(p.xpoints, p.ypoints, p.npoints);
716     }
717
718     /**
719      * Fills a closed polygon defined by
720      * arrays of <i>x</i> and <i>y</i> coordinates.
721      * <p>
722      * This method draws the polygon defined by <code>nPoint</code> line
723      * segments, where the first <code>nPoint&nbsp;-&nbsp;1</code>
724      * line segments are line segments from
725      * <code>(xPoints[i&nbsp;-&nbsp;1],&nbsp;yPoints[i&nbsp;-&nbsp;1])</code>
726      * to <code>(xPoints[i],&nbsp;yPoints[i])</code>, for
727      * 1&nbsp;&le;&nbsp;<i>i</i>&nbsp;&le;&nbsp;<code>nPoints</code>.
728      * The figure is automatically closed by drawing a line connecting
729      * the final point to the first point, if those points are different.
730      * <p>
731      * The area inside the polygon is defined using an
732      * even-odd fill rule, also known as the alternating rule.
733      * @param xPoints a an array of <code>x</code> coordinates.
734      * @param yPoints a an array of <code>y</code> coordinates.
735      * @param nPoints a the total number of points.
736      * @see java.awt.Graphics#drawPolygon(int[], int[], int)
737      */

738     public abstract void fillPolygon(int xPoints[], int yPoints[],
739                      int nPoints);
740
741     /**
742      * Fills the polygon defined by the specified Polygon object with
743      * the graphics context's current color.
744      * <p>
745      * The area inside the polygon is defined using an
746      * even-odd fill rule, also known as the alternating rule.
747      * @param p the polygon to fill.
748      * @see java.awt.Graphics#drawPolygon(int[], int[], int)
749      */

750     public void fillPolygon(Polygon JavaDoc p) {
751     fillPolygon(p.xpoints, p.ypoints, p.npoints);
752     }
753
754     /**
755      * Draws the text given by the specified string, using this
756      * graphics context's current font and color. The baseline of the
757      * leftmost character is at position (<i>x</i>,&nbsp;<i>y</i>) in this
758      * graphics context's coordinate system.
759      * @param str the string to be drawn.
760      * @param x the <i>x</i> coordinate.
761      * @param y the <i>y</i> coordinate.
762      * @see java.awt.Graphics#drawBytes
763      * @see java.awt.Graphics#drawChars
764      */

765     public abstract void drawString(String JavaDoc str, int x, int y);
766
767     /**
768      * Draws the text given by the specified iterator, using this
769      * graphics context's current color. The iterator has to specify a font
770      * for each character. The baseline of the
771      * leftmost character is at position (<i>x</i>,&nbsp;<i>y</i>) in this
772      * graphics context's coordinate system.
773      * @param iterator the iterator whose text is to be drawn
774      * @param x the <i>x</i> coordinate.
775      * @param y the <i>y</i> coordinate.
776      * @see java.awt.Graphics#drawBytes
777      * @see java.awt.Graphics#drawChars
778      */

779    public abstract void drawString(AttributedCharacterIterator JavaDoc iterator,
780                                     int x, int y);
781
782     /**
783      * Draws the text given by the specified character array, using this
784      * graphics context's current font and color. The baseline of the
785      * first character is at position (<i>x</i>,&nbsp;<i>y</i>) in this
786      * graphics context's coordinate system.
787      * @param data the array of characters to be drawn
788      * @param offset the start offset in the data
789      * @param length the number of characters to be drawn
790      * @param x the <i>x</i> coordinate of the baseline of the text
791      * @param y the <i>y</i> coordinate of the baseline of the text
792      * @see java.awt.Graphics#drawBytes
793      * @see java.awt.Graphics#drawString
794      */

795     public void drawChars(char data[], int offset, int length, int x, int y) {
796     drawString(new String JavaDoc(data, offset, length), x, y);
797     }
798
799     /**
800      * Draws the text given by the specified byte array, using this
801      * graphics context's current font and color. The baseline of the
802      * first character is at position (<i>x</i>,&nbsp;<i>y</i>) in this
803      * graphics context's coordinate system.
804      * @param data the data to be drawn
805      * @param offset the start offset in the data
806      * @param length the number of bytes that are drawn
807      * @param x the <i>x</i> coordinate of the baseline of the text
808      * @param y the <i>y</i> coordinate of the baseline of the text
809      * @see java.awt.Graphics#drawChars
810      * @see java.awt.Graphics#drawString
811      */

812     public void drawBytes(byte data[], int offset, int length, int x, int y) {
813     drawString(new String JavaDoc(data, 0, offset, length), x, y);
814     }
815
816     /**
817      * Draws as much of the specified image as is currently available.
818      * The image is drawn with its top-left corner at
819      * (<i>x</i>,&nbsp;<i>y</i>) in this graphics context's coordinate
820      * space. Transparent pixels in the image do not affect whatever
821      * pixels are already there.
822      * <p>
823      * This method returns immediately in all cases, even if the
824      * complete image has not yet been loaded, and it has not been dithered
825      * and converted for the current output device.
826      * <p>
827      * If the image has completely loaded and its pixels are
828      * no longer being changed, then
829      * <code>drawImage</code> returns <code>true</code>.
830      * Otherwise, <code>drawImage</code> returns <code>false</code>
831      * and as more of
832      * the image becomes available
833      * or it is time to draw another frame of animation,
834      * the process that loads the image notifies
835      * the specified image observer.
836      * @param img the specified image to be drawn. This method does
837      * nothing if <code>img</code> is null.
838      * @param x the <i>x</i> coordinate.
839      * @param y the <i>y</i> coordinate.
840      * @param observer object to be notified as more of
841      * the image is converted.
842      * @return <code>false</code> if the image pixels are still changing;
843      * <code>true</code> otherwise.
844      * @see java.awt.Image
845      * @see java.awt.image.ImageObserver
846      * @see java.awt.image.ImageObserver#imageUpdate(java.awt.Image, int, int, int, int, int)
847      */

848     public abstract boolean drawImage(Image JavaDoc img, int x, int y,
849                       ImageObserver JavaDoc observer);
850
851     /**
852      * Draws as much of the specified image as has already been scaled
853      * to fit inside the specified rectangle.
854      * <p>
855      * The image is drawn inside the specified rectangle of this
856      * graphics context's coordinate space, and is scaled if
857      * necessary. Transparent pixels do not affect whatever pixels
858      * are already there.
859      * <p>
860      * This method returns immediately in all cases, even if the
861      * entire image has not yet been scaled, dithered, and converted
862      * for the current output device.
863      * If the current output representation is not yet complete, then
864      * <code>drawImage</code> returns <code>false</code>. As more of
865      * the image becomes available, the process that loads the image notifies
866      * the image observer by calling its <code>imageUpdate</code> method.
867      * <p>
868      * A scaled version of an image will not necessarily be
869      * available immediately just because an unscaled version of the
870      * image has been constructed for this output device. Each size of
871      * the image may be cached separately and generated from the original
872      * data in a separate image production sequence.
873      * @param img the specified image to be drawn. This method does
874      * nothing if <code>img</code> is null.
875      * @param x the <i>x</i> coordinate.
876      * @param y the <i>y</i> coordinate.
877      * @param width the width of the rectangle.
878      * @param height the height of the rectangle.
879      * @param observer object to be notified as more of
880      * the image is converted.
881      * @return <code>false</code> if the image pixels are still changing;
882      * <code>true</code> otherwise.
883      * @see java.awt.Image
884      * @see java.awt.image.ImageObserver
885      * @see java.awt.image.ImageObserver#imageUpdate(java.awt.Image, int, int, int, int, int)
886      */

887     public abstract boolean drawImage(Image JavaDoc img, int x, int y,
888                       int width, int height,
889                       ImageObserver JavaDoc observer);
890     
891     /**
892      * Draws as much of the specified image as is currently available.
893      * The image is drawn with its top-left corner at
894      * (<i>x</i>,&nbsp;<i>y</i>) in this graphics context's coordinate
895      * space. Transparent pixels are drawn in the specified
896      * background color.
897      * <p>
898      * This operation is equivalent to filling a rectangle of the
899      * width and height of the specified image with the given color and then
900      * drawing the image on top of it, but possibly more efficient.
901      * <p>
902      * This method returns immediately in all cases, even if the
903      * complete image has not yet been loaded, and it has not been dithered
904      * and converted for the current output device.
905      * <p>
906      * If the image has completely loaded and its pixels are
907      * no longer being changed, then
908      * <code>drawImage</code> returns <code>true</code>.
909      * Otherwise, <code>drawImage</code> returns <code>false</code>
910      * and as more of
911      * the image becomes available
912      * or it is time to draw another frame of animation,
913      * the process that loads the image notifies
914      * the specified image observer.
915      * @param img the specified image to be drawn. This method does
916      * nothing if <code>img</code> is null.
917      * @param x the <i>x</i> coordinate.
918      * @param y the <i>y</i> coordinate.
919      * @param bgcolor the background color to paint under the
920      * non-opaque portions of the image.
921      * @param observer object to be notified as more of
922      * the image is converted.
923      * @return <code>false</code> if the image pixels are still changing;
924      * <code>true</code> otherwise.
925      * @see java.awt.Image
926      * @see java.awt.image.ImageObserver
927      * @see java.awt.image.ImageObserver#imageUpdate(java.awt.Image, int, int, int, int, int)
928      */

929     public abstract boolean drawImage(Image JavaDoc img, int x, int y,
930                       Color JavaDoc bgcolor,
931                       ImageObserver JavaDoc observer);
932
933     /**
934      * Draws as much of the specified image as has already been scaled
935      * to fit inside the specified rectangle.
936      * <p>
937      * The image is drawn inside the specified rectangle of this
938      * graphics context's coordinate space, and is scaled if
939      * necessary. Transparent pixels are drawn in the specified
940      * background color.
941      * This operation is equivalent to filling a rectangle of the
942      * width and height of the specified image with the given color and then
943      * drawing the image on top of it, but possibly more efficient.
944      * <p>
945      * This method returns immediately in all cases, even if the
946      * entire image has not yet been scaled, dithered, and converted
947      * for the current output device.
948      * If the current output representation is not yet complete then
949      * <code>drawImage</code> returns <code>false</code>. As more of
950      * the image becomes available, the process that loads the image notifies
951      * the specified image observer.
952      * <p>
953      * A scaled version of an image will not necessarily be
954      * available immediately just because an unscaled version of the
955      * image has been constructed for this output device. Each size of
956      * the image may be cached separately and generated from the original
957      * data in a separate image production sequence.
958      * @param img the specified image to be drawn. This method does
959      * nothing if <code>img</code> is null.
960      * @param x the <i>x</i> coordinate.
961      * @param y the <i>y</i> coordinate.
962      * @param width the width of the rectangle.
963      * @param height the height of the rectangle.
964      * @param bgcolor the background color to paint under the
965      * non-opaque portions of the image.
966      * @param observer object to be notified as more of
967      * the image is converted.
968      * @return <code>false</code> if the image pixels are still changing;
969      * <code>true</code> otherwise.
970      * @see java.awt.Image
971      * @see java.awt.image.ImageObserver
972      * @see java.awt.image.ImageObserver#imageUpdate(java.awt.Image, int, int, int, int, int)
973      */

974     public abstract boolean drawImage(Image JavaDoc img, int x, int y,
975                       int width, int height,
976                       Color JavaDoc bgcolor,
977                       ImageObserver JavaDoc observer);
978     
979     /**
980      * Draws as much of the specified area of the specified image as is
981      * currently available, scaling it on the fly to fit inside the
982      * specified area of the destination drawable surface. Transparent pixels
983      * do not affect whatever pixels are already there.
984      * <p>
985      * This method returns immediately in all cases, even if the
986      * image area to be drawn has not yet been scaled, dithered, and converted
987      * for the current output device.
988      * If the current output representation is not yet complete then
989      * <code>drawImage</code> returns <code>false</code>. As more of
990      * the image becomes available, the process that loads the image notifies
991      * the specified image observer.
992      * <p>
993      * This method always uses the unscaled version of the image
994      * to render the scaled rectangle and performs the required
995      * scaling on the fly. It does not use a cached, scaled version
996      * of the image for this operation. Scaling of the image from source
997      * to destination is performed such that the first coordinate
998      * of the source rectangle is mapped to the first coordinate of
999      * the destination rectangle, and the second source coordinate is
1000     * mapped to the second destination coordinate. The subimage is
1001     * scaled and flipped as needed to preserve those mappings.
1002     * @param img the specified image to be drawn. This method does
1003     * nothing if <code>img</code> is null.
1004     * @param dx1 the <i>x</i> coordinate of the first corner of the
1005     * destination rectangle.
1006     * @param dy1 the <i>y</i> coordinate of the first corner of the
1007     * destination rectangle.
1008     * @param dx2 the <i>x</i> coordinate of the second corner of the
1009     * destination rectangle.
1010     * @param dy2 the <i>y</i> coordinate of the second corner of the
1011     * destination rectangle.
1012     * @param sx1 the <i>x</i> coordinate of the first corner of the
1013     * source rectangle.
1014     * @param sy1 the <i>y</i> coordinate of the first corner of the
1015     * source rectangle.
1016     * @param sx2 the <i>x</i> coordinate of the second corner of the
1017     * source rectangle.
1018     * @param sy2 the <i>y</i> coordinate of the second corner of the
1019     * source rectangle.
1020     * @param observer object to be notified as more of the image is
1021     * scaled and converted.
1022     * @return <code>false</code> if the image pixels are still changing;
1023     * <code>true</code> otherwise.
1024     * @see java.awt.Image
1025     * @see java.awt.image.ImageObserver
1026     * @see java.awt.image.ImageObserver#imageUpdate(java.awt.Image, int, int, int, int, int)
1027     * @since JDK1.1
1028     */

1029    public abstract boolean drawImage(Image JavaDoc img,
1030                      int dx1, int dy1, int dx2, int dy2,
1031                      int sx1, int sy1, int sx2, int sy2,
1032                      ImageObserver JavaDoc observer);
1033
1034    /**
1035     * Draws as much of the specified area of the specified image as is
1036     * currently available, scaling it on the fly to fit inside the
1037     * specified area of the destination drawable surface.
1038     * <p>
1039     * Transparent pixels are drawn in the specified background color.
1040     * This operation is equivalent to filling a rectangle of the
1041     * width and height of the specified image with the given color and then
1042     * drawing the image on top of it, but possibly more efficient.
1043     * <p>
1044     * This method returns immediately in all cases, even if the
1045     * image area to be drawn has not yet been scaled, dithered, and converted
1046     * for the current output device.
1047     * If the current output representation is not yet complete then
1048     * <code>drawImage</code> returns <code>false</code>. As more of
1049     * the image becomes available, the process that loads the image notifies
1050     * the specified image observer.
1051     * <p>
1052     * This method always uses the unscaled version of the image
1053     * to render the scaled rectangle and performs the required
1054     * scaling on the fly. It does not use a cached, scaled version
1055     * of the image for this operation. Scaling of the image from source
1056     * to destination is performed such that the first coordinate
1057     * of the source rectangle is mapped to the first coordinate of
1058     * the destination rectangle, and the second source coordinate is
1059     * mapped to the second destination coordinate. The subimage is
1060     * scaled and flipped as needed to preserve those mappings.
1061     * @param img the specified image to be drawn. This method does
1062     * nothing if <code>img</code> is null.
1063     * @param dx1 the <i>x</i> coordinate of the first corner of the
1064     * destination rectangle.
1065     * @param dy1 the <i>y</i> coordinate of the first corner of the
1066     * destination rectangle.
1067     * @param dx2 the <i>x</i> coordinate of the second corner of the
1068     * destination rectangle.
1069     * @param dy2 the <i>y</i> coordinate of the second corner of the
1070     * destination rectangle.
1071     * @param sx1 the <i>x</i> coordinate of the first corner of the
1072     * source rectangle.
1073     * @param sy1 the <i>y</i> coordinate of the first corner of the
1074     * source rectangle.
1075     * @param sx2 the <i>x</i> coordinate of the second corner of the
1076     * source rectangle.
1077     * @param sy2 the <i>y</i> coordinate of the second corner of the
1078     * source rectangle.
1079     * @param bgcolor the background color to paint under the
1080     * non-opaque portions of the image.
1081     * @param observer object to be notified as more of the image is
1082     * scaled and converted.
1083     * @return <code>false</code> if the image pixels are still changing;
1084     * <code>true</code> otherwise.
1085     * @see java.awt.Image
1086     * @see java.awt.image.ImageObserver
1087     * @see java.awt.image.ImageObserver#imageUpdate(java.awt.Image, int, int, int, int, int)
1088     * @since JDK1.1
1089     */

1090    public abstract boolean drawImage(Image JavaDoc img,
1091                      int dx1, int dy1, int dx2, int dy2,
1092                      int sx1, int sy1, int sx2, int sy2,
1093                      Color JavaDoc bgcolor,
1094                      ImageObserver JavaDoc observer);
1095
1096    /**
1097     * Disposes of this graphics context and releases
1098     * any system resources that it is using.
1099     * A <code>Graphics</code> object cannot be used after
1100     * <code>dispose</code>has been called.
1101     * <p>
1102     * When a Java program runs, a large number of <code>Graphics</code>
1103     * objects can be created within a short time frame.
1104     * Although the finalization process of the garbage collector
1105     * also disposes of the same system resources, it is preferable
1106     * to manually free the associated resources by calling this
1107     * method rather than to rely on a finalization process which
1108     * may not run to completion for a long period of time.
1109     * <p>
1110     * Graphics objects which are provided as arguments to the
1111     * <code>paint</code> and <code>update</code> methods
1112     * of components are automatically released by the system when
1113     * those methods return. For efficiency, programmers should
1114     * call <code>dispose</code> when finished using
1115     * a <code>Graphics</code> object only if it was created
1116     * directly from a component or another <code>Graphics</code> object.
1117     * @see java.awt.Graphics#finalize
1118     * @see java.awt.Component#paint
1119     * @see java.awt.Component#update
1120     * @see java.awt.Component#getGraphics
1121     * @see java.awt.Graphics#create
1122     */

1123    public abstract void dispose();
1124
1125    /**
1126     * Disposes of this graphics context once it is no longer referenced.
1127     * @see #dispose
1128     */

1129    public void finalize() {
1130    dispose();
1131    }
1132
1133    /**
1134     * Returns a <code>String</code> object representing this
1135     * <code>Graphics</code> object's value.
1136     * @return a string representation of this graphics context.
1137     */

1138    public String JavaDoc toString() {
1139    return getClass().getName() + "[font=" + getFont() + ",color=" + getColor() + "]";
1140    }
1141
1142    /**
1143     * Returns the bounding rectangle of the current clipping area.
1144     * @return the bounding rectangle of the current clipping area
1145     * or <code>null</code> if no clip is set.
1146     * @deprecated As of JDK version 1.1,
1147     * replaced by <code>getClipBounds()</code>.
1148     */

1149    @Deprecated JavaDoc
1150    public Rectangle JavaDoc getClipRect() {
1151    return getClipBounds();
1152    }
1153
1154    /**
1155     * Returns true if the specified rectangular area might intersect
1156     * the current clipping area.
1157     * The coordinates of the specified rectangular area are in the
1158     * user coordinate space and are relative to the coordinate
1159     * system origin of this graphics context.
1160     * This method may use an algorithm that calculates a result quickly
1161     * but which sometimes might return true even if the specified
1162     * rectangular area does not intersect the clipping area.
1163     * The specific algorithm employed may thus trade off accuracy for
1164     * speed, but it will never return false unless it can guarantee
1165     * that the specified rectangular area does not intersect the
1166     * current clipping area.
1167     * The clipping area used by this method can represent the
1168     * intersection of the user clip as specified through the clip
1169     * methods of this graphics context as well as the clipping
1170     * associated with the device or image bounds and window visibility.
1171     *
1172     * @param x the x coordinate of the rectangle to test against the clip
1173     * @param y the y coordinate of the rectangle to test against the clip
1174     * @param width the width of the rectangle to test against the clip
1175     * @param height the height of the rectangle to test against the clip
1176     * @return <code>true</code> if the specified rectangle intersects
1177     * the bounds of the current clip; <code>false</code>
1178     * otherwise.
1179     */

1180    public boolean hitClip(int x, int y, int width, int height) {
1181    // Note, this implementation is not very efficient.
1182
// Subclasses should override this method and calculate
1183
// the results more directly.
1184
Rectangle JavaDoc clipRect = getClipBounds();
1185    if (clipRect == null) {
1186        return true;
1187    }
1188    return clipRect.intersects(x, y, width, height);
1189    }
1190
1191    /**
1192     * Returns the bounding rectangle of the current clipping area.
1193     * The coordinates in the rectangle are relative to the coordinate
1194     * system origin of this graphics context. This method differs
1195     * from {@link #getClipBounds() getClipBounds} in that an existing
1196     * rectangle is used instead of allocating a new one.
1197     * This method refers to the user clip, which is independent of the
1198     * clipping associated with device bounds and window visibility.
1199     * If no clip has previously been set, or if the clip has been
1200     * cleared using <code>setClip(null)</code>, this method returns the
1201     * specified <code>Rectangle</code>.
1202     * @param r the rectangle where the current clipping area is
1203     * copied to. Any current values in this rectangle are
1204     * overwritten.
1205     * @return the bounding rectangle of the current clipping area.
1206     */

1207    public Rectangle JavaDoc getClipBounds(Rectangle JavaDoc r) {
1208    // Note, this implementation is not very efficient.
1209
// Subclasses should override this method and avoid
1210
// the allocation overhead of getClipBounds().
1211
Rectangle JavaDoc clipRect = getClipBounds();
1212    if (clipRect != null) {
1213        r.x = clipRect.x;
1214        r.y = clipRect.y;
1215        r.width = clipRect.width;
1216        r.height = clipRect.height;
1217    } else if (r == null) {
1218        throw new NullPointerException JavaDoc("null rectangle parameter");
1219    }
1220        return r;
1221    }
1222}
1223
Popular Tags