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();
  83
  84     /**
  85         Returns the blue intensity.
  86     */
  87     unsigned char Blue();
  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     wxC2S_NAME wxC2S_CSS_SYNTAX, to obtain
  97     the colour in the "rgb(r,g,b)" or "rgba(r,g,b,a)" syntax
  98     (e.g. wxColour(255,0,0,85) - "rgba(255,0,0,0.333)"), and
  99     wxC2S_HTML_SYNTAX, to obtain the colour as  "#" followed
 100     by 6 hexadecimal digits (e.g. wxColour(255,0,0) - "#FF0000").
 101     This function never fails and always returns a non-empty string but asserts if
 102     the colour has alpha channel (i.e. is non opaque) but
 103         wxC2S_CSS_SYNTAX();
 104     //@}
 105
 106     /**
 107         Returns a pixel value which is platform-dependent. On Windows, a COLORREF is
 108         returned.
 109         On X, an allocated pixel value is returned.
 110         -1 is returned if the pixel is invalid (on X, unallocated).
 111     */
 112     long GetPixel();
 113
 114     /**
 115         Returns the green intensity.
 116     */
 117     unsigned char Green();
 118
 119     /**
 120         Returns @true if the colour object is valid (the colour has been initialised
 121         with RGB values).
 122     */
 123     bool IsOk();
 124
 125     /**
 126         Returns the red intensity.
 127     */
 128     unsigned char Red();
 129
 130     //@{
 131     /**
 132         Sets the RGB intensity values using the given values (first overload),
 133         extracting them from the packed long (second overload), using the given string (third overloard).
 134         When using third form, Set() accepts: colour names (those listed in
 135         wxTheColourDatabase), the CSS-like
 136         @c "rgb(r,g,b)" or @c "rgba(r,g,b,a)" syntax (case insensitive)
 137         and the HTML-like syntax (i.e. @c "#" followed by 6 hexadecimal digits
 138         for red, green, blue components).
 139         Returns @true if the conversion was successful, @false otherwise.
 140         This function is new since wxWidgets version 2.7.0
 141     */
 142     void Set(unsigned char red, unsigned char green,
 143              unsigned char blue,
 144              unsigned char alpha = wxALPHA_OPAQUE);
 145     void Set(unsigned long RGB);
 146     bool Set(const wxString& str);
 147     //@}
 148
 149     /**
 150         Tests the inequality of two colours by comparing individual red, green, blue
 151         colours and alpha values.
 152     */
 153     bool operator !=(const wxColour& colour);
 154
 155     //@{
 156     /**
 157         Assignment operator, using a colour name to be found in the colour database.
 158
 159         @see wxColourDatabase
 160     */
 161     wxColour operator =(const wxColour& colour);
 162     wxColour operator =(const wxString& colourName);
 163     //@}
 164
 165     /**
 166         Tests the equality of two colours by comparing individual red, green, blue
 167         colours and alpha values.
 168     */
 169     bool operator ==(const wxColour& colour);
 170 };