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