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