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     - ::wxBLACK
  41     - ::wxBLUE
  42     - ::wxCYAN
  43     - ::wxGREEN
  44     - ::wxYELLOW
  45     - ::wxLIGHT_GREY
  46     - ::wxRED
  47     - ::wxWHITE
  48
  49     @see wxColourDatabase, wxPen, wxBrush, wxColourDialog, wxSystemSettings
  50 */
  51 class wxColour : public wxObject
  52 {
  53 public:
  54
  55     /**
  56         Default constructor.
  57     */
  58     wxColour();
  59
  60     /**
  61         @param red
  62             The red value.
  63         @param green
  64             The green value.
  65         @param blue
  66             The blue value.
  67         @param alpha
  68             The alpha value. Alpha values range from 0 (wxALPHA_TRANSPARENT) to
  69             255 (wxALPHA_OPAQUE).
  70     */
  71     wxColour(unsigned char red, unsigned char green, unsigned char blue,
  72              unsigned char alpha = wxALPHA_OPAQUE);
  73
  74     /**
  75         @param colourName
  76             The colour name.
  77     */
  78     wxColour(const wxString& colourName);
  79
  80     /**
  81         Copy constructor.
  82     */
  83     wxColour(const wxColour& colour);
  84
  85     /**
  86         Returns the alpha value, on platforms where alpha is not yet supported, this
  87         always returns wxALPHA_OPAQUE.
  88     */
  89     virtual unsigned char Alpha() const;
  90
  91     /**
  92         Returns the blue intensity.
  93     */
  94     virtual unsigned char Blue() const;
  95
  96     /**
  97         Converts this colour to a wxString using the given flags.
  98
  99         The supported flags are @c wxC2S_NAME, to obtain the colour name
 100         (e.g. wxColour(255,0,0) == "red"), @c wxC2S_CSS_SYNTAX, to obtain
 101         the colour in the "rgb(r,g,b)" or "rgba(r,g,b,a)" syntax
 102         (e.g. wxColour(255,0,0,85) == "rgba(255,0,0,0.333)"), and
 103         @c wxC2S_HTML_SYNTAX, to obtain the colour as "#" followed by 6
 104         hexadecimal digits (e.g. wxColour(255,0,0) == "#FF0000").
 105
 106         This function never fails and always returns a non-empty string but
 107         asserts if the colour has alpha channel (i.e. is non opaque) but
 108         @c wxC2S_CSS_SYNTAX (which is the only one supporting alpha) is not
 109         specified in flags.
 110
 111         @since 2.7.0
 112     */
 113     virtual wxString GetAsString(long flags = wxC2S_NAME | wxC2S_CSS_SYNTAX) const;
 114
 115     //@{
 116     /**
 117         Sets the RGB or RGBA colour values from a single 32 bit value.
 118
 119         The arguments @a colRGB and @a colRGBA should be of the form 0x00BBGGRR
 120         and 0xAABBGGRR respectively where @c 0xRR, @c 0xGG, @c 0xBB and @c 0xAA
 121         are the values of the red, blue, green and alpha components.
 122
 123         Notice the right-to-left order of components!
 124
 125         @see GetRGB(), GetRGBA()
 126
 127         @since 2.9.1
 128     */
 129     void SetRGB(wxUint32 colRGB);
 130     void SetRGBA(wxUint32 colRGBA);
 131     //@}
 132
 133     //@{
 134     /**
 135         Gets the RGB or RGBA colour values as a single 32 bit value.
 136
 137         The returned value is of the same form as expected by SetRGB() and
 138         SetRGBA().
 139
 140         Notice that GetRGB() returns the value with 0 as its highest byte
 141         independently of the value actually returned by Alpha(). So for a fully
 142         opaque colour, the return value of GetRGBA() is @c 0xFFBBGGRR while
 143         that of GetRGB() is @c 0x00BBGGRR.
 144
 145         @since 2.9.1
 146     */
 147     wxUint32 GetRGB() const;
 148     wxUint32 GetRGBA() const;
 149     //@}
 150
 151     /**
 152         Returns a pixel value which is platform-dependent.
 153         On Windows, a COLORREF is returned.
 154         On X, an allocated pixel value is returned.
 155         If the pixel is invalid (on X, unallocated), @c -1 is returned.
 156     */
 157     int GetPixel() const;
 158
 159     /**
 160         Returns the green intensity.
 161     */
 162     virtual unsigned char Green() const;
 163
 164     /**
 165         Returns @true if the colour object is valid (the colour has been initialised
 166         with RGB values).
 167     */
 168     virtual bool IsOk() const;
 169
 170     /**
 171         Returns the red intensity.
 172     */
 173     virtual unsigned char Red() const;
 174
 175     //@{
 176     /**
 177         Sets the RGB intensity values using the given values (first overload),
 178         extracting them from the packed long (second overload), using the given
 179         string (third overloard).
 180
 181         When using third form, Set() accepts: colour names (those listed in
 182         wxTheColourDatabase()), the CSS-like @c "rgb(r,g,b)" or
 183         @c "rgba(r,g,b,a)" syntax (case insensitive) and the HTML-like syntax
 184         (i.e. @c "#" followed by 6 hexadecimal digits for red, green, blue
 185         components).
 186
 187         Returns @true if the conversion was successful, @false otherwise.
 188
 189         @since 2.7.0
 190     */
 191     void Set(unsigned char red, unsigned char green,
 192              unsigned char blue,
 193              unsigned char alpha = wxALPHA_OPAQUE);
 194     void Set(unsigned long RGB);
 195     bool Set(const wxString& str);
 196     //@}
 197
 198     /**
 199         Tests the inequality of two colours by comparing individual red, green, blue
 200         colours and alpha values.
 201     */
 202     bool operator !=(const wxColour& colour) const;
 203
 204     /**
 205         Assignment operator, using a colour name to be found in the colour database.
 206
 207         @see wxColourDatabase
 208     */
 209     wxColour& operator=(const wxColour& colour);
 210
 211     /**
 212         Tests the equality of two colours by comparing individual red, green, blue
 213         colours and alpha values.
 214     */
 215     bool operator ==(const wxColour& colour) const;
 216 };
 217
 218
 219 /** @name Predefined colors. */
 220 //@{
 221 wxColour wxNullColour;
 222 wxColour* wxBLACK;
 223 wxColour* wxBLUE;
 224 wxColour* wxCYAN;
 225 wxColour* wxGREEN;
 226 wxColour* wxYELLOW;
 227 wxColour* wxLIGHT_GREY;
 228 wxColour* wxRED;
 229 wxColour* wxWHITE;
 230 //@}
 231
 232
 233
 234 // ============================================================================
 235 // Global functions/macros
 236 // ============================================================================
 237
 238 /** @addtogroup group_funcmacro_misc */
 239 //@{
 240
 241 /**
 242     Converts string to a wxColour best represented by the given string. Returns
 243     @true on success.
 244
 245     @see wxToString(const wxColour&)
 246
 247     @header{wx/colour.h}
 248 */
 249 bool wxFromString(const wxString& string, wxColour* colour);
 250
 251 /**
 252     Converts the given wxColour into a string.
 253
 254     @see wxFromString(const wxString&, wxColour*)
 255
 256     @header{wx/colour.h}
 257 */
 258 wxString wxToString(const wxColour& colour);
 259
 260 //@}
 261