Home » openjdk-7 » java » awt » [javadoc | source]

    1   /*
    2    * Copyright (c) 1995, 2006, Oracle and/or its affiliates. All rights reserved.
    3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
    4    *
    5    * This code is free software; you can redistribute it and/or modify it
    6    * under the terms of the GNU General Public License version 2 only, as
    7    * published by the Free Software Foundation.  Oracle designates this
    8    * particular file as subject to the "Classpath" exception as provided
    9    * by Oracle in the LICENSE file that accompanied this code.
   10    *
   11    * This code is distributed in the hope that it will be useful, but WITHOUT
   12    * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   13    * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   14    * version 2 for more details (a copy is included in the LICENSE file that
   15    * accompanied this code).
   16    *
   17    * You should have received a copy of the GNU General Public License version
   18    * 2 along with this work; if not, write to the Free Software Foundation,
   19    * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   20    *
   21    * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
   22    * or visit www.oracle.com if you need additional information or have any
   23    * questions.
   24    */
   25   package java.awt;
   26   
   27   import java.io;
   28   import java.lang;
   29   import java.util;
   30   import java.awt.image.ImageObserver;
   31   import java.text.AttributedCharacterIterator;
   32   
   33   /**
   34    * The <code>Graphics</code> class is the abstract base class for
   35    * all graphics contexts that allow an application to draw onto
   36    * components that are realized on various devices, as well as
   37    * onto off-screen images.
   38    * <p>
   39    * A <code>Graphics</code> object encapsulates state information needed
   40    * for the basic rendering operations that Java supports.  This
   41    * state information includes the following properties:
   42    * <p>
   43    * <ul>
   44    * <li>The <code>Component</code> object on which to draw.
   45    * <li>A translation origin for rendering and clipping coordinates.
   46    * <li>The current clip.
   47    * <li>The current color.
   48    * <li>The current font.
   49    * <li>The current logical pixel operation function (XOR or Paint).
   50    * <li>The current XOR alternation color
   51    *     (see {@link Graphics#setXORMode}).
   52    * </ul>
   53    * <p>
   54    * Coordinates are infinitely thin and lie between the pixels of the
   55    * output device.
   56    * Operations that draw the outline of a figure operate by traversing
   57    * an infinitely thin path between pixels with a pixel-sized pen that hangs
   58    * down and to the right of the anchor point on the path.
   59    * Operations that fill a figure operate by filling the interior
   60    * of that infinitely thin path.
   61    * Operations that render horizontal text render the ascending
   62    * portion of character glyphs entirely above the baseline coordinate.
   63    * <p>
   64    * The graphics pen hangs down and to the right from the path it traverses.
   65    * This has the following implications:
   66    * <p><ul>
   67    * <li>If you draw a figure that covers a given rectangle, that
   68    * figure occupies one extra row of pixels on the right and bottom edges
   69    * as compared to filling a figure that is bounded by that same rectangle.
   70    * <li>If you draw a horizontal line along the same <i>y</i> coordinate as
   71    * the baseline of a line of text, that line is drawn entirely below
   72    * the text, except for any descenders.
   73    * </ul><p>
   74    * All coordinates that appear as arguments to the methods of this
   75    * <code>Graphics</code> object are considered relative to the
   76    * translation origin of this <code>Graphics</code> object prior to
   77    * the invocation of the method.
   78    * <p>
   79    * All rendering operations modify only pixels which lie within the
   80    * area bounded by the current clip, which is specified by a {@link Shape}
   81    * in user space and is controlled by the program using the
   82    * <code>Graphics</code> object.  This <i>user clip</i>
   83    * is transformed into device space and combined with the
   84    * <i>device clip</i>, which is defined by the visibility of windows and
   85    * device extents.  The combination of the user clip and device clip
   86    * defines the <i>composite clip</i>, which determines the final clipping
   87    * region.  The user clip cannot be modified by the rendering
   88    * system to reflect the resulting composite clip. The user clip can only
   89    * be changed through the <code>setClip</code> or <code>clipRect</code>
   90    * methods.
   91    * All drawing or writing is done in the current color,
   92    * using the current paint mode, and in the current font.
   93    *
   94    * @author      Sami Shaio
   95    * @author      Arthur van Hoff
   96    * @see     java.awt.Component
   97    * @see     java.awt.Graphics#clipRect(int, int, int, int)
   98    * @see     java.awt.Graphics#setColor(java.awt.Color)
   99    * @see     java.awt.Graphics#setPaintMode()
  100    * @see     java.awt.Graphics#setXORMode(java.awt.Color)
  101    * @see     java.awt.Graphics#setFont(java.awt.Font)
  102    * @since       JDK1.0
  103    */
  104   public abstract class Graphics {
  105   
  106       /**
  107        * Constructs a new <code>Graphics</code> object.
  108        * This constructor is the default contructor for a graphics
  109        * context.
  110        * <p>
  111        * Since <code>Graphics</code> is an abstract class, applications
  112        * cannot call this constructor directly. Graphics contexts are
  113        * obtained from other graphics contexts or are created by calling
  114        * <code>getGraphics</code> on a component.
  115        * @see        java.awt.Graphics#create()
  116        * @see        java.awt.Component#getGraphics
  117        */
  118       protected Graphics() {
  119       }
  120   
  121       /**
  122        * Creates a new <code>Graphics</code> object that is
  123        * a copy of this <code>Graphics</code> object.
  124        * @return     a new graphics context that is a copy of
  125        *                       this graphics context.
  126        */
  127       public abstract Graphics create();
  128   
  129       /**
  130        * Creates a new <code>Graphics</code> object based on this
  131        * <code>Graphics</code> object, but with a new translation and clip area.
  132        * The new <code>Graphics</code> object has its origin
  133        * translated to the specified point (<i>x</i>,&nbsp;<i>y</i>).
  134        * Its clip area is determined by the intersection of the original
  135        * clip area with the specified rectangle.  The arguments are all
  136        * interpreted in the coordinate system of the original
  137        * <code>Graphics</code> object. The new graphics context is
  138        * identical to the original, except in two respects:
  139        * <p>
  140        * <ul>
  141        * <li>
  142        * The new graphics context is translated by (<i>x</i>,&nbsp;<i>y</i>).
  143        * That is to say, the point (<code>0</code>,&nbsp;<code>0</code>) in the
  144        * new graphics context is the same as (<i>x</i>,&nbsp;<i>y</i>) in
  145        * the original graphics context.
  146        * <li>
  147        * The new graphics context has an additional clipping rectangle, in
  148        * addition to whatever (translated) clipping rectangle it inherited
  149        * from the original graphics context. The origin of the new clipping
  150        * rectangle is at (<code>0</code>,&nbsp;<code>0</code>), and its size
  151        * is specified by the <code>width</code> and <code>height</code>
  152        * arguments.
  153        * </ul>
  154        * <p>
  155        * @param      x   the <i>x</i> coordinate.
  156        * @param      y   the <i>y</i> coordinate.
  157        * @param      width   the width of the clipping rectangle.
  158        * @param      height   the height of the clipping rectangle.
  159        * @return     a new graphics context.
  160        * @see        java.awt.Graphics#translate
  161        * @see        java.awt.Graphics#clipRect
  162        */
  163       public Graphics create(int x, int y, int width, int height) {
  164           Graphics g = create();
  165           if (g == null) return null;
  166           g.translate(x, y);
  167           g.clipRect(0, 0, width, height);
  168           return g;
  169       }
  170   
  171       /**
  172        * Translates the origin of the graphics context to the point
  173        * (<i>x</i>,&nbsp;<i>y</i>) in the current coordinate system.
  174        * Modifies this graphics context so that its new origin corresponds
  175        * to the point (<i>x</i>,&nbsp;<i>y</i>) in this graphics context's
  176        * original coordinate system.  All coordinates used in subsequent
  177        * rendering operations on this graphics context will be relative
  178        * to this new origin.
  179        * @param  x   the <i>x</i> coordinate.
  180        * @param  y   the <i>y</i> coordinate.
  181        */
  182       public abstract void translate(int x, int y);
  183   
  184       /**
  185        * Gets this graphics context's current color.
  186        * @return    this graphics context's current color.
  187        * @see       java.awt.Color
  188        * @see       java.awt.Graphics#setColor(Color)
  189        */
  190       public abstract Color getColor();
  191   
  192       /**
  193        * Sets this graphics context's current color to the specified
  194        * color. All subsequent graphics operations using this graphics
  195        * context use this specified color.
  196        * @param     c   the new rendering color.
  197        * @see       java.awt.Color
  198        * @see       java.awt.Graphics#getColor
  199        */
  200       public abstract void setColor(Color c);
  201   
  202       /**
  203        * Sets the paint mode of this graphics context to overwrite the
  204        * destination with this graphics context's current color.
  205        * This sets the logical pixel operation function to the paint or
  206        * overwrite mode.  All subsequent rendering operations will
  207        * overwrite the destination with the current color.
  208        */
  209       public abstract void setPaintMode();
  210   
  211       /**
  212        * Sets the paint mode of this graphics context to alternate between
  213        * this graphics context's current color and the new specified color.
  214        * This specifies that logical pixel operations are performed in the
  215        * XOR mode, which alternates pixels between the current color and
  216        * a specified XOR color.
  217        * <p>
  218        * When drawing operations are performed, pixels which are the
  219        * current color are changed to the specified color, and vice versa.
  220        * <p>
  221        * Pixels that are of colors other than those two colors are changed
  222        * in an unpredictable but reversible manner; if the same figure is
  223        * drawn twice, then all pixels are restored to their original values.
  224        * @param     c1 the XOR alternation color
  225        */
  226       public abstract void setXORMode(Color c1);
  227   
  228       /**
  229        * Gets the current font.
  230        * @return    this graphics context's current font.
  231        * @see       java.awt.Font
  232        * @see       java.awt.Graphics#setFont(Font)
  233        */
  234       public abstract Font getFont();
  235   
  236       /**
  237        * Sets this graphics context's font to the specified font.
  238        * All subsequent text operations using this graphics context
  239        * use this font. A null argument is silently ignored.
  240        * @param  font   the font.
  241        * @see     java.awt.Graphics#getFont
  242        * @see     java.awt.Graphics#drawString(java.lang.String, int, int)
  243        * @see     java.awt.Graphics#drawBytes(byte[], int, int, int, int)
  244        * @see     java.awt.Graphics#drawChars(char[], int, int, int, int)
  245       */
  246       public abstract void setFont(Font font);
  247   
  248       /**
  249        * Gets the font metrics of the current font.
  250        * @return    the font metrics of this graphics
  251        *                    context's current font.
  252        * @see       java.awt.Graphics#getFont
  253        * @see       java.awt.FontMetrics
  254        * @see       java.awt.Graphics#getFontMetrics(Font)
  255        */
  256       public FontMetrics getFontMetrics() {
  257           return getFontMetrics(getFont());
  258       }
  259   
  260       /**
  261        * Gets the font metrics for the specified font.
  262        * @return    the font metrics for the specified font.
  263        * @param     f the specified font
  264        * @see       java.awt.Graphics#getFont
  265        * @see       java.awt.FontMetrics
  266        * @see       java.awt.Graphics#getFontMetrics()
  267        */
  268       public abstract FontMetrics getFontMetrics(Font f);
  269   
  270   
  271       /**
  272        * Returns the bounding rectangle of the current clipping area.
  273        * This method refers to the user clip, which is independent of the
  274        * clipping associated with device bounds and window visibility.
  275        * If no clip has previously been set, or if the clip has been
  276        * cleared using <code>setClip(null)</code>, this method returns
  277        * <code>null</code>.
  278        * The coordinates in the rectangle are relative to the coordinate
  279        * system origin of this graphics context.
  280        * @return      the bounding rectangle of the current clipping area,
  281        *              or <code>null</code> if no clip is set.
  282        * @see         java.awt.Graphics#getClip
  283        * @see         java.awt.Graphics#clipRect
  284        * @see         java.awt.Graphics#setClip(int, int, int, int)
  285        * @see         java.awt.Graphics#setClip(Shape)
  286        * @since       JDK1.1
  287        */
  288       public abstract Rectangle getClipBounds();
  289   
  290       /**
  291        * Intersects the current clip with the specified rectangle.
  292        * The resulting clipping area is the intersection of the current
  293        * clipping area and the specified rectangle.  If there is no
  294        * current clipping area, either because the clip has never been
  295        * set, or the clip has been cleared using <code>setClip(null)</code>,
  296        * the specified rectangle becomes the new clip.
  297        * This method sets the user clip, which is independent of the
  298        * clipping associated with device bounds and window visibility.
  299        * This method can only be used to make the current clip smaller.
  300        * To set the current clip larger, use any of the setClip methods.
  301        * Rendering operations have no effect outside of the clipping area.
  302        * @param x the x coordinate of the rectangle to intersect the clip with
  303        * @param y the y coordinate of the rectangle to intersect the clip with
  304        * @param width the width of the rectangle to intersect the clip with
  305        * @param height the height of the rectangle to intersect the clip with
  306        * @see #setClip(int, int, int, int)
  307        * @see #setClip(Shape)
  308        */
  309       public abstract void clipRect(int x, int y, int width, int height);
  310   
  311       /**
  312        * Sets the current clip to the rectangle specified by the given
  313        * coordinates.  This method sets the user clip, which is
  314        * independent of the clipping associated with device bounds
  315        * and window visibility.
  316        * Rendering operations have no effect outside of the clipping area.
  317        * @param       x the <i>x</i> coordinate of the new clip rectangle.
  318        * @param       y the <i>y</i> coordinate of the new clip rectangle.
  319        * @param       width the width of the new clip rectangle.
  320        * @param       height the height of the new clip rectangle.
  321        * @see         java.awt.Graphics#clipRect
  322        * @see         java.awt.Graphics#setClip(Shape)
  323        * @see         java.awt.Graphics#getClip
  324        * @since       JDK1.1
  325        */
  326       public abstract void setClip(int x, int y, int width, int height);
  327   
  328       /**
  329        * Gets the current clipping area.
  330        * This method returns the user clip, which is independent of the
  331        * clipping associated with device bounds and window visibility.
  332        * If no clip has previously been set, or if the clip has been
  333        * cleared using <code>setClip(null)</code>, this method returns
  334        * <code>null</code>.
  335        * @return      a <code>Shape</code> object representing the
  336        *              current clipping area, or <code>null</code> if
  337        *              no clip is set.
  338        * @see         java.awt.Graphics#getClipBounds
  339        * @see         java.awt.Graphics#clipRect
  340        * @see         java.awt.Graphics#setClip(int, int, int, int)
  341        * @see         java.awt.Graphics#setClip(Shape)
  342        * @since       JDK1.1
  343        */
  344       public abstract Shape getClip();
  345   
  346       /**
  347        * Sets the current clipping area to an arbitrary clip shape.
  348        * Not all objects that implement the <code>Shape</code>
  349        * interface can be used to set the clip.  The only
  350        * <code>Shape</code> objects that are guaranteed to be
  351        * supported are <code>Shape</code> objects that are
  352        * obtained via the <code>getClip</code> method and via
  353        * <code>Rectangle</code> objects.  This method sets the
  354        * user clip, which is independent of the clipping associated
  355        * with device bounds and window visibility.
  356        * @param clip the <code>Shape</code> to use to set the clip
  357        * @see         java.awt.Graphics#getClip()
  358        * @see         java.awt.Graphics#clipRect
  359        * @see         java.awt.Graphics#setClip(int, int, int, int)
  360        * @since       JDK1.1
  361        */
  362       public abstract void setClip(Shape clip);
  363   
  364       /**
  365        * Copies an area of the component by a distance specified by
  366        * <code>dx</code> and <code>dy</code>. From the point specified
  367        * by <code>x</code> and <code>y</code>, this method
  368        * copies downwards and to the right.  To copy an area of the
  369        * component to the left or upwards, specify a negative value for
  370        * <code>dx</code> or <code>dy</code>.
  371        * If a portion of the source rectangle lies outside the bounds
  372        * of the component, or is obscured by another window or component,
  373        * <code>copyArea</code> will be unable to copy the associated
  374        * pixels. The area that is omitted can be refreshed by calling
  375        * the component's <code>paint</code> method.
  376        * @param       x the <i>x</i> coordinate of the source rectangle.
  377        * @param       y the <i>y</i> coordinate of the source rectangle.
  378        * @param       width the width of the source rectangle.
  379        * @param       height the height of the source rectangle.
  380        * @param       dx the horizontal distance to copy the pixels.
  381        * @param       dy the vertical distance to copy the pixels.
  382        */
  383       public abstract void copyArea(int x, int y, int width, int height,
  384                                     int dx, int dy);
  385   
  386       /**
  387        * Draws a line, using the current color, between the points
  388        * <code>(x1,&nbsp;y1)</code> and <code>(x2,&nbsp;y2)</code>
  389        * in this graphics context's coordinate system.
  390        * @param   x1  the first point's <i>x</i> coordinate.
  391        * @param   y1  the first point's <i>y</i> coordinate.
  392        * @param   x2  the second point's <i>x</i> coordinate.
  393        * @param   y2  the second point's <i>y</i> coordinate.
  394        */
  395       public abstract void drawLine(int x1, int y1, int x2, int y2);
  396   
  397       /**
  398        * Fills the specified rectangle.
  399        * The left and right edges of the rectangle are at
  400        * <code>x</code> and <code>x&nbsp;+&nbsp;width&nbsp;-&nbsp;1</code>.
  401        * The top and bottom edges are at
  402        * <code>y</code> and <code>y&nbsp;+&nbsp;height&nbsp;-&nbsp;1</code>.
  403        * The resulting rectangle covers an area
  404        * <code>width</code> pixels wide by
  405        * <code>height</code> pixels tall.
  406        * The rectangle is filled using the graphics context's current color.
  407        * @param         x   the <i>x</i> coordinate
  408        *                         of the rectangle to be filled.
  409        * @param         y   the <i>y</i> coordinate
  410        *                         of the rectangle to be filled.
  411        * @param         width   the width of the rectangle to be filled.
  412        * @param         height   the height of the rectangle to be filled.
  413        * @see           java.awt.Graphics#clearRect
  414        * @see           java.awt.Graphics#drawRect
  415        */
  416       public abstract void fillRect(int x, int y, int width, int height);
  417   
  418       /**
  419        * Draws the outline of the specified rectangle.
  420        * The left and right edges of the rectangle are at
  421        * <code>x</code> and <code>x&nbsp;+&nbsp;width</code>.
  422        * The top and bottom edges are at
  423        * <code>y</code> and <code>y&nbsp;+&nbsp;height</code>.
  424        * The rectangle is drawn using the graphics context's current color.
  425        * @param         x   the <i>x</i> coordinate
  426        *                         of the rectangle to be drawn.
  427        * @param         y   the <i>y</i> coordinate
  428        *                         of the rectangle to be drawn.
  429        * @param         width   the width of the rectangle to be drawn.
  430        * @param         height   the height of the rectangle to be drawn.
  431        * @see          java.awt.Graphics#fillRect
  432        * @see          java.awt.Graphics#clearRect
  433        */
  434       public void drawRect(int x, int y, int width, int height) {
  435           if ((width < 0) || (height < 0)) {
  436               return;
  437           }
  438   
  439           if (height == 0 || width == 0) {
  440               drawLine(x, y, x + width, y + height);
  441           } else {
  442               drawLine(x, y, x + width - 1, y);
  443               drawLine(x + width, y, x + width, y + height - 1);
  444               drawLine(x + width, y + height, x + 1, y + height);
  445               drawLine(x, y + height, x, y + 1);
  446           }
  447       }
  448   
  449       /**
  450        * Clears the specified rectangle by filling it with the background
  451        * color of the current drawing surface. This operation does not
  452        * use the current paint mode.
  453        * <p>
  454        * Beginning with Java&nbsp;1.1, the background color
  455        * of offscreen images may be system dependent. Applications should
  456        * use <code>setColor</code> followed by <code>fillRect</code> to
  457        * ensure that an offscreen image is cleared to a specific color.
  458        * @param       x the <i>x</i> coordinate of the rectangle to clear.
  459        * @param       y the <i>y</i> coordinate of the rectangle to clear.
  460        * @param       width the width of the rectangle to clear.
  461        * @param       height the height of the rectangle to clear.
  462        * @see         java.awt.Graphics#fillRect(int, int, int, int)
  463        * @see         java.awt.Graphics#drawRect
  464        * @see         java.awt.Graphics#setColor(java.awt.Color)
  465        * @see         java.awt.Graphics#setPaintMode
  466        * @see         java.awt.Graphics#setXORMode(java.awt.Color)
  467        */
  468       public abstract void clearRect(int x, int y, int width, int height);
  469   
  470       /**
  471        * Draws an outlined round-cornered rectangle using this graphics
  472        * context's current color. The left and right edges of the rectangle
  473        * are at <code>x</code> and <code>x&nbsp;+&nbsp;width</code>,
  474        * respectively. The top and bottom edges of the rectangle are at
  475        * <code>y</code> and <code>y&nbsp;+&nbsp;height</code>.
  476        * @param      x the <i>x</i> coordinate of the rectangle to be drawn.
  477        * @param      y the <i>y</i> coordinate of the rectangle to be drawn.
  478        * @param      width the width of the rectangle to be drawn.
  479        * @param      height the height of the rectangle to be drawn.
  480        * @param      arcWidth the horizontal diameter of the arc
  481        *                    at the four corners.
  482        * @param      arcHeight the vertical diameter of the arc
  483        *                    at the four corners.
  484        * @see        java.awt.Graphics#fillRoundRect
  485        */
  486       public abstract void drawRoundRect(int x, int y, int width, int height,
  487                                          int arcWidth, int arcHeight);
  488   
  489       /**
  490        * Fills the specified rounded corner rectangle with the current color.
  491        * The left and right edges of the rectangle
  492        * are at <code>x</code> and <code>x&nbsp;+&nbsp;width&nbsp;-&nbsp;1</code>,
  493        * respectively. The top and bottom edges of the rectangle are at
  494        * <code>y</code> and <code>y&nbsp;+&nbsp;height&nbsp;-&nbsp;1</code>.
  495        * @param       x the <i>x</i> coordinate of the rectangle to be filled.
  496        * @param       y the <i>y</i> coordinate of the rectangle to be filled.
  497        * @param       width the width of the rectangle to be filled.
  498        * @param       height the height of the rectangle to be filled.
  499        * @param       arcWidth the horizontal diameter
  500        *                     of the arc at the four corners.
  501        * @param       arcHeight the vertical diameter
  502        *                     of the arc at the four corners.
  503        * @see         java.awt.Graphics#drawRoundRect
  504        */
  505       public abstract void fillRoundRect(int x, int y, int width, int height,
  506                                          int arcWidth, int arcHeight);
  507   
  508       /**
  509        * Draws a 3-D highlighted outline of the specified rectangle.
  510        * The edges of the rectangle are highlighted so that they
  511        * appear to be beveled and lit from the upper left corner.
  512        * <p>
  513        * The colors used for the highlighting effect are determined
  514        * based on the current color.
  515        * The resulting rectangle covers an area that is
  516        * <code>width&nbsp;+&nbsp;1</code> pixels wide
  517        * by <code>height&nbsp;+&nbsp;1</code> pixels tall.
  518        * @param       x the <i>x</i> coordinate of the rectangle to be drawn.
  519        * @param       y the <i>y</i> coordinate of the rectangle to be drawn.
  520        * @param       width the width of the rectangle to be drawn.
  521        * @param       height the height of the rectangle to be drawn.
  522        * @param       raised a boolean that determines whether the rectangle
  523        *                      appears to be raised above the surface
  524        *                      or sunk into the surface.
  525        * @see         java.awt.Graphics#fill3DRect
  526        */
  527       public void draw3DRect(int x, int y, int width, int height,
  528                              boolean raised) {
  529           Color c = getColor();
  530           Color brighter = c.brighter();
  531           Color darker = c.darker();
  532   
  533           setColor(raised ? brighter : darker);
  534           drawLine(x, y, x, y + height);
  535           drawLine(x + 1, y, x + width - 1, y);
  536           setColor(raised ? darker : brighter);
  537           drawLine(x + 1, y + height, x + width, y + height);
  538           drawLine(x + width, y, x + width, y + height - 1);
  539           setColor(c);
  540       }
  541   
  542       /**
  543        * Paints a 3-D highlighted rectangle filled with the current color.
  544        * The edges of the rectangle will be highlighted so that it appears
  545        * as if the edges were beveled and lit from the upper left corner.
  546        * The colors used for the highlighting effect will be determined from
  547        * the current color.
  548        * @param       x the <i>x</i> coordinate of the rectangle to be filled.
  549        * @param       y the <i>y</i> coordinate of the rectangle to be filled.
  550        * @param       width the width of the rectangle to be filled.
  551        * @param       height the height of the rectangle to be filled.
  552        * @param       raised a boolean value that determines whether the
  553        *                      rectangle appears to be raised above the surface
  554        *                      or etched into the surface.
  555        * @see         java.awt.Graphics#draw3DRect
  556        */
  557       public void fill3DRect(int x, int y, int width, int height,
  558                              boolean raised) {
  559           Color c = getColor();
  560           Color brighter = c.brighter();
  561           Color darker = c.darker();
  562   
  563           if (!raised) {
  564               setColor(darker);
  565           }
  566           fillRect(x+1, y+1, width-2, height-2);
  567           setColor(raised ? brighter : darker);
  568           drawLine(x, y, x, y + height - 1);
  569           drawLine(x + 1, y, x + width - 2, y);
  570           setColor(raised ? darker : brighter);
  571           drawLine(x + 1, y + height - 1, x + width - 1, y + height - 1);
  572           drawLine(x + width - 1, y, x + width - 1, y + height - 2);
  573           setColor(c);
  574       }
  575   
  576       /**
  577        * Draws the outline of an oval.
  578        * The result is a circle or ellipse that fits within the
  579        * rectangle specified by the <code>x</code>, <code>y</code>,
  580        * <code>width</code>, and <code>height</code> arguments.
  581        * <p>
  582        * The oval covers an area that is
  583        * <code>width&nbsp;+&nbsp;1</code> pixels wide
  584        * and <code>height&nbsp;+&nbsp;1</code> pixels tall.
  585        * @param       x the <i>x</i> coordinate of the upper left
  586        *                     corner of the oval to be drawn.
  587        * @param       y the <i>y</i> coordinate of the upper left
  588        *                     corner of the oval to be drawn.
  589        * @param       width the width of the oval to be drawn.
  590        * @param       height the height of the oval to be drawn.
  591        * @see         java.awt.Graphics#fillOval
  592        */
  593       public abstract void drawOval(int x, int y, int width, int height);
  594   
  595       /**
  596        * Fills an oval bounded by the specified rectangle with the
  597        * current color.
  598        * @param       x the <i>x</i> coordinate of the upper left corner
  599        *                     of the oval to be filled.
  600        * @param       y the <i>y</i> coordinate of the upper left corner
  601        *                     of the oval to be filled.
  602        * @param       width the width of the oval to be filled.
  603        * @param       height the height of the oval to be filled.
  604        * @see         java.awt.Graphics#drawOval
  605        */
  606       public abstract void fillOval(int x, int y, int width, int height);
  607   
  608       /**
  609        * Draws the outline of a circular or elliptical arc
  610        * covering the specified rectangle.
  611        * <p>
  612        * The resulting arc begins at <code>startAngle</code> and extends
  613        * for <code>arcAngle</code> degrees, using the current color.
  614        * Angles are interpreted such that 0&nbsp;degrees
  615        * is at the 3&nbsp;o'clock position.
  616        * A positive value indicates a counter-clockwise rotation
  617        * while a negative value indicates a clockwise rotation.
  618        * <p>
  619        * The center of the arc is the center of the rectangle whose origin
  620        * is (<i>x</i>,&nbsp;<i>y</i>) and whose size is specified by the
  621        * <code>width</code> and <code>height</code> arguments.
  622        * <p>
  623        * The resulting arc covers an area
  624        * <code>width&nbsp;+&nbsp;1</code> pixels wide
  625        * by <code>height&nbsp;+&nbsp;1</code> pixels tall.
  626        * <p>
  627        * The angles are specified relative to the non-square extents of
  628        * the bounding rectangle such that 45 degrees always falls on the
  629        * line from the center of the ellipse to the upper right corner of
  630        * the bounding rectangle. As a result, if the bounding rectangle is
  631        * noticeably longer in one axis than the other, the angles to the
  632        * start and end of the arc segment will be skewed farther along the
  633        * longer axis of the bounds.
  634        * @param        x the <i>x</i> coordinate of the
  635        *                    upper-left corner of the arc to be drawn.
  636        * @param        y the <i>y</i>  coordinate of the
  637        *                    upper-left corner of the arc to be drawn.
  638        * @param        width the width of the arc to be drawn.
  639        * @param        height the height of the arc to be drawn.
  640        * @param        startAngle the beginning angle.
  641        * @param        arcAngle the angular extent of the arc,
  642        *                    relative to the start angle.
  643        * @see         java.awt.Graphics#fillArc
  644        */
  645       public abstract void drawArc(int x, int y, int width, int height,
  646                                    int startAngle, int arcAngle);
  647   
  648       /**
  649        * Fills a circular or elliptical arc covering the specified rectangle.
  650        * <p>
  651        * The resulting arc begins at <code>startAngle</code> and extends
  652        * for <code>arcAngle</code> degrees.
  653        * Angles are interpreted such that 0&nbsp;degrees
  654        * is at the 3&nbsp;o'clock position.
  655        * A positive value indicates a counter-clockwise rotation
  656        * while a negative value indicates a clockwise rotation.
  657        * <p>
  658        * The center of the arc is the center of the rectangle whose origin
  659        * is (<i>x</i>,&nbsp;<i>y</i>) and whose size is specified by the
  660        * <code>width</code> and <code>height</code> arguments.
  661        * <p>
  662        * The resulting arc covers an area
  663        * <code>width&nbsp;+&nbsp;1</code> pixels wide
  664        * by <code>height&nbsp;+&nbsp;1</code> pixels tall.
  665        * <p>
  666        * The angles are specified relative to the non-square extents of
  667        * the bounding rectangle such that 45 degrees always falls on the
  668        * line from the center of the ellipse to the upper right corner of
  669        * the bounding rectangle. As a result, if the bounding rectangle is
  670        * noticeably longer in one axis than the other, the angles to the
  671        * start and end of the arc segment will be skewed farther along the
  672        * longer axis of the bounds.
  673        * @param        x the <i>x</i> coordinate of the
  674        *                    upper-left corner of the arc to be filled.
  675        * @param        y the <i>y</i>  coordinate of the
  676        *                    upper-left corner of the arc to be filled.
  677        * @param        width the width of the arc to be filled.
  678        * @param        height the height of the arc to be filled.
  679        * @param        startAngle the beginning angle.
  680        * @param        arcAngle the angular extent of the arc,
  681        *                    relative to the start angle.
  682        * @see         java.awt.Graphics#drawArc
  683        */
  684       public abstract void fillArc(int x, int y, int width, int height,
  685                                    int startAngle, int arcAngle);
  686   
  687       /**
  688        * Draws a sequence of connected lines defined by
  689        * arrays of <i>x</i> and <i>y</i> coordinates.
  690        * Each pair of (<i>x</i>,&nbsp;<i>y</i>) coordinates defines a point.
  691        * The figure is not closed if the first point
  692        * differs from the last point.
  693        * @param       xPoints an array of <i>x</i> points
  694        * @param       yPoints an array of <i>y</i> points
  695        * @param       nPoints the total number of points
  696        * @see         java.awt.Graphics#drawPolygon(int[], int[], int)
  697        * @since       JDK1.1
  698        */
  699       public abstract void drawPolyline(int xPoints[], int yPoints[],
  700                                         int nPoints);
  701   
  702       /**
  703        * Draws a closed polygon defined by
  704        * arrays of <i>x</i> and <i>y</i> coordinates.
  705        * Each pair of (<i>x</i>,&nbsp;<i>y</i>) coordinates defines a point.
  706        * <p>
  707        * This method draws the polygon defined by <code>nPoint</code> line
  708        * segments, where the first <code>nPoint&nbsp;-&nbsp;1</code>
  709        * line segments are line segments from
  710        * <code>(xPoints[i&nbsp;-&nbsp;1],&nbsp;yPoints[i&nbsp;-&nbsp;1])</code>
  711        * to <code>(xPoints[i],&nbsp;yPoints[i])</code>, for
  712        * 1&nbsp;&le;&nbsp;<i>i</i>&nbsp;&le;&nbsp;<code>nPoints</code>.
  713        * The figure is automatically closed by drawing a line connecting
  714        * the final point to the first point, if those points are different.
  715        * @param        xPoints   a an array of <code>x</code> coordinates.
  716        * @param        yPoints   a an array of <code>y</code> coordinates.
  717        * @param        nPoints   a the total number of points.
  718        * @see          java.awt.Graphics#fillPolygon
  719        * @see          java.awt.Graphics#drawPolyline
  720        */
  721       public abstract void drawPolygon(int xPoints[], int yPoints[],
  722                                        int nPoints);
  723   
  724       /**
  725        * Draws the outline of a polygon defined by the specified
  726        * <code>Polygon</code> object.
  727        * @param        p the polygon to draw.
  728        * @see          java.awt.Graphics#fillPolygon
  729        * @see          java.awt.Graphics#drawPolyline
  730        */
  731       public void drawPolygon(Polygon p) {
  732           drawPolygon(p.xpoints, p.ypoints, p.npoints);
  733       }
  734   
  735       /**
  736        * Fills a closed polygon defined by
  737        * arrays of <i>x</i> and <i>y</i> coordinates.
  738        * <p>
  739        * This method draws the polygon defined by <code>nPoint</code> line
  740        * segments, where the first <code>nPoint&nbsp;-&nbsp;1</code>
  741        * line segments are line segments from
  742        * <code>(xPoints[i&nbsp;-&nbsp;1],&nbsp;yPoints[i&nbsp;-&nbsp;1])</code>
  743        * to <code>(xPoints[i],&nbsp;yPoints[i])</code>, for
  744        * 1&nbsp;&le;&nbsp;<i>i</i>&nbsp;&le;&nbsp;<code>nPoints</code>.
  745        * The figure is automatically closed by drawing a line connecting
  746        * the final point to the first point, if those points are different.
  747        * <p>
  748        * The area inside the polygon is defined using an
  749        * even-odd fill rule, also known as the alternating rule.
  750        * @param        xPoints   a an array of <code>x</code> coordinates.
  751        * @param        yPoints   a an array of <code>y</code> coordinates.
  752        * @param        nPoints   a the total number of points.
  753        * @see          java.awt.Graphics#drawPolygon(int[], int[], int)
  754        */
  755       public abstract void fillPolygon(int xPoints[], int yPoints[],
  756                                        int nPoints);
  757   
  758       /**
  759        * Fills the polygon defined by the specified Polygon object with
  760        * the graphics context's current color.
  761        * <p>
  762        * The area inside the polygon is defined using an
  763        * even-odd fill rule, also known as the alternating rule.
  764        * @param        p the polygon to fill.
  765        * @see          java.awt.Graphics#drawPolygon(int[], int[], int)
  766        */
  767       public void fillPolygon(Polygon p) {
  768           fillPolygon(p.xpoints, p.ypoints, p.npoints);
  769       }
  770   
  771       /**
  772        * Draws the text given by the specified string, using this
  773        * graphics context's current font and color. The baseline of the
  774        * leftmost character is at position (<i>x</i>,&nbsp;<i>y</i>) in this
  775        * graphics context's coordinate system.
  776        * @param       str      the string to be drawn.
  777        * @param       x        the <i>x</i> coordinate.
  778        * @param       y        the <i>y</i> coordinate.
  779        * @throws NullPointerException if <code>str</code> is <code>null</code>.
  780        * @see         java.awt.Graphics#drawBytes
  781        * @see         java.awt.Graphics#drawChars
  782        */
  783       public abstract void drawString(String str, int x, int y);
  784   
  785       /**
  786        * Renders the text of the specified iterator applying its attributes
  787        * in accordance with the specification of the
  788        * {@link java.awt.font.TextAttribute TextAttribute} class.
  789        * <p>
  790        * The baseline of the leftmost character is at position
  791        * (<i>x</i>,&nbsp;<i>y</i>) in this graphics context's coordinate system.
  792        * @param       iterator the iterator whose text is to be drawn
  793        * @param       x        the <i>x</i> coordinate.
  794        * @param       y        the <i>y</i> coordinate.
  795        * @throws NullPointerException if <code>iterator</code> is
  796        * <code>null</code>.
  797        * @see         java.awt.Graphics#drawBytes
  798        * @see         java.awt.Graphics#drawChars
  799        */
  800      public abstract void drawString(AttributedCharacterIterator iterator,
  801                                       int x, int y);
  802   
  803       /**
  804        * Draws the text given by the specified character array, using this
  805        * graphics context's current font and color. The baseline of the
  806        * first character is at position (<i>x</i>,&nbsp;<i>y</i>) in this
  807        * graphics context's coordinate system.
  808        * @param data the array of characters to be drawn
  809        * @param offset the start offset in the data
  810        * @param length the number of characters to be drawn
  811        * @param x the <i>x</i> coordinate of the baseline of the text
  812        * @param y the <i>y</i> coordinate of the baseline of the text
  813        * @throws NullPointerException if <code>data</code> is <code>null</code>.
  814        * @throws IndexOutOfBoundsException if <code>offset</code> or
  815        * <code>length</code>is less than zero, or
  816        * <code>offset+length</code> is greater than the length of the
  817        * <code>data</code> array.
  818        * @see         java.awt.Graphics#drawBytes
  819        * @see         java.awt.Graphics#drawString
  820        */
  821       public void drawChars(char data[], int offset, int length, int x, int y) {
  822           drawString(new String(data, offset, length), x, y);
  823       }
  824   
  825       /**
  826        * Draws the text given by the specified byte array, using this
  827        * graphics context's current font and color. The baseline of the
  828        * first character is at position (<i>x</i>,&nbsp;<i>y</i>) in this
  829        * graphics context's coordinate system.
  830        * <p>
  831        * Use of this method is not recommended as each byte is interpreted
  832        * as a Unicode code point in the range 0 to 255, and so can only be
  833        * used to draw Latin characters in that range.
  834        * @param data the data to be drawn
  835        * @param offset the start offset in the data
  836        * @param length the number of bytes that are drawn
  837        * @param x the <i>x</i> coordinate of the baseline of the text
  838        * @param y the <i>y</i> coordinate of the baseline of the text
  839        * @throws NullPointerException if <code>data</code> is <code>null</code>.
  840        * @throws IndexOutOfBoundsException if <code>offset</code> or
  841        * <code>length</code>is less than zero, or <code>offset+length</code>
  842        * is greater than the length of the <code>data</code> array.
  843        * @see         java.awt.Graphics#drawChars
  844        * @see         java.awt.Graphics#drawString
  845        */
  846       public void drawBytes(byte data[], int offset, int length, int x, int y) {
  847           drawString(new String(data, 0, offset, length), x, y);
  848       }
  849   
  850       /**
  851        * Draws as much of the specified image as is currently available.
  852        * The image is drawn with its top-left corner at
  853        * (<i>x</i>,&nbsp;<i>y</i>) in this graphics context's coordinate
  854        * space. Transparent pixels in the image do not affect whatever
  855        * pixels are already there.
  856        * <p>
  857        * This method returns immediately in all cases, even if the
  858        * complete image has not yet been loaded, and it has not been dithered
  859        * and converted for the current output device.
  860        * <p>
  861        * If the image has completely loaded and its pixels are
  862        * no longer being changed, then
  863        * <code>drawImage</code> returns <code>true</code>.
  864        * Otherwise, <code>drawImage</code> returns <code>false</code>
  865        * and as more of
  866        * the image becomes available
  867        * or it is time to draw another frame of animation,
  868        * the process that loads the image notifies
  869        * the specified image observer.
  870        * @param    img the specified image to be drawn. This method does
  871        *               nothing if <code>img</code> is null.
  872        * @param    x   the <i>x</i> coordinate.
  873        * @param    y   the <i>y</i> coordinate.
  874        * @param    observer    object to be notified as more of
  875        *                          the image is converted.
  876        * @return   <code>false</code> if the image pixels are still changing;
  877        *           <code>true</code> otherwise.
  878        * @see      java.awt.Image
  879        * @see      java.awt.image.ImageObserver
  880        * @see      java.awt.image.ImageObserver#imageUpdate(java.awt.Image, int, int, int, int, int)
  881        */
  882       public abstract boolean drawImage(Image img, int x, int y,
  883                                         ImageObserver observer);
  884   
  885       /**
  886        * Draws as much of the specified image as has already been scaled
  887        * to fit inside the specified rectangle.
  888        * <p>
  889        * The image is drawn inside the specified rectangle of this
  890        * graphics context's coordinate space, and is scaled if
  891        * necessary. Transparent pixels do not affect whatever pixels
  892        * are already there.
  893        * <p>
  894        * This method returns immediately in all cases, even if the
  895        * entire image has not yet been scaled, dithered, and converted
  896        * for the current output device.
  897        * If the current output representation is not yet complete, then
  898        * <code>drawImage</code> returns <code>false</code>. As more of
  899        * the image becomes available, the process that loads the image notifies
  900        * the image observer by calling its <code>imageUpdate</code> method.
  901        * <p>
  902        * A scaled version of an image will not necessarily be
  903        * available immediately just because an unscaled version of the
  904        * image has been constructed for this output device.  Each size of
  905        * the image may be cached separately and generated from the original
  906        * data in a separate image production sequence.
  907        * @param    img    the specified image to be drawn. This method does
  908        *                  nothing if <code>img</code> is null.
  909        * @param    x      the <i>x</i> coordinate.
  910        * @param    y      the <i>y</i> coordinate.
  911        * @param    width  the width of the rectangle.
  912        * @param    height the height of the rectangle.
  913        * @param    observer    object to be notified as more of
  914        *                          the image is converted.
  915        * @return   <code>false</code> if the image pixels are still changing;
  916        *           <code>true</code> otherwise.
  917        * @see      java.awt.Image
  918        * @see      java.awt.image.ImageObserver
  919        * @see      java.awt.image.ImageObserver#imageUpdate(java.awt.Image, int, int, int, int, int)
  920        */
  921       public abstract boolean drawImage(Image img, int x, int y,
  922                                         int width, int height,
  923                                         ImageObserver observer);
  924   
  925       /**
  926        * Draws as much of the specified image as is currently available.
  927        * The image is drawn with its top-left corner at
  928        * (<i>x</i>,&nbsp;<i>y</i>) in this graphics context's coordinate
  929        * space.  Transparent pixels are drawn in the specified
  930        * background color.
  931        * <p>
  932        * This operation is equivalent to filling a rectangle of the
  933        * width and height of the specified image with the given color and then
  934        * drawing the image on top of it, but possibly more efficient.
  935        * <p>
  936        * This method returns immediately in all cases, even if the
  937        * complete image has not yet been loaded, and it has not been dithered
  938        * and converted for the current output device.
  939        * <p>
  940        * If the image has completely loaded and its pixels are
  941        * no longer being changed, then
  942        * <code>drawImage</code> returns <code>true</code>.
  943        * Otherwise, <code>drawImage</code> returns <code>false</code>
  944        * and as more of
  945        * the image becomes available
  946        * or it is time to draw another frame of animation,
  947        * the process that loads the image notifies
  948        * the specified image observer.
  949        * @param    img the specified image to be drawn. This method does
  950        *               nothing if <code>img</code> is null.
  951        * @param    x      the <i>x</i> coordinate.
  952        * @param    y      the <i>y</i> coordinate.
  953        * @param    bgcolor the background color to paint under the
  954        *                         non-opaque portions of the image.
  955        * @param    observer    object to be notified as more of
  956        *                          the image is converted.
  957        * @return   <code>false</code> if the image pixels are still changing;
  958        *           <code>true</code> otherwise.
  959        * @see      java.awt.Image
  960        * @see      java.awt.image.ImageObserver
  961        * @see      java.awt.image.ImageObserver#imageUpdate(java.awt.Image, int, int, int, int, int)
  962        */
  963       public abstract boolean drawImage(Image img, int x, int y,
  964                                         Color bgcolor,
  965                                         ImageObserver observer);
  966   
  967       /**
  968        * Draws as much of the specified image as has already been scaled
  969        * to fit inside the specified rectangle.
  970        * <p>
  971        * The image is drawn inside the specified rectangle of this
  972        * graphics context's coordinate space, and is scaled if
  973        * necessary. Transparent pixels are drawn in the specified
  974        * background color.
  975        * This operation is equivalent to filling a rectangle of the
  976        * width and height of the specified image with the given color and then
  977        * drawing the image on top of it, but possibly more efficient.
  978        * <p>
  979        * This method returns immediately in all cases, even if the
  980        * entire image has not yet been scaled, dithered, and converted
  981        * for the current output device.
  982        * If the current output representation is not yet complete then
  983        * <code>drawImage</code> returns <code>false</code>. As more of
  984        * the image becomes available, the process that loads the image notifies
  985        * the specified image observer.
  986        * <p>
  987        * A scaled version of an image will not necessarily be
  988        * available immediately just because an unscaled version of the
  989        * image has been constructed for this output device.  Each size of
  990        * the image may be cached separately and generated from the original
  991        * data in a separate image production sequence.
  992        * @param    img       the specified image to be drawn. This method does
  993        *                     nothing if <code>img</code> is null.
  994        * @param    x         the <i>x</i> coordinate.
  995        * @param    y         the <i>y</i> coordinate.
  996        * @param    width     the width of the rectangle.
  997        * @param    height    the height of the rectangle.
  998        * @param    bgcolor   the background color to paint under the
  999        *                         non-opaque portions of the image.
 1000        * @param    observer    object to be notified as more of
 1001        *                          the image is converted.
 1002        * @return   <code>false</code> if the image pixels are still changing;
 1003        *           <code>true</code> otherwise.
 1004        * @see      java.awt.Image
 1005        * @see      java.awt.image.ImageObserver
 1006        * @see      java.awt.image.ImageObserver#imageUpdate(java.awt.Image, int, int, int, int, int)
 1007        */
 1008       public abstract boolean drawImage(Image img, int x, int y,
 1009                                         int width, int height,
 1010                                         Color bgcolor,
 1011                                         ImageObserver observer);
 1012   
 1013       /**
 1014        * Draws as much of the specified area of the specified image as is
 1015        * currently available, scaling it on the fly to fit inside the
 1016        * specified area of the destination drawable surface. Transparent pixels
 1017        * do not affect whatever pixels are already there.
 1018        * <p>
 1019        * This method returns immediately in all cases, even if the
 1020        * image area to be drawn has not yet been scaled, dithered, and converted
 1021        * for the current output device.
 1022        * If the current output representation is not yet complete then
 1023        * <code>drawImage</code> returns <code>false</code>. As more of
 1024        * the image becomes available, the process that loads the image notifies
 1025        * the specified image observer.
 1026        * <p>
 1027        * This method always uses the unscaled version of the image
 1028        * to render the scaled rectangle and performs the required
 1029        * scaling on the fly. It does not use a cached, scaled version
 1030        * of the image for this operation. Scaling of the image from source
 1031        * to destination is performed such that the first coordinate
 1032        * of the source rectangle is mapped to the first coordinate of
 1033        * the destination rectangle, and the second source coordinate is
 1034        * mapped to the second destination coordinate. The subimage is
 1035        * scaled and flipped as needed to preserve those mappings.
 1036        * @param       img the specified image to be drawn. This method does
 1037        *                  nothing if <code>img</code> is null.
 1038        * @param       dx1 the <i>x</i> coordinate of the first corner of the
 1039        *                    destination rectangle.
 1040        * @param       dy1 the <i>y</i> coordinate of the first corner of the
 1041        *                    destination rectangle.
 1042        * @param       dx2 the <i>x</i> coordinate of the second corner of the
 1043        *                    destination rectangle.
 1044        * @param       dy2 the <i>y</i> coordinate of the second corner of the
 1045        *                    destination rectangle.
 1046        * @param       sx1 the <i>x</i> coordinate of the first corner of the
 1047        *                    source rectangle.
 1048        * @param       sy1 the <i>y</i> coordinate of the first corner of the
 1049        *                    source rectangle.
 1050        * @param       sx2 the <i>x</i> coordinate of the second corner of the
 1051        *                    source rectangle.
 1052        * @param       sy2 the <i>y</i> coordinate of the second corner of the
 1053        *                    source rectangle.
 1054        * @param       observer object to be notified as more of the image is
 1055        *                    scaled and converted.
 1056        * @return   <code>false</code> if the image pixels are still changing;
 1057        *           <code>true</code> otherwise.
 1058        * @see         java.awt.Image
 1059        * @see         java.awt.image.ImageObserver
 1060        * @see         java.awt.image.ImageObserver#imageUpdate(java.awt.Image, int, int, int, int, int)
 1061        * @since       JDK1.1
 1062        */
 1063       public abstract boolean drawImage(Image img,
 1064                                         int dx1, int dy1, int dx2, int dy2,
 1065                                         int sx1, int sy1, int sx2, int sy2,
 1066                                         ImageObserver observer);
 1067   
 1068       /**
 1069        * Draws as much of the specified area of the specified image as is
 1070        * currently available, scaling it on the fly to fit inside the
 1071        * specified area of the destination drawable surface.
 1072        * <p>
 1073        * Transparent pixels are drawn in the specified background color.
 1074        * This operation is equivalent to filling a rectangle of the
 1075        * width and height of the specified image with the given color and then
 1076        * drawing the image on top of it, but possibly more efficient.
 1077        * <p>
 1078        * This method returns immediately in all cases, even if the
 1079        * image area to be drawn has not yet been scaled, dithered, and converted
 1080        * for the current output device.
 1081        * If the current output representation is not yet complete then
 1082        * <code>drawImage</code> returns <code>false</code>. As more of
 1083        * the image becomes available, the process that loads the image notifies
 1084        * the specified image observer.
 1085        * <p>
 1086        * This method always uses the unscaled version of the image
 1087        * to render the scaled rectangle and performs the required
 1088        * scaling on the fly. It does not use a cached, scaled version
 1089        * of the image for this operation. Scaling of the image from source
 1090        * to destination is performed such that the first coordinate
 1091        * of the source rectangle is mapped to the first coordinate of
 1092        * the destination rectangle, and the second source coordinate is
 1093        * mapped to the second destination coordinate. The subimage is
 1094        * scaled and flipped as needed to preserve those mappings.
 1095        * @param       img the specified image to be drawn. This method does
 1096        *                  nothing if <code>img</code> is null.
 1097        * @param       dx1 the <i>x</i> coordinate of the first corner of the
 1098        *                    destination rectangle.
 1099        * @param       dy1 the <i>y</i> coordinate of the first corner of the
 1100        *                    destination rectangle.
 1101        * @param       dx2 the <i>x</i> coordinate of the second corner of the
 1102        *                    destination rectangle.
 1103        * @param       dy2 the <i>y</i> coordinate of the second corner of the
 1104        *                    destination rectangle.
 1105        * @param       sx1 the <i>x</i> coordinate of the first corner of the
 1106        *                    source rectangle.
 1107        * @param       sy1 the <i>y</i> coordinate of the first corner of the
 1108        *                    source rectangle.
 1109        * @param       sx2 the <i>x</i> coordinate of the second corner of the
 1110        *                    source rectangle.
 1111        * @param       sy2 the <i>y</i> coordinate of the second corner of the
 1112        *                    source rectangle.
 1113        * @param       bgcolor the background color to paint under the
 1114        *                    non-opaque portions of the image.
 1115        * @param       observer object to be notified as more of the image is
 1116        *                    scaled and converted.
 1117        * @return   <code>false</code> if the image pixels are still changing;
 1118        *           <code>true</code> otherwise.
 1119        * @see         java.awt.Image
 1120        * @see         java.awt.image.ImageObserver
 1121        * @see         java.awt.image.ImageObserver#imageUpdate(java.awt.Image, int, int, int, int, int)
 1122        * @since       JDK1.1
 1123        */
 1124       public abstract boolean drawImage(Image img,
 1125                                         int dx1, int dy1, int dx2, int dy2,
 1126                                         int sx1, int sy1, int sx2, int sy2,
 1127                                         Color bgcolor,
 1128                                         ImageObserver observer);
 1129   
 1130       /**
 1131        * Disposes of this graphics context and releases
 1132        * any system resources that it is using.
 1133        * A <code>Graphics</code> object cannot be used after
 1134        * <code>dispose</code>has been called.
 1135        * <p>
 1136        * When a Java program runs, a large number of <code>Graphics</code>
 1137        * objects can be created within a short time frame.
 1138        * Although the finalization process of the garbage collector
 1139        * also disposes of the same system resources, it is preferable
 1140        * to manually free the associated resources by calling this
 1141        * method rather than to rely on a finalization process which
 1142        * may not run to completion for a long period of time.
 1143        * <p>
 1144        * Graphics objects which are provided as arguments to the
 1145        * <code>paint</code> and <code>update</code> methods
 1146        * of components are automatically released by the system when
 1147        * those methods return. For efficiency, programmers should
 1148        * call <code>dispose</code> when finished using
 1149        * a <code>Graphics</code> object only if it was created
 1150        * directly from a component or another <code>Graphics</code> object.
 1151        * @see         java.awt.Graphics#finalize
 1152        * @see         java.awt.Component#paint
 1153        * @see         java.awt.Component#update
 1154        * @see         java.awt.Component#getGraphics
 1155        * @see         java.awt.Graphics#create
 1156        */
 1157       public abstract void dispose();
 1158   
 1159       /**
 1160        * Disposes of this graphics context once it is no longer referenced.
 1161        * @see #dispose
 1162        */
 1163       public void finalize() {
 1164           dispose();
 1165       }
 1166   
 1167       /**
 1168        * Returns a <code>String</code> object representing this
 1169        *                        <code>Graphics</code> object's value.
 1170        * @return       a string representation of this graphics context.
 1171        */
 1172       public String toString() {
 1173           return getClass().getName() + "[font=" + getFont() + ",color=" + getColor() + "]";
 1174       }
 1175   
 1176       /**
 1177        * Returns the bounding rectangle of the current clipping area.
 1178        * @return      the bounding rectangle of the current clipping area
 1179        *              or <code>null</code> if no clip is set.
 1180        * @deprecated As of JDK version 1.1,
 1181        * replaced by <code>getClipBounds()</code>.
 1182        */
 1183       @Deprecated
 1184       public Rectangle getClipRect() {
 1185           return getClipBounds();
 1186       }
 1187   
 1188       /**
 1189        * Returns true if the specified rectangular area might intersect
 1190        * the current clipping area.
 1191        * The coordinates of the specified rectangular area are in the
 1192        * user coordinate space and are relative to the coordinate
 1193        * system origin of this graphics context.
 1194        * This method may use an algorithm that calculates a result quickly
 1195        * but which sometimes might return true even if the specified
 1196        * rectangular area does not intersect the clipping area.
 1197        * The specific algorithm employed may thus trade off accuracy for
 1198        * speed, but it will never return false unless it can guarantee
 1199        * that the specified rectangular area does not intersect the
 1200        * current clipping area.
 1201        * The clipping area used by this method can represent the
 1202        * intersection of the user clip as specified through the clip
 1203        * methods of this graphics context as well as the clipping
 1204        * associated with the device or image bounds and window visibility.
 1205        *
 1206        * @param x the x coordinate of the rectangle to test against the clip
 1207        * @param y the y coordinate of the rectangle to test against the clip
 1208        * @param width the width of the rectangle to test against the clip
 1209        * @param height the height of the rectangle to test against the clip
 1210        * @return <code>true</code> if the specified rectangle intersects
 1211        *         the bounds of the current clip; <code>false</code>
 1212        *         otherwise.
 1213        */
 1214       public boolean hitClip(int x, int y, int width, int height) {
 1215           // Note, this implementation is not very efficient.
 1216           // Subclasses should override this method and calculate
 1217           // the results more directly.
 1218           Rectangle clipRect = getClipBounds();
 1219           if (clipRect == null) {
 1220               return true;
 1221           }
 1222           return clipRect.intersects(x, y, width, height);
 1223       }
 1224   
 1225       /**
 1226        * Returns the bounding rectangle of the current clipping area.
 1227        * The coordinates in the rectangle are relative to the coordinate
 1228        * system origin of this graphics context.  This method differs
 1229        * from {@link #getClipBounds() getClipBounds} in that an existing
 1230        * rectangle is used instead of allocating a new one.
 1231        * This method refers to the user clip, which is independent of the
 1232        * clipping associated with device bounds and window visibility.
 1233        *  If no clip has previously been set, or if the clip has been
 1234        * cleared using <code>setClip(null)</code>, this method returns the
 1235        * specified <code>Rectangle</code>.
 1236        * @param  r    the rectangle where the current clipping area is
 1237        *              copied to.  Any current values in this rectangle are
 1238        *              overwritten.
 1239        * @return      the bounding rectangle of the current clipping area.
 1240        */
 1241       public Rectangle getClipBounds(Rectangle r) {
 1242           // Note, this implementation is not very efficient.
 1243           // Subclasses should override this method and avoid
 1244           // the allocation overhead of getClipBounds().
 1245           Rectangle clipRect = getClipBounds();
 1246           if (clipRect != null) {
 1247               r.x = clipRect.x;
 1248               r.y = clipRect.y;
 1249               r.width = clipRect.width;
 1250               r.height = clipRect.height;
 1251           } else if (r == null) {
 1252               throw new NullPointerException("null rectangle parameter");
 1253           }
 1254           return r;
 1255       }
 1256   }

Home » openjdk-7 » java » awt » [javadoc | source]