interface/wx/colour.h

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