View Javadoc
1   /*
2    * Copyright (c) 1997, 2008, 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  
26  package java.awt;
27  
28  import java.awt.image.ColorModel;
29  import java.awt.geom.AffineTransform;
30  import java.awt.geom.Rectangle2D;
31  
32  /**
33   * This <code>Paint</code> interface defines how color patterns
34   * can be generated for {@link Graphics2D} operations.  A class
35   * implementing the <code>Paint</code> interface is added to the
36   * <code>Graphics2D</code> context in order to define the color
37   * pattern used by the <code>draw</code> and <code>fill</code> methods.
38   * <p>
39   * Instances of classes implementing <code>Paint</code> must be
40   * read-only because the <code>Graphics2D</code> does not clone
41   * these objects when they are set as an attribute with the
42   * <code>setPaint</code> method or when the <code>Graphics2D</code>
43   * object is itself cloned.
44   * @see PaintContext
45   * @see Color
46   * @see GradientPaint
47   * @see TexturePaint
48   * @see Graphics2D#setPaint
49   * @version 1.36, 06/05/07
50   */
51  
52  public interface Paint extends Transparency {
53      /**
54       * Creates and returns a {@link PaintContext} used to
55       * generate the color pattern.
56       * The arguments to this method convey additional information
57       * about the rendering operation that may be
58       * used or ignored on various implementations of the {@code Paint} interface.
59       * A caller must pass non-{@code null} values for all of the arguments
60       * except for the {@code ColorModel} argument which may be {@code null} to
61       * indicate that no specific {@code ColorModel} type is preferred.
62       * Implementations of the {@code Paint} interface are allowed to use or ignore
63       * any of the arguments as makes sense for their function, and are
64       * not constrained to use the specified {@code ColorModel} for the returned
65       * {@code PaintContext}, even if it is not {@code null}.
66       * Implementations are allowed to throw {@code NullPointerException} for
67       * any {@code null} argument other than the {@code ColorModel} argument,
68       * but are not required to do so.
69       *
70       * @param cm the preferred {@link ColorModel} which represents the most convenient
71       *           format for the caller to receive the pixel data, or {@code null}
72       *           if there is no preference.
73       * @param deviceBounds the device space bounding box
74       *                     of the graphics primitive being rendered.
75       *                     Implementations of the {@code Paint} interface
76       *                     are allowed to throw {@code NullPointerException}
77       *                     for a {@code null} {@code deviceBounds}.
78       * @param userBounds the user space bounding box
79       *                   of the graphics primitive being rendered.
80       *                     Implementations of the {@code Paint} interface
81       *                     are allowed to throw {@code NullPointerException}
82       *                     for a {@code null} {@code userBounds}.
83       * @param xform the {@link AffineTransform} from user
84       *              space into device space.
85       *                     Implementations of the {@code Paint} interface
86       *                     are allowed to throw {@code NullPointerException}
87       *                     for a {@code null} {@code xform}.
88       * @param hints the set of hints that the context object can use to
89       *              choose between rendering alternatives.
90       *                     Implementations of the {@code Paint} interface
91       *                     are allowed to throw {@code NullPointerException}
92       *                     for a {@code null} {@code hints}.
93       * @return the {@code PaintContext} for
94       *         generating color patterns.
95       * @see PaintContext
96       * @see ColorModel
97       * @see Rectangle
98       * @see Rectangle2D
99       * @see AffineTransform
100      * @see RenderingHints
101      */
102     public PaintContext createContext(ColorModel cm,
103                                       Rectangle deviceBounds,
104                                       Rectangle2D userBounds,
105                                       AffineTransform xform,
106                                       RenderingHints hints);
107 
108 }