wxPython/src/_bitmap.i

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        _bitmap.i
   3 // Purpose:     SWIG interface for wxBitmap and wxMask
   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
  18 %{
  19 #include <wx/image.h>
  20
  21     static char** ConvertListOfStrings(PyObject* listOfStrings) {
  22         char**    cArray = NULL;
  23         int       count;
  24
  25         if (!PyList_Check(listOfStrings)) {
  26             PyErr_SetString(PyExc_TypeError, "Expected a list of strings.");
  27             return NULL;
  28         }
  29         count = PyList_Size(listOfStrings);
  30         cArray = new char*[count];
  31
  32         for(int x=0; x<count; x++) {
  33             // TODO: Need some validation and error checking here
  34             cArray[x] = PyString_AsString(PyList_GET_ITEM(listOfStrings, x));
  35         }
  36         return cArray;
  37     }
  38
  39 %}
  40
  41 //---------------------------------------------------------------------------
  42
  43 // TODO:  When the API stabalizes and is available on other platforms, add
  44 // wrappers for the new wxBitmap, wxRawBitmap, wxDIB stuff...
  45
  46 DocStr(wxBitmap,
  47 "The wx.Bitmap class encapsulates the concept of a platform-dependent
  48 bitmap.  It can be either monochrome or colour, and either loaded from
  49 a file or created dynamically.  A bitmap can be selected into a memory
  50 device context (instance of `wx.MemoryDC`). This enables the bitmap to
  51 be copied to a window or memory device context using `wx.DC.Blit`, or
  52 to be used as a drawing surface.
  53
  54 The BMP and XMP image file formats are supported on all platforms by
  55 wx.Bitmap.  Other formats are automatically loaded by `wx.Image` and
  56 converted to a wx.Bitmap, so any image file format supported by
  57 `wx.Image` can be used.
  58
  59 :todo: Add wrappers and support for raw bitmap data access.  Can this
  60        be be put into Python without losing the speed benefits of the
  61        teplates and iterators in rawbmp.h?
  62
  63 :todo: Find a way to do very efficient PIL Image <--> wx.Bitmap
  64        converstions.
  65 ");
  66
  67
  68 class wxBitmap : public wxGDIObject
  69 {
  70 public:
  71     DocCtorStr(
  72         wxBitmap(const wxString& name, wxBitmapType type=wxBITMAP_TYPE_ANY),
  73         "Loads a bitmap from a file.
  74
  75 :param name:  Name of the file to load the bitmap from.
  76 :param type: The type of image to expect.  Can be one of the following
  77     constants (assuming that the neccessary `wx.Image` handlers are
  78     loaded):
  79
  80         * wx.BITMAP_TYPE_ANY
  81         * wx.BITMAP_TYPE_BMP
  82         * wx.BITMAP_TYPE_ICO
  83         * wx.BITMAP_TYPE_CUR
  84         * wx.BITMAP_TYPE_XBM
  85         * wx.BITMAP_TYPE_XPM
  86         * wx.BITMAP_TYPE_TIF
  87         * wx.BITMAP_TYPE_GIF
  88         * wx.BITMAP_TYPE_PNG
  89         * wx.BITMAP_TYPE_JPEG
  90         * wx.BITMAP_TYPE_PNM
  91         * wx.BITMAP_TYPE_PCX
  92         * wx.BITMAP_TYPE_PICT
  93         * wx.BITMAP_TYPE_ICON
  94         * wx.BITMAP_TYPE_ANI
  95         * wx.BITMAP_TYPE_IFF
  96
  97 :see: Alternate constructors `wx.EmptyBitmap`, `wx.BitmapFromIcon`,
  98       `wx.BitmapFromImage`, `wx.BitmapFromXPMData`,
  99       `wx.BitmapFromBits`
 100 ");
 101
 102     ~wxBitmap();
 103
 104     DocCtorStrName(
 105         wxBitmap(int width, int height, int depth=-1),
 106         "Creates a new bitmap of the given size.  A depth of -1 indicates the
 107 depth of the current screen or visual. Some platforms only support 1
 108 for monochrome and -1 for the current colour setting.",
 109         EmptyBitmap);
 110
 111     DocCtorStrName(
 112         wxBitmap(const wxIcon& icon),
 113         "Create a new bitmap from a `wx.Icon` object.",
 114         BitmapFromIcon);
 115
 116     DocCtorStrName(
 117         wxBitmap(const wxImage& image, int depth=-1),
 118         "Creates bitmap object from a `wx.Image`. This has to be done to
 119 actually display a `wx.Image` as you cannot draw an image directly on
 120 a window. The resulting bitmap will use the provided colour depth (or
 121 that of the current screen colour depth if depth is -1) which entails
 122 that a colour reduction may have to take place.",
 123         BitmapFromImage);
 124
 125
 126     %extend {
 127         DocStr(wxBitmap(PyObject* listOfStrings),
 128                "Construct a Bitmap from a list of strings formatted as XPM data.");
 129         %name(BitmapFromXPMData) wxBitmap(PyObject* listOfStrings) {
 130             char**    cArray = NULL;
 131             wxBitmap* bmp;
 132
 133             cArray = ConvertListOfStrings(listOfStrings);
 134             if (! cArray)
 135                 return NULL;
 136             bmp = new wxBitmap(cArray);
 137             delete [] cArray;
 138             return bmp;
 139         }
 140
 141         DocStr(wxBitmap(PyObject* bits, int width, int height, int depth=1 ),
 142                "Creates a bitmap from an array of bits.  You should only use this
 143 function for monochrome bitmaps (depth 1) in portable programs: in
 144 this case the bits parameter should contain an XBM image.  For other
 145 bit depths, the behaviour is platform dependent.");
 146         %name(BitmapFromBits) wxBitmap(PyObject* bits, int width, int height, int depth=1 ) {
 147             char* buf;
 148             int   length;
 149             PyString_AsStringAndSize(bits, &buf, &length);
 150             return new wxBitmap(buf, width, height, depth);
 151         }
 152     }
 153
 154
 155 #ifdef __WXMSW__
 156     void SetPalette(wxPalette& palette);
 157 #endif
 158
 159     // wxGDIImage methods
 160 #ifdef __WXMSW__
 161     long GetHandle();
 162     %extend {
 163         void SetHandle(long handle) { self->SetHandle((WXHANDLE)handle); }
 164     }
 165 #endif
 166
 167     bool Ok();
 168
 169     DocDeclStr(
 170         int , GetWidth(),
 171         "Gets the width of the bitmap in pixels.");
 172
 173
 174     DocDeclStr(
 175         int , GetHeight(),
 176         "Gets the height of the bitmap in pixels.");
 177
 178
 179     DocDeclStr(
 180         int , GetDepth(),
 181         "Gets the colour depth of the bitmap. A value of 1 indicates a
 182 monochrome bitmap.");
 183
 184
 185
 186     %extend {
 187         DocStr(GetSize, "Get the size of the bitmap.");
 188         wxSize GetSize() {
 189             wxSize size(self->GetWidth(), self->GetHeight());
 190             return size;
 191         }
 192     }
 193
 194
 195     DocDeclStr(
 196         virtual wxImage , ConvertToImage() const,
 197         "Creates a platform-independent image from a platform-dependent
 198 bitmap. This preserves mask information so that bitmaps and images can
 199 be converted back and forth without loss in that respect.");
 200
 201
 202     DocDeclStr(
 203         virtual wxMask* , GetMask() const,
 204         "Gets the associated mask (if any) which may have been loaded from a
 205 file or explpicitly set for the bitmap.
 206
 207 :see: `SetMask`, `wx.Mask`
 208 ");
 209
 210
 211     DocDeclStr(
 212         virtual void , SetMask(wxMask* mask),
 213         "Sets the mask for this bitmap.
 214
 215 :see: `GetMask`, `wx.Mask`
 216 ");
 217
 218
 219     %extend {
 220         DocStr(SetMaskColour,
 221                "Create a Mask based on a specified colour in the Bitmap.");
 222         void SetMaskColour(const wxColour& colour) {
 223             wxMask *mask = new wxMask(*self, colour);
 224             self->SetMask(mask);
 225         }
 226     }
 227
 228
 229     DocDeclStr(
 230         virtual wxBitmap , GetSubBitmap(const wxRect& rect) const,
 231         "Returns a sub-bitmap of the current one as long as the rect belongs
 232 entirely to the bitmap. This function preserves bit depth and mask
 233 information.");
 234
 235
 236     DocDeclStr(
 237         virtual bool , SaveFile(const wxString &name, wxBitmapType type,
 238                                 wxPalette *palette = NULL),
 239         "Saves a bitmap in the named file.  See `__init__` for a description of
 240 the ``type`` parameter.");
 241
 242
 243     DocDeclStr(
 244         virtual bool , LoadFile(const wxString &name, wxBitmapType type),
 245         "Loads a bitmap from a file.  See `__init__` for a description of the
 246 ``type`` parameter.");
 247
 248
 249
 250 #if wxUSE_PALETTE
 251     virtual wxPalette *GetPalette() const;
 252     virtual void SetPalette(const wxPalette& palette);
 253 #endif
 254
 255
 256     virtual bool CopyFromIcon(const wxIcon& icon);
 257
 258     DocDeclStr(
 259         virtual void , SetHeight(int height),
 260         "Set the height property (does not affect the existing bitmap data).");
 261
 262
 263     DocDeclStr(
 264         virtual void , SetWidth(int width),
 265         "Set the width property (does not affect the existing bitmap data).");
 266
 267
 268     DocDeclStr(
 269         virtual void , SetDepth(int depth),
 270         "Set the depth property (does not affect the existing bitmap data).");
 271
 272
 273     %extend {
 274         DocStr(SetSize, "Set the bitmap size (does not affect the existing bitmap data).");
 275         void SetSize(const wxSize& size) {
 276             self->SetWidth(size.x);
 277             self->SetHeight(size.y);
 278         }
 279     }
 280
 281 #ifdef __WXMSW__
 282     bool CopyFromCursor(const wxCursor& cursor);
 283     int GetQuality();
 284     void SetQuality(int q);
 285 #endif
 286
 287     %pythoncode { def __nonzero__(self): return self.Ok() }
 288
 289     %extend {
 290         bool __eq__(const wxBitmap* other) { return other ? (*self == *other) : False; }
 291         bool __ne__(const wxBitmap* other) { return other ? (*self != *other) : True;  }
 292     }
 293 };
 294
 295
 296 //---------------------------------------------------------------------------
 297
 298 DocStr(wxMask,
 299 "This class encapsulates a monochrome mask bitmap, where the masked
 300 area is black and the unmasked area is white. When associated with a
 301 bitmap and drawn in a device context, the unmasked area of the bitmap
 302 will be drawn, and the masked area will not be drawn.
 303
 304 A mask may be associated with a `wx.Bitmap`. It is used in
 305 `wx.DC.DrawBitmap` or `wx.DC.Blit` when the source device context is a
 306 `wx.MemoryDC` with a `wx.Bitmap` selected into it that contains a
 307 mask.
 308 ");
 309
 310 class wxMask : public wxObject {
 311 public:
 312
 313     DocStr(wxMask,
 314            "Constructs a mask from a `wx.Bitmap` and a `wx.Colour` in that bitmap
 315 that indicates the transparent portions of the mask.  In other words,
 316 the pixels in ``bitmap`` that match ``colour`` will be the transparent
 317 portions of the mask.  If no ``colour`` or an invalid ``colour`` is
 318 passed then BLACK is used.
 319
 320 :see: `wx.Bitmap`, `wx.Colour`");
 321
 322     %extend {
 323         wxMask(const wxBitmap& bitmap, const wxColour& colour = wxNullColour) {
 324             if ( !colour.Ok() )
 325                 return new wxMask(bitmap, *wxBLACK);
 326             else
 327                 return new wxMask(bitmap, colour);
 328         }
 329     }
 330
 331     //~wxMask();
 332 };
 333
 334 %pythoncode { MaskColour = wx._deprecated(Mask, "wx.MaskColour is deprecated, use `wx.Mask` instead.") }
 335
 336 //---------------------------------------------------------------------------
 337 //---------------------------------------------------------------------------