juce/source/src/gui/graphics/colour/juce_ColourGradient.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library - "Jules' Utility Class Extensions"
   5    Copyright 2004-11 by Raw Material Software Ltd.
   6
   7   ------------------------------------------------------------------------------
   8
   9    JUCE can be redistributed and/or modified under the terms of the GNU General
  10    Public License (Version 2), as published by the Free Software Foundation.
  11    A copy of the license is included in the JUCE distribution, or can be found
  12    online at www.gnu.org/licenses.
  13
  14    JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
  15    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  16    A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  17
  18   ------------------------------------------------------------------------------
  19
  20    To release a closed-source product which uses JUCE, commercial licenses are
  21    available: visit www.rawmaterialsoftware.com/juce for more information.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef __JUCE_COLOURGRADIENT_JUCEHEADER__
  27 #define __JUCE_COLOURGRADIENT_JUCEHEADER__
  28
  29 #include "juce_Colour.h"
  30 #include "../geometry/juce_Point.h"
  31 #include "../../../containers/juce_Array.h"
  32 #include "../../../memory/juce_HeapBlock.h"
  33
  34
  35 //==============================================================================
  36 /**
  37     Describes the layout and colours that should be used to paint a colour gradient.
  38
  39     @see Graphics::setGradientFill
  40 */
  41 class JUCE_API  ColourGradient
  42 {
  43 public:
  44     //==============================================================================
  45     /** Creates a gradient object.
  46
  47         (x1, y1) is the location to draw with colour1. Likewise (x2, y2) is where
  48         colour2 should be. In between them there's a gradient.
  49
  50         If isRadial is true, the colours form a circular gradient with (x1, y1) at
  51         its centre.
  52
  53         The alpha transparencies of the colours are used, so note that
  54         if you blend from transparent to a solid colour, the RGB of the transparent
  55         colour will become visible in parts of the gradient. e.g. blending
  56         from Colour::transparentBlack to Colours::white will produce a
  57         muddy grey colour midway, but Colour::transparentWhite to Colours::white
  58         will be white all the way across.
  59
  60         @see ColourGradient
  61     */
  62     ColourGradient (const Colour& colour1, float x1, float y1,
  63                     const Colour& colour2, float x2, float y2,
  64                     bool isRadial);
  65
  66     /** Creates an uninitialised gradient.
  67
  68         If you use this constructor instead of the other one, be sure to set all the
  69         object's public member variables before using it!
  70     */
  71     ColourGradient() noexcept;
  72
  73     /** Destructor */
  74     ~ColourGradient();
  75
  76     //==============================================================================
  77     /** Removes any colours that have been added.
  78
  79         This will also remove any start and end colours, so the gradient won't work. You'll
  80         need to add more colours with addColour().
  81     */
  82     void clearColours();
  83
  84     /** Adds a colour at a point along the length of the gradient.
  85
  86         This allows the gradient to go through a spectrum of colours, instead of just a
  87         start and end colour.
  88
  89         @param proportionAlongGradient      a value between 0 and 1.0, which is the proportion
  90                                             of the distance along the line between the two points
  91                                             at which the colour should occur.
  92         @param colour                       the colour that should be used at this point
  93         @returns the index at which the new point was added
  94     */
  95     int addColour (double proportionAlongGradient,
  96                    const Colour& colour);
  97
  98     /** Removes one of the colours from the gradient. */
  99     void removeColour (int index);
 100
 101     /** Multiplies the alpha value of all the colours by the given scale factor */
 102     void multiplyOpacity (float multiplier) noexcept;
 103
 104     //==============================================================================
 105     /** Returns the number of colour-stops that have been added. */
 106     int getNumColours() const noexcept;
 107
 108     /** Returns the position along the length of the gradient of the colour with this index.
 109
 110         The index is from 0 to getNumColours() - 1. The return value will be between 0.0 and 1.0
 111     */
 112     double getColourPosition (int index) const noexcept;
 113
 114     /** Returns the colour that was added with a given index.
 115         The index is from 0 to getNumColours() - 1.
 116     */
 117     const Colour getColour (int index) const noexcept;
 118
 119     /** Changes the colour at a given index.
 120         The index is from 0 to getNumColours() - 1.
 121     */
 122     void setColour (int index, const Colour& newColour) noexcept;
 123
 124     /** Returns the an interpolated colour at any position along the gradient.
 125         @param position     the position along the gradient, between 0 and 1
 126     */
 127     Colour getColourAtPosition (double position) const noexcept;
 128
 129     //==============================================================================
 130     /** Creates a set of interpolated premultiplied ARGB values.
 131         This will resize the HeapBlock, fill it with the colours, and will return the number of
 132         colours that it added.
 133     */
 134     int createLookupTable (const AffineTransform& transform, HeapBlock <PixelARGB>& resultLookupTable) const;
 135
 136     /** Returns true if all colours are opaque. */
 137     bool isOpaque() const noexcept;
 138
 139     /** Returns true if all colours are completely transparent. */
 140     bool isInvisible() const noexcept;
 141
 142     //==============================================================================
 143     Point<float> point1, point2;
 144
 145     /** If true, the gradient should be filled circularly, centred around
 146         point1, with point2 defining a point on the circumference.
 147
 148         If false, the gradient is linear between the two points.
 149     */
 150     bool isRadial;
 151
 152     bool operator== (const ColourGradient& other) const noexcept;
 153     bool operator!= (const ColourGradient& other) const noexcept;
 154
 155
 156 private:
 157     //==============================================================================
 158     struct ColourPoint
 159     {
 160         ColourPoint() noexcept {}
 161
 162         ColourPoint (const double position_, const Colour& colour_) noexcept
 163             : position (position_), colour (colour_)
 164         {}
 165
 166         bool operator== (const ColourPoint& other) const noexcept;
 167         bool operator!= (const ColourPoint& other) const noexcept;
 168
 169         double position;
 170         Colour colour;
 171     };
 172
 173     Array <ColourPoint> colours;
 174
 175     JUCE_LEAK_DETECTOR (ColourGradient);
 176 };
 177
 178
 179 #endif   // __JUCE_COLOURGRADIENT_JUCEHEADER__