interface/wx/colour.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        colour.h
   3 // Purpose:     interface of wxColour
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8
   9
  10 /**
  11     Flags for wxColour -> wxString conversion (see wxColour::GetAsString).
  12
  13     @{
  14 */
  15 enum {
  16     wxC2S_NAME             = 1,   // return colour name, when possible
  17     wxC2S_CSS_SYNTAX       = 2,   // return colour in rgb(r,g,b) syntax
  18     wxC2S_HTML_SYNTAX      = 4    // return colour in #rrggbb syntax
  19 };
  20
  21 //@}
  22
  23 const unsigned char wxALPHA_TRANSPARENT = 0;
  24 const unsigned char wxALPHA_OPAQUE = 0xff;
  25
  26 /**
  27     @class wxColour
  28
  29     A colour is an object representing a combination of Red, Green, and Blue
  30     (RGB) intensity values, and is used to determine drawing colours. See the
  31     entry for wxColourDatabase for how a pointer to a predefined, named colour
  32     may be returned instead of creating a new colour.
  33
  34     Valid RGB values are in the range 0 to 255.
  35
  36     You can retrieve the current system colour settings with wxSystemSettings.
  37
  38     @library{wxcore}
  39     @category{gdi}
  40
  41     @stdobjects
  42     - ::wxNullColour - An empty, invalid colour.
  43     - ::wxTransparentColour - Valid but fully transparent colour (new in 2.9.1).
  44     - ::wxBLACK
  45     - ::wxBLUE
  46     - ::wxCYAN
  47     - ::wxGREEN
  48     - ::wxYELLOW
  49     - ::wxLIGHT_GREY
  50     - ::wxRED
  51     - ::wxWHITE
  52
  53     @see wxColourDatabase, wxPen, wxBrush, wxColourDialog, wxSystemSettings
  54 */
  55 class wxColour : public wxObject
  56 {
  57 public:
  58
  59     /**
  60         Default constructor.
  61     */
  62     wxColour();
  63
  64     /**
  65         @param red
  66             The red value.
  67         @param green
  68             The green value.
  69         @param blue
  70             The blue value.
  71         @param alpha
  72             The alpha value. Alpha values range from 0 (wxALPHA_TRANSPARENT) to
  73             255 (wxALPHA_OPAQUE).
  74     */
  75     wxColour(unsigned char red, unsigned char green, unsigned char blue,
  76              unsigned char alpha = wxALPHA_OPAQUE);
  77
  78     /**
  79         @param colourName
  80             The colour name.
  81     */
  82     wxColour(const wxString& colourName);
  83
  84     /**
  85         @param colRGB
  86             A packed RGB value.
  87     */
  88     wxColour(unsigned long colRGB);
  89
  90     /**
  91         Copy constructor.
  92     */
  93     wxColour(const wxColour& colour);
  94
  95     /**
  96         Returns the alpha value, on platforms where alpha is not yet supported, this
  97         always returns wxALPHA_OPAQUE.
  98     */
  99     virtual unsigned char Alpha() const;
 100
 101     /**
 102         Returns the blue intensity.
 103     */
 104     virtual unsigned char Blue() const;
 105
 106     /**
 107         Converts this colour to a wxString using the given flags.
 108
 109         The supported flags are @c wxC2S_NAME, to obtain the colour name
 110         (e.g. wxColour(255,0,0) == "red"), @c wxC2S_CSS_SYNTAX, to obtain
 111         the colour in the "rgb(r,g,b)" or "rgba(r,g,b,a)" syntax
 112         (e.g. wxColour(255,0,0,85) == "rgba(255,0,0,0.333)"), and
 113         @c wxC2S_HTML_SYNTAX, to obtain the colour as "#" followed by 6
 114         hexadecimal digits (e.g. wxColour(255,0,0) == "#FF0000").
 115
 116         This function never fails and always returns a non-empty string but
 117         asserts if the colour has alpha channel (i.e. is non opaque) but
 118         @c wxC2S_CSS_SYNTAX (which is the only one supporting alpha) is not
 119         specified in flags.
 120
 121         @since 2.7.0
 122     */
 123     virtual wxString GetAsString(long flags = wxC2S_NAME | wxC2S_CSS_SYNTAX) const;
 124
 125     //@{
 126     /**
 127         Sets the RGB or RGBA colour values from a single 32 bit value.
 128
 129         The arguments @a colRGB and @a colRGBA should be of the form 0x00BBGGRR
 130         and 0xAABBGGRR respectively where @c 0xRR, @c 0xGG, @c 0xBB and @c 0xAA
 131         are the values of the red, blue, green and alpha components.
 132
 133         Notice the right-to-left order of components!
 134
 135         @see GetRGB(), GetRGBA()
 136
 137         @since 2.9.1
 138     */
 139     void SetRGB(wxUint32 colRGB);
 140     void SetRGBA(wxUint32 colRGBA);
 141     //@}
 142
 143     //@{
 144     /**
 145         Gets the RGB or RGBA colour values as a single 32 bit value.
 146
 147         The returned value is of the same form as expected by SetRGB() and
 148         SetRGBA().
 149
 150         Notice that GetRGB() returns the value with 0 as its highest byte
 151         independently of the value actually returned by Alpha(). So for a fully
 152         opaque colour, the return value of GetRGBA() is @c 0xFFBBGGRR while
 153         that of GetRGB() is @c 0x00BBGGRR.
 154
 155         @since 2.9.1
 156     */
 157     wxUint32 GetRGB() const;
 158     wxUint32 GetRGBA() const;
 159     //@}
 160
 161     /**
 162         Returns a pixel value which is platform-dependent.
 163         On Windows, a COLORREF is returned.
 164         On X, an allocated pixel value is returned.
 165         If the pixel is invalid (on X, unallocated), @c -1 is returned.
 166     */
 167     wxIntPtr GetPixel() const;
 168
 169     /**
 170         Returns the green intensity.
 171     */
 172     virtual unsigned char Green() const;
 173
 174     /**
 175         Returns @true if the colour object is valid (the colour has been initialised
 176         with RGB values).
 177     */
 178     virtual bool IsOk() const;
 179
 180     /**
 181         Returns the red intensity.
 182     */
 183     virtual unsigned char Red() const;
 184
 185     //@{
 186     /**
 187         Sets the RGB intensity values using the given values (first overload),
 188         extracting them from the packed long (second overload), using the given
 189         string (third overload).
 190
 191         When using third form, Set() accepts: colour names (those listed in
 192         wxColourDatabase), the CSS-like @c "rgb(r,g,b)" or @c "rgba(r,g,b,a)" syntax
 193         (case insensitive) and the HTML-like syntax: @c "#" followed by 6 hexadecimal
 194         digits for red, green, blue components.
 195
 196         Returns @true if the conversion was successful, @false otherwise.
 197
 198         @since 2.7.0
 199     */
 200     void Set(unsigned char red, unsigned char green,
 201              unsigned char blue,
 202              unsigned char alpha = wxALPHA_OPAQUE);
 203     void Set(unsigned long RGB);
 204     bool Set(const wxString& str);
 205     //@}
 206
 207     /**
 208         Tests the inequality of two colours by comparing individual red, green, blue
 209         colours and alpha values.
 210     */
 211     bool operator !=(const wxColour& colour) const;
 212
 213     /**
 214         Assignment operator, using a colour name to be found in the colour database.
 215
 216         @see wxColourDatabase
 217     */
 218     wxColour& operator=(const wxColour& colour);
 219
 220     /**
 221         Tests the equality of two colours by comparing individual red, green, blue
 222         colours and alpha values.
 223     */
 224     bool operator ==(const wxColour& colour) const;
 225
 226     /**
 227         Assign 0 or 255 to rgb out parameters.
 228         @since 2.9.0
 229     */
 230     static void MakeMono(unsigned char* r, unsigned char* g, unsigned char* b, bool on);
 231
 232     /**
 233         Create a disabled (dimmed) colour from (in/out) rgb parameters.
 234         @since 2.9.0
 235     */
 236     static void MakeDisabled(unsigned char* r, unsigned char* g, unsigned char* b, unsigned char brightness = 255);
 237
 238     /**
 239         Make a disabled version of this colour.
 240
 241         This method modifies the object in place and returns the object itself.
 242
 243         @since 2.9.5
 244      */
 245     wxColour& MakeDisabled(unsigned char brightness = 255);
 246
 247     /**
 248         Create a grey colour from (in/out) rgb parameters using integer arithmetic.
 249         @since 2.9.0
 250     */
 251     static void MakeGrey(unsigned char* r, unsigned char* g, unsigned char* b);
 252
 253     /**
 254         Create a grey colour from (in/out) rgb parameters using floating point arithmetic.
 255         Defaults to using the standard ITU-T BT.601 when converting to YUV, where every pixel equals
 256         (R * @a weight_r) + (G * @a weight_g) + (B * @a weight_b).
 257         @since 2.9.0
 258     */
 259     static void MakeGrey(unsigned char* r, unsigned char* g, unsigned char* b,
 260                          double weight_r, double weight_g, double weight_b);
 261
 262     /**
 263         Blend colour, taking alpha into account.
 264         @since 2.9.0
 265     */
 266     static unsigned char AlphaBlend(unsigned char fg, unsigned char bg, double alpha);
 267
 268     /**
 269         ChangeLightness() is a utility function that simply darkens
 270         or lightens a color, based on the specified percentage
 271         ialpha of 0 would be completely black, 200 completely white
 272         an ialpha of 100 returns the same colour
 273         @since 2.9.0
 274     */
 275     static void ChangeLightness(unsigned char* r, unsigned char* g, unsigned char* b, int ialpha);
 276
 277     /**
 278         wxColour wrapper for ChangeLightness(r,g,b,ialpha).
 279         @since 2.9.0
 280     */
 281     wxColour ChangeLightness(int ialpha) const;
 282 };
 283
 284
 285 /** @name Predefined colors. */
 286 //@{
 287 wxColour wxNullColour;
 288 wxColour wxTransparentColour;
 289 wxColour* wxBLACK;
 290 wxColour* wxBLUE;
 291 wxColour* wxCYAN;
 292 wxColour* wxGREEN;
 293 wxColour* wxYELLOW;
 294 wxColour* wxLIGHT_GREY;
 295 wxColour* wxRED;
 296 wxColour* wxWHITE;
 297 //@}
 298
 299
 300
 301 // ============================================================================
 302 // Global functions/macros
 303 // ============================================================================
 304
 305 /** @addtogroup group_funcmacro_misc */
 306 //@{
 307
 308 /**
 309     Converts string to a wxColour best represented by the given string. Returns
 310     @true on success.
 311
 312     @see wxToString(const wxColour&)
 313
 314     @header{wx/colour.h}
 315 */
 316 bool wxFromString(const wxString& string, wxColour* colour);
 317
 318 /**
 319     Converts the given wxColour into a string.
 320
 321     @see wxFromString(const wxString&, wxColour*)
 322
 323     @header{wx/colour.h}
 324 */
 325 wxString wxToString(const wxColour& colour);
 326
 327 //@}
 328