libjava/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., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 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  * Instance Variables
  56  */
  57
  58 /*************************************************************************/
  59
  60 /*
  61  * Constructors
  62  */
  63
  64 /**
  65   * Default constructor for subclasses.
  66   */
  67 protected
  68 Graphics()
  69 {
  70 }
  71
  72 /*************************************************************************/
  73
  74 /*
  75  * Instance Methods
  76  */
  77
  78 /**
  79   * Returns a copy of this <code>Graphics</code> object.
  80   *
  81   * @return A copy of this object.
  82   */
  83 public abstract Graphics
  84 create();
  85
  86 /*************************************************************************/
  87
  88 /**
  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.
  93   *
  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.
  98   *
  99   * @return A copy of this object, modified as specified.
 100   */
 101 public Graphics
 102 create(int x, int y, int width, int height)
 103 {
 104   Graphics g = create();
 105
 106   g.translate(x, y);
 107   // FIXME: I'm not sure if this will work.  Are the old clip rect bounds
 108   // translated above?
 109   g.clipRect(0, 0, width, height);
 110
 111   return(g);
 112 }
 113
 114 /*************************************************************************/
 115
 116 /**
 117   * Translates this context so that its new origin point is the point
 118   * (x, y).
 119   *
 120   * @param x The new X coordinate of the origin.
 121   * @param y The new Y coordinate of the origin.
 122   */
 123 public abstract void
 124 translate(int x, int y);
 125
 126 /*************************************************************************/
 127
 128 /**
 129   * Returns the current color for this object.
 130   *
 131   * @return The color for this object.
 132   */
 133 public abstract Color
 134 getColor();
 135
 136 /*************************************************************************/
 137
 138 /**
 139   * Sets the current color for this object.
 140   *
 141   * @param color The new color.
 142   */
 143 public abstract void
 144 setColor(Color color);
 145
 146 /*************************************************************************/
 147
 148 /**
 149   * Sets this context into "paint" mode, where the target pixels are
 150   * completely overwritten when drawn on.
 151   */
 152 public abstract void
 153 setPaintMode();
 154
 155 /*************************************************************************/
 156
 157 /**
 158   * Sets this context info "XOR" mode, where the targe pixles are
 159   * XOR-ed when drawn on.
 160   *
 161   * @param color The color to XOR against.
 162   */
 163 public abstract void
 164 setXORMode(Color color);
 165
 166 /*************************************************************************/
 167
 168 /**
 169   * Returns the current font for this graphics context.
 170   *
 171   * @return The current font.
 172   */
 173 public abstract Font
 174 getFont();
 175
 176 /*************************************************************************/
 177
 178 /**
 179   * Sets the font for this graphics context to the specified value.
 180   *
 181   * @param font The new font.
 182   */
 183 public abstract void
 184 setFont(Font font);
 185
 186 /*************************************************************************/
 187
 188 /**
 189   * Returns the font metrics for the current font.
 190   *
 191   * @return The font metrics for the current font.
 192   */
 193 public FontMetrics
 194 getFontMetrics()
 195 {
 196   return(getFontMetrics(getFont()));
 197 }
 198
 199 /*************************************************************************/
 200
 201 /**
 202   * Returns the font metrics for the specified font.
 203   *
 204   * @param font The font to return metrics for.
 205   *
 206   * @return The requested font metrics.
 207   */
 208 public abstract FontMetrics
 209 getFontMetrics(Font font);
 210
 211 /*************************************************************************/
 212
 213 /**
 214   * Returns the bounding rectangle of the clipping region for this
 215   * graphics context.
 216   *
 217   * @return The bounding rectangle for the clipping region.
 218   */
 219 public abstract Rectangle
 220 getClipBounds();
 221
 222 /*************************************************************************/
 223
 224 /**
 225   * Returns the bounding rectangle of the clipping region for this
 226   * graphics context.
 227   *
 228   * @return The bounding rectangle for the clipping region.
 229   *
 230   * @deprecated This method is deprecated in favor of
 231   * <code>getClipBounds()</code>.
 232   */
 233 public Rectangle
 234 getClipRect()
 235 {
 236   return(getClipBounds());
 237 }
 238
 239 /*************************************************************************/
 240
 241 /**
 242   * Sets the clipping region to the intersection of the current clipping
 243   * region and the rectangle determined by the specified parameters.
 244   *
 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.
 249   */
 250 public abstract void
 251 clipRect(int x, int y, int width, int height);
 252
 253 /*************************************************************************/
 254
 255 /**
 256   * Sets the clipping region to the rectangle determined by the specified
 257   * parameters.
 258   *
 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.
 263   */
 264 public abstract void
 265 setClip(int x, int y, int width, int height);
 266
 267 /*************************************************************************/
 268
 269 /**
 270   * Returns the current clipping region as a <code>Shape</code> object.
 271   *
 272   * @return The clipping region as a <code>Shape</code>.
 273   */
 274 public abstract Shape
 275 getClip();
 276
 277 /*************************************************************************/
 278
 279 /**
 280   * Sets the clipping region to the specified <code>Shape</code>.
 281   *
 282   * @param clip The new clipping region.
 283   */
 284 public abstract void
 285 setClip(Shape clip);
 286
 287 /*************************************************************************/
 288
 289 /**
 290   * Copies the specified rectangle to the specified offset location.
 291   *
 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.
 298   */
 299 public abstract void
 300 copyArea(int x, int y, int width, int height, int dx, int dy);
 301
 302 /*************************************************************************/
 303
 304 /**
 305   * Draws a line between the two specified points.
 306   *
 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.
 311   */
 312 public abstract void
 313 drawLine(int x1, int y1, int x2, int y2);
 314
 315 /*************************************************************************/
 316
 317 /**
 318   * Fills the area bounded by the specified rectangle.
 319   *
 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.
 324   */
 325 public abstract void
 326 fillRect(int x, int y, int width, int height);
 327
 328 /*************************************************************************/
 329
 330 /**
 331   * Draws the outline of the specified rectangle.
 332   *
 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.
 337   */
 338 public void
 339 drawRect(int x, int y, int width, int height)
 340 {
 341   int x1 = x;
 342   int y1 = y;
 343   int x2 = x + width;
 344   int y2 = y + 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);
 349 }
 350
 351 /*************************************************************************/
 352
 353 /**
 354   * Clears the specified rectangle.
 355   *
 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.
 360   */
 361 public abstract void
 362 clearRect(int x, int y, int width, int height);
 363
 364 /*************************************************************************/
 365
 366 /**
 367   * Draws the outline of the specified rectangle with rounded cornders.
 368   *
 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.
 375   */
 376 public abstract void
 377 drawRoundRect(int x, int y, int width, int height, int arcWidth, int arcHeight);
 378
 379 /*************************************************************************/
 380
 381 /**
 382   * Fills the specified rectangle with rounded cornders.
 383   *
 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.
 390   */
 391 public abstract void
 392 fillRoundRect(int x, int y, int width, int height, int arcWidth, int arcHeight);
 393
 394 /*************************************************************************/
 395
 396 public void
 397 draw3DRect(int x, int y, int width, int height, boolean raised)
 398 {
 399   Color color = getColor();
 400   Color tl = color.brighter();
 401   Color br = color.darker();
 402
 403   if (!raised)
 404     {
 405       Color tmp = tl;
 406       tl = br;
 407       br = tmp;
 408     }
 409
 410   int x1 = x;
 411   int y1 = y;
 412   int x2 = x + width;
 413   int y2 = y + height;
 414
 415   setColor(tl);
 416   drawLine(x1, y1, x2, y1);
 417   drawLine(x1, y2, x1, y1);
 418   setColor(br);
 419   drawLine(x2, y1, x2, y2);
 420   drawLine(x2, y2, x1, y2);
 421   setColor(color);
 422 }
 423
 424 /**
 425   * Fills the specified rectangle with a 3D effect
 426   *
 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.
 433   */
 434 public void
 435 fill3DRect(int x, int y, int width, int height, boolean raised)
 436 {
 437   fillRect(x, y, width, height);
 438   draw3DRect(x, y, width-1, height-1, raised);
 439 }
 440
 441 /*************************************************************************/
 442
 443 /**
 444   * Draws an oval that just fits within the specified rectangle.
 445   *
 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.
 450   */
 451 public abstract void
 452 drawOval(int x, int y, int width, int height);
 453
 454 /*************************************************************************/
 455
 456 /**
 457   * Fills an oval that just fits within the specified rectangle.
 458   *
 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.
 463   */
 464 public abstract void
 465 fillOval(int x, int y, int width, int height);
 466
 467 /*************************************************************************/
 468
 469 /**
 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.
 474   *
 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.
 481   */
 482 public abstract void
 483 drawArc(int x, int y, int width, int height, int arcStart, int arcAngle);
 484
 485 /*************************************************************************/
 486
 487 /**
 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.
 492   *
 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.
 499   */
 500 public abstract void
 501 fillArc(int x, int y, int width, int height, int arcStart, int arcAngle);
 502
 503 /*************************************************************************/
 504
 505 /**
 506   * Draws a series of interconnected lines determined by the arrays
 507   * of corresponding x and y coordinates.
 508   *
 509   * @param xPoints The X coordinate array.
 510   * @param yPoints The Y coordinate array.
 511   * @param npoints The number of points to draw.
 512   */
 513 public abstract void
 514 drawPolyline(int xPoints[], int yPoints[], int npoints);
 515
 516 /*************************************************************************/
 517
 518 /**
 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.
 522   *
 523   * @param xPoints The X coordinate array.
 524   * @param yPoints The Y coordinate array.
 525   * @param npoints The number of points to draw.
 526   */
 527 public abstract void
 528 drawPolygon(int xPoints[], int yPoints[], int npoints);
 529
 530 /*************************************************************************/
 531
 532 /**
 533   * Draws the specified polygon.
 534   *
 535   * @param polygon The polygon to draw.
 536   */
 537 public void
 538 drawPolygon(Polygon polygon)
 539 {
 540   drawPolygon(polygon.xpoints, polygon.ypoints, polygon.npoints);
 541 }
 542
 543 /*************************************************************************/
 544
 545 /**
 546   * Fills the polygon determined by the arrays
 547   * of corresponding x and y coordinates.
 548   *
 549   * @param xPoints The X coordinate array.
 550   * @param yPoints The Y coordinate array.
 551   * @param npoints The number of points to draw.
 552   */
 553 public abstract void
 554 fillPolygon(int xPoints[], int yPoints[], int npoints);
 555
 556 /*************************************************************************/
 557
 558 /**
 559   * Fills the specified polygon
 560   *
 561   * @param polygon The polygon to fill.
 562   */
 563 public void
 564 fillPolygon(Polygon polygon)
 565 {
 566   fillPolygon(polygon.xpoints, polygon.ypoints, polygon.npoints);
 567 }
 568
 569 /*************************************************************************/
 570
 571 /**
 572   * Draws the specified string starting at the specified point.
 573   *
 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.
 577   */
 578 public abstract void
 579 drawString(String string, int x, int y);
 580
 581 public abstract void drawString (AttributedCharacterIterator ci, int x, int y);
 582
 583 /*************************************************************************/
 584
 585 /**
 586   * Draws the specified characters starting at the specified point.
 587   *
 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.
 593   */
 594 public void
 595 drawChars(char data[], int offset, int length, int x, int y)
 596 {
 597   drawString(new String(data, offset, length), x, y);
 598 }
 599
 600 public void
 601 drawBytes(byte[] data, int offset, int length, int x, int y)
 602 {
 603   String str = new String(data, offset, length);
 604   drawString(str, x, y);
 605 }
 606
 607 /*************************************************************************/
 608
 609 /**
 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
 613   * available.
 614   *
 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.
 619   *
 620   * @return <code>true</code> if all the image data is available,
 621   * <code>false</code> otherwise.
 622   */
 623 public abstract boolean
 624 drawImage(Image image, int x, int y, ImageObserver observer);
 625
 626 /*************************************************************************/
 627
 628 /**
 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
 633   * available.
 634   *
 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.
 641   *
 642   * @return <code>true</code> if all the image data is available,
 643   * <code>false</code> otherwise.
 644   */
 645 public abstract boolean
 646 drawImage(Image image, int x, int y, int width, int height,
 647           ImageObserver observer);
 648
 649 /*************************************************************************/
 650
 651 /**
 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
 655   * available.
 656   *
 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.
 662   *
 663   * @return <code>true</code> if all the image data is available,
 664   * <code>false</code> otherwise.
 665   */
 666 public abstract boolean
 667 drawImage(Image image, int x, int y, Color bgcolor, ImageObserver observer);
 668
 669 /*************************************************************************/
 670
 671 /**
 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
 676   * available.
 677   *
 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.
 685   *
 686   * @return <code>true</code> if all the image data is available,
 687   * <code>false</code> otherwise.
 688   */
 689 public abstract boolean
 690 drawImage(Image image, int x, int y, int width, int height, Color bgcolor,
 691           ImageObserver observer);
 692
 693 /*************************************************************************/
 694
 695 /**
 696   * FIXME: Write Javadocs for this when you understand it.
 697   */
 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);
 701
 702 /*************************************************************************/
 703
 704 /**
 705   * FIXME: Write Javadocs for this when you understand it.
 706   */
 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);
 710
 711 /*************************************************************************/
 712
 713 /**
 714   * Free any resources held by this graphics context immediately instead
 715   * of waiting for the object to be garbage collected and finalized.
 716   */
 717 public abstract void
 718 dispose();
 719
 720 /*************************************************************************/
 721
 722 /**
 723   * Frees the resources held by this graphics context when it is
 724   * garbage collected.
 725   */
 726 public void
 727 finalize()
 728 {
 729   dispose();
 730 }
 731
 732 /*************************************************************************/
 733
 734 /**
 735  * Returns a string representation of this object.
 736  *
 737  * @return A string representation of this object.
 738  */
 739 public String
 740 toString()
 741 {
 742   return getClass ().getName () + "[font=" + getFont () + ",color=" + getColor () + "]";
 743 }
 744
 745 public boolean
 746 hitClip(int x, int y, int width, int height)
 747 {
 748   throw new UnsupportedOperationException("not implemented yet");
 749 }
 750
 751 public Rectangle
 752 getClipBounds(Rectangle r)
 753 {
 754   Rectangle clipBounds = getClipBounds();
 755
 756   if (r == null)
 757     return clipBounds;
 758
 759   r.x      = clipBounds.x;
 760   r.y      = clipBounds.y;
 761   r.width  = clipBounds.width;
 762   r.height = clipBounds.height;
 763   return r;
 764 }
 765
 766 } // class Graphics
 767