interface/colour.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        colour.h
   3 // Purpose:     documentation for wxColour class
   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:
  28     wxNullColour
  29     Pointers:
  30     wxBLACK
  31
  32     wxWHITE
  33
  34     wxRED
  35
  36     wxBLUE
  37
  38     wxGREEN
  39
  40     wxCYAN
  41
  42     wxLIGHT_GREY
  43
  44     @seealso
  45     wxColourDatabase, wxPen, wxBrush, wxColourDialog, wxSystemSettings
  46 */
  47 class wxColour : public wxObject
  48 {
  49 public:
  50     //@{
  51     /**
  52         Copy constructor.
  53
  54         @param red
  55             The red value.
  56         @param green
  57             The green value.
  58         @param blue
  59             The blue value.
  60         @param alpha
  61             The alpha value. Alpha values range from 0 (wxALPHA_TRANSPARENT) to 255
  62         (wxALPHA_OPAQUE).
  63         @param colourName
  64             The colour name.
  65         @param colour
  66             The colour to copy.
  67
  68         @see wxColourDatabase
  69     */
  70     wxColour();
  71     wxColour(unsigned char red, unsigned char green,
  72              unsigned char blue,
  73              unsigned char alpha = wxALPHA_OPAQUE);
  74     wxColour(const wxString& colourNname);
  75     wxColour(const wxColour& colour);
  76     //@}
  77
  78     /**
  79         Returns the alpha value, on platforms where alpha is not yet supported, this
  80         always returns wxALPHA_OPAQUE.
  81     */
  82     unsigned char Alpha() const;
  83
  84     /**
  85         Returns the blue intensity.
  86     */
  87     unsigned char Blue() const;
  88
  89     //@{
  90     /**
  91         is not
  92         specified in flags.
  93         This function is new since wxWidgets version 2.7.0
  94     */
  95     wxString GetAsString(long flags);
  96     const wxC2S_NAME, to obtain the colour name (e.g.
  97             wxColour(255,0,0) - "red"), wxC2S_CSS_SYNTAX, to obtain
  98     the colour in the "rgb(r,g,b)" or "rgba(r,g,b,a)" syntax
  99     (e.g. wxColour(255,0,0,85) - "rgba(255,0,0,0.333)"), and
 100     wxC2S_HTML_SYNTAX, to obtain the colour as  "#" followed
 101     by 6 hexadecimal digits (e.g. wxColour(255,0,0) - "#FF0000").
 102     This function never fails and always returns a non-empty string but asserts if
 103     the colour has alpha channel (i.e. is non opaque) but
 104         wxC2S_CSS_SYNTAX();
 105     //@}
 106
 107     /**
 108         Returns a pixel value which is platform-dependent. On Windows, a COLORREF is
 109         returned.
 110         On X, an allocated pixel value is returned.
 111         -1 is returned if the pixel is invalid (on X, unallocated).
 112     */
 113     long GetPixel() const;
 114
 115     /**
 116         Returns the green intensity.
 117     */
 118     unsigned char Green() const;
 119
 120     /**
 121         Returns @true if the colour object is valid (the colour has been initialised
 122         with RGB values).
 123     */
 124     bool IsOk() const;
 125
 126     /**
 127         Returns the red intensity.
 128     */
 129     unsigned char Red() const;
 130
 131     //@{
 132     /**
 133         Sets the RGB intensity values using the given values (first overload),
 134         extracting them from the packed long (second overload), using the given string (third overloard).
 135         When using third form, Set() accepts: colour names (those listed in
 136         wxTheColourDatabase), the CSS-like
 137         @c "rgb(r,g,b)" or @c "rgba(r,g,b,a)" syntax (case insensitive)
 138         and the HTML-like syntax (i.e. @c "#" followed by 6 hexadecimal digits
 139         for red, green, blue components).
 140         Returns @true if the conversion was successful, @false otherwise.
 141         This function is new since wxWidgets version 2.7.0
 142     */
 143     void Set(unsigned char red, unsigned char green,
 144              unsigned char blue,
 145              unsigned char alpha = wxALPHA_OPAQUE);
 146     void Set(unsigned long RGB);
 147     bool Set(const wxString& str);
 148     //@}
 149
 150     /**
 151         Tests the inequality of two colours by comparing individual red, green, blue
 152         colours and alpha values.
 153     */
 154     bool operator !=(const wxColour& colour);
 155
 156     //@{
 157     /**
 158         Assignment operator, using a colour name to be found in the colour database.
 159
 160         @see wxColourDatabase
 161     */
 162     wxColour operator =(const wxColour& colour);
 163     wxColour operator =(const wxString& colourName);
 164     //@}
 165
 166     /**
 167         Tests the equality of two colours by comparing individual red, green, blue
 168         colours and alpha values.
 169     */
 170     bool operator ==(const wxColour& colour);
 171 };