awt/java/awt/GradientPaint.java

/*
 *  Licensed to the Apache Software Foundation (ASF) under one or more
 *  contributor license agreements.  See the NOTICE file distributed with
 *  this work for additional information regarding copyright ownership.
 *  The ASF licenses this file to You under the Apache License, Version 2.0
 *  (the "License"); you may not use this file except in compliance with
 *  the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */

package java.awt;

import java.awt.geom.AffineTransform;
import java.awt.geom.Point2D;
import java.awt.geom.Rectangle2D;
import java.awt.image.ColorModel;

import org.apache.harmony.awt.internal.nls.Messages;

/**
 * The GradientPaint class defines a way to fill a Shape with a linear color
 * gradient pattern. 
 * <p>
 * The GradientPaint's fill pattern is determined by two points and two colors, 
 * plus the cyclic mode option.
 * Each of the two points is painted with its corresponding color, and on 
 * the line segment connecting the two points, the color is proportionally
 * changed between the two colors. For points on the same line which are not 
 * between the two specified points (outside of the connecting segment) their
 * color is determined by the cyclic mode option. If the mode is cyclic, then
 * the rest of the line repeats the color pattern of the connecting segment, 
 * cycling back and forth between the two colors. If not, the mode is acyclic 
 * which means that all points 
 * on the line outside the connecting line segment are given the same 
 * color as the closest of the two specified points.
 * <p>
 * The color of points that are not on the line connecting the two 
 * specified points are given by perpendicular projection: by taking 
 * the set of lines perpendicular to the connecting line and for each 
 * one, the whole line is colored with the same color.
 */
public class GradientPaint implements Paint {
    
    /** The start point color. */
    Color color1;

    /** The end color point. */
    Color color2;

    /** The location of the start point. */
    Point2D point1;

    /** The location of the end point. */
    Point2D point2;

    /** The indicator of cycle filling. If TRUE filling 
     * repeated outside points stripe, if FALSE solid color filling outside. */
    boolean cyclic;

    /**
     * Instantiates a new GradientPaint with cyclic or acyclic mode.
     * 
     * @param point1 the first specified point.
     * @param color1 the Color of the first specified point. 
     * @param point2 the second specified point.
     * @param color2 the Color of the second specified point.
     * @param cyclic the cyclic mode - true if the gradient pattern should cycle 
     * repeatedly between the two colors; false otherwise.
     */
    public GradientPaint(Point2D point1, Color color1, Point2D point2,
            Color color2, boolean cyclic) {
        if (point1 == null || point2 == null) {
            // awt.6D=Point is null
            throw new NullPointerException(Messages.getString("awt.6D")); //$NON-NLS-1$
        }
        if (color1 == null || color2 == null) {
            // awt.6E=Color is null
            throw new NullPointerException(Messages.getString("awt.6E")); //$NON-NLS-1$
        }

        this.point1 = point1;
        this.point2 = point2;
        this.color1 = color1;
        this.color2 = color2;
        this.cyclic = cyclic;
    }

    /**
     * Instantiates a new GradientPaint with cyclic or acyclic mode;
     * points are specified by coordinates.
     * 
     * @param x1 the X coordinate of the first point.
     * @param y1 the Y coordinate of the first point.
     * @param color1 the color of the first point.
     * @param x2 the X coordinate of the second point.
     * @param y2 the Y coordinate of the second point.
     * @param color2 the color of the second point.
     * @param cyclic the cyclic mode - true if the gradient pattern should cycle 
     * repeatedly between the two colors; false otherwise.
     */
    public GradientPaint(float x1, float y1, Color color1, float x2, float y2, Color color2,
            boolean cyclic) {
        this(new Point2D.Float(x1, y1), color1, new Point2D.Float(x2, y2), color2, cyclic);
    }

    /**
     * Instantiates a new acyclic GradientPaint;
     * points are specified by coordinates.
     * 
     * @param x1 the X coordinate of the first point.
     * @param y1 the Y coordinate of the first point.
     * @param color1 the color of the first point.
     * @param x2 the X coordinate of the second point.
     * @param y2 the Y coordinate of the second point.
     * @param color2 the color of the second point.
     */
    public GradientPaint(float x1, float y1, Color color1, float x2, float y2, Color color2) {
        this(x1, y1, color1, x2, y2, color2, false);
    }

    /**
     * Instantiates a new acyclic GradientPaint.
     * 
     * @param point1 the first specified point.
     * @param color1 the Color of the first specified point. 
     * @param point2 the second specified point.
     * @param color2 the Color of the second specified point.
     */
    public GradientPaint(Point2D point1, Color color1, Point2D point2, Color color2) {
        this(point1, color1, point2, color2, false);
    }

    /**
     * Creates PaintContext for a color pattern generating. 
     * 
     * @param cm the ColorModel of the Paint data.
     * @param deviceBounds the bounding Rectangle of graphics primitives
     * being rendered in the device space. 
     * @param userBounds tthe bounding Rectangle of graphics primitives
     * being rendered in the user space. 
     * @param t the AffineTransform from user space into device space.
     * @param hints the RrenderingHints object.
     * 
     * @return the PaintContext for color pattern generating.
     * 
     * @see java.awt.Paint#createContext(java.awt.image.ColorModel, java.awt.Rectangle, java.awt.geom.Rectangle2D, java.awt.geom.AffineTransform, java.awt.RenderingHints)
     */
    public PaintContext createContext(ColorModel cm, Rectangle deviceBounds,
            Rectangle2D userBounds, AffineTransform t, RenderingHints hints) {
        return new GradientPaintContext(cm, t, point1, color1, point2, color2, cyclic);
    }

    /**
     * Gets the color of the first point.
     * 
     * @return the color of the first point.
     */
    public Color getColor1() {
        return color1;
    }

    /**
     * Gets the color of the second point.
     * 
     * @return the color of the second point.
     */
    public Color getColor2() {
        return color2;
    }

    /**
     * Gets the first point.
     * 
     * @return the Point object - the first point. 
     */
    public Point2D getPoint1() {
        return point1;
    }

    /**
     * Gets the second point.
     * 
     * @return the Point object - the second point.
     */
    public Point2D getPoint2() {
        return point2;
    }

    /**
     * Gets the transparency mode for the GradientPaint.
     * 
     * @return the transparency mode for the GradientPaint.
     * 
     * @see java.awt.Transparency#getTransparency()
     */
    public int getTransparency() {
        int a1 = color1.getAlpha();
        int a2 = color2.getAlpha();
        return (a1 == 0xFF && a2 == 0xFF) ? OPAQUE : TRANSLUCENT;
    }

    /**
     * Returns the GradientPaint mode: true for cyclic mode, false for
     * acyclic mode.
     * 
     * @return true if the gradient cycles repeatedly between the two colors; 
     * false otherwise.
     */
    public boolean isCyclic() {
        return cyclic;
    }
}