This patch (committed) adds some API doc comments to Graphics2D.java. These have
been sitting on my hard drive for a while - they're not comprehensive or complete,
but they're better than nothing at all:
2006-05-15 David Gilbert <[EMAIL PROTECTED]>
* java/awt/Graphics2D.java: Added some API doc comments.
Regards,
Dave
Index: java/awt/Graphics2D.java
===================================================================
RCS file: /sources/classpath/classpath/java/awt/Graphics2D.java,v
retrieving revision 1.8
diff -u -r1.8 Graphics2D.java
--- java/awt/Graphics2D.java 2 Jul 2005 20:32:24 -0000 1.8
+++ java/awt/Graphics2D.java 15 May 2006 09:20:06 -0000
@@ -1,4 +1,4 @@
-/* Copyright (C) 2000, 2002, 2004 Free Software Foundation
+/* Copyright (C) 2000, 2002, 2004, 2006, Free Software Foundation
This file is part of GNU Classpath.
@@ -45,10 +45,36 @@
import java.awt.image.ImageObserver;
import java.awt.image.RenderedImage;
import java.awt.image.renderable.RenderableImage;
+import java.awt.print.PageFormat;
+import java.awt.print.Printable;
+import java.awt.print.PrinterJob;
import java.text.AttributedCharacterIterator;
import java.util.Map;
/**
+ * An abstract class defining a device independent two-dimensional vector
+ * graphics API. Concrete subclasses implement this API for output of
+ * vector graphics to: (*)
+ * <p>
+ * <ul>
+ * <li>a [EMAIL PROTECTED] javax.swing.JComponent} - in the
+ * [EMAIL PROTECTED] javax.swing.JComponent#paint(Graphics)} method, the
incoming
+ * [EMAIL PROTECTED] Graphics} should always be an instance of
+ * <code>Graphics2D</code> (*);</li>
+ * <li>a [EMAIL PROTECTED] BufferedImage} - see
+ * [EMAIL PROTECTED] BufferedImage#createGraphics()} (*);</li>
+ * <li>a [EMAIL PROTECTED] PrinterJob} - in the
+ * [EMAIL PROTECTED] Printable#print(Graphics, PageFormat, int)} method,
the incoming
+ * [EMAIL PROTECTED] Graphics} should always be an instance of
<code>Graphics2D</code>
+ * (*).</li>
+ * </ul>
+ * <p>
+ * (*) Support for this API is not fully implemented in GNU Classpath yet.
+ * <p>
+ * Third party libraries provide support for output to other formats via this
+ * API, including encapsulated postscript (EPS), portable document format
(PDF),
+ * and scalable vector graphics (SVG).
+ *
* @author Rolf W. Rasmussen ([EMAIL PROTECTED])
*/
public abstract class Graphics2D extends Graphics
@@ -70,6 +96,14 @@
super.fill3DRect(x, y, width, height, raised);
}
+ /**
+ * Draws an outline around a shape using the current stroke and paint.
+ *
+ * @param shape the shape (<code>null</code> not permitted).
+ *
+ * @see #getStroke()
+ * @see #getPaint()
+ */
public abstract void draw(Shape shape);
public abstract boolean drawImage(Image image, AffineTransform xform,
@@ -86,18 +120,57 @@
public abstract void drawRenderableImage(RenderableImage image,
AffineTransform xform);
+ /**
+ * Draws a string at the specified location, using the current font.
+ *
+ * @param text the string to draw.
+ * @param x the x-coordinate.
+ * @param y the y-coordinate.
+ *
+ * @see Graphics#setFont(Font)
+ */
public abstract void drawString(String text, int x, int y);
+ /**
+ * Draws a string at the specified location, using the current font.
+ *
+ * @param text the string to draw.
+ * @param x the x-coordinate.
+ * @param y the y-coordinate.
+ *
+ * @see Graphics#setFont(Font)
+ */
public abstract void drawString(String text, float x, float y);
+ /**
+ * Draws an attributed string at the specified location.
+ *
+ * @param iterator the source of the attributed text.
+ * @param x the x-coordinate.
+ * @param y the y-coordinate.
+ */
public abstract void drawString(AttributedCharacterIterator iterator,
int x, int y);
+ /**
+ * Draws an attributed string at the specified location.
+ *
+ * @param iterator the source of the attributed text.
+ * @param x the x-coordinate.
+ * @param y the y-coordinate.
+ */
public abstract void drawString(AttributedCharacterIterator iterator,
float x, float y);
- // public abstract void drawGlyphVector(GlyphVector g, float x, float y);
-
+ /**
+ * Fills the interior of the specified <code>shape</code> using the current
+ * paint.
+ *
+ * @param shape the shape to fill (<code>null</code> not permitted).
+ *
+ * @see #draw(Shape)
+ * @see #getPaint()
+ */
public abstract void fill(Shape shape);
public abstract boolean hit(Rectangle rect, Shape text,
@@ -105,21 +178,72 @@
public abstract GraphicsConfiguration getDeviceConfiguration();
+ /**
+ * Sets the current compositing rule.
+ *
+ * @param comp the composite.
+ *
+ * @see #getComposite()
+ */
public abstract void setComposite(Composite comp);
-
+
+ /**
+ * Sets the paint to be used for subsequent drawing operations.
+ *
+ * @param paint the paint (<code>null</code> not permitted).
+ *
+ * @see #getPaint()
+ */
public abstract void setPaint(Paint paint);
+ /**
+ * Sets the stroke to be used for subsequent drawing operations.
+ *
+ * @param stroke the stroke (<code>null</code> not permitted).
+ *
+ * @see #getStroke()
+ */
public abstract void setStroke(Stroke stroke);
+ /**
+ * Adds or updates a hint in the current rendering hints table.
+ *
+ * @param hintKey the hint key.
+ * @param hintValue the hint value.
+ */
public abstract void setRenderingHint(RenderingHints.Key hintKey,
Object hintValue);
+ /**
+ * Returns the current value of a rendering hint.
+ *
+ * @param hintKey the key for the hint.
+ *
+ * @return The value for the specified hint.
+ */
public abstract Object getRenderingHint(RenderingHints.Key hintKey);
+ /**
+ * Replaces the current rendering hints with the supplied hints.
+ *
+ * @param hints the hints.
+ *
+ * @see #addRenderingHints(Map)
+ */
public abstract void setRenderingHints(Map hints);
+ /**
+ * Adds/updates the rendering hint.
+ *
+ * @param hints the hints to add or update.
+ */
public abstract void addRenderingHints(Map hints);
+ /**
+ * Returns the current rendering hints.
+ *
+ * @return The current rendering hints.
+ */
public abstract RenderingHints getRenderingHints();
public abstract void translate(int x, int y);
@@ -134,25 +258,104 @@
public abstract void shear(double shearX, double shearY);
- public abstract void transform(AffineTransform Tx);
+ /**
+ * Sets the current transform to a concatenation of <code>transform</code>
+ * and the existing transform.
+ *
+ * @param transform the transform.
+ */
+ public abstract void transform(AffineTransform transform);
- public abstract void setTransform(AffineTransform Tx);
-
+ /**
+ * Sets the current transform. If the caller specifies a <code>null</code>
+ * transform, this method should set the current transform to the
+ * identity transform.
+ *
+ * @param transform the transform (<code>null</code> permitted).
+ *
+ * @see #getTransform()
+ */
+ public abstract void setTransform(AffineTransform transform);
+
+ /**
+ * Returns the current transform.
+ *
+ * @return The current transform.
+ *
+ * @see #setTransform(AffineTransform)
+ */
public abstract AffineTransform getTransform();
+ /**
+ * Returns the current paint.
+ *
+ * @return The current paint.
+ *
+ * @see #setPaint(Paint)
+ */
public abstract Paint getPaint();
+ /**
+ * Returns the current compositing rule.
+ *
+ * @return The current compositing rule.
+ *
+ * @see #setComposite(Composite)
+ */
public abstract Composite getComposite();
+ /**
+ * Sets the background color (used by the
+ * [EMAIL PROTECTED] Graphics#clearRect(int, int, int, int)} method).
+ *
+ * @param color the color.
+ *
+ * @see #getBackground()
+ */
public abstract void setBackground(Color color);
+ /**
+ * Returns the color used by the
+ * [EMAIL PROTECTED] Graphics#clearRect(int, int, int, int)} method.
+ *
+ * @return The background color.
+ *
+ * @see #setBackground(Color)
+ */
public abstract Color getBackground();
+ /**
+ * Returns the current stroke.
+ *
+ * @return The current stroke.
+ *
+ * @see #setStroke(Stroke)
+ */
public abstract Stroke getStroke();
+ /**
+ * Sets the clip region to the intersection of the current clipping region
+ * and <code>s</code>.
+ *
+ * @param s the shape to intersect with the current clipping region.
+ *
+ * @see Graphics#setClip(Shape)
+ */
public abstract void clip(Shape s);
- public abstract FontRenderContext getFontRenderContext ();
-
- public abstract void drawGlyphVector (GlyphVector g, float x, float y);
+ /**
+ * Returns the font render context.
+ *
+ * @return The font render context.
+ */
+ public abstract FontRenderContext getFontRenderContext();
+
+ /**
+ * Draws a glyph vector at the specified location.
+ *
+ * @param g the glyph vector.
+ * @param x the x-coordinate.
+ * @param y the y-coordinate.
+ */
+ public abstract void drawGlyphVector(GlyphVector g, float x, float y);
}
