OSDN Git Service

2006-02-23 Scott Gilbertson <scottg@mantatest.com>
[pf3gnuchains/gcc-fork.git] / libjava / classpath / java / awt / Graphics.java
1 /* Graphics.java -- Abstract Java drawing class
2    Copyright (C) 1999, 2000, 2002, 2004, 2005  Free Software Foundation, Inc.
3
4 This file is part of GNU Classpath.
5
6 GNU Classpath is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation; either version 2, or (at your option)
9 any later version.
10
11 GNU Classpath is distributed in the hope that it will be useful, but
12 WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14 General Public License for more details.
15
16 You should have received a copy of the GNU General Public License
17 along with GNU Classpath; see the file COPYING.  If not, write to the
18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
19 02110-1301 USA.
20
21 Linking this library statically or dynamically with other modules is
22 making a combined work based on this library.  Thus, the terms and
23 conditions of the GNU General Public License cover the whole
24 combination.
25
26 As a special exception, the copyright holders of this library give you
27 permission to link this library with independent modules to produce an
28 executable, regardless of the license terms of these independent
29 modules, and to copy and distribute the resulting executable under
30 terms of your choice, provided that you also meet, for each linked
31 independent module, the terms and conditions of the license of that
32 module.  An independent module is a module which is not derived from
33 or based on this library.  If you modify this library, you may extend
34 this exception to your version of the library, but you are not
35 obligated to do so.  If you do not wish to do so, delete this
36 exception statement from your version. */
37
38
39 package java.awt;
40
41 import java.awt.image.ImageObserver;
42 import java.text.AttributedCharacterIterator;
43
44 /**
45  * This is the abstract superclass of classes for drawing to graphics
46  * devices such as the screen or printers.
47  *
48  * @author Aaron M. Renn (arenn@urbanophile.com)
49  * @author Warren Levy (warrenl@cygnus.com)
50  */
51 public abstract class Graphics
52 {
53
54   /**
55    * Default constructor for subclasses.
56    */
57   protected
58   Graphics()
59   {
60   }
61
62   /**
63    * Returns a copy of this <code>Graphics</code> object.
64    *
65    * @return A copy of this object.
66    */
67   public abstract Graphics create();
68
69   /**
70    * Returns a copy of this <code>Graphics</code> object.  The origin point
71    * will be translated to the point (x, y) and the cliping rectangle set
72    * to the intersection of the clipping rectangle in this object and the
73    * rectangle specified by the parameters to this method.
74    *
75    * @param x The new X coordinate of the clipping region rect.
76    * @param y The new Y coordinate of the clipping region rect.
77    * @param width The width of the clipping region intersect rectangle. 
78    * @param height The height of the clipping region intersect rectangle. 
79    *
80    * @return A copy of this object, modified as specified.
81    */
82   public Graphics create(int x, int y, int width, int height)
83   {
84     Graphics g = create();
85
86     g.translate(x, y);
87     // FIXME: I'm not sure if this will work.  Are the old clip rect bounds
88     // translated above?
89     g.clipRect(0, 0, width, height);
90
91     return(g);
92   }
93
94   /**
95    * Translates this context so that its new origin point is the point
96    * (x, y).
97    *
98    * @param x The new X coordinate of the origin.
99    * @param y The new Y coordinate of the origin.
100    */
101   public abstract void translate(int x, int y);
102
103   /**
104    * Returns the current color for this object.
105    *
106    * @return The color for this object.
107    */
108   public abstract Color getColor();
109
110   /**
111    * Sets the current color for this object.
112    *
113    * @param color The new color.
114    */
115   public abstract void setColor(Color color);
116
117   /**
118    * Sets this context into "paint" mode, where the target pixels are
119    * completely overwritten when drawn on.
120    */
121   public abstract void setPaintMode();
122
123   /**
124    * Sets this context info "XOR" mode, where the targe pixles are
125    * XOR-ed when drawn on. 
126    *
127    * @param color The color to XOR against.
128    */
129   public abstract void setXORMode(Color color);
130   
131   /**
132    * Returns the current font for this graphics context.
133    *
134    * @return The current font.
135    */
136   public abstract Font getFont();
137
138   /**
139    * Sets the font for this graphics context to the specified value.
140    *
141    * @param font The new font.
142    */
143   public abstract void setFont(Font font);
144
145   /**
146    * Returns the font metrics for the current font.
147    *
148    * @return The font metrics for the current font.
149    */
150   public FontMetrics getFontMetrics()
151   {
152     return getFontMetrics(getFont());
153   }
154
155   /**
156    * Returns the font metrics for the specified font.
157    *
158    * @param font The font to return metrics for.
159    *
160    * @return The requested font metrics.
161    */
162   public abstract FontMetrics getFontMetrics(Font font);
163
164   /**
165    * Returns the bounding rectangle of the clipping region for this 
166    * graphics context.
167    *
168    * @return The bounding rectangle for the clipping region.
169    */
170   public abstract Rectangle getClipBounds();
171
172   /**
173    * Returns the bounding rectangle of the clipping region for this 
174    * graphics context.
175    *
176    * @return The bounding rectangle for the clipping region.
177    *
178    * @deprecated This method is deprecated in favor of
179    * <code>getClipBounds()</code>.
180    */
181   public Rectangle getClipRect()
182   {
183     return getClipBounds();
184   }
185
186   /**
187    * Sets the clipping region to the intersection of the current clipping
188    * region and the rectangle determined by the specified parameters.
189    *
190    * @param x The X coordinate of the upper left corner of the intersect rect.
191    * @param y The Y coordinate of the upper left corner of the intersect rect.
192    * @param width The width of the intersect rect.
193    * @param height The height of the intersect rect.
194    */
195   public abstract void clipRect(int x, int y, int width, int height);
196
197   /**
198    * Sets the clipping region to the rectangle determined by the specified
199    * parameters.
200    *
201    * @param x The X coordinate of the upper left corner of the rect.
202    * @param y The Y coordinate of the upper left corner of the rect.
203    * @param width The width of the rect.
204    * @param height The height of the rect.
205    */
206   public abstract void setClip(int x, int y, int width, int height);
207
208   /**
209    * Returns the current clipping region as a <code>Shape</code> object.
210    *
211    * @return The clipping region as a <code>Shape</code>.
212    */
213   public abstract Shape getClip();
214
215   /**
216    * Sets the clipping region to the specified <code>Shape</code>.
217    *
218    * @param clip The new clipping region.
219    */
220   public abstract void setClip(Shape clip);
221
222   /**
223    * Copies the specified rectangle to the specified offset location.
224    *
225    * @param x The X coordinate of the upper left corner of the copy rect.
226    * @param y The Y coordinate of the upper left corner of the copy rect.
227    * @param width The width of the copy rect.
228    * @param height The height of the copy rect.
229    * @param dx The offset from the X value to start drawing.
230    * @param dy The offset from the Y value to start drawing.
231    */
232   public abstract void copyArea(int x, int y, int width, int height, int dx,
233                                 int dy);
234
235   /**
236    * Draws a line between the two specified points.
237    *
238    * @param x1 The X coordinate of the first point.
239    * @param y1 The Y coordinate of the first point.
240    * @param x2 The X coordinate of the second point.
241    * @param y2 The Y coordinate of the second point.
242    */
243   public abstract void drawLine(int x1, int y1, int x2, int y2);
244
245   /**
246    * Fills the area bounded by the specified rectangle.
247    *
248    * @param x The X coordinate of the upper left corner of the fill rect.
249    * @param y The Y coordinate of the upper left corner of the fill rect.
250    * @param width The width of the fill rect.
251    * @param height The height of the fill rect.
252    */
253   public abstract void fillRect(int x, int y, int width, int height);
254
255   /**
256    * Draws the outline of the specified rectangle.
257    *
258    * @param x The X coordinate of the upper left corner of the draw rect.
259    * @param y The Y coordinate of the upper left corner of the draw rect.
260    * @param width The width of the draw rect.
261    * @param height The height of the draw rect.
262    */
263   public void drawRect(int x, int y, int width, int height)
264   {
265     int x1 = x;
266     int y1 = y;
267     int x2 = x + width;
268     int y2 = y + height;
269     drawLine(x1, y1, x2, y1);
270     drawLine(x2, y1, x2, y2);
271     drawLine(x2, y2, x1, y2);
272     drawLine(x1, y2, x1, y1);
273   }
274
275   /**
276    * Clears the specified rectangle.
277    *
278    * @param x The X coordinate of the upper left corner of the clear rect.
279    * @param y The Y coordinate of the upper left corner of the clear rect.
280    * @param width The width of the clear rect.
281    * @param height The height of the clear rect.
282    */
283   public abstract void clearRect(int x, int y, int width, int height);
284
285   /**
286    * Draws the outline of the specified rectangle with rounded cornders.
287    *
288    * @param x The X coordinate of the upper left corner of the draw rect.
289    * @param y The Y coordinate of the upper left corner of the draw rect.
290    * @param width The width of the draw rect.
291    * @param height The height of the draw rect.
292    * @param arcWidth The width of the corner arcs.
293    * @param arcHeight The height of the corner arcs.
294    */
295   public abstract void drawRoundRect(int x, int y, int width, int height,
296                                      int arcWidth, int arcHeight);
297
298   /**
299    * Fills the specified rectangle with rounded cornders.
300    *
301    * @param x The X coordinate of the upper left corner of the fill rect.
302    * @param y The Y coordinate of the upper left corner of the fill rect.
303    * @param width The width of the fill rect.
304    * @param height The height of the fill rect.
305    * @param arcWidth The width of the corner arcs.
306    * @param arcHeight The height of the corner arcs.
307    */
308   public abstract void fillRoundRect(int x, int y, int width, int height,
309                                      int arcWidth, int arcHeight);
310
311   public void draw3DRect(int x, int y, int width, int height, boolean raised)
312   {
313     Color color = getColor();
314     Color tl = color.brighter();
315     Color br = color.darker();
316     
317     if (!raised)
318       {
319         Color tmp = tl;
320         tl = br;
321         br = tmp;
322       }
323     
324     int x1 = x;
325     int y1 = y;
326     int x2 = x + width;
327     int y2 = y + height;
328     
329     setColor(tl);
330     drawLine(x1, y1, x2, y1);
331     drawLine(x1, y2, x1, y1);
332     setColor(br);
333     drawLine(x2, y1, x2, y2);
334     drawLine(x2, y2, x1, y2);
335     setColor(color);
336   }
337
338   /**
339    * Fills the specified rectangle with a 3D effect
340    *
341    * @param x The X coordinate of the upper left corner of the fill rect.
342    * @param y The Y coordinate of the upper left corner of the fill rect.
343    * @param width The width of the fill rect.
344    * @param height The height of the fill rect.
345    * @param raised <code>true</code> if the rectangle appears raised,
346    * <code>false</code> if it should appear etched.
347    */
348   public void fill3DRect(int x, int y, int width, int height, boolean raised)
349   {
350     fillRect(x, y, width, height);
351     draw3DRect(x, y, width-1, height-1, raised);
352   }
353
354   /**
355    * Draws an oval that just fits within the specified rectangle.
356    *
357    * @param x The X coordinate of the upper left corner of the rect.
358    * @param y The Y coordinate of the upper left corner of the rect.
359    * @param width The width of the rect.
360    * @param height The height of the rect.
361    */
362   public abstract void drawOval(int x, int y, int width, int height);
363
364   /**
365    * Fills an oval that just fits within the specified rectangle.
366    *
367    * @param x The X coordinate of the upper left corner of the rect.
368    * @param y The Y coordinate of the upper left corner of the rect.
369    * @param width The width of the rect.
370    * @param height The height of the rect.
371    */
372   public abstract void fillOval(int x, int y, int width, int height);
373
374   /**
375    * Draws an arc using the specified bounding rectangle and the specified
376    * angle parameter.  The arc is centered at the center of the rectangle.
377    * The arc starts at the arcAngle position and extend for arcAngle
378    * degrees.  The degree origin is at the 3 o'clock position.
379    *
380    * @param x The X coordinate of the upper left corner of the rect.
381    * @param y The Y coordinate of the upper left corner of the rect.
382    * @param width The width of the rect.
383    * @param height The height of the rect.
384    * @param arcStart The beginning angle of the arc.
385    * @param arcAngle The extent of the arc.
386    */
387   public abstract void drawArc(int x, int y, int width, int height,
388                                int arcStart, int arcAngle);
389
390   /**
391    * Fills the arc define by the specified bounding rectangle and the specified
392    * angle parameter.  The arc is centered at the center of the rectangle.
393    * The arc starts at the arcAngle position and extend for arcAngle
394    * degrees.  The degree origin is at the 3 o'clock position.
395    *
396    * @param x The X coordinate of the upper left corner of the rect.
397    * @param y The Y coordinate of the upper left corner of the rect.
398    * @param width The width of the rect.
399    * @param height The height of the rect.
400    * @param arcStart The beginning angle of the arc.
401    * @param arcAngle The extent of the arc.
402    */
403   public abstract void fillArc(int x, int y, int width, int height,
404                                int arcStart, int arcAngle);
405
406   /**
407    * Draws a series of interconnected lines determined by the arrays
408    * of corresponding x and y coordinates.
409    *
410    * @param xPoints The X coordinate array.
411    * @param yPoints The Y coordinate array.
412    * @param npoints The number of points to draw.
413    */
414   public abstract void drawPolyline(int xPoints[], int yPoints[], int npoints);
415
416   /**
417    * Draws a series of interconnected lines determined by the arrays
418    * of corresponding x and y coordinates.  The figure is closed if necessary
419    * by connecting the first and last points.
420    *
421    * @param xPoints The X coordinate array.
422    * @param yPoints The Y coordinate array.
423    * @param npoints The number of points to draw.
424    */
425   public abstract void drawPolygon(int xPoints[], int yPoints[], int npoints);
426
427   /**
428    * Draws the specified polygon.
429    *
430    * @param polygon The polygon to draw.
431    */
432   public void drawPolygon(Polygon polygon)
433   {
434     drawPolygon(polygon.xpoints, polygon.ypoints, polygon.npoints);
435   }
436
437   /**
438    * Fills the polygon determined by the arrays
439    * of corresponding x and y coordinates.
440    *
441    * @param xPoints The X coordinate array.
442    * @param yPoints The Y coordinate array.
443    * @param npoints The number of points to draw.
444    */
445   public abstract void fillPolygon(int xPoints[], int yPoints[], int npoints);
446
447   /**
448    * Fills the specified polygon
449    *
450    * @param polygon The polygon to fill.
451    */
452   public void fillPolygon(Polygon polygon)
453   {
454     fillPolygon(polygon.xpoints, polygon.ypoints, polygon.npoints);
455   }
456
457   /**
458    * Draws the specified string starting at the specified point.
459    *
460    * @param string The string to draw.
461    * @param x The X coordinate of the point to draw at.
462    * @param y The Y coordinate of the point to draw at.
463    */
464   public abstract void drawString(String string, int x, int y);
465
466   public abstract void drawString (AttributedCharacterIterator ci, int x,
467                                    int y);
468
469   /**
470    * Draws the specified characters starting at the specified point.
471    *
472    * @param data The array of characters to draw.
473    * @param offset The offset into the array to start drawing characters from.
474    * @param length The number of characters to draw.
475    * @param x The X coordinate of the point to draw at.
476    * @param y The Y coordinate of the point to draw at.
477    */
478   public void drawChars(char data[], int offset, int length, int x, int y)
479   {
480     drawString(new String(data, offset, length), x, y);
481   }
482
483   public void drawBytes(byte[] data, int offset, int length, int x, int y)
484   {
485     String str = new String(data, offset, length);
486     drawString(str, x, y);
487   }
488
489   /**
490    * Draws all of the image that is available and returns.  If the image
491    * is not completely loaded, <code>false</code> is returned and 
492    * the specified iamge observer is notified as more data becomes 
493    * available.
494    *
495    * @param image The image to draw.
496    * @param x The X coordinate of the point to draw at.
497    * @param y The Y coordinate of the point to draw at.
498    * @param observer The image observer to notify as data becomes available.
499    *
500    * @return <code>true</code> if all the image data is available,
501    * <code>false</code> otherwise.
502    */
503   public abstract boolean drawImage(Image image, int x, int y,
504                                     ImageObserver observer);
505  
506   /**
507    * Draws all of the image that is available and returns.  The image
508    * is scaled to fit in the specified rectangle.  If the image
509    * is not completely loaded, <code>false</code> is returned and 
510    * the specified iamge observer is notified as more data becomes 
511    * available.
512    *
513    * @param image The image to draw.
514    * @param x The X coordinate of the point to draw at.
515    * @param y The Y coordinate of the point to draw at.
516    * @param width The width of the rectangle to draw in.
517    * @param height The height of the rectangle to draw in.
518    * @param observer The image observer to notify as data becomes available.
519    *
520    * @return <code>true</code> if all the image data is available,
521    * <code>false</code> otherwise.
522    */
523   public abstract boolean drawImage(Image image, int x, int y, int width,
524                                     int height, ImageObserver observer);
525  
526   /**
527    * Draws all of the image that is available and returns.  If the image
528    * is not completely loaded, <code>false</code> is returned and 
529    * the specified iamge observer is notified as more data becomes 
530    * available.
531    *
532    * @param image The image to draw.
533    * @param x The X coordinate of the point to draw at.
534    * @param y The Y coordinate of the point to draw at.
535    * @param bgcolor The background color to use for the image.
536    * @param observer The image observer to notify as data becomes available.
537    *
538    * @return <code>true</code> if all the image data is available,
539    * <code>false</code> otherwise.
540    */
541   public abstract boolean drawImage(Image image, int x, int y, Color bgcolor,
542                                     ImageObserver observer);
543  
544   /**
545    * Draws all of the image that is available and returns.  The image
546    * is scaled to fit in the specified rectangle.  If the image
547    * is not completely loaded, <code>false</code> is returned and 
548    * the specified iamge observer is notified as more data becomes 
549    * available.
550    *
551    * @param image The image to draw.
552    * @param x The X coordinate of the point to draw at.
553    * @param y The Y coordinate of the point to draw at.
554    * @param width The width of the rectangle to draw in.
555    * @param height The height of the rectangle to draw in.
556    * @param bgcolor The background color to use for the image.
557    * @param observer The image observer to notify as data becomes available.
558    *
559    * @return <code>true</code> if all the image data is available,
560    * <code>false</code> otherwise.
561    */
562   public abstract boolean drawImage(Image image, int x, int y, int width,
563                                     int height, Color bgcolor,
564                                     ImageObserver observer);
565
566   /**
567    * FIXME: Write Javadocs for this when you understand it.
568    */
569   public abstract boolean drawImage(Image image, int dx1, int dy1, int dx2,
570                                     int dy2, int sx1, int sy1, int sx2,
571                                     int sy2, ImageObserver observer);
572
573   /**
574    * FIXME: Write Javadocs for this when you understand it.
575    */
576   public abstract boolean drawImage(Image image, int dx1, int dy1, int dx2,
577                                     int dy2, int sx1, int sy1, int sx2,
578                                     int sy2, Color bgcolor,
579                                     ImageObserver observer);
580
581   /**
582    * Free any resources held by this graphics context immediately instead
583    * of waiting for the object to be garbage collected and finalized.
584    */
585   public abstract void dispose();
586
587   /**
588    * Frees the resources held by this graphics context when it is
589    * garbage collected.
590    */
591   public void finalize()
592   {
593     dispose();
594   }
595
596   /**
597    * Returns a string representation of this object.
598    *
599    * @return A string representation of this object. 
600    */
601   public String toString()
602   {
603     return getClass ().getName () + "[font=" + getFont () + ",color="
604            + getColor () + "]";
605   }
606
607   /**
608    * Returns <code>true</code> if the specified rectangle intersects with the
609    * current clip, <code>false</code> otherwise.
610    *
611    * @param x the X coordinate of the upper left corner of the test rectangle
612    * @param y the Y coordinate of the upper left corner of the test rectangle
613    * @param width the width of the upper left corner of the test rectangle
614    * @param height the height of the upper left corner of the test rectangle
615    * @return <code>true</code> if the specified rectangle intersects with the
616    *         current clip, <code>false</code> otherwise
617    */
618   public boolean hitClip(int x, int y, int width, int height)
619   {
620     Shape clip = getClip();
621     if (clip == null)
622       return true;
623     return getClip().intersects(x, y, width, height);
624   }
625
626   public Rectangle getClipBounds(Rectangle r)
627   {
628     Rectangle clipBounds = getClipBounds();
629   
630     if (r == null)
631       return clipBounds;
632
633     r.x      = clipBounds.x;
634     r.y      = clipBounds.y;
635     r.width  = clipBounds.width;
636     r.height = clipBounds.height;
637     return r;
638   }
639 }