gomp-20050608-branch/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     return getClip().intersects(x, y, width, height);
 621   }
 622
 623   public Rectangle getClipBounds(Rectangle r)
 624   {
 625     Rectangle clipBounds = getClipBounds();
 626
 627     if (r == null)
 628       return clipBounds;
 629
 630     r.x      = clipBounds.x;
 631     r.y      = clipBounds.y;
 632     r.width  = clipBounds.width;
 633     r.height = clipBounds.height;
 634     return r;
 635   }
 636 }