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