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