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 colour setting.", "",
 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     DocDeclStr(
 205         virtual wxMask* , GetMask() const,
 206         "Gets the associated mask (if any) which may have been loaded from a
 207 file or explpicitly set for the bitmap.
 208
 209 :see: `SetMask`, `wx.Mask`
 210 ", "");
 211
 212     // MSW only?    wxBitmap GetMaskBitmap() const;
 213
 214     DocDeclStr(
 215         virtual void , SetMask(wxMask* mask),
 216         "Sets the mask for this bitmap.
 217
 218 :see: `GetMask`, `wx.Mask`
 219 ", "");
 220
 221
 222     %extend {
 223         DocStr(SetMaskColour,
 224                "Create a Mask based on a specified colour in the Bitmap.", "");
 225         void SetMaskColour(const wxColour& colour) {
 226             wxMask *mask = new wxMask(*self, colour);
 227             self->SetMask(mask);
 228         }
 229     }
 230
 231
 232     DocDeclStr(
 233         virtual wxBitmap , GetSubBitmap(const wxRect& rect) const,
 234         "Returns a sub-bitmap of the current one as long as the rect belongs
 235 entirely to the bitmap. This function preserves bit depth and mask
 236 information.", "");
 237
 238
 239     DocDeclStr(
 240         virtual bool , SaveFile(const wxString &name, wxBitmapType type,
 241                                 wxPalette *palette = NULL),
 242         "Saves a bitmap in the named file.  See `__init__` for a description of
 243 the ``type`` parameter.", "");
 244
 245
 246     DocDeclStr(
 247         virtual bool , LoadFile(const wxString &name, wxBitmapType type),
 248         "Loads a bitmap from a file.  See `__init__` for a description of the
 249 ``type`` parameter.", "");
 250
 251
 252
 253     virtual wxPalette *GetPalette() const;
 254 #ifdef __WXMSW__
 255     virtual void SetPalette(const wxPalette& palette);
 256 #endif
 257
 258
 259     virtual bool CopyFromIcon(const wxIcon& icon);
 260
 261     DocDeclStr(
 262         virtual void , SetHeight(int height),
 263         "Set the height property (does not affect the existing bitmap data).", "");
 264
 265
 266     DocDeclStr(
 267         virtual void , SetWidth(int width),
 268         "Set the width property (does not affect the existing bitmap data).", "");
 269
 270
 271     DocDeclStr(
 272         virtual void , SetDepth(int depth),
 273         "Set the depth property (does not affect the existing bitmap data).", "");
 274
 275
 276     %extend {
 277         DocStr(SetSize, "Set the bitmap size (does not affect the existing bitmap data).", "");
 278         void SetSize(const wxSize& size) {
 279             self->SetWidth(size.x);
 280             self->SetHeight(size.y);
 281         }
 282     }
 283
 284 #ifdef __WXMSW__
 285     bool CopyFromCursor(const wxCursor& cursor);
 286
 287 // WXWIN_COMPATIBILITY_2_4
 288   #if 0
 289     int GetQuality();
 290     void SetQuality(int q);
 291     %pythoncode { GetQuality = wx._deprecated(GetQuality) }
 292     %pythoncode { SetQuality = wx._deprecated(SetQuality) }
 293   #endif
 294 #endif
 295
 296     %pythoncode { def __nonzero__(self): return self.Ok() }
 297
 298     %extend {
 299         bool __eq__(const wxBitmap* other) { return other ? (*self == *other) : false; }
 300         bool __ne__(const wxBitmap* other) { return other ? (*self != *other) : true;  }
 301     }
 302 };
 303
 304
 305 //---------------------------------------------------------------------------
 306
 307 DocStr(wxMask,
 308 "This class encapsulates a monochrome mask bitmap, where the masked
 309 area is black and the unmasked area is white. When associated with a
 310 bitmap and drawn in a device context, the unmasked area of the bitmap
 311 will be drawn, and the masked area will not be drawn.
 312
 313 A mask may be associated with a `wx.Bitmap`. It is used in
 314 `wx.DC.DrawBitmap` or `wx.DC.Blit` when the source device context is a
 315 `wx.MemoryDC` with a `wx.Bitmap` selected into it that contains a
 316 mask.", "");
 317
 318 MustHaveApp(wxMask);
 319
 320 class wxMask : public wxObject {
 321 public:
 322
 323     DocStr(wxMask,
 324            "Constructs a mask from a `wx.Bitmap` and a `wx.Colour` in that bitmap
 325 that indicates the transparent portions of the mask.  In other words,
 326 the pixels in ``bitmap`` that match ``colour`` will be the transparent
 327 portions of the mask.  If no ``colour`` or an invalid ``colour`` is
 328 passed then BLACK is used.
 329
 330 :see: `wx.Bitmap`, `wx.Colour`", "");
 331
 332     %extend {
 333         wxMask(const wxBitmap& bitmap, const wxColour& colour = wxNullColour) {
 334             if ( !colour.Ok() )
 335                 return new wxMask(bitmap, *wxBLACK);
 336             else
 337                 return new wxMask(bitmap, colour);
 338         }
 339     }
 340
 341     //~wxMask();
 342 };
 343
 344 %pythoncode { MaskColour = wx._deprecated(Mask, "wx.MaskColour is deprecated, use `wx.Mask` instead.") }
 345
 346 //---------------------------------------------------------------------------
 347 //---------------------------------------------------------------------------