1 /* Graphics.java -- Abstract Java drawing class
2 Copyright (C) 1999, 2000, 2002, 2004, 2005 Free Software Foundation, Inc.
4 This file is part of GNU Classpath.
6 GNU Classpath is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation; either version 2, or (at your option)
11 GNU Classpath is distributed in the hope that it will be useful, but
12 WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 General Public License for more details.
16 You should have received a copy of the GNU General Public License
17 along with GNU Classpath; see the file COPYING. If not, write to the
18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
21 Linking this library statically or dynamically with other modules is
22 making a combined work based on this library. Thus, the terms and
23 conditions of the GNU General Public License cover the whole
26 As a special exception, the copyright holders of this library give you
27 permission to link this library with independent modules to produce an
28 executable, regardless of the license terms of these independent
29 modules, and to copy and distribute the resulting executable under
30 terms of your choice, provided that you also meet, for each linked
31 independent module, the terms and conditions of the license of that
32 module. An independent module is a module which is not derived from
33 or based on this library. If you modify this library, you may extend
34 this exception to your version of the library, but you are not
35 obligated to do so. If you do not wish to do so, delete this
36 exception statement from your version. */
41 import java
.awt
.image
.ImageObserver
;
42 import java
.text
.AttributedCharacterIterator
;
45 * This is the abstract superclass of classes for drawing to graphics
46 * devices such as the screen or printers.
48 * @author Aaron M. Renn (arenn@urbanophile.com)
49 * @author Warren Levy (warrenl@cygnus.com)
51 public abstract class Graphics
58 /*************************************************************************/
65 * Default constructor for subclasses.
72 /*************************************************************************/
79 * Returns a copy of this <code>Graphics</code> object.
81 * @return A copy of this object.
83 public abstract Graphics
86 /*************************************************************************/
89 * Returns a copy of this <code>Graphics</code> object. The origin point
90 * will be translated to the point (x, y) and the cliping rectangle set
91 * to the intersection of the clipping rectangle in this object and the
92 * rectangle specified by the parameters to this method.
94 * @param x The new X coordinate of the clipping region rect.
95 * @param y The new Y coordinate of the clipping region rect.
96 * @param width The width of the clipping region intersect rectangle.
97 * @param height The height of the clipping region intersect rectangle.
99 * @return A copy of this object, modified as specified.
102 create(int x
, int y
, int width
, int height
)
104 Graphics g
= create();
107 // FIXME: I'm not sure if this will work. Are the old clip rect bounds
109 g
.clipRect(0, 0, width
, height
);
114 /*************************************************************************/
117 * Translates this context so that its new origin point is the point
120 * @param x The new X coordinate of the origin.
121 * @param y The new Y coordinate of the origin.
124 translate(int x
, int y
);
126 /*************************************************************************/
129 * Returns the current color for this object.
131 * @return The color for this object.
133 public abstract Color
136 /*************************************************************************/
139 * Sets the current color for this object.
141 * @param color The new color.
144 setColor(Color color
);
146 /*************************************************************************/
149 * Sets this context into "paint" mode, where the target pixels are
150 * completely overwritten when drawn on.
155 /*************************************************************************/
158 * Sets this context info "XOR" mode, where the targe pixles are
159 * XOR-ed when drawn on.
161 * @param color The color to XOR against.
164 setXORMode(Color color
);
166 /*************************************************************************/
169 * Returns the current font for this graphics context.
171 * @return The current font.
176 /*************************************************************************/
179 * Sets the font for this graphics context to the specified value.
181 * @param font The new font.
186 /*************************************************************************/
189 * Returns the font metrics for the current font.
191 * @return The font metrics for the current font.
196 return(getFontMetrics(getFont()));
199 /*************************************************************************/
202 * Returns the font metrics for the specified font.
204 * @param font The font to return metrics for.
206 * @return The requested font metrics.
208 public abstract FontMetrics
209 getFontMetrics(Font font
);
211 /*************************************************************************/
214 * Returns the bounding rectangle of the clipping region for this
217 * @return The bounding rectangle for the clipping region.
219 public abstract Rectangle
222 /*************************************************************************/
225 * Returns the bounding rectangle of the clipping region for this
228 * @return The bounding rectangle for the clipping region.
230 * @deprecated This method is deprecated in favor of
231 * <code>getClipBounds()</code>.
236 return(getClipBounds());
239 /*************************************************************************/
242 * Sets the clipping region to the intersection of the current clipping
243 * region and the rectangle determined by the specified parameters.
245 * @param x The X coordinate of the upper left corner of the intersect rect.
246 * @param y The Y coordinate of the upper left corner of the intersect rect.
247 * @param width The width of the intersect rect.
248 * @param height The height of the intersect rect.
251 clipRect(int x
, int y
, int width
, int height
);
253 /*************************************************************************/
256 * Sets the clipping region to the rectangle determined by the specified
259 * @param x The X coordinate of the upper left corner of the rect.
260 * @param y The Y coordinate of the upper left corner of the rect.
261 * @param width The width of the rect.
262 * @param height The height of the rect.
265 setClip(int x
, int y
, int width
, int height
);
267 /*************************************************************************/
270 * Returns the current clipping region as a <code>Shape</code> object.
272 * @return The clipping region as a <code>Shape</code>.
274 public abstract Shape
277 /*************************************************************************/
280 * Sets the clipping region to the specified <code>Shape</code>.
282 * @param clip The new clipping region.
287 /*************************************************************************/
290 * Copies the specified rectangle to the specified offset location.
292 * @param x The X coordinate of the upper left corner of the copy rect.
293 * @param y The Y coordinate of the upper left corner of the copy rect.
294 * @param width The width of the copy rect.
295 * @param height The height of the copy rect.
296 * @param dx The offset from the X value to start drawing.
297 * @param dy The offset from the Y value to start drawing.
300 copyArea(int x
, int y
, int width
, int height
, int dx
, int dy
);
302 /*************************************************************************/
305 * Draws a line between the two specified points.
307 * @param x1 The X coordinate of the first point.
308 * @param y1 The Y coordinate of the first point.
309 * @param x2 The X coordinate of the second point.
310 * @param y2 The Y coordinate of the second point.
313 drawLine(int x1
, int y1
, int x2
, int y2
);
315 /*************************************************************************/
318 * Fills the area bounded by the specified rectangle.
320 * @param x The X coordinate of the upper left corner of the fill rect.
321 * @param y The Y coordinate of the upper left corner of the fill rect.
322 * @param width The width of the fill rect.
323 * @param height The height of the fill rect.
326 fillRect(int x
, int y
, int width
, int height
);
328 /*************************************************************************/
331 * Draws the outline of the specified rectangle.
333 * @param x The X coordinate of the upper left corner of the draw rect.
334 * @param y The Y coordinate of the upper left corner of the draw rect.
335 * @param width The width of the draw rect.
336 * @param height The height of the draw rect.
339 drawRect(int x
, int y
, int width
, int height
)
345 drawLine(x1
, y1
, x2
, y1
);
346 drawLine(x2
, y1
, x2
, y2
);
347 drawLine(x2
, y2
, x1
, y2
);
348 drawLine(x1
, y2
, x1
, y1
);
351 /*************************************************************************/
354 * Clears the specified rectangle.
356 * @param x The X coordinate of the upper left corner of the clear rect.
357 * @param y The Y coordinate of the upper left corner of the clear rect.
358 * @param width The width of the clear rect.
359 * @param height The height of the clear rect.
362 clearRect(int x
, int y
, int width
, int height
);
364 /*************************************************************************/
367 * Draws the outline of the specified rectangle with rounded cornders.
369 * @param x The X coordinate of the upper left corner of the draw rect.
370 * @param y The Y coordinate of the upper left corner of the draw rect.
371 * @param width The width of the draw rect.
372 * @param height The height of the draw rect.
373 * @param arcWidth The width of the corner arcs.
374 * @param arcHeight The height of the corner arcs.
377 drawRoundRect(int x
, int y
, int width
, int height
, int arcWidth
, int arcHeight
);
379 /*************************************************************************/
382 * Fills the specified rectangle with rounded cornders.
384 * @param x The X coordinate of the upper left corner of the fill rect.
385 * @param y The Y coordinate of the upper left corner of the fill rect.
386 * @param width The width of the fill rect.
387 * @param height The height of the fill rect.
388 * @param arcWidth The width of the corner arcs.
389 * @param arcHeight The height of the corner arcs.
392 fillRoundRect(int x
, int y
, int width
, int height
, int arcWidth
, int arcHeight
);
394 /*************************************************************************/
397 draw3DRect(int x
, int y
, int width
, int height
, boolean raised
)
399 Color color
= getColor();
400 Color tl
= color
.brighter();
401 Color br
= color
.darker();
416 drawLine(x1
, y1
, x2
, y1
);
417 drawLine(x1
, y2
, x1
, y1
);
419 drawLine(x2
, y1
, x2
, y2
);
420 drawLine(x2
, y2
, x1
, y2
);
425 * Fills the specified rectangle with a 3D effect
427 * @param x The X coordinate of the upper left corner of the fill rect.
428 * @param y The Y coordinate of the upper left corner of the fill rect.
429 * @param width The width of the fill rect.
430 * @param height The height of the fill rect.
431 * @param raised <code>true</code> if the rectangle appears raised,
432 * <code>false</code> if it should appear etched.
435 fill3DRect(int x
, int y
, int width
, int height
, boolean raised
)
437 fillRect(x
, y
, width
, height
);
438 draw3DRect(x
, y
, width
-1, height
-1, raised
);
441 /*************************************************************************/
444 * Draws an oval that just fits within the specified rectangle.
446 * @param x The X coordinate of the upper left corner of the rect.
447 * @param y The Y coordinate of the upper left corner of the rect.
448 * @param width The width of the rect.
449 * @param height The height of the rect.
452 drawOval(int x
, int y
, int width
, int height
);
454 /*************************************************************************/
457 * Fills an oval that just fits within the specified rectangle.
459 * @param x The X coordinate of the upper left corner of the rect.
460 * @param y The Y coordinate of the upper left corner of the rect.
461 * @param width The width of the rect.
462 * @param height The height of the rect.
465 fillOval(int x
, int y
, int width
, int height
);
467 /*************************************************************************/
470 * Draws an arc using the specified bounding rectangle and the specified
471 * angle parameter. The arc is centered at the center of the rectangle.
472 * The arc starts at the arcAngle position and extend for arcAngle
473 * degrees. The degree origin is at the 3 o'clock position.
475 * @param x The X coordinate of the upper left corner of the rect.
476 * @param y The Y coordinate of the upper left corner of the rect.
477 * @param width The width of the rect.
478 * @param height The height of the rect.
479 * @param arcStart The beginning angle of the arc.
480 * @param arcAngle The extent of the arc.
483 drawArc(int x
, int y
, int width
, int height
, int arcStart
, int arcAngle
);
485 /*************************************************************************/
488 * Fills the arc define by the specified bounding rectangle and the specified
489 * angle parameter. The arc is centered at the center of the rectangle.
490 * The arc starts at the arcAngle position and extend for arcAngle
491 * degrees. The degree origin is at the 3 o'clock position.
493 * @param x The X coordinate of the upper left corner of the rect.
494 * @param y The Y coordinate of the upper left corner of the rect.
495 * @param width The width of the rect.
496 * @param height The height of the rect.
497 * @param arcStart The beginning angle of the arc.
498 * @param arcAngle The extent of the arc.
501 fillArc(int x
, int y
, int width
, int height
, int arcStart
, int arcAngle
);
503 /*************************************************************************/
506 * Draws a series of interconnected lines determined by the arrays
507 * of corresponding x and y coordinates.
509 * @param xPoints The X coordinate array.
510 * @param yPoints The Y coordinate array.
511 * @param npoints The number of points to draw.
514 drawPolyline(int xPoints
[], int yPoints
[], int npoints
);
516 /*************************************************************************/
519 * Draws a series of interconnected lines determined by the arrays
520 * of corresponding x and y coordinates. The figure is closed if necessary
521 * by connecting the first and last points.
523 * @param xPoints The X coordinate array.
524 * @param yPoints The Y coordinate array.
525 * @param npoints The number of points to draw.
528 drawPolygon(int xPoints
[], int yPoints
[], int npoints
);
530 /*************************************************************************/
533 * Draws the specified polygon.
535 * @param polygon The polygon to draw.
538 drawPolygon(Polygon polygon
)
540 drawPolygon(polygon
.xpoints
, polygon
.ypoints
, polygon
.npoints
);
543 /*************************************************************************/
546 * Fills the polygon determined by the arrays
547 * of corresponding x and y coordinates.
549 * @param xPoints The X coordinate array.
550 * @param yPoints The Y coordinate array.
551 * @param npoints The number of points to draw.
554 fillPolygon(int xPoints
[], int yPoints
[], int npoints
);
556 /*************************************************************************/
559 * Fills the specified polygon
561 * @param polygon The polygon to fill.
564 fillPolygon(Polygon polygon
)
566 fillPolygon(polygon
.xpoints
, polygon
.ypoints
, polygon
.npoints
);
569 /*************************************************************************/
572 * Draws the specified string starting at the specified point.
574 * @param string The string to draw.
575 * @param x The X coordinate of the point to draw at.
576 * @param y The Y coordinate of the point to draw at.
579 drawString(String string
, int x
, int y
);
581 public abstract void drawString (AttributedCharacterIterator ci
, int x
, int y
);
583 /*************************************************************************/
586 * Draws the specified characters starting at the specified point.
588 * @param data The array of characters to draw.
589 * @param offset The offset into the array to start drawing characters from.
590 * @param length The number of characters to draw.
591 * @param x The X coordinate of the point to draw at.
592 * @param y The Y coordinate of the point to draw at.
595 drawChars(char data
[], int offset
, int length
, int x
, int y
)
597 drawString(new String(data
, offset
, length
), x
, y
);
601 drawBytes(byte[] data
, int offset
, int length
, int x
, int y
)
603 String str
= new String(data
, offset
, length
);
604 drawString(str
, x
, y
);
607 /*************************************************************************/
610 * Draws all of the image that is available and returns. If the image
611 * is not completely loaded, <code>false</code> is returned and
612 * the specified iamge observer is notified as more data becomes
615 * @param image The image to draw.
616 * @param x The X coordinate of the point to draw at.
617 * @param y The Y coordinate of the point to draw at.
618 * @param observer The image observer to notify as data becomes available.
620 * @return <code>true</code> if all the image data is available,
621 * <code>false</code> otherwise.
623 public abstract boolean
624 drawImage(Image image
, int x
, int y
, ImageObserver observer
);
626 /*************************************************************************/
629 * Draws all of the image that is available and returns. The image
630 * is scaled to fit in the specified rectangle. If the image
631 * is not completely loaded, <code>false</code> is returned and
632 * the specified iamge observer is notified as more data becomes
635 * @param image The image to draw.
636 * @param x The X coordinate of the point to draw at.
637 * @param y The Y coordinate of the point to draw at.
638 * @param width The width of the rectangle to draw in.
639 * @param height The height of the rectangle to draw in.
640 * @param observer The image observer to notify as data becomes available.
642 * @return <code>true</code> if all the image data is available,
643 * <code>false</code> otherwise.
645 public abstract boolean
646 drawImage(Image image
, int x
, int y
, int width
, int height
,
647 ImageObserver observer
);
649 /*************************************************************************/
652 * Draws all of the image that is available and returns. If the image
653 * is not completely loaded, <code>false</code> is returned and
654 * the specified iamge observer is notified as more data becomes
657 * @param image The image to draw.
658 * @param x The X coordinate of the point to draw at.
659 * @param y The Y coordinate of the point to draw at.
660 * @param bgcolor The background color to use for the image.
661 * @param observer The image observer to notify as data becomes available.
663 * @return <code>true</code> if all the image data is available,
664 * <code>false</code> otherwise.
666 public abstract boolean
667 drawImage(Image image
, int x
, int y
, Color bgcolor
, ImageObserver observer
);
669 /*************************************************************************/
672 * Draws all of the image that is available and returns. The image
673 * is scaled to fit in the specified rectangle. If the image
674 * is not completely loaded, <code>false</code> is returned and
675 * the specified iamge observer is notified as more data becomes
678 * @param image The image to draw.
679 * @param x The X coordinate of the point to draw at.
680 * @param y The Y coordinate of the point to draw at.
681 * @param width The width of the rectangle to draw in.
682 * @param height The height of the rectangle to draw in.
683 * @param bgcolor The background color to use for the image.
684 * @param observer The image observer to notify as data becomes available.
686 * @return <code>true</code> if all the image data is available,
687 * <code>false</code> otherwise.
689 public abstract boolean
690 drawImage(Image image
, int x
, int y
, int width
, int height
, Color bgcolor
,
691 ImageObserver observer
);
693 /*************************************************************************/
696 * FIXME: Write Javadocs for this when you understand it.
698 public abstract boolean
699 drawImage(Image image
, int dx1
, int dy1
, int dx2
, int dy2
, int sx1
, int sy1
,
700 int sx2
, int sy2
, ImageObserver observer
);
702 /*************************************************************************/
705 * FIXME: Write Javadocs for this when you understand it.
707 public abstract boolean
708 drawImage(Image image
, int dx1
, int dy1
, int dx2
, int dy2
, int sx1
, int sy1
,
709 int sx2
, int sy2
, Color bgcolor
, ImageObserver observer
);
711 /*************************************************************************/
714 * Free any resources held by this graphics context immediately instead
715 * of waiting for the object to be garbage collected and finalized.
720 /*************************************************************************/
723 * Frees the resources held by this graphics context when it is
732 /*************************************************************************/
735 * Returns a string representation of this object.
737 * @return A string representation of this object.
742 return getClass ().getName () + "[font=" + getFont () + ",color=" + getColor () + "]";
746 hitClip(int x
, int y
, int width
, int height
)
748 throw new UnsupportedOperationException("not implemented yet");
752 getClipBounds(Rectangle r
)
754 Rectangle clipBounds
= getClipBounds();
761 r
.width
= clipBounds
.width
;
762 r
.height
= clipBounds
.height
;