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