interface/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     @class wxColour
  11     @wxheader{colour.h}
  12
  13     A colour is an object representing a combination of Red, Green, and Blue
  14     (RGB) intensity values, and is used to determine drawing colours. See the
  15     entry for wxColourDatabase for how a pointer to a predefined, named colour
  16     may be returned instead of creating a new colour.
  17
  18     Valid RGB values are in the range 0 to 255.
  19
  20     You can retrieve the current system colour settings with wxSystemSettings.
  21
  22     @library{wxcore}
  23     @category{gdi}
  24
  25     @stdobjects
  26     - ::wxNullColour - An empty, invalid colour.
  27     - ::wxBLACK
  28     - ::wxBLUE
  29     - ::wxCYAN
  30     - ::wxGREEN
  31     - ::wxLIGHT_GREY
  32     - ::wxRED
  33     - ::wxWHITE
  34
  35     @see wxColourDatabase, wxPen, wxBrush, wxColourDialog, wxSystemSettings
  36 */
  37 class wxColour : public wxObject
  38 {
  39 public:
  40
  41     /**
  42         Default constructor.
  43     */
  44     wxColour();
  45
  46     /**
  47         @param red
  48             The red value.
  49         @param green
  50             The green value.
  51         @param blue
  52             The blue value.
  53         @param alpha
  54             The alpha value. Alpha values range from 0 (wxALPHA_TRANSPARENT) to
  55             255 (wxALPHA_OPAQUE).
  56     */
  57     wxColour(unsigned char red, unsigned char green, unsigned char blue,
  58              unsigned char alpha = wxALPHA_OPAQUE);
  59
  60     /**
  61         @param colourName
  62             The colour name.
  63     */
  64     wxColour(const wxString& colourName);
  65
  66     /**
  67         Copy constructor.
  68     */
  69     wxColour(const wxColour& colour);
  70
  71     /**
  72         Returns the alpha value, on platforms where alpha is not yet supported, this
  73         always returns wxALPHA_OPAQUE.
  74     */
  75     unsigned char Alpha() const;
  76
  77     /**
  78         Returns the blue intensity.
  79     */
  80     unsigned char Blue() const;
  81
  82     /**
  83         Converts this colour to a wxString using the given flags.
  84
  85         The supported flags are wxC2S_NAME, to obtain the colour name (e.g.
  86         wxColour(255,0,0) == "red"), wxC2S_CSS_SYNTAX, to obtain the colour in
  87         the "rgb(r,g,b)" or "rgba(r,g,b,a)" syntax (e.g.
  88         wxColour(255,0,0,85) == "rgba(255,0,0,0.333)"), and wxC2S_HTML_SYNTAX,
  89         to obtain the colour as "#" followed by 6 hexadecimal digits (e.g.
  90         wxColour(255,0,0) == "#FF0000").
  91
  92         This function never fails and always returns a non-empty string but
  93         asserts if the colour has alpha channel (i.e. is non opaque) but
  94         wxC2S_CSS_SYNTAX (which is the only one supporting alpha) is not
  95         specified in flags.
  96
  97         @wxsince{2.7.0}
  98     */
  99     wxString GetAsString(long flags);
 100
 101     /**
 102         Returns a pixel value which is platform-dependent. On Windows, a COLORREF is
 103         returned.
 104         On X, an allocated pixel value is returned.
 105         -1 is returned if the pixel is invalid (on X, unallocated).
 106     */
 107     long GetPixel() const;
 108
 109     /**
 110         Returns the green intensity.
 111     */
 112     unsigned char Green() const;
 113
 114     /**
 115         Returns @true if the colour object is valid (the colour has been initialised
 116         with RGB values).
 117     */
 118     bool IsOk() const;
 119
 120     /**
 121         Returns the red intensity.
 122     */
 123     unsigned char Red() const;
 124
 125     //@{
 126     /**
 127         Sets the RGB intensity values using the given values (first overload),
 128         extracting them from the packed long (second overload), using the given
 129         string (third overloard).
 130
 131         When using third form, Set() accepts: colour names (those listed in
 132         wxTheColourDatabase()), the CSS-like @c "rgb(r,g,b)" or
 133         @c "rgba(r,g,b,a)" syntax (case insensitive) and the HTML-like syntax
 134         (i.e. @c "#" followed by 6 hexadecimal digits for red, green, blue
 135         components).
 136
 137         Returns @true if the conversion was successful, @false otherwise.
 138
 139         @wxsince{2.7.0}
 140     */
 141     void Set(unsigned char red, unsigned char green,
 142              unsigned char blue,
 143              unsigned char alpha = wxALPHA_OPAQUE);
 144     void Set(unsigned long RGB);
 145     bool Set(const wxString& str);
 146     //@}
 147
 148     /**
 149         Tests the inequality of two colours by comparing individual red, green, blue
 150         colours and alpha values.
 151     */
 152     bool operator !=(const wxColour& colour);
 153
 154     //@{
 155     /**
 156         Assignment operator, using a colour name to be found in the colour database.
 157
 158         @see wxColourDatabase
 159     */
 160     wxColour operator =(const wxColour& colour);
 161     wxColour operator =(const wxString& colourName);
 162     //@}
 163
 164     /**
 165         Tests the equality of two colours by comparing individual red, green, blue
 166         colours and alpha values.
 167     */
 168     bool operator ==(const wxColour& colour);
 169 };
 170
 171
 172 /** @name Predefined colors. */
 173 //@{
 174 wxColour wxNullColour;
 175 wxColour* wxBLACK;
 176 wxColour* wxBLUE;
 177 wxColour* wxCYAN;
 178 wxColour* wxGREEN;
 179 wxColour* wxLIGHT_GREY;
 180 wxColour* wxRED;
 181 wxColour* wxWHITE;
 182 //@}
 183
 184
 185
 186 // ============================================================================
 187 // Global functions/macros
 188 // ============================================================================
 189
 190 /** @ingroup group_funcmacro_misc */
 191 //@{
 192
 193 /**
 194     Converts string to a wxColour best represented by the given string. Returns
 195     @true on success.
 196
 197     @see wxToString(const wxColour&)
 198
 199     @header{wx/colour.h}
 200 */
 201 bool wxFromString(const wxString& string, wxColour* colour);
 202
 203 /**
 204     Converts the given wxColour into a string.
 205
 206     @see wxFromString(const wxString&, wxColour*)
 207
 208     @header{wx/colour.h}
 209 */
 210 wxString wxToString(const wxColour& colour);
 211
 212 //@}
 213