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