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