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