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 enum {
  21     wxC2S_NAME,             // return colour name, when possible
  22     wxC2S_CSS_SYNTAX,       // return colour in rgb(r,g,b) syntax
  23     wxC2S_HTML_SYNTAX,      // return colour in #rrggbb syntax
  24 };
  25
  26 enum {
  27     wxALPHA_TRANSPARENT,
  28     wxALPHA_OPAQUE
  29 };
  30
  31
  32 DocStr(wxColour,
  33 "A colour is an object representing a combination of Red, Green, and
  34 Blue (RGB) intensity values, and is used to determine drawing colours,
  35 window colours, etc.  Valid RGB values are in the range 0 to 255.
  36
  37 In wxPython there are typemaps that will automatically convert from a
  38 colour name, from a '#RRGGBB' colour hex value string, or from a 3 or 4
  39 integer tuple to a wx.Colour object when calling C++ methods that
  40 expect a wxColour.  This means that the following are all
  41 equivallent::
  42
  43     win.SetBackgroundColour(wxColour(0,0,255))
  44     win.SetBackgroundColour('BLUE')
  45     win.SetBackgroundColour('#0000FF')
  46     win.SetBackgroundColour((0,0,255))
  47
  48 Additional colour names and their coresponding values can be added
  49 using `wx.ColourDatabase`.  Various system colours (as set in the
  50 user's system preferences) can be retrieved with
  51 `wx.SystemSettings.GetColour`.
  52 ", "");
  53
  54
  55 MustHaveApp( wxColour(const wxString& colorName) );
  56
  57 class wxColour : public wxObject {
  58 public:
  59
  60     DocCtorStr(
  61         wxColour(byte red=0, byte green=0, byte blue=0, byte alpha=wxALPHA_OPAQUE),
  62         "Constructs a colour from red, green, blue and alpha values.
  63
  64 :see: Alternate constructors `wx.NamedColour` and `wx.ColourRGB`.
  65 ", "");
  66
  67     DocCtorStrName(
  68         wxColour( const wxString& colorName),
  69         "Constructs a colour object using a colour name listed in
  70 ``wx.TheColourDatabase``.", "",
  71         NamedColour);
  72
  73     DocCtorStrName(
  74         wxColour( unsigned long colRGB ),
  75         "Constructs a colour from a packed RGB value.", "",
  76         ColourRGB);
  77
  78     ~wxColour();
  79
  80
  81     DocDeclStr(
  82         byte , Red(),
  83         "Returns the red intensity.", "");
  84
  85     DocDeclStr(
  86         byte , Green(),
  87         "Returns the green intensity.", "");
  88
  89     DocDeclStr(
  90         byte , Blue(),
  91         "Returns the blue intensity.", "");
  92
  93     DocDeclStr(
  94         byte , Alpha(),
  95         "Returns the Alpha value.", "");
  96
  97     DocDeclStr(
  98         bool , IsOk(),
  99         "Returns True if the colour object is valid (the colour has been
 100 initialised with RGB values).", "");
 101     %pythoncode { Ok = IsOk }
 102
 103     DocDeclStr(
 104         void , Set(byte red, byte green, byte blue, byte alpha=wxALPHA_OPAQUE),
 105         "Sets the RGB intensity values.", "");
 106
 107     DocDeclStrName(
 108         void , Set(unsigned long colRGB),
 109         "Sets the RGB intensity values from a packed RGB value.", "",
 110         SetRGB);
 111
 112     DocDeclStrName(
 113         void , Set(const wxString& colourName),
 114         "Sets the RGB intensity values using a colour name listed in
 115 ``wx.TheColourDatabase``.", "",
 116         SetFromName);
 117
 118
 119     DocDeclStr(
 120         wxString , GetAsString(long flags = wxC2S_NAME | wxC2S_CSS_SYNTAX) const,
 121         "Return the colour as a string.  Acceptable flags are:
 122
 123             =================== ==================================
 124             wx.C2S_NAME          return colour name, when possible
 125             wx.C2S_CSS_SYNTAX    return colour in rgb(r,g,b) syntax
 126             wx.C2S_HTML_SYNTAX   return colour in #rrggbb syntax
 127             =================== ==================================", "");
 128
 129
 130     DocDeclStr(
 131         long , GetPixel() const,
 132         "Returns a pixel value which is platform-dependent. On Windows, a
 133 COLORREF is returned. On X, an allocated pixel value is returned.  -1
 134 is returned if the pixel is invalid (on X, unallocated).", "");
 135
 136
 137     %extend {
 138         KeepGIL(__eq__);
 139         DocStr(__eq__, "Compare colours for equality.", "");
 140         bool __eq__(PyObject* other) {
 141             wxColour  temp, *obj = &temp;
 142             if ( other == Py_None ) return false;
 143             if ( ! wxColour_helper(other, &obj) ) {
 144                 PyErr_Clear();
 145                 return false;
 146             }
 147             return self->operator==(*obj);
 148         }
 149
 150
 151         KeepGIL(__ne__);
 152         DocStr(__ne__, "Compare colours for inequality.", "");
 153         bool __ne__(PyObject* other) {
 154             wxColour  temp, *obj = &temp;
 155             if ( other == Py_None ) return true;
 156             if ( ! wxColour_helper(other, &obj)) {
 157                 PyErr_Clear();
 158                 return true;
 159             }
 160             return self->operator!=(*obj);
 161         }
 162     }
 163
 164
 165     %extend {
 166         KeepGIL(Get);
 167         DocAStr(Get,
 168                 "Get(self, bool includeAlpha=False) -> (r,g,b) or (r,g,b,a)",
 169                 "Returns the RGB intensity values as a tuple, optionally the alpha value as well.", "");
 170         PyObject* Get(bool includeAlpha=false) {
 171             PyObject* rv = PyTuple_New(includeAlpha ? 4 : 3);
 172             int red = -1;
 173             int green = -1;
 174             int blue = -1;
 175             int alpha = wxALPHA_OPAQUE;
 176             if (self->IsOk()) {
 177                 red =   self->Red();
 178                 green = self->Green();
 179                 blue =  self->Blue();
 180                 alpha = self->Alpha();
 181             }
 182             PyTuple_SetItem(rv, 0, PyInt_FromLong(red));
 183             PyTuple_SetItem(rv, 1, PyInt_FromLong(green));
 184             PyTuple_SetItem(rv, 2, PyInt_FromLong(blue));
 185             if (includeAlpha)
 186                 PyTuple_SetItem(rv, 3, PyInt_FromLong(alpha));
 187             return rv;
 188         }
 189
 190         KeepGIL(GetRGB);
 191         DocStr(GetRGB,
 192                "Return the colour as a packed RGB value", "");
 193         unsigned long GetRGB() {
 194             return self->Red() | (self->Green() << 8) | (self->Blue() << 16);
 195         }
 196     }
 197
 198
 199     %pythoncode {
 200         asTuple = wx._deprecated(Get, "asTuple is deprecated, use `Get` instead")
 201         def __str__(self):                  return str(self.Get(True))
 202         def __repr__(self):                 return 'wx.Colour' + str(self.Get(True))
 203         def __len__(self):                  return len(self.Get())
 204         def __getitem__(self, index):       return self.Get()[index]
 205         def __nonzero__(self):              return self.IsOk()
 206         __safe_for_unpickling__ = True
 207         def __reduce__(self):               return (Colour, self.Get(True))
 208         }
 209
 210     %property(Pixel, GetPixel, doc="See `GetPixel`");
 211     %property(RGB, GetRGB, SetRGB, doc="See `GetRGB` and `SetRGB`");
 212
 213 };
 214
 215 %pythoncode {
 216     Color = Colour
 217     NamedColor = NamedColour
 218     ColorRGB = ColourRGB
 219 }
 220
 221 //---------------------------------------------------------------------------
 222