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         Returns a pixel value which is platform-dependent.
 117         On Windows, a COLORREF is returned.
 118         On X, an allocated pixel value is returned.
 119         If the pixel is invalid (on X, unallocated), @c -1 is returned.
 120     */
 121     int GetPixel() const;
 122
 123     /**
 124         Returns the green intensity.
 125     */
 126     virtual unsigned char Green() const;
 127
 128     /**
 129         Returns @true if the colour object is valid (the colour has been initialised
 130         with RGB values).
 131     */
 132     virtual bool IsOk() const;
 133
 134     /**
 135         Returns the red intensity.
 136     */
 137     virtual unsigned char Red() const;
 138
 139     //@{
 140     /**
 141         Sets the RGB intensity values using the given values (first overload),
 142         extracting them from the packed long (second overload), using the given
 143         string (third overloard).
 144
 145         When using third form, Set() accepts: colour names (those listed in
 146         wxTheColourDatabase()), the CSS-like @c "rgb(r,g,b)" or
 147         @c "rgba(r,g,b,a)" syntax (case insensitive) and the HTML-like syntax
 148         (i.e. @c "#" followed by 6 hexadecimal digits for red, green, blue
 149         components).
 150
 151         Returns @true if the conversion was successful, @false otherwise.
 152
 153         @since 2.7.0
 154     */
 155     void Set(unsigned char red, unsigned char green,
 156              unsigned char blue,
 157              unsigned char alpha = wxALPHA_OPAQUE);
 158     void Set(unsigned long RGB);
 159     bool Set(const wxString& str);
 160     //@}
 161
 162     /**
 163         Tests the inequality of two colours by comparing individual red, green, blue
 164         colours and alpha values.
 165     */
 166     bool operator !=(const wxColour& colour) const;
 167
 168     /**
 169         Assignment operator, using a colour name to be found in the colour database.
 170
 171         @see wxColourDatabase
 172     */
 173     wxColour& operator=(const wxColour& colour);
 174
 175     /**
 176         Tests the equality of two colours by comparing individual red, green, blue
 177         colours and alpha values.
 178     */
 179     bool operator ==(const wxColour& colour) const;
 180 };
 181
 182
 183 /** @name Predefined colors. */
 184 //@{
 185 wxColour wxNullColour;
 186 wxColour* wxBLACK;
 187 wxColour* wxBLUE;
 188 wxColour* wxCYAN;
 189 wxColour* wxGREEN;
 190 wxColour* wxYELLOW;
 191 wxColour* wxLIGHT_GREY;
 192 wxColour* wxRED;
 193 wxColour* wxWHITE;
 194 //@}
 195
 196
 197
 198 // ============================================================================
 199 // Global functions/macros
 200 // ============================================================================
 201
 202 /** @addtogroup group_funcmacro_misc */
 203 //@{
 204
 205 /**
 206     Converts string to a wxColour best represented by the given string. Returns
 207     @true on success.
 208
 209     @see wxToString(const wxColour&)
 210
 211     @header{wx/colour.h}
 212 */
 213 bool wxFromString(const wxString& string, wxColour* colour);
 214
 215 /**
 216     Converts the given wxColour into a string.
 217
 218     @see wxFromString(const wxString&, wxColour*)
 219
 220     @header{wx/colour.h}
 221 */
 222 wxString wxToString(const wxColour& colour);
 223
 224 //@}
 225