Java tutorial
/* * Copyright (c) 1996, 2017, 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.awt.RenderingHints.Key; import java.awt.geom.AffineTransform; import java.awt.image.ImageObserver; import java.awt.image.BufferedImageOp; import java.awt.image.BufferedImage; import java.awt.image.RenderedImage; import java.awt.image.renderable.RenderableImage; import java.awt.font.GlyphVector; import java.awt.font.FontRenderContext; import java.awt.font.TextAttribute; import java.text.AttributedCharacterIterator; import java.util.Map; /** * This {@code Graphics2D} class extends the * {@link Graphics} class to provide more sophisticated * control over geometry, coordinate transformations, color management, * and text layout. This is the fundamental class for rendering * 2-dimensional shapes, text and images on the Java(tm) platform. * * <h2>Coordinate Spaces</h2> * All coordinates passed to a {@code Graphics2D} object are specified * in a device-independent coordinate system called User Space, which is * used by applications. The {@code Graphics2D} object contains * an {@link AffineTransform} object as part of its rendering state * that defines how to convert coordinates from user space to * device-dependent coordinates in Device Space. * <p> * Coordinates in device space usually refer to individual device pixels * and are aligned on the infinitely thin gaps between these pixels. * Some {@code Graphics2D} objects can be used to capture rendering * operations for storage into a graphics metafile for playback on a * concrete device of unknown physical resolution at a later time. Since * the resolution might not be known when the rendering operations are * captured, the {@code Graphics2D Transform} is set up * to transform user coordinates to a virtual device space that * approximates the expected resolution of the target device. Further * transformations might need to be applied at playback time if the * estimate is incorrect. * <p> * Some of the operations performed by the rendering attribute objects * occur in the device space, but all {@code Graphics2D} methods take * user space coordinates. * <p> * Every {@code Graphics2D} object is associated with a target that * defines where rendering takes place. A * {@link GraphicsConfiguration} object defines the characteristics * of the rendering target, such as pixel format and resolution. * The same rendering target is used throughout the life of a * {@code Graphics2D} object. * <p> * When creating a {@code Graphics2D} object, the * {@code GraphicsConfiguration} * specifies the <a id="deftransform">default transform</a> for * the target of the {@code Graphics2D} (a * {@link Component} or {@link Image}). This default transform maps the * user space coordinate system to screen and printer device coordinates * such that the origin maps to the upper left hand corner of the * target region of the device with increasing X coordinates extending * to the right and increasing Y coordinates extending downward. * The scaling of the default transform is set to identity for those devices * that are close to 72 dpi, such as screen devices. * The scaling of the default transform is set to approximately 72 user * space coordinates per square inch for high resolution devices, such as * printers. For image buffers, the default transform is the * {@code Identity} transform. * * <h2>Rendering Process</h2> * The Rendering Process can be broken down into four phases that are * controlled by the {@code Graphics2D} rendering attributes. * The renderer can optimize many of these steps, either by caching the * results for future calls, by collapsing multiple virtual steps into * a single operation, or by recognizing various attributes as common * simple cases that can be eliminated by modifying other parts of the * operation. * <p> * The steps in the rendering process are: * <ol> * <li> * Determine what to render. * <li> * Constrain the rendering operation to the current {@code Clip}. * The {@code Clip} is specified by a {@link Shape} in user * space and is controlled by the program using the various clip * manipulation methods of {@code Graphics} and * {@code Graphics2D}. This <i>user clip</i> * is transformed into device space by the current * {@code Transform} 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 is not modified by the rendering * system to reflect the resulting composite clip. * <li> * Determine what colors to render. * <li> * Apply the colors to the destination drawing surface using the current * {@link Composite} attribute in the {@code Graphics2D} context. * </ol> * <br> * The three types of rendering operations, along with details of each * of their particular rendering processes are: * <ol> * <li> * <b><a id="rendershape">{@code Shape} operations</a></b> * <ol> * <li> * If the operation is a {@code draw(Shape)} operation, then * the {@link Stroke#createStrokedShape(Shape) createStrokedShape} * method on the current {@link Stroke} attribute in the * {@code Graphics2D} context is used to construct a new * {@code Shape} object that contains the outline of the specified * {@code Shape}. * <li> * The {@code Shape} is transformed from user space to device space * using the current {@code Transform} * in the {@code Graphics2D} context. * <li> * The outline of the {@code Shape} is extracted using the * {@link Shape#getPathIterator(AffineTransform) getPathIterator} method of * {@code Shape}, which returns a * {@link java.awt.geom.PathIterator PathIterator} * object that iterates along the boundary of the {@code Shape}. * <li> * If the {@code Graphics2D} object cannot handle the curved segments * that the {@code PathIterator} object returns then it can call the * alternate * {@link Shape#getPathIterator(AffineTransform, double) getPathIterator} * method of {@code Shape}, which flattens the {@code Shape}. * <li> * The current {@link Paint} in the {@code Graphics2D} context * is queried for a {@link PaintContext}, which specifies the * colors to render in device space. * </ol> * <li> * <b><a id=rendertext>Text operations</a></b> * <ol> * <li> * The following steps are used to determine the set of glyphs required * to render the indicated {@code String}: * <ol> * <li> * If the argument is a {@code String}, then the current * {@code Font} in the {@code Graphics2D} context is asked to * convert the Unicode characters in the {@code String} into a set of * glyphs for presentation with whatever basic layout and shaping * algorithms the font implements. * <li> * If the argument is an * {@link AttributedCharacterIterator}, * the iterator is asked to convert itself to a * {@link java.awt.font.TextLayout TextLayout} * using its embedded font attributes. The {@code TextLayout} * implements more sophisticated glyph layout algorithms that * perform Unicode bi-directional layout adjustments automatically * for multiple fonts of differing writing directions. * <li> * If the argument is a * {@link GlyphVector}, then the * {@code GlyphVector} object already contains the appropriate * font-specific glyph codes with explicit coordinates for the position of * each glyph. * </ol> * <li> * The current {@code Font} is queried to obtain outlines for the * indicated glyphs. These outlines are treated as shapes in user space * relative to the position of each glyph that was determined in step 1. * <li> * The character outlines are filled as indicated above * under <a href="#rendershape">{@code Shape} operations</a>. * <li> * The current {@code Paint} is queried for a * {@code PaintContext}, which specifies * the colors to render in device space. * </ol> * <li> * <b><a id= renderingimage>{@code Image} Operations</a></b> * <ol> * <li> * The region of interest is defined by the bounding box of the source * {@code Image}. * This bounding box is specified in Image Space, which is the * {@code Image} object's local coordinate system. * <li> * If an {@code AffineTransform} is passed to * {@link #drawImage(java.awt.Image, java.awt.geom.AffineTransform, java.awt.image.ImageObserver) drawImage(Image, AffineTransform, ImageObserver)}, * the {@code AffineTransform} is used to transform the bounding * box from image space to user space. If no {@code AffineTransform} * is supplied, the bounding box is treated as if it is already in user space. * <li> * The bounding box of the source {@code Image} is transformed from user * space into device space using the current {@code Transform}. * Note that the result of transforming the bounding box does not * necessarily result in a rectangular region in device space. * <li> * The {@code Image} object determines what colors to render, * sampled according to the source to destination * coordinate mapping specified by the current {@code Transform} and the * optional image transform. * </ol> * </ol> * * <h2>Default Rendering Attributes</h2> * The default values for the {@code Graphics2D} rendering attributes are: * <dl> * <dt><i>{@code Paint}</i> * <dd>The color of the {@code Component}. * <dt><i>{@code Font}</i> * <dd>The {@code Font} of the {@code Component}. * <dt><i>{@code Stroke}</i> * <dd>A square pen with a linewidth of 1, no dashing, miter segment joins * and square end caps. * <dt><i>{@code Transform}</i> * <dd>The * {@link GraphicsConfiguration#getDefaultTransform() getDefaultTransform} * for the {@code GraphicsConfiguration} of the {@code Component}. * <dt><i>{@code Composite}</i> * <dd>The {@link AlphaComposite#SRC_OVER} rule. * <dt><i>{@code Clip}</i> * <dd>No rendering {@code Clip}, the output is clipped to the * {@code Component}. * </dl> * * <h2>Rendering Compatibility Issues</h2> * The JDK(tm) 1.1 rendering model is based on a pixelization model * that specifies that coordinates * are infinitely thin, lying between the pixels. Drawing operations are * performed using a one-pixel wide pen that fills the * pixel below and to the right of the anchor point on the path. * The JDK 1.1 rendering model is consistent with the * capabilities of most of the existing class of platform * renderers that need to resolve integer coordinates to a * discrete pen that must fall completely on a specified number of pixels. * <p> * The Java 2D(tm) (Java(tm) 2 platform) API supports antialiasing renderers. * A pen with a width of one pixel does not need to fall * completely on pixel N as opposed to pixel N+1. The pen can fall * partially on both pixels. It is not necessary to choose a bias * direction for a wide pen since the blending that occurs along the * pen traversal edges makes the sub-pixel position of the pen * visible to the user. On the other hand, when antialiasing is * turned off by setting the * {@link RenderingHints#KEY_ANTIALIASING KEY_ANTIALIASING} hint key * to the * {@link RenderingHints#VALUE_ANTIALIAS_OFF VALUE_ANTIALIAS_OFF} * hint value, the renderer might need * to apply a bias to determine which pixel to modify when the pen * is straddling a pixel boundary, such as when it is drawn * along an integer coordinate in device space. While the capabilities * of an antialiasing renderer make it no longer necessary for the * rendering model to specify a bias for the pen, it is desirable for the * antialiasing and non-antialiasing renderers to perform similarly for * the common cases of drawing one-pixel wide horizontal and vertical * lines on the screen. To ensure that turning on antialiasing by * setting the * {@link RenderingHints#KEY_ANTIALIASING KEY_ANTIALIASING} hint * key to * {@link RenderingHints#VALUE_ANTIALIAS_ON VALUE_ANTIALIAS_ON} * does not cause such lines to suddenly become twice as wide and half * as opaque, it is desirable to have the model specify a path for such * lines so that they completely cover a particular set of pixels to help * increase their crispness. * <p> * Java 2D API maintains compatibility with JDK 1.1 rendering * behavior, such that legacy operations and existing renderer * behavior is unchanged under Java 2D API. Legacy * methods that map onto general {@code draw} and * {@code fill} methods are defined, which clearly indicates * how {@code Graphics2D} extends {@code Graphics} based * on settings of {@code Stroke} and {@code Transform} * attributes and rendering hints. The definition * performs identically under default attribute settings. * For example, the default {@code Stroke} is a * {@code BasicStroke} with a width of 1 and no dashing and the * default Transform for screen drawing is an Identity transform. * <p> * The following two rules provide predictable rendering behavior whether * aliasing or antialiasing is being used. * <ul> * <li> Device coordinates are defined to be between device pixels which * avoids any inconsistent results between aliased and antialiased * rendering. If coordinates were defined to be at a pixel's center, some * of the pixels covered by a shape, such as a rectangle, would only be * half covered. * With aliased rendering, the half covered pixels would either be * rendered inside the shape or outside the shape. With anti-aliased * rendering, the pixels on the entire edge of the shape would be half * covered. On the other hand, since coordinates are defined to be * between pixels, a shape like a rectangle would have no half covered * pixels, whether or not it is rendered using antialiasing. * <li> Lines and paths stroked using the {@code BasicStroke} * object may be "normalized" to provide consistent rendering of the * outlines when positioned at various points on the drawable and * whether drawn with aliased or antialiased rendering. This * normalization process is controlled by the * {@link RenderingHints#KEY_STROKE_CONTROL KEY_STROKE_CONTROL} hint. * The exact normalization algorithm is not specified, but the goals * of this normalization are to ensure that lines are rendered with * consistent visual appearance regardless of how they fall on the * pixel grid and to promote more solid horizontal and vertical * lines in antialiased mode so that they resemble their non-antialiased * counterparts more closely. A typical normalization step might * promote antialiased line endpoints to pixel centers to reduce the * amount of blending or adjust the subpixel positioning of * non-antialiased lines so that the floating point line widths * round to even or odd pixel counts with equal likelihood. This * process can move endpoints by up to half a pixel (usually towards * positive infinity along both axes) to promote these consistent * results. * </ul> * <p> * The following definitions of general legacy methods * perform identically to previously specified behavior under default * attribute settings: * <ul> * <li> * For {@code fill} operations, including {@code fillRect}, * {@code fillRoundRect}, {@code fillOval}, * {@code fillArc}, {@code fillPolygon}, and * {@code clearRect}, {@link #fill(Shape) fill} can now be called * with the desired {@code Shape}. For example, when filling a * rectangle: * <pre> * fill(new Rectangle(x, y, w, h)); * </pre> * is called. * * <li> * Similarly, for draw operations, including {@code drawLine}, * {@code drawRect}, {@code drawRoundRect}, * {@code drawOval}, {@code drawArc}, {@code drawPolyline}, * and {@code drawPolygon}, {@link #draw(Shape) draw} can now be * called with the desired {@code Shape}. For example, when drawing a * rectangle: * <pre> * draw(new Rectangle(x, y, w, h)); * </pre> * is called. * * <li> * The {@code draw3DRect} and {@code fill3DRect} methods were * implemented in terms of the {@code drawLine} and * {@code fillRect} methods in the {@code Graphics} class which * would predicate their behavior upon the current {@code Stroke} * and {@code Paint} objects in a {@code Graphics2D} context. * This class overrides those implementations with versions that use * the current {@code Color} exclusively, overriding the current * {@code Paint} and which uses {@code fillRect} to describe * the exact same behavior as the preexisting methods regardless of the * setting of the current {@code Stroke}. * </ul> * The {@code Graphics} class defines only the {@code setColor} * method to control the color to be painted. Since the Java 2D API extends * the {@code Color} object to implement the new {@code Paint} * interface, the existing * {@code setColor} method is now a convenience method for setting the * current {@code Paint} attribute to a {@code Color} object. * {@code setColor(c)} is equivalent to {@code setPaint(c)}. * <p> * The {@code Graphics} class defines two methods for controlling * how colors are applied to the destination. * <ol> * <li> * The {@code setPaintMode} method is implemented as a convenience * method to set the default {@code Composite}, equivalent to * {@code setComposite(new AlphaComposite.SrcOver)}. * <li> * The {@code setXORMode(Color xorcolor)} method is implemented * as a convenience method to set a special {@code Composite} object that * ignores the {@code Alpha} components of source colors and sets the * destination color to the value: * <pre> * dstpixel = (PixelOf(srccolor) ^ PixelOf(xorcolor) ^ dstpixel); * </pre> * </ol> * * @author Jim Graham * @see java.awt.RenderingHints */ public abstract class Graphics2D extends Graphics { /** * Constructs a new {@code Graphics2D} object. Since * {@code Graphics2D} is an abstract class, and since it must be * customized by subclasses for different output devices, * {@code Graphics2D} objects cannot be created directly. * Instead, {@code Graphics2D} objects must be obtained from another * {@code Graphics2D} object, created by a * {@code Component}, or obtained from images such as * {@link BufferedImage} objects. * @see java.awt.Component#getGraphics * @see java.awt.Graphics#create */ protected Graphics2D() { } /** * 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 + 1</code> pixels wide * by <code>height + 1</code> pixels tall. This method * uses the current {@code Color} exclusively and ignores * the current {@code Paint}. * @param x the x coordinate of the rectangle to be drawn. * @param y the y 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 */ public void draw3DRect(int x, int y, int width, int height, boolean raised) { Paint p = getPaint(); Color c = getColor(); Color brighter = c.brighter(); Color darker = c.darker(); setColor(raised ? brighter : darker); //drawLine(x, y, x, y + height); fillRect(x, y, 1, height + 1); //drawLine(x + 1, y, x + width - 1, y); fillRect(x + 1, y, width - 1, 1); setColor(raised ? darker : brighter); //drawLine(x + 1, y + height, x + width, y + height); fillRect(x + 1, y + height, width, 1); //drawLine(x + width, y, x + width, y + height - 1); fillRect(x + width, y, 1, height); setPaint(p); } /** * Paints a 3-D highlighted rectangle filled with the current color. * The edges of the rectangle are highlighted so that it appears * as if the edges were beveled and lit from the upper left corner. * The colors used for the highlighting effect and for filling are * determined from the current {@code Color}. This method uses * the current {@code Color} exclusively and ignores the current * {@code Paint}. * @param x the x coordinate of the rectangle to be filled. * @param y the y 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 raised a boolean value that determines whether the * rectangle appears to be raised above the surface * or etched into the surface. * @see java.awt.Graphics#draw3DRect */ public void fill3DRect(int x, int y, int width, int height, boolean raised) { Paint p = getPaint(); Color c = getColor(); Color brighter = c.brighter(); Color darker = c.darker(); if (!raised) { setColor(darker); } else if (p != c) { setColor(c); } fillRect(x + 1, y + 1, width - 2, height - 2); setColor(raised ? brighter : darker); //drawLine(x, y, x, y + height - 1); fillRect(x, y, 1, height); //drawLine(x + 1, y, x + width - 2, y); fillRect(x + 1, y, width - 2, 1); setColor(raised ? darker : brighter); //drawLine(x + 1, y + height - 1, x + width - 1, y + height - 1); fillRect(x + 1, y + height - 1, width - 1, 1); //drawLine(x + width - 1, y, x + width - 1, y + height - 2); fillRect(x + width - 1, y, 1, height - 1); setPaint(p); } /** * Strokes the outline of a {@code Shape} using the settings of the * current {@code Graphics2D} context. The rendering attributes * applied include the {@code Clip}, {@code Transform}, * {@code Paint}, {@code Composite} and * {@code Stroke} attributes. * @param s the {@code Shape} to be rendered * @see #setStroke * @see #setPaint * @see java.awt.Graphics#setColor * @see #transform * @see #setTransform * @see #clip * @see #setClip * @see #setComposite */ public abstract void draw(Shape s); /** * Renders an image, applying a transform from image space into user space * before drawing. * The transformation from user space into device space is done with * the current {@code Transform} in the {@code Graphics2D}. * The specified transformation is applied to the image before the * transform attribute in the {@code Graphics2D} context is applied. * The rendering attributes applied include the {@code Clip}, * {@code Transform}, and {@code Composite} attributes. * Note that no rendering is done if the specified transform is * noninvertible. * @param img the specified image to be rendered. * This method does nothing if {@code img} is null. * @param xform the transformation from image space into user space * @param obs the {@link ImageObserver} * to be notified as more of the {@code Image} * is converted * @return {@code true} if the {@code Image} is * fully loaded and completely rendered, or if it's null; * {@code false} if the {@code Image} is still being loaded. * @see #transform * @see #setTransform * @see #setComposite * @see #clip * @see #setClip */ public abstract boolean drawImage(Image img, AffineTransform xform, ImageObserver obs); /** * Renders a {@code BufferedImage} that is * filtered with a * {@link BufferedImageOp}. * The rendering attributes applied include the {@code Clip}, * {@code Transform} * and {@code Composite} attributes. This is equivalent to: * <pre> * img1 = op.filter(img, null); * drawImage(img1, new AffineTransform(1f,0f,0f,1f,x,y), null); * </pre> * @param op the filter to be applied to the image before rendering * @param img the specified {@code BufferedImage} to be rendered. * This method does nothing if {@code img} is null. * @param x the x coordinate of the location in user space where * the upper left corner of the image is rendered * @param y the y coordinate of the location in user space where * the upper left corner of the image is rendered * * @see #transform * @see #setTransform * @see #setComposite * @see #clip * @see #setClip */ public abstract void drawImage(BufferedImage img, BufferedImageOp op, int x, int y); /** * Renders a {@link RenderedImage}, * applying a transform from image * space into user space before drawing. * The transformation from user space into device space is done with * the current {@code Transform} in the {@code Graphics2D}. * The specified transformation is applied to the image before the * transform attribute in the {@code Graphics2D} context is applied. * The rendering attributes applied include the {@code Clip}, * {@code Transform}, and {@code Composite} attributes. Note * that no rendering is done if the specified transform is * noninvertible. * @param img the image to be rendered. This method does * nothing if {@code img} is null. * @param xform the transformation from image space into user space * @see #transform * @see #setTransform * @see #setComposite * @see #clip * @see #setClip */ public abstract void drawRenderedImage(RenderedImage img, AffineTransform xform); /** * Renders a * {@link RenderableImage}, * applying a transform from image space into user space before drawing. * The transformation from user space into device space is done with * the current {@code Transform} in the {@code Graphics2D}. * The specified transformation is applied to the image before the * transform attribute in the {@code Graphics2D} context is applied. * The rendering attributes applied include the {@code Clip}, * {@code Transform}, and {@code Composite} attributes. Note * that no rendering is done if the specified transform is * noninvertible. *<p> * Rendering hints set on the {@code Graphics2D} object might * be used in rendering the {@code RenderableImage}. * If explicit control is required over specific hints recognized by a * specific {@code RenderableImage}, or if knowledge of which hints * are used is required, then a {@code RenderedImage} should be * obtained directly from the {@code RenderableImage} * and rendered using *{@link #drawRenderedImage(RenderedImage, AffineTransform) drawRenderedImage}. * @param img the image to be rendered. This method does * nothing if {@code img} is null. * @param xform the transformation from image space into user space * @see #transform * @see #setTransform * @see #setComposite * @see #clip * @see #setClip * @see #drawRenderedImage */ public abstract void drawRenderableImage(RenderableImage img, AffineTransform xform); /** * Renders the text of the specified {@code String}, using the * current text attribute state in the {@code Graphics2D} context. * The baseline of the * first character is at position (<i>x</i>, <i>y</i>) in * the User Space. * The rendering attributes applied include the {@code Clip}, * {@code Transform}, {@code Paint}, {@code Font} and * {@code Composite} attributes. For characters in script * systems such as Hebrew and Arabic, the glyphs can be rendered from * right to left, in which case the coordinate supplied is the * location of the leftmost character on the baseline. * @param str the string to be rendered * @param x the x coordinate of the location where the * {@code String} should be rendered * @param y the y coordinate of the location where the * {@code String} should be rendered * @throws NullPointerException if {@code str} is * {@code null} * @see java.awt.Graphics#drawBytes * @see java.awt.Graphics#drawChars * @since 1.0 */ public abstract void drawString(String str, int x, int y); /** * Renders the text specified by the specified {@code String}, * using the current text attribute state in the {@code Graphics2D} context. * The baseline of the first character is at position * (<i>x</i>, <i>y</i>) in the User Space. * The rendering attributes applied include the {@code Clip}, * {@code Transform}, {@code Paint}, {@code Font} and * {@code Composite} attributes. For characters in script systems * such as Hebrew and Arabic, the glyphs can be rendered from right to * left, in which case the coordinate supplied is the location of the * leftmost character on the baseline. * @param str the {@code String} to be rendered * @param x the x coordinate of the location where the * {@code String} should be rendered * @param y the y coordinate of the location where the * {@code String} should be rendered * @throws NullPointerException if {@code str} is * {@code null} * @see #setPaint * @see java.awt.Graphics#setColor * @see java.awt.Graphics#setFont * @see #setTransform * @see #setComposite * @see #setClip */ public abstract void drawString(String str, float x, float y); /** * Renders the text of the specified iterator applying its attributes * in accordance with the specification of the {@link TextAttribute} class. * <p> * The baseline of the first character is at position * (<i>x</i>, <i>y</i>) in User Space. * For characters in script systems such as Hebrew and Arabic, * the glyphs can be rendered from right to left, in which case the * coordinate supplied is the location of the leftmost character * on the baseline. * @param iterator the iterator whose text is to be rendered * @param x the x coordinate where the iterator's text is to be * rendered * @param y the y coordinate where the iterator's text is to be * rendered * @throws NullPointerException if {@code iterator} is * {@code null} * @see #setPaint * @see java.awt.Graphics#setColor * @see #setTransform * @see #setComposite * @see #setClip */ public abstract void drawString(AttributedCharacterIterator iterator, int x, int y); /** * Renders the text of the specified iterator applying its attributes * in accordance with the specification of the {@link TextAttribute} class. * <p> * The baseline of the first character is at position * (<i>x</i>, <i>y</i>) in User Space. * For characters in script systems such as Hebrew and Arabic, * the glyphs can be rendered from right to left, in which case the * coordinate supplied is the location of the leftmost character * on the baseline. * @param iterator the iterator whose text is to be rendered * @param x the x coordinate where the iterator's text is to be * rendered * @param y the y coordinate where the iterator's text is to be * rendered * @throws NullPointerException if {@code iterator} is * {@code null} * @see #setPaint * @see java.awt.Graphics#setColor * @see #setTransform * @see #setComposite * @see #setClip */ public abstract void drawString(AttributedCharacterIterator iterator, float x, float y); /** * Renders the text of the specified * {@link GlyphVector} using * the {@code Graphics2D} context's rendering attributes. * The rendering attributes applied include the {@code Clip}, * {@code Transform}, {@code Paint}, and * {@code Composite} attributes. The {@code GlyphVector} * specifies individual glyphs from a {@link Font}. * The {@code GlyphVector} can also contain the glyph positions. * This is the fastest way to render a set of characters to the * screen. * @param g the {@code GlyphVector} to be rendered * @param x the x position in User Space where the glyphs should * be rendered * @param y the y position in User Space where the glyphs should * be rendered * @throws NullPointerException if {@code g} is {@code null}. * * @see java.awt.Font#createGlyphVector * @see java.awt.font.GlyphVector * @see #setPaint * @see java.awt.Graphics#setColor * @see #setTransform * @see #setComposite * @see #setClip */ public abstract void drawGlyphVector(GlyphVector g, float x, float y); /** * Fills the interior of a {@code Shape} using the settings of the * {@code Graphics2D} context. The rendering attributes applied * include the {@code Clip}, {@code Transform}, * {@code Paint}, and {@code Composite}. * @param s the {@code Shape} to be filled * @see #setPaint * @see java.awt.Graphics#setColor * @see #transform * @see #setTransform * @see #setComposite * @see #clip * @see #setClip */ public abstract void fill(Shape s); /** * Checks whether or not the specified {@code Shape} intersects * the specified {@link Rectangle}, which is in device * space. If {@code onStroke} is false, this method checks * whether or not the interior of the specified {@code Shape} * intersects the specified {@code Rectangle}. If * {@code onStroke} is {@code true}, this method checks * whether or not the {@code Stroke} of the specified * {@code Shape} outline intersects the specified * {@code Rectangle}. * The rendering attributes taken into account include the * {@code Clip}, {@code Transform}, and {@code Stroke} * attributes. * @param rect the area in device space to check for a hit * @param s the {@code Shape} to check for a hit * @param onStroke flag used to choose between testing the * stroked or the filled shape. If the flag is {@code true}, the * {@code Stroke} outline is tested. If the flag is * {@code false}, the filled {@code Shape} is tested. * @return {@code true} if there is a hit; {@code false} * otherwise. * @see #setStroke * @see #fill * @see #draw * @see #transform * @see #setTransform * @see #clip * @see #setClip */ public abstract boolean hit(Rectangle rect, Shape s, boolean onStroke); /** * Returns the device configuration associated with this * {@code Graphics2D}. * @return the device configuration of this {@code Graphics2D}. */ public abstract GraphicsConfiguration getDeviceConfiguration(); /** * Sets the {@code Composite} for the {@code Graphics2D} context. * The {@code Composite} is used in all drawing methods such as * {@code drawImage}, {@code drawString}, {@code draw}, * and {@code fill}. It specifies how new pixels are to be combined * with the existing pixels on the graphics device during the rendering * process. * <p>If this {@code Graphics2D} context is drawing to a * {@code Component} on the display screen and the * {@code Composite} is a custom object rather than an * instance of the {@code AlphaComposite} class, and if * there is a security manager, its {@code checkPermission} * method is called with an {@code AWTPermission("readDisplayPixels")} * permission. * @throws SecurityException * if a custom {@code Composite} object is being * used to render to the screen and a security manager * is set and its {@code checkPermission} method * does not allow the operation. * @param comp the {@code Composite} object to be used for rendering * @see java.awt.Graphics#setXORMode * @see java.awt.Graphics#setPaintMode * @see #getComposite * @see AlphaComposite * @see SecurityManager#checkPermission * @see java.awt.AWTPermission */ public abstract void setComposite(Composite comp); /** * Sets the {@code Paint} attribute for the * {@code Graphics2D} context. Calling this method * with a {@code null Paint} object does * not have any effect on the current {@code Paint} attribute * of this {@code Graphics2D}. * @param paint the {@code Paint} object to be used to generate * color during the rendering process, or {@code null} * @see java.awt.Graphics#setColor * @see #getPaint * @see GradientPaint * @see TexturePaint */ public abstract void setPaint(Paint paint); /** * Sets the {@code Stroke} for the {@code Graphics2D} context. * @param s the {@code Stroke} object to be used to stroke a * {@code Shape} during the rendering process * @see BasicStroke * @see #getStroke */ public abstract void setStroke(Stroke s); /** * Sets the value of a single preference for the rendering algorithms. * Hint categories include controls for rendering quality and overall * time/quality trade-off in the rendering process. Refer to the * {@code RenderingHints} class for definitions of some common * keys and values. * @param hintKey the key of the hint to be set. * @param hintValue the value indicating preferences for the specified * hint category. * @see #getRenderingHint(RenderingHints.Key) * @see RenderingHints */ public abstract void setRenderingHint(Key hintKey, Object hintValue); /** * Returns the value of a single preference for the rendering algorithms. * Hint categories include controls for rendering quality and overall * time/quality trade-off in the rendering process. Refer to the * {@code RenderingHints} class for definitions of some common * keys and values. * @param hintKey the key corresponding to the hint to get. * @return an object representing the value for the specified hint key. * Some of the keys and their associated values are defined in the * {@code RenderingHints} class. * @see RenderingHints * @see #setRenderingHint(RenderingHints.Key, Object) */ public abstract Object getRenderingHint(Key hintKey); /** * Replaces the values of all preferences for the rendering * algorithms with the specified {@code hints}. * The existing values for all rendering hints are discarded and * the new set of known hints and values are initialized from the * specified {@link Map} object. * Hint categories include controls for rendering quality and * overall time/quality trade-off in the rendering process. * Refer to the {@code RenderingHints} class for definitions of * some common keys and values. * @param hints the rendering hints to be set * @see #getRenderingHints * @see RenderingHints */ public abstract void setRenderingHints(Map<?, ?> hints); /** * Sets the values of an arbitrary number of preferences for the * rendering algorithms. * Only values for the rendering hints that are present in the * specified {@code Map} object are modified. * All other preferences not present in the specified * object are left unmodified. * Hint categories include controls for rendering quality and * overall time/quality trade-off in the rendering process. * Refer to the {@code RenderingHints} class for definitions of * some common keys and values. * @param hints the rendering hints to be set * @see RenderingHints */ public abstract void addRenderingHints(Map<?, ?> hints); /** * Gets the preferences for the rendering algorithms. Hint categories * include controls for rendering quality and overall time/quality * trade-off in the rendering process. * Returns all of the hint key/value pairs that were ever specified in * one operation. Refer to the * {@code RenderingHints} class for definitions of some common * keys and values. * @return a reference to an instance of {@code RenderingHints} * that contains the current preferences. * @see RenderingHints * @see #setRenderingHints(Map) */ public abstract RenderingHints getRenderingHints(); /** * Translates the origin of the {@code Graphics2D} context to the * point (<i>x</i>, <i>y</i>) in the current coordinate system. * Modifies the {@code Graphics2D} context so that its new origin * corresponds to the point (<i>x</i>, <i>y</i>) in the * {@code Graphics2D} context's former coordinate system. All * coordinates used in subsequent rendering operations on this graphics * context are relative to this new origin. * @param x the specified x coordinate * @param y the specified y coordinate * @since 1.0 */ public abstract void translate(int x, int y); /** * Concatenates the current * {@code Graphics2D Transform} * with a translation transform. * Subsequent rendering is translated by the specified * distance relative to the previous position. * This is equivalent to calling transform(T), where T is an * {@code AffineTransform} represented by the following matrix: * <pre> * [ 1 0 tx ] * [ 0 1 ty ] * [ 0 0 1 ] * </pre> * @param tx the distance to translate along the x-axis * @param ty the distance to translate along the y-axis */ public abstract void translate(double tx, double ty); /** * Concatenates the current {@code Graphics2D} * {@code Transform} with a rotation transform. * Subsequent rendering is rotated by the specified radians relative * to the previous origin. * This is equivalent to calling {@code transform(R)}, where R is an * {@code AffineTransform} represented by the following matrix: * <pre> * [ cos(theta) -sin(theta) 0 ] * [ sin(theta) cos(theta) 0 ] * [ 0 0 1 ] * </pre> * Rotating with a positive angle theta rotates points on the positive * x axis toward the positive y axis. * @param theta the angle of rotation in radians */ public abstract void rotate(double theta); /** * Concatenates the current {@code Graphics2D} * {@code Transform} with a translated rotation * transform. Subsequent rendering is transformed by a transform * which is constructed by translating to the specified location, * rotating by the specified radians, and translating back by the same * amount as the original translation. This is equivalent to the * following sequence of calls: * <pre> * translate(x, y); * rotate(theta); * translate(-x, -y); * </pre> * Rotating with a positive angle theta rotates points on the positive * x axis toward the positive y axis. * @param theta the angle of rotation in radians * @param x the x coordinate of the origin of the rotation * @param y the y coordinate of the origin of the rotation */ public abstract void rotate(double theta, double x, double y); /** * Concatenates the current {@code Graphics2D} * {@code Transform} with a scaling transformation * Subsequent rendering is resized according to the specified scaling * factors relative to the previous scaling. * This is equivalent to calling {@code transform(S)}, where S is an * {@code AffineTransform} represented by the following matrix: * <pre> * [ sx 0 0 ] * [ 0 sy 0 ] * [ 0 0 1 ] * </pre> * @param sx the amount by which X coordinates in subsequent * rendering operations are multiplied relative to previous * rendering operations. * @param sy the amount by which Y coordinates in subsequent * rendering operations are multiplied relative to previous * rendering operations. */ public abstract void scale(double sx, double sy); /** * Concatenates the current {@code Graphics2D} * {@code Transform} with a shearing transform. * Subsequent renderings are sheared by the specified * multiplier relative to the previous position. * This is equivalent to calling {@code transform(SH)}, where SH * is an {@code AffineTransform} represented by the following * matrix: * <pre> * [ 1 shx 0 ] * [ shy 1 0 ] * [ 0 0 1 ] * </pre> * @param shx the multiplier by which coordinates are shifted in * the positive X axis direction as a function of their Y coordinate * @param shy the multiplier by which coordinates are shifted in * the positive Y axis direction as a function of their X coordinate */ public abstract void shear(double shx, double shy); /** * Composes an {@code AffineTransform} object with the * {@code Transform} in this {@code Graphics2D} according * to the rule last-specified-first-applied. If the current * {@code Transform} is Cx, the result of composition * with Tx is a new {@code Transform} Cx'. Cx' becomes the * current {@code Transform} for this {@code Graphics2D}. * Transforming a point p by the updated {@code Transform} Cx' is * equivalent to first transforming p by Tx and then transforming * the result by the original {@code Transform} Cx. In other * words, Cx'(p) = Cx(Tx(p)). A copy of the Tx is made, if necessary, * so further modifications to Tx do not affect rendering. * @param Tx the {@code AffineTransform} object to be composed with * the current {@code Transform} * @see #setTransform * @see AffineTransform */ public abstract void transform(AffineTransform Tx); /** * Overwrites the Transform in the {@code Graphics2D} context. * WARNING: This method should <b>never</b> be used to apply a new * coordinate transform on top of an existing transform because the * {@code Graphics2D} might already have a transform that is * needed for other purposes, such as rendering Swing * components or applying a scaling transformation to adjust for the * resolution of a printer. * <p>To add a coordinate transform, use the * {@code transform}, {@code rotate}, {@code scale}, * or {@code shear} methods. The {@code setTransform} * method is intended only for restoring the original * {@code Graphics2D} transform after rendering, as shown in this * example: * <pre> * // Get the current transform * AffineTransform saveAT = g2.getTransform(); * // Perform transformation * g2d.transform(...); * // Render * g2d.draw(...); * // Restore original transform * g2d.setTransform(saveAT); * </pre> * * @param Tx the {@code AffineTransform} that was retrieved * from the {@code getTransform} method * @see #transform * @see #getTransform * @see AffineTransform */ public abstract void setTransform(AffineTransform Tx); /** * Returns a copy of the current {@code Transform} in the * {@code Graphics2D} context. * @return the current {@code AffineTransform} in the * {@code Graphics2D} context. * @see #transform * @see #setTransform */ public abstract AffineTransform getTransform(); /** * Returns the current {@code Paint} of the * {@code Graphics2D} context. * @return the current {@code Graphics2D Paint}, * which defines a color or pattern. * @see #setPaint * @see java.awt.Graphics#setColor */ public abstract Paint getPaint(); /** * Returns the current {@code Composite} in the * {@code Graphics2D} context. * @return the current {@code Graphics2D Composite}, * which defines a compositing style. * @see #setComposite */ public abstract Composite getComposite(); /** * Sets the background color for the {@code Graphics2D} context. * The background color is used for clearing a region. * When a {@code Graphics2D} is constructed for a * {@code Component}, the background color is * inherited from the {@code Component}. Setting the background color * in the {@code Graphics2D} context only affects the subsequent * {@code clearRect} calls and not the background color of the * {@code Component}. To change the background * of the {@code Component}, use appropriate methods of * the {@code Component}. * @param color the background color that is used in * subsequent calls to {@code clearRect} * @see #getBackground * @see java.awt.Graphics#clearRect */ public abstract void setBackground(Color color); /** * Returns the background color used for clearing a region. * @return the current {@code Graphics2D Color}, * which defines the background color. * @see #setBackground */ public abstract Color getBackground(); /** * Returns the current {@code Stroke} in the * {@code Graphics2D} context. * @return the current {@code Graphics2D Stroke}, * which defines the line style. * @see #setStroke */ public abstract Stroke getStroke(); /** * Intersects the current {@code Clip} with the interior of the * specified {@code Shape} and sets the {@code Clip} to the * resulting intersection. The specified {@code Shape} is * transformed with the current {@code Graphics2D} * {@code Transform} before being intersected with the current * {@code Clip}. This method is used to make the current * {@code Clip} smaller. * To make the {@code Clip} larger, use {@code setClip}. * The <i>user clip</i> modified by this method is independent of the * clipping associated with device bounds and visibility. If no clip has * previously been set, or if the clip has been cleared using * {@link Graphics#setClip(Shape) setClip} with a {@code null} * argument, the specified {@code Shape} becomes the new * user clip. * @param s the {@code Shape} to be intersected with the current * {@code Clip}. If {@code s} is {@code null}, * this method clears the current {@code Clip}. */ public abstract void clip(Shape s); /** * Get the rendering context of the {@code Font} within this * {@code Graphics2D} context. * The {@link FontRenderContext} * encapsulates application hints such as anti-aliasing and * fractional metrics, as well as target device specific information * such as dots-per-inch. This information should be provided by the * application when using objects that perform typographical * formatting, such as {@code Font} and * {@code TextLayout}. This information should also be provided * by applications that perform their own layout and need accurate * measurements of various characteristics of glyphs such as advance * and line height when various rendering hints have been applied to * the text rendering. * * @return a reference to an instance of FontRenderContext. * @see java.awt.font.FontRenderContext * @see java.awt.Font#createGlyphVector * @see java.awt.font.TextLayout * @since 1.2 */ public abstract FontRenderContext getFontRenderContext(); }