wxPython/src/_colour.i

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        _colour.i
   3 // Purpose:     SWIG interface for wxColour
   4 //
   5 // Author:      Robin Dunn
   6 //
   7 // Created:     7-July-1997
   8 // RCS-ID:      $Id$
   9 // Copyright:   (c) 2003 by Total Control Software
  10 // Licence:     wxWindows license
  11 /////////////////////////////////////////////////////////////////////////////
  12
  13 // Not a %module
  14
  15
  16 //---------------------------------------------------------------------------
  17 %newgroup;
  18
  19
  20 DocStr(wxColour,
  21 "A colour is an object representing a combination of Red, Green, and
  22 Blue (RGB) intensity values, and is used to determine drawing colours,
  23 window colours, etc.  Valid RGB values are in the range 0 to 255.
  24
  25 In wxPython there are typemaps that will automatically convert from a
  26 colour name, from a '#RRGGBB' colour hex value string, or from a 3
  27 integer tuple to a wx.Colour object when calling C++ methods that
  28 expect a wxColour.  This means that the following are all
  29 equivallent::
  30
  31     win.SetBackgroundColour(wxColour(0,0,255))
  32     win.SetBackgroundColour('BLUE')
  33     win.SetBackgroundColour('#0000FF')
  34     win.SetBackgroundColour((0,0,255))
  35
  36 Additional colour names and their coresponding values can be added
  37 using `wx.ColourDatabase`.  Various system colours (as set in the
  38 user's system preferences) can be retrieved with
  39 `wx.SystemSettings.GetColour`.
  40 ", "");
  41
  42
  43 MustHaveApp( wxColour(const wxString& colorName) );
  44
  45 class wxColour : public wxObject {
  46 public:
  47
  48     DocCtorStr(
  49         wxColour(byte red=0, byte green=0, byte blue=0),
  50         "Constructs a colour from red, green and blue values.
  51
  52 :see: Alternate constructors `wx.NamedColour` and `wx.ColourRGB`.
  53 ", "");
  54
  55     DocCtorStrName(
  56         wxColour( const wxString& colorName),
  57         "Constructs a colour object using a colour name listed in
  58 ``wx.TheColourDatabase``.", "",
  59         NamedColour);
  60
  61     DocCtorStrName(
  62         wxColour( unsigned long colRGB ),
  63         "Constructs a colour from a packed RGB value.", "",
  64         ColourRGB);
  65
  66     ~wxColour();
  67
  68
  69     DocDeclStr(
  70         byte , Red(),
  71         "Returns the red intensity.", "");
  72
  73     DocDeclStr(
  74         byte , Green(),
  75         "Returns the green intensity.", "");
  76
  77     DocDeclStr(
  78         byte , Blue(),
  79         "Returns the blue intensity.", "");
  80
  81     DocDeclStr(
  82         bool , Ok(),
  83         "Returns True if the colour object is valid (the colour has been
  84 initialised with RGB values).", "");
  85
  86     DocDeclStr(
  87         void , Set(byte red, byte green, byte blue),
  88         "Sets the RGB intensity values.", "");
  89
  90     DocDeclStrName(
  91         void , Set(unsigned long colRGB),
  92         "Sets the RGB intensity values from a packed RGB value.", "",
  93         SetRGB);
  94
  95     DocDeclStrName(
  96         void , InitFromName(const wxString& colourName),
  97         "Sets the RGB intensity values using a colour name listed in
  98 ``wx.TheColourDatabase``.", "",
  99         SetFromName);
 100
 101
 102     DocDeclStr(
 103         long , GetPixel() const,
 104         "Returns a pixel value which is platform-dependent. On Windows, a
 105 COLORREF is returned. On X, an allocated pixel value is returned.  -1
 106 is returned if the pixel is invalid (on X, unallocated).", "");
 107
 108
 109     %extend {
 110         KeepGIL(__eq__);
 111         DocStr(__eq__, "Compare colours for equality.", "");
 112         bool __eq__(PyObject* other) {
 113             wxColour  temp, *obj = &temp;
 114             if ( other == Py_None ) return false;
 115             if ( ! wxColour_helper(other, &obj) ) {
 116                 PyErr_Clear();
 117                 return false;
 118             }
 119             return self->operator==(*obj);
 120         }
 121
 122
 123         KeepGIL(__ne__);
 124         DocStr(__ne__, "Compare colours for inequality.", "");
 125         bool __ne__(PyObject* other) {
 126             wxColour  temp, *obj = &temp;
 127             if ( other == Py_None ) return true;
 128             if ( ! wxColour_helper(other, &obj)) {
 129                 PyErr_Clear();
 130                 return true;
 131             }
 132             return self->operator!=(*obj);
 133         }
 134     }
 135
 136
 137     %extend {
 138         DocAStr(Get,
 139                 "Get() -> (r, g, b)",
 140                 "Returns the RGB intensity values as a tuple.", "");
 141         PyObject* Get() {
 142             PyObject* rv = PyTuple_New(3);
 143             int red = -1;
 144             int green = -1;
 145             int blue = -1;
 146             if (self->Ok()) {
 147                 red =   self->Red();
 148                 green = self->Green();
 149                 blue =  self->Blue();
 150             }
 151             PyTuple_SetItem(rv, 0, PyInt_FromLong(red));
 152             PyTuple_SetItem(rv, 1, PyInt_FromLong(green));
 153             PyTuple_SetItem(rv, 2, PyInt_FromLong(blue));
 154             return rv;
 155         }
 156
 157         DocStr(GetRGB,
 158                "Return the colour as a packed RGB value", "");
 159         unsigned long GetRGB() {
 160             return self->Red() | (self->Green() << 8) | (self->Blue() << 16);
 161         }
 162     }
 163
 164
 165     %pythoncode {
 166         asTuple = wx._deprecated(Get, "asTuple is deprecated, use `Get` instead")
 167         def __str__(self):                  return str(self.Get())
 168         def __repr__(self):                 return 'wx.Colour' + str(self.Get())
 169         def __nonzero__(self):              return self.Ok()
 170         __safe_for_unpickling__ = True
 171         def __reduce__(self):               return (Colour, self.Get())
 172         }
 173 };
 174
 175 %pythoncode {
 176     Color = Colour
 177     NamedColor = NamedColour
 178     ColorRGB = ColourRGB
 179 }
 180
 181 //---------------------------------------------------------------------------
 182