--- a/jdk/src/share/classes/java/awt/Paint.java Mon Mar 31 15:56:12 2008 +0400
+++ b/jdk/src/share/classes/java/awt/Paint.java Fri Apr 04 20:20:16 2008 +0400
@@ -46,42 +46,58 @@
* @see GradientPaint
* @see TexturePaint
* @see Graphics2D#setPaint
+ * @version 1.36, 06/05/07
*/
public interface Paint extends Transparency {
/**
* Creates and returns a {@link PaintContext} used to
* generate the color pattern.
- * Since the ColorModel argument to createContext is only a
- * hint, implementations of Paint should accept a null argument
- * for ColorModel. Note that if the application does not
- * prefer a specific ColorModel, the null ColorModel argument
- * will give the Paint implementation full leeway in using the
- * most efficient ColorModel it prefers for its raster processing.
- * <p>
- * Since the API documentation was not specific about this in
- * releases before 1.4, there may be implementations of
- * <code>Paint</code> that do not accept a null
- * <code>ColorModel</code> argument.
- * If a developer is writing code which passes a null
- * <code>ColorModel</code> argument to the
- * <code>createContext</code> method of <code>Paint</code>
- * objects from arbitrary sources it would be wise to code defensively
- * by manufacturing a non-null <code>ColorModel</code> for those
- * objects which throw a <code>NullPointerException</code>.
- * @param cm the {@link ColorModel} that receives the
- * <code>Paint</code> data. This is used only as a hint.
+ * The arguments to this method convey additional information
+ * about the rendering operation that may be
+ * used or ignored on various implementations of the {@code Paint} interface.
+ * A caller must pass non-{@code null} values for all of the arguments
+ * except for the {@code ColorModel} argument which may be {@code null} to
+ * indicate that no specific {@code ColorModel} type is preferred.
+ * Implementations of the {@code Paint} interface are allowed to use or ignore
+ * any of the arguments as makes sense for their function, and are
+ * not constrained to use the specified {@code ColorModel} for the returned
+ * {@code PaintContext}, even if it is not {@code null}.
+ * Implementations are allowed to throw {@code NullPointerException} for
+ * any {@code null} argument other than the {@code ColorModel} argument,
+ * but are not required to do so.
+ *
+ * @param cm the preferred {@link ColorModel} which represents the most convenient
+ * format for the caller to receive the pixel data, or {@code null}
+ * if there is no preference.
* @param deviceBounds the device space bounding box
- * of the graphics primitive being rendered
+ * of the graphics primitive being rendered.
+ * Implementations of the {@code Paint} interface
+ * are allowed to throw {@code NullPointerException}
+ * for a {@code null} {@code deviceBounds}.
* @param userBounds the user space bounding box
- * of the graphics primitive being rendered
+ * of the graphics primitive being rendered.
+ * Implementations of the {@code Paint} interface
+ * are allowed to throw {@code NullPointerException}
+ * for a {@code null} {@code userBounds}.
* @param xform the {@link AffineTransform} from user
- * space into device space
- * @param hints the hint that the context object uses to
- * choose between rendering alternatives
- * @return the <code>PaintContext</code> for
- * generating color patterns
+ * space into device space.
+ * Implementations of the {@code Paint} interface
+ * are allowed to throw {@code NullPointerException}
+ * for a {@code null} {@code xform}.
+ * @param hints the set of hints that the context object can use to
+ * choose between rendering alternatives.
+ * Implementations of the {@code Paint} interface
+ * are allowed to throw {@code NullPointerException}
+ * for a {@code null} {@code hints}.
+ * @return the {@code PaintContext} for
+ * generating color patterns.
* @see PaintContext
+ * @see ColorModel
+ * @see Rectangle
+ * @see Rectangle2D
+ * @see AffineTransform
+ * @see RenderingHints
*/
public PaintContext createContext(ColorModel cm,
Rectangle deviceBounds,