/*

 * Copyright (c) 1995, 2014, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package java.awt;

import java.io.*;

import java.lang.*;

import java.util.*;

import java.awt.image.ImageObserver;

import java.text.AttributedCharacterIterator;

/**

 * The <code>Graphics</code> class is the abstract base class for

 * all graphics contexts that allow an application to draw onto

 * components that are realized on various devices, as well as

 * onto off-screen images.

 * <p>

 * A <code>Graphics</code> object encapsulates state information needed

 * for the basic rendering operations that Java supports.  This

 * state information includes the following properties:

 *

 * <ul>

 * <li>The <code>Component</code> object on which to draw.

 * <li>A translation origin for rendering and clipping coordinates.

 * <li>The current clip.

 * <li>The current color.

 * <li>The current font.

 * <li>The current logical pixel operation function (XOR or Paint).

 * <li>The current XOR alternation color

 *     (see {@link Graphics#setXORMode}).

 * </ul>

 * <p>

 * Coordinates are infinitely thin and lie between the pixels of the

 * output device.

 * Operations that draw the outline of a figure operate by traversing

 * an infinitely thin path between pixels with a pixel-sized pen that hangs

 * down and to the right of the anchor point on the path.

 * Operations that fill a figure operate by filling the interior

 * of that infinitely thin path.

 * Operations that render horizontal text render the ascending

 * portion of character glyphs entirely above the baseline coordinate.

 * <p>

 * The graphics pen hangs down and to the right from the path it traverses.

 * This has the following implications:

 * <ul>

 * <li>If you draw a figure that covers a given rectangle, that

 * figure occupies one extra row of pixels on the right and bottom edges

 * as compared to filling a figure that is bounded by that same rectangle.

 * <li>If you draw a horizontal line along the same <i>y</i> coordinate as

 * the baseline of a line of text, that line is drawn entirely below

 * the text, except for any descenders.

 * </ul><p>

 * All coordinates that appear as arguments to the methods of this

 * <code>Graphics</code> object are considered relative to the

 * translation origin of this <code>Graphics</code> object prior to

 * the invocation of the method.

 * <p>

 * All rendering operations modify only pixels which lie within the

 * area bounded by the current clip, which is specified by a {@link Shape}

 * in user space and is controlled by the program using the

 * <code>Graphics</code> object.  This <i>user clip</i>

 * is transformed into device space and combined with the

 * <i>device clip</i>, which is defined by the visibility of windows and

 * device extents.  The combination of the user clip and device clip

 * defines the <i>composite clip</i>, which determines the final clipping

 * region.  The user clip cannot be modified by the rendering

 * system to reflect the resulting composite clip. The user clip can only

 * be changed through the <code>setClip</code> or <code>clipRect</code>

 * methods.

 * All drawing or writing is done in the current color,

 * using the current paint mode, and in the current font.

 *

 * @author      Sami Shaio

 * @author      Arthur van Hoff

 * @see     java.awt.Component

 * @see     java.awt.Graphics#clipRect(int, int, int, int)

 * @see     java.awt.Graphics#setColor(java.awt.Color)

 * @see     java.awt.Graphics#setPaintMode()

 * @see     java.awt.Graphics#setXORMode(java.awt.Color)

 * @see     java.awt.Graphics#setFont(java.awt.Font)

 * @since       1.0

 */

public abstract class Graphics {

    /**

     * Constructs a new <code>Graphics</code> object.

     * This constructor is the default constructor for a graphics

     * context.

     * <p>

     * Since <code>Graphics</code> is an abstract class, applications

     * cannot call this constructor directly. Graphics contexts are

     * obtained from other graphics contexts or are created by calling

     * <code>getGraphics</code> on a component.

     * @see        java.awt.Graphics#create()

     * @see        java.awt.Component#getGraphics

     */

    protected Graphics() {

    }

    /**

     * Creates a new <code>Graphics</code> object that is

     * a copy of this <code>Graphics</code> object.

     * @return     a new graphics context that is a copy of

     *                       this graphics context.

     */

    public abstract Graphics create();

    /**

     * Creates a new <code>Graphics</code> object based on this

     * <code>Graphics</code> object, but with a new translation and clip area.

     * The new <code>Graphics</code> object has its origin

     * translated to the specified point (<i>x</i>,&nbsp;<i>y</i>).

     * Its clip area is determined by the intersection of the original

     * clip area with the specified rectangle.  The arguments are all

     * interpreted in the coordinate system of the original

     * <code>Graphics</code> object. The new graphics context is

     * identical to the original, except in two respects:

     *

     * <ul>

     * <li>

     * The new graphics context is translated by (<i>x</i>,&nbsp;<i>y</i>).

     * That is to say, the point (<code>0</code>,&nbsp;<code>0</code>) in the

     * new graphics context is the same as (<i>x</i>,&nbsp;<i>y</i>) in

     * the original graphics context.

     * <li>

     * The new graphics context has an additional clipping rectangle, in

     * addition to whatever (translated) clipping rectangle it inherited

     * from the original graphics context. The origin of the new clipping

     * rectangle is at (<code>0</code>,&nbsp;<code>0</code>), and its size

     * is specified by the <code>width</code> and <code>height</code>

     * arguments.

     * </ul>

     *

     * @param      x   the <i>x</i> coordinate.

     * @param      y   the <i>y</i> coordinate.

     * @param      width   the width of the clipping rectangle.

     * @param      height   the height of the clipping rectangle.

     * @return     a new graphics context.

     * @see        java.awt.Graphics#translate

     * @see        java.awt.Graphics#clipRect

     */

    public Graphics create(int x, int y, int width, int height) {

        Graphics g = create();

        if (g == null) return null;

        g.translate(x, y);

        g.clipRect(0, 0, width, height);

        return g;

    }

    /**

     * Translates the origin of the graphics context to the point

     * (<i>x</i>,&nbsp;<i>y</i>) in the current coordinate system.

     * Modifies this graphics context so that its new origin corresponds

     * to the point (<i>x</i>,&nbsp;<i>y</i>) in this graphics context's

     * original coordinate system.  All coordinates used in subsequent

     * rendering operations on this graphics context will be relative

     * to this new origin.

     * @param  x   the <i>x</i> coordinate.

     * @param  y   the <i>y</i> coordinate.

     */

    public abstract void translate(int x, int y);

    /**

     * Gets this graphics context's current color.

     * @return    this graphics context's current color.

     * @see       java.awt.Color

     * @see       java.awt.Graphics#setColor(Color)

     */

    public abstract Color getColor();

    /**

     * Sets this graphics context's current color to the specified

     * color. All subsequent graphics operations using this graphics

     * context use this specified color.

     * @param     c   the new rendering color.

     * @see       java.awt.Color

     * @see       java.awt.Graphics#getColor

     */

    public abstract void setColor(Color c);

    /**

     * Sets the paint mode of this graphics context to overwrite the

     * destination with this graphics context's current color.

     * This sets the logical pixel operation function to the paint or

     * overwrite mode.  All subsequent rendering operations will

     * overwrite the destination with the current color.

     */

    public abstract void setPaintMode();

    /**

     * Sets the paint mode of this graphics context to alternate between

     * this graphics context's current color and the new specified color.

     * This specifies that logical pixel operations are performed in the

     * XOR mode, which alternates pixels between the current color and

     * a specified XOR color.

     * <p>

     * When drawing operations are performed, pixels which are the

     * current color are changed to the specified color, and vice versa.

     * <p>

     * Pixels that are of colors other than those two colors are changed

     * in an unpredictable but reversible manner; if the same figure is

     * drawn twice, then all pixels are restored to their original values.

     * @param     c1 the XOR alternation color

     */

    public abstract void setXORMode(Color c1);

    /**

     * Gets the current font.

     * @return    this graphics context's current font.

     * @see       java.awt.Font

     * @see       java.awt.Graphics#setFont(Font)

     */

    public abstract Font getFont();

    /**

     * Sets this graphics context's font to the specified font.

     * All subsequent text operations using this graphics context

     * use this font. A null argument is silently ignored.

     * @param  font   the font.

     * @see     java.awt.Graphics#getFont

     * @see     java.awt.Graphics#drawString(java.lang.String, int, int)

     * @see     java.awt.Graphics#drawBytes(byte[], int, int, int, int)

     * @see     java.awt.Graphics#drawChars(char[], int, int, int, int)

    */

    public abstract void setFont(Font font);

    /**

     * Gets the font metrics of the current font.

     * @return    the font metrics of this graphics

     *                    context's current font.

     * @see       java.awt.Graphics#getFont

     * @see       java.awt.FontMetrics

     * @see       java.awt.Graphics#getFontMetrics(Font)

     */

    public FontMetrics getFontMetrics() {

        return getFontMetrics(getFont());

    }

    /**

     * Gets the font metrics for the specified font.

     * @return    the font metrics for the specified font.

     * @param     f the specified font

     * @see       java.awt.Graphics#getFont

     * @see       java.awt.FontMetrics

     * @see       java.awt.Graphics#getFontMetrics()

     */

    public abstract FontMetrics getFontMetrics(Font f);

    /**

     * Returns the bounding rectangle of the current clipping area.

     * This method refers to the user clip, which is independent of the

     * clipping associated with device bounds and window visibility.

     * If no clip has previously been set, or if the clip has been

     * cleared using <code>setClip(null)</code>, this method returns

     * <code>null</code>.

     * The coordinates in the rectangle are relative to the coordinate

     * system origin of this graphics context.

     * @return      the bounding rectangle of the current clipping area,

     *              or <code>null</code> if no clip is set.

     * @see         java.awt.Graphics#getClip

     * @see         java.awt.Graphics#clipRect

     * @see         java.awt.Graphics#setClip(int, int, int, int)

     * @see         java.awt.Graphics#setClip(Shape)

     * @since       1.1

     */

    public abstract Rectangle getClipBounds();

    /**

     * Intersects the current clip with the specified rectangle.

     * The resulting clipping area is the intersection of the current

     * clipping area and the specified rectangle.  If there is no

     * current clipping area, either because the clip has never been

     * set, or the clip has been cleared using <code>setClip(null)</code>,

     * the specified rectangle becomes the new clip.

     * This method sets the user clip, which is independent of the

     * clipping associated with device bounds and window visibility.

     * This method can only be used to make the current clip smaller.

     * To set the current clip larger, use any of the setClip methods.

     * Rendering operations have no effect outside of the clipping area.

     * @param x the x coordinate of the rectangle to intersect the clip with

     * @param y the y coordinate of the rectangle to intersect the clip with

     * @param width the width of the rectangle to intersect the clip with

     * @param height the height of the rectangle to intersect the clip with

     * @see #setClip(int, int, int, int)

     * @see #setClip(Shape)

     */

    public abstract void clipRect(int x, int y, int width, int height);

    /**

     * Sets the current clip to the rectangle specified by the given

     * coordinates.  This method sets the user clip, which is

     * independent of the clipping associated with device bounds

     * and window visibility.

     * Rendering operations have no effect outside of the clipping area.

     * @param       x the <i>x</i> coordinate of the new clip rectangle.

     * @param       y the <i>y</i> coordinate of the new clip rectangle.

     * @param       width the width of the new clip rectangle.

     * @param       height the height of the new clip rectangle.

     * @see         java.awt.Graphics#clipRect

     * @see         java.awt.Graphics#setClip(Shape)

     * @see         java.awt.Graphics#getClip

     * @since       1.1

     */

    public abstract void setClip(int x, int y, int width, int height);

    /**

     * Gets the current clipping area.

     * This method returns the user clip, which is independent of the

     * clipping associated with device bounds and window visibility.

     * If no clip has previously been set, or if the clip has been

     * cleared using <code>setClip(null)</code>, this method returns

     * <code>null</code>.

     * @return      a <code>Shape</code> object representing the

     *              current clipping area, or <code>null</code> if

     *              no clip is set.

     * @see         java.awt.Graphics#getClipBounds

     * @see         java.awt.Graphics#clipRect

     * @see         java.awt.Graphics#setClip(int, int, int, int)

     * @see         java.awt.Graphics#setClip(Shape)

     * @since       1.1

     */

    public abstract Shape getClip();

    /**

     * Sets the current clipping area to an arbitrary clip shape.

     * Not all objects that implement the <code>Shape</code>

     * interface can be used to set the clip.  The only

     * <code>Shape</code> objects that are guaranteed to be

     * supported are <code>Shape</code> objects that are

     * obtained via the <code>getClip</code> method and via

     * <code>Rectangle</code> objects.  This method sets the

     * user clip, which is independent of the clipping associated

     * with device bounds and window visibility.

     * @param clip the <code>Shape</code> to use to set the clip

     * @see         java.awt.Graphics#getClip()

     * @see         java.awt.Graphics#clipRect

     * @see         java.awt.Graphics#setClip(int, int, int, int)

     * @since       1.1

     */

    public abstract void setClip(Shape clip);

    /**

     * Copies an area of the component by a distance specified by

     * <code>dx</code> and <code>dy</code>. From the point specified

     * by <code>x</code> and <code>y</code>, this method

     * copies downwards and to the right.  To copy an area of the

     * component to the left or upwards, specify a negative value for

     * <code>dx</code> or <code>dy</code>.

     * If a portion of the source rectangle lies outside the bounds

     * of the component, or is obscured by another window or component,

     * <code>copyArea</code> will be unable to copy the associated

     * pixels. The area that is omitted can be refreshed by calling

     * the component's <code>paint</code> method.

     * @param       x the <i>x</i> coordinate of the source rectangle.

     * @param       y the <i>y</i> coordinate of the source rectangle.

     * @param       width the width of the source rectangle.

     * @param       height the height of the source rectangle.

     * @param       dx the horizontal distance to copy the pixels.

     * @param       dy the vertical distance to copy the pixels.

     */

    public abstract void copyArea(int x, int y, int width, int height,

                                  int dx, int dy);

    /**

     * Draws a line, using the current color, between the points

     * <code>(x1,&nbsp;y1)</code> and <code>(x2,&nbsp;y2)</code>

     * in this graphics context's coordinate system.

     * @param   x1  the first point's <i>x</i> coordinate.

     * @param   y1  the first point's <i>y</i> coordinate.

     * @param   x2  the second point's <i>x</i> coordinate.

     * @param   y2  the second point's <i>y</i> coordinate.

     */

    public abstract void drawLine(int x1, int y1, int x2, int y2);

    /**

     * Fills the specified rectangle.

     * The left and right edges of the rectangle are at

     * <code>x</code> and <code>x&nbsp;+&nbsp;width&nbsp;-&nbsp;1</code>.

     * The top and bottom edges are at

     * <code>y</code> and <code>y&nbsp;+&nbsp;height&nbsp;-&nbsp;1</code>.

     * The resulting rectangle covers an area

     * <code>width</code> pixels wide by

     * <code>height</code> pixels tall.

     * The rectangle is filled using the graphics context's current color.

     * @param         x   the <i>x</i> coordinate

     *                         of the rectangle to be filled.

     * @param         y   the <i>y</i> coordinate

     *                         of the rectangle to be filled.

     * @param         width   the width of the rectangle to be filled.

     * @param         height   the height of the rectangle to be filled.

     * @see           java.awt.Graphics#clearRect

     * @see           java.awt.Graphics#drawRect

     */

    public abstract void fillRect(int x, int y, int width, int height);

    /**

     * Draws the outline of the specified rectangle.

     * The left and right edges of the rectangle are at

     * <code>x</code> and <code>x&nbsp;+&nbsp;width</code>.

     * The top and bottom edges are at

     * <code>y</code> and <code>y&nbsp;+&nbsp;height</code>.

     * The rectangle is drawn using the graphics context's current color.

     * @param         x   the <i>x</i> coordinate

     *                         of the rectangle to be drawn.

     * @param         y   the <i>y</i> coordinate

     *                         of the rectangle to be drawn.

     * @param         width   the width of the rectangle to be drawn.

     * @param         height   the height of the rectangle to be drawn.

     * @see          java.awt.Graphics#fillRect

     * @see          java.awt.Graphics#clearRect

     */

    public void drawRect(int x, int y, int width, int height) {

        if ((width < 0) || (height < 0)) {

            return;

        }

        if (height == 0 || width == 0) {

            drawLine(x, y, x + width, y + height);

        } else {

            drawLine(x, y, x + width - 1, y);

            drawLine(x + width, y, x + width, y + height - 1);

            drawLine(x + width, y + height, x + 1, y + height);

            drawLine(x, y + height, x, y + 1);

        }

    }

    /**

     * Clears the specified rectangle by filling it with the background

     * color of the current drawing surface. This operation does not

     * use the current paint mode.

     * <p>

     * Beginning with Java 1.1, the background color

     * of offscreen images may be system dependent. Applications should

     * use <code>setColor</code> followed by <code>fillRect</code> to

     * ensure that an offscreen image is cleared to a specific color.

     * @param       x the <i>x</i> coordinate of the rectangle to clear.

     * @param       y the <i>y</i> coordinate of the rectangle to clear.

     * @param       width the width of the rectangle to clear.

     * @param       height the height of the rectangle to clear.

     * @see         java.awt.Graphics#fillRect(int, int, int, int)

     * @see         java.awt.Graphics#drawRect

     * @see         java.awt.Graphics#setColor(java.awt.Color)

     * @see         java.awt.Graphics#setPaintMode

     * @see         java.awt.Graphics#setXORMode(java.awt.Color)

     */

    public abstract void clearRect(int x, int y, int width, int height);

    /**

     * Draws an outlined round-cornered rectangle using this graphics

     * context's current color. The left and right edges of the rectangle

     * are at <code>x</code> and <code>x&nbsp;+&nbsp;width</code>,

     * respectively. The top and bottom edges of the rectangle are at

     * <code>y</code> and <code>y&nbsp;+&nbsp;height</code>.

     * @param      x the <i>x</i> coordinate of the rectangle to be drawn.

     * @param      y the <i>y</i> coordinate of the rectangle to be drawn.

     * @param      width the width of the rectangle to be drawn.

     * @param      height the height of the rectangle to be drawn.

     * @param      arcWidth the horizontal diameter of the arc

     *                    at the four corners.

     * @param      arcHeight the vertical diameter of the arc

     *                    at the four corners.

     * @see        java.awt.Graphics#fillRoundRect

     */

    public abstract void drawRoundRect(int x, int y, int width, int height,

                                       int arcWidth, int arcHeight);

    /**

     * Fills the specified rounded corner rectangle with the current color.

     * The left and right edges of the rectangle

     * are at <code>x</code> and <code>x&nbsp;+&nbsp;width&nbsp;-&nbsp;1</code>,

     * respectively. The top and bottom edges of the rectangle are at

     * <code>y</code> and <code>y&nbsp;+&nbsp;height&nbsp;-&nbsp;1</code>.

     * @param       x the <i>x</i> coordinate of the rectangle to be filled.

     * @param       y the <i>y</i> coordinate of the rectangle to be filled.

     * @param       width the width of the rectangle to be filled.

     * @param       height the height of the rectangle to be filled.

     * @param       arcWidth the horizontal diameter

     *                     of the arc at the four corners.

     * @param       arcHeight the vertical diameter

     *                     of the arc at the four corners.

     * @see         java.awt.Graphics#drawRoundRect

     */

    public abstract void fillRoundRect(int x, int y, int width, int height,

                                       int arcWidth, int arcHeight);

    /**

     * Draws a 3-D highlighted outline of the specified rectangle.

     * The edges of the rectangle are highlighted so that they

     * appear to be beveled and lit from the upper left corner.

     * <p>

     * The colors used for the highlighting effect are determined

     * based on the current color.

     * The resulting rectangle covers an area that is

     * <code>width&nbsp;+&nbsp;1</code> pixels wide

     * by <code>height&nbsp;+&nbsp;1</code> pixels tall.

     * @param       x the <i>x</i> coordinate of the rectangle to be drawn.

     * @param       y the <i>y</i> coordinate of the rectangle to be drawn.

     * @param       width the width of the rectangle to be drawn.

     * @param       height the height of the rectangle to be drawn.

     * @param       raised a boolean that determines whether the rectangle

     *                      appears to be raised above the surface

     *                      or sunk into the surface.

     * @see         java.awt.Graphics#fill3DRect

     */