Home » openjdk-7 » java » awt » [javadoc | source]

    1   /*
    2    * Copyright (c) 2006, 2011, 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.geom.AffineTransform;
   29   import java.awt.geom.Point2D;
   30   import java.awt.geom.Rectangle2D;
   31   import java.awt.image.ColorModel;
   32   import java.beans.ConstructorProperties;
   33   
   34   /**
   35    * The {@code LinearGradientPaint} class provides a way to fill
   36    * a {@link java.awt.Shape} with a linear color gradient pattern.  The user
   37    * may specify two or more gradient colors, and this paint will provide an
   38    * interpolation between each color.  The user also specifies start and end
   39    * points which define where in user space the color gradient should begin
   40    * and end.
   41    * <p>
   42    * The user must provide an array of floats specifying how to distribute the
   43    * colors along the gradient.  These values should range from 0.0 to 1.0 and
   44    * act like keyframes along the gradient (they mark where the gradient should
   45    * be exactly a particular color).
   46    * <p>
   47    * In the event that the user does not set the first keyframe value equal
   48    * to 0 and/or the last keyframe value equal to 1, keyframes will be created
   49    * at these positions and the first and last colors will be replicated there.
   50    * So, if a user specifies the following arrays to construct a gradient:<br>
   51    * <pre>
   52    *     {Color.BLUE, Color.RED}, {.3f, .7f}
   53    * </pre>
   54    * this will be converted to a gradient with the following keyframes:<br>
   55    * <pre>
   56    *     {Color.BLUE, Color.BLUE, Color.RED, Color.RED}, {0f, .3f, .7f, 1f}
   57    * </pre>
   58    *
   59    * <p>
   60    * The user may also select what action the {@code LinearGradientPaint} object
   61    * takes when it is filling the space outside the start and end points by
   62    * setting {@code CycleMethod} to either {@code REFLECTION} or {@code REPEAT}.
   63    * The distances between any two colors in any of the reflected or repeated
   64    * copies of the gradient are the same as the distance between those same two
   65    * colors between the start and end points.
   66    * Note that some minor variations in distances may occur due to sampling at
   67    * the granularity of a pixel.
   68    * If no cycle method is specified, {@code NO_CYCLE} will be chosen by
   69    * default, which means the endpoint colors will be used to fill the
   70    * remaining area.
   71    * <p>
   72    * The colorSpace parameter allows the user to specify in which colorspace
   73    * the interpolation should be performed, default sRGB or linearized RGB.
   74    *
   75    * <p>
   76    * The following code demonstrates typical usage of
   77    * {@code LinearGradientPaint}:
   78    * <p>
   79    * <pre>
   80    *     Point2D start = new Point2D.Float(0, 0);
   81    *     Point2D end = new Point2D.Float(50, 50);
   82    *     float[] dist = {0.0f, 0.2f, 1.0f};
   83    *     Color[] colors = {Color.RED, Color.WHITE, Color.BLUE};
   84    *     LinearGradientPaint p =
   85    *         new LinearGradientPaint(start, end, dist, colors);
   86    * </pre>
   87    * <p>
   88    * This code will create a {@code LinearGradientPaint} which interpolates
   89    * between red and white for the first 20% of the gradient and between white
   90    * and blue for the remaining 80%.
   91    *
   92    * <p>
   93    * This image demonstrates the example code above for each
   94    * of the three cycle methods:
   95    * <p>
   96    * <center>
   97    * <img src = "doc-files/LinearGradientPaint.png">
   98    * </center>
   99    *
  100    * @see java.awt.Paint
  101    * @see java.awt.Graphics2D#setPaint
  102    * @author Nicholas Talian, Vincent Hardy, Jim Graham, Jerry Evans
  103    * @since 1.6
  104    */
  105   public final class LinearGradientPaint extends MultipleGradientPaint {
  106   
  107       /** Gradient start and end points. */
  108       private final Point2D start, end;
  109   
  110       /**
  111        * Constructs a {@code LinearGradientPaint} with a default
  112        * {@code NO_CYCLE} repeating method and {@code SRGB} color space.
  113        *
  114        * @param startX the X coordinate of the gradient axis start point
  115        *               in user space
  116        * @param startY the Y coordinate of the gradient axis start point
  117        *               in user space
  118        * @param endX   the X coordinate of the gradient axis end point
  119        *               in user space
  120        * @param endY   the Y coordinate of the gradient axis end point
  121        *               in user space
  122        * @param fractions numbers ranging from 0.0 to 1.0 specifying the
  123        *                  distribution of colors along the gradient
  124        * @param colors array of colors corresponding to each fractional value
  125        *
  126        * @throws NullPointerException
  127        * if {@code fractions} array is null,
  128        * or {@code colors} array is null,
  129        * @throws IllegalArgumentException
  130        * if start and end points are the same points,
  131        * or {@code fractions.length != colors.length},
  132        * or {@code colors} is less than 2 in size,
  133        * or a {@code fractions} value is less than 0.0 or greater than 1.0,
  134        * or the {@code fractions} are not provided in strictly increasing order
  135        */
  136       public LinearGradientPaint(float startX, float startY,
  137                                  float endX, float endY,
  138                                  float[] fractions, Color[] colors)
  139       {
  140           this(new Point2D.Float(startX, startY),
  141                new Point2D.Float(endX, endY),
  142                fractions,
  143                colors,
  144                CycleMethod.NO_CYCLE);
  145       }
  146   
  147       /**
  148        * Constructs a {@code LinearGradientPaint} with a default {@code SRGB}
  149        * color space.
  150        *
  151        * @param startX the X coordinate of the gradient axis start point
  152        *               in user space
  153        * @param startY the Y coordinate of the gradient axis start point
  154        *               in user space
  155        * @param endX   the X coordinate of the gradient axis end point
  156        *               in user space
  157        * @param endY   the Y coordinate of the gradient axis end point
  158        *               in user space
  159        * @param fractions numbers ranging from 0.0 to 1.0 specifying the
  160        *                  distribution of colors along the gradient
  161        * @param colors array of colors corresponding to each fractional value
  162        * @param cycleMethod either {@code NO_CYCLE}, {@code REFLECT},
  163        *                    or {@code REPEAT}
  164        *
  165        * @throws NullPointerException
  166        * if {@code fractions} array is null,
  167        * or {@code colors} array is null,
  168        * or {@code cycleMethod} is null
  169        * @throws IllegalArgumentException
  170        * if start and end points are the same points,
  171        * or {@code fractions.length != colors.length},
  172        * or {@code colors} is less than 2 in size,
  173        * or a {@code fractions} value is less than 0.0 or greater than 1.0,
  174        * or the {@code fractions} are not provided in strictly increasing order
  175        */
  176       public LinearGradientPaint(float startX, float startY,
  177                                  float endX, float endY,
  178                                  float[] fractions, Color[] colors,
  179                                  CycleMethod cycleMethod)
  180       {
  181           this(new Point2D.Float(startX, startY),
  182                new Point2D.Float(endX, endY),
  183                fractions,
  184                colors,
  185                cycleMethod);
  186       }
  187   
  188       /**
  189        * Constructs a {@code LinearGradientPaint} with a default
  190        * {@code NO_CYCLE} repeating method and {@code SRGB} color space.
  191        *
  192        * @param start the gradient axis start {@code Point2D} in user space
  193        * @param end the gradient axis end {@code Point2D} in user space
  194        * @param fractions numbers ranging from 0.0 to 1.0 specifying the
  195        *                  distribution of colors along the gradient
  196        * @param colors array of colors corresponding to each fractional value
  197        *
  198        * @throws NullPointerException
  199        * if one of the points is null,
  200        * or {@code fractions} array is null,
  201        * or {@code colors} array is null
  202        * @throws IllegalArgumentException
  203        * if start and end points are the same points,
  204        * or {@code fractions.length != colors.length},
  205        * or {@code colors} is less than 2 in size,
  206        * or a {@code fractions} value is less than 0.0 or greater than 1.0,
  207        * or the {@code fractions} are not provided in strictly increasing order
  208        */
  209       public LinearGradientPaint(Point2D start, Point2D end,
  210                                  float[] fractions, Color[] colors)
  211       {
  212           this(start, end,
  213                fractions, colors,
  214                CycleMethod.NO_CYCLE);
  215       }
  216   
  217       /**
  218        * Constructs a {@code LinearGradientPaint} with a default {@code SRGB}
  219        * color space.
  220        *
  221        * @param start the gradient axis start {@code Point2D} in user space
  222        * @param end the gradient axis end {@code Point2D} in user space
  223        * @param fractions numbers ranging from 0.0 to 1.0 specifying the
  224        *                  distribution of colors along the gradient
  225        * @param colors array of colors corresponding to each fractional value
  226        * @param cycleMethod either {@code NO_CYCLE}, {@code REFLECT},
  227        *                    or {@code REPEAT}
  228        *
  229        * @throws NullPointerException
  230        * if one of the points is null,
  231        * or {@code fractions} array is null,
  232        * or {@code colors} array is null,
  233        * or {@code cycleMethod} is null
  234        * @throws IllegalArgumentException
  235        * if start and end points are the same points,
  236        * or {@code fractions.length != colors.length},
  237        * or {@code colors} is less than 2 in size,
  238        * or a {@code fractions} value is less than 0.0 or greater than 1.0,
  239        * or the {@code fractions} are not provided in strictly increasing order
  240        */
  241       public LinearGradientPaint(Point2D start, Point2D end,
  242                                  float[] fractions, Color[] colors,
  243                                  CycleMethod cycleMethod)
  244       {
  245           this(start, end,
  246                fractions, colors,
  247                cycleMethod,
  248                ColorSpaceType.SRGB,
  249                new AffineTransform());
  250       }
  251   
  252       /**
  253        * Constructs a {@code LinearGradientPaint}.
  254        *
  255        * @param start the gradient axis start {@code Point2D} in user space
  256        * @param end the gradient axis end {@code Point2D} in user space
  257        * @param fractions numbers ranging from 0.0 to 1.0 specifying the
  258        *                  distribution of colors along the gradient
  259        * @param colors array of colors corresponding to each fractional value
  260        * @param cycleMethod either {@code NO_CYCLE}, {@code REFLECT},
  261        *                    or {@code REPEAT}
  262        * @param colorSpace which color space to use for interpolation,
  263        *                   either {@code SRGB} or {@code LINEAR_RGB}
  264        * @param gradientTransform transform to apply to the gradient
  265        *
  266        * @throws NullPointerException
  267        * if one of the points is null,
  268        * or {@code fractions} array is null,
  269        * or {@code colors} array is null,
  270        * or {@code cycleMethod} is null,
  271        * or {@code colorSpace} is null,
  272        * or {@code gradientTransform} is null
  273        * @throws IllegalArgumentException
  274        * if start and end points are the same points,
  275        * or {@code fractions.length != colors.length},
  276        * or {@code colors} is less than 2 in size,
  277        * or a {@code fractions} value is less than 0.0 or greater than 1.0,
  278        * or the {@code fractions} are not provided in strictly increasing order
  279        */
  280       @ConstructorProperties({ "startPoint", "endPoint", "fractions", "colors", "cycleMethod", "colorSpace", "transform" })
  281       public LinearGradientPaint(Point2D start, Point2D end,
  282                                  float[] fractions, Color[] colors,
  283                                  CycleMethod cycleMethod,
  284                                  ColorSpaceType colorSpace,
  285                                  AffineTransform gradientTransform)
  286       {
  287           super(fractions, colors, cycleMethod, colorSpace, gradientTransform);
  288   
  289           // check input parameters
  290           if (start == null || end == null) {
  291               throw new NullPointerException("Start and end points must be" +
  292                                              "non-null");
  293           }
  294   
  295           if (start.equals(end)) {
  296               throw new IllegalArgumentException("Start point cannot equal" +
  297                                                  "endpoint");
  298           }
  299   
  300           // copy the points...
  301           this.start = new Point2D.Double(start.getX(), start.getY());
  302           this.end = new Point2D.Double(end.getX(), end.getY());
  303       }
  304   
  305       /**
  306        * Creates and returns a {@link PaintContext} used to
  307        * generate a linear color gradient pattern.
  308        * See the {@link Paint#createContext specification} of the
  309        * method in the {@link Paint} interface for information
  310        * on null parameter handling.
  311        *
  312        * @param cm the preferred {@link ColorModel} which represents the most convenient
  313        *           format for the caller to receive the pixel data, or {@code null}
  314        *           if there is no preference.
  315        * @param deviceBounds the device space bounding box
  316        *                     of the graphics primitive being rendered.
  317        * @param userBounds the user space bounding box
  318        *                   of the graphics primitive being rendered.
  319        * @param transform the {@link AffineTransform} from user
  320        *              space into device space.
  321        * @param hints the set of hints that the context object can use to
  322        *              choose between rendering alternatives.
  323        * @return the {@code PaintContext} for
  324        *         generating color patterns.
  325        * @see Paint
  326        * @see PaintContext
  327        * @see ColorModel
  328        * @see Rectangle
  329        * @see Rectangle2D
  330        * @see AffineTransform
  331        * @see RenderingHints
  332        */
  333       public PaintContext createContext(ColorModel cm,
  334                                         Rectangle deviceBounds,
  335                                         Rectangle2D userBounds,
  336                                         AffineTransform transform,
  337                                         RenderingHints hints)
  338       {
  339           // avoid modifying the user's transform...
  340           transform = new AffineTransform(transform);
  341           // incorporate the gradient transform
  342           transform.concatenate(gradientTransform);
  343   
  344           if ((fractions.length == 2) &&
  345               (cycleMethod != CycleMethod.REPEAT) &&
  346               (colorSpace == ColorSpaceType.SRGB))
  347           {
  348               // faster to use the basic GradientPaintContext for this
  349               // common case
  350               boolean cyclic = (cycleMethod != CycleMethod.NO_CYCLE);
  351               return new GradientPaintContext(cm, start, end,
  352                                               transform,
  353                                               colors[0], colors[1],
  354                                               cyclic);
  355           } else {
  356               return new LinearGradientPaintContext(this, cm,
  357                                                     deviceBounds, userBounds,
  358                                                     transform, hints,
  359                                                     start, end,
  360                                                     fractions, colors,
  361                                                     cycleMethod, colorSpace);
  362           }
  363       }
  364   
  365       /**
  366        * Returns a copy of the start point of the gradient axis.
  367        *
  368        * @return a {@code Point2D} object that is a copy of the point
  369        * that anchors the first color of this {@code LinearGradientPaint}
  370        */
  371       public Point2D getStartPoint() {
  372           return new Point2D.Double(start.getX(), start.getY());
  373       }
  374   
  375       /**
  376        * Returns a copy of the end point of the gradient axis.
  377        *
  378        * @return a {@code Point2D} object that is a copy of the point
  379        * that anchors the last color of this {@code LinearGradientPaint}
  380        */
  381       public Point2D getEndPoint() {
  382           return new Point2D.Double(end.getX(), end.getY());
  383       }
  384   }

Home » openjdk-7 » java » awt » [javadoc | source]