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