LinearGradientPaint


1   /*
2    * @(#)LinearGradientPaint.java 1.3 07/05/30
3    *
4    * Copyright 2007 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package java.awt;
9   
10  import java.awt.geom.AffineTransform  ;
11  import java.awt.geom.NoninvertibleTransformException  ;
12  import java.awt.geom.Point2D  ;
13  import java.awt.geom.Rectangle2D  ;
14  import java.awt.image.ColorModel  ;
15  
16  /**
17   * The {@code LinearGradientPaint} class provides a way to fill
18   * a {@link java.awt.Shape} with a linear color gradient pattern.  The user
19   * may specify two or more gradient colors, and this paint will provide an
20   * interpolation between each color.  The user also specifies start and end
21   * points which define where in user space the color gradient should begin 
22   * and end.
23   * <p>
24   * The user must provide an array of floats specifying how to distribute the
25   * colors along the gradient.  These values should range from 0.0 to 1.0 and 
26   * act like keyframes along the gradient (they mark where the gradient should 
27   * be exactly a particular color).
28   * <p>
29   * In the event that the user does not set the first keyframe value equal
30   * to 0 and/or the last keyframe value equal to 1, keyframes will be created
31   * at these positions and the first and last colors will be replicated there.
32   * So, if a user specifies the following arrays to construct a gradient:<br>
33   * <pre>
34   *     {Color.BLUE, Color.RED}, {.3f, .7f}
35   * </pre>
36   * this will be converted to a gradient with the following keyframes:<br>
37   * <pre>
38   *     {Color.BLUE, Color.BLUE, Color.RED, Color.RED}, {0f, .3f, .7f, 1f}
39   * </pre>
40   *
41   * <p>
42   * The user may also select what action the {@code LinearGradientPaint}
43   * should take when filling color outside the start and end points.
44   * If no cycle method is specified, {@code NO_CYCLE} will be chosen by
45   * default, which means the endpoint colors will be used to fill the
46   * remaining area.
47   * <p>
48   * The colorSpace parameter allows the user to specify in which colorspace
49   * the interpolation should be performed, default sRGB or linearized RGB.
50   *
51   * <p>
52   * The following code demonstrates typical usage of
53   * {@code LinearGradientPaint}:
54   * <p>
55   * <pre>
56   *     Point2D start = new Point2D.Float(0, 0);
57   *     Point2D end = new Point2D.Float(50, 50);
58   *     float[] dist = {0.0f, 0.2f, 1.0f};
59   *     Color[] colors = {Color.RED, Color.WHITE, Color.BLUE};
60   *     LinearGradientPaint p =
61   *         new LinearGradientPaint(start, end, dist, colors);
62   * </pre>
63   * <p>
64   * This code will create a {@code LinearGradientPaint} which interpolates
65   * between red and white for the first 20% of the gradient and between white
66   * and blue for the remaining 80%.
67   *
68   * <p>
69   * This image demonstrates the example code above for each
70   * of the three cycle methods:
71   * <p>
72   * <center>
73   * <img src = "doc-files/LinearGradientPaint.png">
74   * </center>
75   *  
76   * @see java.awt.Paint
77   * @see java.awt.Graphics2D#setPaint
78   * @author Nicholas Talian, Vincent Hardy, Jim Graham, Jerry Evans
79   * @since 1.6
80   */
81  public final class LinearGradientPaint extends MultipleGradientPaint   {
82  
83      /** Gradient start and end points. */
84      private final Point2D   start, end;
85         
86      /**
87       * Constructs a {@code LinearGradientPaint} with a default 
88       * {@code NO_CYCLE} repeating method and {@code SRGB} color space.
89       *
90       * @param startX the X coordinate of the gradient axis start point 
91       *               in user space
92       * @param startY the Y coordinate of the gradient axis start point 
93       *               in user space
94       * @param endX   the X coordinate of the gradient axis end point 
95       *               in user space
96       * @param endY   the Y coordinate of the gradient axis end point 
97       *               in user space
98       * @param fractions numbers ranging from 0.0 to 1.0 specifying the 
99       *                  distribution of colors along the gradient
100      * @param colors array of colors corresponding to each fractional value
101      *     
102      * @throws NullPointerException
103      * if {@code fractions} array is null,
104      * or {@code colors} array is null,
105      * @throws IllegalArgumentException
106      * if start and end points are the same points,
107      * or {@code fractions.length != colors.length},
108      * or {@code colors} is less than 2 in size,
109      * or a {@code fractions} value is less than 0.0 or greater than 1.0,
110      * or the {@code fractions} are not provided in strictly increasing order
111      */
112     public LinearGradientPaint(float startX, float startY, 
113                                float endX, float endY, 
114                                float[] fractions, Color  [] colors)
115     {
116         this(new Point2D.Float  (startX, startY),
117              new Point2D.Float  (endX, endY), 
118              fractions, 
119              colors,
120              CycleMethod.NO_CYCLE);
121     }
122 
123     /**
124      * Constructs a {@code LinearGradientPaint} with a default {@code SRGB}
125      * color space.
126      *
127      * @param startX the X coordinate of the gradient axis start point 
128      *               in user space
129      * @param startY the Y coordinate of the gradient axis start point 
130      *               in user space
131      * @param endX   the X coordinate of the gradient axis end point 
132      *               in user space
133      * @param endY   the Y coordinate of the gradient axis end point 
134      *               in user space
135      * @param fractions numbers ranging from 0.0 to 1.0 specifying the 
136      *                  distribution of colors along the gradient
137      * @param colors array of colors corresponding to each fractional value
138      * @param cycleMethod either {@code NO_CYCLE}, {@code REFLECT},
139      *                    or {@code REPEAT}
140      *
141      * @throws NullPointerException
142      * if {@code fractions} array is null,
143      * or {@code colors} array is null,
144      * or {@code cycleMethod} is null
145      * @throws IllegalArgumentException
146      * if start and end points are the same points,
147      * or {@code fractions.length != colors.length},
148      * or {@code colors} is less than 2 in size,
149      * or a {@code fractions} value is less than 0.0 or greater than 1.0,
150      * or the {@code fractions} are not provided in strictly increasing order
151      */
152     public LinearGradientPaint(float startX, float startY, 
153                                float endX, float endY, 
154                                float[] fractions, Color  [] colors, 
155                                CycleMethod cycleMethod)
156     {
157         this(new Point2D.Float  (startX, startY), 
158              new Point2D.Float  (endX, endY), 
159              fractions, 
160              colors,
161              cycleMethod);
162     }
163 
164     /**
165      * Constructs a {@code LinearGradientPaint} with a default 
166      * {@code NO_CYCLE} repeating method and {@code SRGB} color space.
167      *
168      * @param start the gradient axis start {@code Point2D} in user space
169      * @param end the gradient axis end {@code Point2D} in user space
170      * @param fractions numbers ranging from 0.0 to 1.0 specifying the 
171      *                  distribution of colors along the gradient
172      * @param colors array of colors corresponding to each fractional value
173      *
174      * @throws NullPointerException
175      * if one of the points is null,
176      * or {@code fractions} array is null,
177      * or {@code colors} array is null
178      * @throws IllegalArgumentException
179      * if start and end points are the same points,
180      * or {@code fractions.length != colors.length},
181      * or {@code colors} is less than 2 in size,
182      * or a {@code fractions} value is less than 0.0 or greater than 1.0,
183      * or the {@code fractions} are not provided in strictly increasing order
184      */
185     public LinearGradientPaint(Point2D   start, Point2D   end,
186                                float[] fractions, Color  [] colors)
187     {
188         this(start, end,
189              fractions, colors,
190              CycleMethod.NO_CYCLE);
191     }
192     
193     /**
194      * Constructs a {@code LinearGradientPaint} with a default {@code SRGB}
195      * color space.
196      *
197      * @param start the gradient axis start {@code Point2D} in user space
198      * @param end the gradient axis end {@code Point2D} in user space
199      * @param fractions numbers ranging from 0.0 to 1.0 specifying the 
200      *                  distribution of colors along the gradient
201      * @param colors array of colors corresponding to each fractional value
202      * @param cycleMethod either {@code NO_CYCLE}, {@code REFLECT},
203      *                    or {@code REPEAT}
204      *   
205      * @throws NullPointerException
206      * if one of the points is null,
207      * or {@code fractions} array is null,
208      * or {@code colors} array is null,
209      * or {@code cycleMethod} is null
210      * @throws IllegalArgumentException
211      * if start and end points are the same points,
212      * or {@code fractions.length != colors.length},
213      * or {@code colors} is less than 2 in size,
214      * or a {@code fractions} value is less than 0.0 or greater than 1.0,
215      * or the {@code fractions} are not provided in strictly increasing order
216      */
217     public LinearGradientPaint(Point2D   start, Point2D   end,
218                                float[] fractions, Color  [] colors, 
219                                CycleMethod cycleMethod)
220     {
221         this(start, end,
222              fractions, colors,
223              cycleMethod,
224              ColorSpaceType.SRGB,
225              new AffineTransform  ());
226     }
227     
228     /**
229      * Constructs a {@code LinearGradientPaint}.
230      *
231      * @param start the gradient axis start {@code Point2D} in user space
232      * @param end the gradient axis end {@code Point2D} in user space
233      * @param fractions numbers ranging from 0.0 to 1.0 specifying the 
234      *                  distribution of colors along the gradient
235      * @param colors array of colors corresponding to each fractional value
236      * @param cycleMethod either {@code NO_CYCLE}, {@code REFLECT},
237      *                    or {@code REPEAT}
238      * @param colorSpace which color space to use for interpolation, 
239      *                   either {@code SRGB} or {@code LINEAR_RGB}
240      * @param gradientTransform transform to apply to the gradient
241      *     
242      * @throws NullPointerException
243      * if one of the points is null,
244      * or {@code fractions} array is null,
245      * or {@code colors} array is null,
246      * or {@code cycleMethod} is null,
247      * or {@code colorSpace} is null,
248      * or {@code gradientTransform} is null
249      * @throws IllegalArgumentException
250      * if start and end points are the same points,
251      * or {@code fractions.length != colors.length},
252      * or {@code colors} is less than 2 in size,
253      * or a {@code fractions} value is less than 0.0 or greater than 1.0,
254      * or the {@code fractions} are not provided in strictly increasing order
255      */
256     public LinearGradientPaint(Point2D   start, Point2D   end,
257                                float[] fractions, Color  [] colors,
258                                CycleMethod cycleMethod, 
259                                ColorSpaceType colorSpace, 
260                                AffineTransform   gradientTransform)
261     {
262         super(fractions, colors, cycleMethod, colorSpace, gradientTransform);
263 
264         // check input parameters
265         if (start == null || end == null) {
266             throw new NullPointerException  ("Start and end points must be" +
267                                            "non-null");
268         }
269 
270         if (start.equals(end)) {
271             throw new IllegalArgumentException  ("Start point cannot equal" +
272                                                "endpoint");
273         }
274 
275         // copy the points...
276         this.start = new Point2D.Double  (start.getX(), start.getY());
277         this.end = new Point2D.Double  (end.getX(), end.getY());
278     }
279 
280     /**
281      * {@inheritDoc}
282      */
283     public PaintContext   createContext(ColorModel   cm,
284                                       Rectangle   deviceBounds,
285                                       Rectangle2D   userBounds,
286                                       AffineTransform   transform,
287                                       RenderingHints   hints)
288     {
289         // avoid modifying the user's transform...
290         transform = new AffineTransform  (transform);
291         // incorporate the gradient transform
292         transform.concatenate(gradientTransform); 
293 
294         if ((fractions.length == 2) &&
295             (cycleMethod != CycleMethod.REPEAT) &&
296             (colorSpace == ColorSpaceType.SRGB))
297         {
298             // faster to use the basic GradientPaintContext for this
299             // common case
300             boolean cyclic = (cycleMethod != CycleMethod.NO_CYCLE);
301             return new GradientPaintContext  (cm, start, end,
302                                             transform,
303                                             colors[0], colors[1],
304                                             cyclic);
305         } else {
306             return new LinearGradientPaintContext  (this, cm,
307                                                   deviceBounds, userBounds,
308                                                   transform, hints,
309                                                   start, end,
310                                                   fractions, colors,
311                                                   cycleMethod, colorSpace);
312         }
313     }
314     
315     /**
316      * Returns a copy of the start point of the gradient axis.
317      *
318      * @return a {@code Point2D} object that is a copy of the point
319      * that anchors the first color of this {@code LinearGradientPaint}
320      */
321     public Point2D   getStartPoint() {
322         return new Point2D.Double  (start.getX(), start.getY());
323     }
324     
325     /**
326      * Returns a copy of the end point of the gradient axis.
327      *
328      * @return a {@code Point2D} object that is a copy of the point
329      * that anchors the last color of this {@code LinearGradientPaint}
330      */
331     public Point2D   getEndPoint() {
332         return new Point2D.Double  (end.getX(), end.getY());
333     }
334 }
335
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags