Back to index...

	/*
	* Copyright (c) 2006, 2013, 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:
	* <center>
	* <img src = "doc-files/LinearGradientPaint.png"
	* alt="image showing the output of the example code">
	* </center>
	*
	* @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());
	}
	}

Back to index...