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