| /* | |
| * Copyright (c) 2006, 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.geom.AffineTransform; | |
| import java.awt.geom.Point2D; | |
| import java.awt.geom.Rectangle2D; | |
| import java.awt.image.ColorModel; | |
| import java.beans.ConstructorProperties; | |
| /** | |
| * The {@code LinearGradientPaint} class provides a way to fill | |
| * a {@link java.awt.Shape} with a linear color gradient pattern. The user | |
| * may specify two or more gradient colors, and this paint will provide an | |
| * interpolation between each color. The user also specifies start and end | |
| * points which define where in user space the color gradient should begin | |
| * and end. | |
| * <p> | |
| * The user must provide an array of floats specifying how to distribute the | |
| * colors along the gradient. These values should range from 0.0 to 1.0 and | |
| * act like keyframes along the gradient (they mark where the gradient should | |
| * be exactly a particular color). | |
| * <p> | |
| * In the event that the user does not set the first keyframe value equal | |
| * to 0 and/or the last keyframe value equal to 1, keyframes will be created | |
| * at these positions and the first and last colors will be replicated there. | |
| * So, if a user specifies the following arrays to construct a gradient:<br> | |
| * <pre> | |
| * {Color.BLUE, Color.RED}, {.3f, .7f} | |
| * </pre> | |
| * this will be converted to a gradient with the following keyframes:<br> | |
| * <pre> | |
| * {Color.BLUE, Color.BLUE, Color.RED, Color.RED}, {0f, .3f, .7f, 1f} | |
| * </pre> | |
| * | |
| * <p> | |
| * The user may also select what action the {@code LinearGradientPaint} object | |
| * takes when it is filling the space outside the start and end points by | |
| * setting {@code CycleMethod} to either {@code REFLECTION} or {@code REPEAT}. | |
| * The distances between any two colors in any of the reflected or repeated | |
| * copies of the gradient are the same as the distance between those same two | |
| * colors between the start and end points. | |
| * Note that some minor variations in distances may occur due to sampling at | |
| * the granularity of a pixel. | |
| * If no cycle method is specified, {@code NO_CYCLE} will be chosen by | |
| * default, which means the endpoint colors will be used to fill the | |
| * remaining area. | |
| * <p> | |
| * The colorSpace parameter allows the user to specify in which colorspace | |
| * the interpolation should be performed, default sRGB or linearized RGB. | |
| * | |
| * <p> | |
| * The following code demonstrates typical usage of | |
| * {@code LinearGradientPaint}: | |
| * <pre> | |
| * Point2D start = new Point2D.Float(0, 0); | |
| * Point2D end = new Point2D.Float(50, 50); | |
| * float[] dist = {0.0f, 0.2f, 1.0f}; | |
| * Color[] colors = {Color.RED, Color.WHITE, Color.BLUE}; | |
| * LinearGradientPaint p = | |
| * new LinearGradientPaint(start, end, dist, colors); | |
| * </pre> | |
| * <p> | |
| * This code will create a {@code LinearGradientPaint} which interpolates | |
| * between red and white for the first 20% of the gradient and between white | |
| * and blue for the remaining 80%. | |
| * | |
| * <p> | |
| * This image demonstrates the example code above for each | |
| * of the three cycle methods: | |
| * <p style="text-align:center"> | |
| * <img src = "doc-files/LinearGradientPaint.png" | |
| * alt="image showing the output of the example code"> | |
| * | |
| * @see java.awt.Paint | |
| * @see java.awt.Graphics2D#setPaint | |
| * @author Nicholas Talian, Vincent Hardy, Jim Graham, Jerry Evans | |
| * @since 1.6 | |
| */ | |
| public final class LinearGradientPaint extends MultipleGradientPaint { | |
| /** Gradient start and end points. */ | |
| private final Point2D start, end; | |
| /** | |
| * Constructs a {@code LinearGradientPaint} with a default | |
| * {@code NO_CYCLE} repeating method and {@code SRGB} color space. | |
| * | |
| * @param startX the X coordinate of the gradient axis start point | |
| * in user space | |
| * @param startY the Y coordinate of the gradient axis start point | |
| * in user space | |
| * @param endX the X coordinate of the gradient axis end point | |
| * in user space | |
| * @param endY the Y coordinate of the gradient axis end point | |
| * in user space | |
| * @param fractions numbers ranging from 0.0 to 1.0 specifying the | |
| * distribution of colors along the gradient | |
| * @param colors array of colors corresponding to each fractional value | |
| * | |
| * @throws NullPointerException | |
| * if {@code fractions} array is null, | |
| * or {@code colors} array is null, | |
| * @throws IllegalArgumentException | |
| * if start and end points are the same points, | |
| * or {@code fractions.length != colors.length}, | |
| * or {@code colors} is less than 2 in size, | |
| * or a {@code fractions} value is less than 0.0 or greater than 1.0, | |
| * or the {@code fractions} are not provided in strictly increasing order | |
| */ | |
| public LinearGradientPaint(float startX, float startY, | |
| float endX, float endY, | |
| float[] fractions, Color[] colors) | |
| { | |
| this(new Point2D.Float(startX, startY), | |
| new Point2D.Float(endX, endY), | |
| fractions, | |
| colors, | |
| CycleMethod.NO_CYCLE); | |
| } | |
| /** | |
| * Constructs a {@code LinearGradientPaint} with a default {@code SRGB} | |
| * color space. | |
| * | |
| * @param startX the X coordinate of the gradient axis start point | |
| * in user space | |
| * @param startY the Y coordinate of the gradient axis start point | |
| * in user space | |
| * @param endX the X coordinate of the gradient axis end point | |
| * in user space | |
| * @param endY the Y coordinate of the gradient axis end point | |
| * in user space | |
| * @param fractions numbers ranging from 0.0 to 1.0 specifying the | |
| * distribution of colors along the gradient | |
| * @param colors array of colors corresponding to each fractional value | |
| * @param cycleMethod either {@code NO_CYCLE}, {@code REFLECT}, | |
| * or {@code REPEAT} | |
| * | |
| * @throws NullPointerException | |
| * if {@code fractions} array is null, | |
| * or {@code colors} array is null, | |
| * or {@code cycleMethod} is null | |
| * @throws IllegalArgumentException | |
| * if start and end points are the same points, | |
| * or {@code fractions.length != colors.length}, | |
| * or {@code colors} is less than 2 in size, | |
| * or a {@code fractions} value is less than 0.0 or greater than 1.0, | |
| * or the {@code fractions} are not provided in strictly increasing order | |
| */ | |
| public LinearGradientPaint(float startX, float startY, | |
| float endX, float endY, | |
| float[] fractions, Color[] colors, | |
| CycleMethod cycleMethod) | |
| { | |
| this(new Point2D.Float(startX, startY), | |
| new Point2D.Float(endX, endY), | |
| fractions, | |
| colors, | |
| cycleMethod); | |
| } | |
| /** | |
| * Constructs a {@code LinearGradientPaint} with a default | |
| * {@code NO_CYCLE} repeating method and {@code SRGB} color space. | |
| * | |
| * @param start the gradient axis start {@code Point2D} in user space | |
| * @param end the gradient axis end {@code Point2D} in user space | |
| * @param fractions numbers ranging from 0.0 to 1.0 specifying the | |
| * distribution of colors along the gradient | |
| * @param colors array of colors corresponding to each fractional value | |
| * | |
| * @throws NullPointerException | |
| * if one of the points is null, | |
| * or {@code fractions} array is null, | |
| * or {@code colors} array is null | |
| * @throws IllegalArgumentException | |
| * if start and end points are the same points, | |
| * or {@code fractions.length != colors.length}, | |
| * or {@code colors} is less than 2 in size, | |
| * or a {@code fractions} value is less than 0.0 or greater than 1.0, | |
| * or the {@code fractions} are not provided in strictly increasing order | |
| */ | |
| public LinearGradientPaint(Point2D start, Point2D end, | |
| float[] fractions, Color[] colors) | |
| { | |
| this(start, end, | |
| fractions, colors, | |
| CycleMethod.NO_CYCLE); | |
| } | |
| /** | |
| * Constructs a {@code LinearGradientPaint} with a default {@code SRGB} | |
| * color space. | |
| * | |
| * @param start the gradient axis start {@code Point2D} in user space | |
| * @param end the gradient axis end {@code Point2D} in user space | |
| * @param fractions numbers ranging from 0.0 to 1.0 specifying the | |
| * distribution of colors along the gradient | |
| * @param colors array of colors corresponding to each fractional value | |
| * @param cycleMethod either {@code NO_CYCLE}, {@code REFLECT}, | |
| * or {@code REPEAT} | |
| * | |
| * @throws NullPointerException | |
| * if one of the points is null, | |
| * or {@code fractions} array is null, | |
| * or {@code colors} array is null, | |
| * or {@code cycleMethod} is null | |
| * @throws IllegalArgumentException | |
| * if start and end points are the same points, | |
| * or {@code fractions.length != colors.length}, | |
| * or {@code colors} is less than 2 in size, | |
| * or a {@code fractions} value is less than 0.0 or greater than 1.0, | |
| * or the {@code fractions} are not provided in strictly increasing order | |
| */ | |
| public LinearGradientPaint(Point2D start, Point2D end, | |
| float[] fractions, Color[] colors, | |
| CycleMethod cycleMethod) | |
| { | |
| this(start, end, | |
| fractions, colors, | |
| cycleMethod, | |
| ColorSpaceType.SRGB, | |
| new AffineTransform()); | |
| } | |
| /** | |
| * Constructs a {@code LinearGradientPaint}. | |
| * | |
| * @param start the gradient axis start {@code Point2D} in user space | |
| * @param end the gradient axis end {@code Point2D} in user space | |
| * @param fractions numbers ranging from 0.0 to 1.0 specifying the | |
| * distribution of colors along the gradient | |
| * @param colors array of colors corresponding to each fractional value | |
| * @param cycleMethod either {@code NO_CYCLE}, {@code REFLECT}, | |
| * or {@code REPEAT} | |
| * @param colorSpace which color space to use for interpolation, | |
| * either {@code SRGB} or {@code LINEAR_RGB} | |
| * @param gradientTransform transform to apply to the gradient | |
| * | |
| * @throws NullPointerException | |
| * if one of the points is null, | |
| * or {@code fractions} array is null, | |
| * or {@code colors} array is null, | |
| * or {@code cycleMethod} is null, | |
| * or {@code colorSpace} is null, | |
| * or {@code gradientTransform} is null | |
| * @throws IllegalArgumentException | |
| * if start and end points are the same points, | |
| * or {@code fractions.length != colors.length}, | |
| * or {@code colors} is less than 2 in size, | |
| * or a {@code fractions} value is less than 0.0 or greater than 1.0, | |
| * or the {@code fractions} are not provided in strictly increasing order | |
| */ | |
| @ConstructorProperties({ "startPoint", "endPoint", "fractions", "colors", "cycleMethod", "colorSpace", "transform" }) | |
| public LinearGradientPaint(Point2D start, Point2D end, | |
| float[] fractions, Color[] colors, | |
| CycleMethod cycleMethod, | |
| ColorSpaceType colorSpace, | |
| AffineTransform gradientTransform) | |
| { | |
| super(fractions, colors, cycleMethod, colorSpace, gradientTransform); | |
| // check input parameters | |
| if (start == null || end == null) { | |
| throw new NullPointerException("Start and end points must be" + | |
| "non-null"); | |
| } | |
| if (start.equals(end)) { | |
| throw new IllegalArgumentException("Start point cannot equal" + | |
| "endpoint"); | |
| } | |
| // copy the points... | |
| this.start = new Point2D.Double(start.getX(), start.getY()); | |
| this.end = new Point2D.Double(end.getX(), end.getY()); | |
| } | |
| /** | |
| * Creates and returns a {@link PaintContext} used to | |
| * generate a linear color gradient pattern. | |
| * See the {@link Paint#createContext specification} of the | |
| * method in the {@link Paint} interface for information | |
| * on null parameter handling. | |
| * | |
| * @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. | |
| * @param userBounds the user space bounding box | |
| * of the graphics primitive being rendered. | |
| * @param transform the {@link AffineTransform} from user | |
| * space into device space. | |
| * @param hints the set of hints that the context object can use to | |
| * choose between rendering alternatives. | |
| * @return the {@code PaintContext} for | |
| * generating color patterns. | |
| * @see Paint | |
| * @see PaintContext | |
| * @see ColorModel | |
| * @see Rectangle | |
| * @see Rectangle2D | |
| * @see AffineTransform | |
| * @see RenderingHints | |
| */ | |
| public PaintContext createContext(ColorModel cm, | |
| Rectangle deviceBounds, | |
| Rectangle2D userBounds, | |
| AffineTransform transform, | |
| RenderingHints hints) | |
| { | |
| // avoid modifying the user's transform... | |
| transform = new AffineTransform(transform); | |
| // incorporate the gradient transform | |
| transform.concatenate(gradientTransform); | |
| if ((fractions.length == 2) && | |
| (cycleMethod != CycleMethod.REPEAT) && | |
| (colorSpace == ColorSpaceType.SRGB)) | |
| { | |
| // faster to use the basic GradientPaintContext for this | |
| // common case | |
| boolean cyclic = (cycleMethod != CycleMethod.NO_CYCLE); | |
| return new GradientPaintContext(cm, start, end, | |
| transform, | |
| colors[0], colors[1], | |
| cyclic); | |
| } else { | |
| return new LinearGradientPaintContext(this, cm, | |
| deviceBounds, userBounds, | |
| transform, hints, | |
| start, end, | |
| fractions, colors, | |
| cycleMethod, colorSpace); | |
| } | |
| } | |
| /** | |
| * Returns a copy of the start point of the gradient axis. | |
| * | |
| * @return a {@code Point2D} object that is a copy of the point | |
| * that anchors the first color of this {@code LinearGradientPaint} | |
| */ | |
| public Point2D getStartPoint() { | |
| return new Point2D.Double(start.getX(), start.getY()); | |
| } | |
| /** | |
| * Returns a copy of the end point of the gradient axis. | |
| * | |
| * @return a {@code Point2D} object that is a copy of the point | |
| * that anchors the last color of this {@code LinearGradientPaint} | |
| */ | |
| public Point2D getEndPoint() { | |
| return new Point2D.Double(end.getX(), end.getY()); | |
| } | |
| } |