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         %name(BitmapFromXPMData) wxBitmap(PyObject* listOfStrings) {
 132             char**    cArray = NULL;
 133             wxBitmap* bmp;
 134
 135             cArray = ConvertListOfStrings(listOfStrings);
 136             if (! cArray)
 137                 return NULL;
 138             bmp = new wxBitmap(cArray);
 139             delete [] cArray;
 140             return bmp;
 141         }
 142
 143         DocStr(wxBitmap(PyObject* bits, int width, int height, int depth=1 ),
 144                "Creates a bitmap from an array of bits.  You should only use this
 145 function for monochrome bitmaps (depth 1) in portable programs: in
 146 this case the bits parameter should contain an XBM image.  For other
 147 bit depths, the behaviour is platform dependent.", "");
 148         %name(BitmapFromBits) wxBitmap(PyObject* bits, int width, int height, int depth=1 ) {
 149             char* buf;
 150             int   length;
 151             PyString_AsStringAndSize(bits, &buf, &length);
 152             return new wxBitmap(buf, width, height, depth);
 153         }
 154     }
 155
 156
 157     // wxGDIImage methods
 158 #ifdef __WXMSW__
 159     long GetHandle();
 160     %extend {
 161         void SetHandle(long handle) { self->SetHandle((WXHANDLE)handle); }
 162     }
 163 #endif
 164
 165     bool Ok();
 166
 167     DocDeclStr(
 168         int , GetWidth(),
 169         "Gets the width of the bitmap in pixels.", "");
 170
 171
 172     DocDeclStr(
 173         int , GetHeight(),
 174         "Gets the height of the bitmap in pixels.", "");
 175
 176
 177     DocDeclStr(
 178         int , GetDepth(),
 179         "Gets the colour depth of the bitmap. A value of 1 indicates a
 180 monochrome bitmap.", "");
 181
 182
 183
 184     %extend {
 185         DocStr(GetSize, "Get the size of the bitmap.", "");
 186         wxSize GetSize() {
 187             wxSize size(self->GetWidth(), self->GetHeight());
 188             return size;
 189         }
 190     }
 191
 192
 193     DocDeclStr(
 194         virtual wxImage , ConvertToImage() const,
 195         "Creates a platform-independent image from a platform-dependent
 196 bitmap. This preserves mask information so that bitmaps and images can
 197 be converted back and forth without loss in that respect.", "");
 198
 199
 200     DocDeclStr(
 201         virtual wxMask* , GetMask() const,
 202         "Gets the associated mask (if any) which may have been loaded from a
 203 file or explpicitly set for the bitmap.
 204
 205 :see: `SetMask`, `wx.Mask`
 206 ", "");
 207
 208
 209     DocDeclStr(
 210         virtual void , SetMask(wxMask* mask),
 211         "Sets the mask for this bitmap.
 212
 213 :see: `GetMask`, `wx.Mask`
 214 ", "");
 215
 216
 217     %extend {
 218         DocStr(SetMaskColour,
 219                "Create a Mask based on a specified colour in the Bitmap.", "");
 220         void SetMaskColour(const wxColour& colour) {
 221             wxMask *mask = new wxMask(*self, colour);
 222             self->SetMask(mask);
 223         }
 224     }
 225
 226
 227     DocDeclStr(
 228         virtual wxBitmap , GetSubBitmap(const wxRect& rect) const,
 229         "Returns a sub-bitmap of the current one as long as the rect belongs
 230 entirely to the bitmap. This function preserves bit depth and mask
 231 information.", "");
 232
 233
 234     DocDeclStr(
 235         virtual bool , SaveFile(const wxString &name, wxBitmapType type,
 236                                 wxPalette *palette = NULL),
 237         "Saves a bitmap in the named file.  See `__init__` for a description of
 238 the ``type`` parameter.", "");
 239
 240
 241     DocDeclStr(
 242         virtual bool , LoadFile(const wxString &name, wxBitmapType type),
 243         "Loads a bitmap from a file.  See `__init__` for a description of the
 244 ``type`` parameter.", "");
 245
 246
 247
 248     virtual wxPalette *GetPalette() const;
 249 #ifdef __WXMSW__
 250     virtual void SetPalette(const wxPalette& palette);
 251 #endif
 252
 253
 254     virtual bool CopyFromIcon(const wxIcon& icon);
 255
 256     DocDeclStr(
 257         virtual void , SetHeight(int height),
 258         "Set the height property (does not affect the existing bitmap data).", "");
 259
 260
 261     DocDeclStr(
 262         virtual void , SetWidth(int width),
 263         "Set the width property (does not affect the existing bitmap data).", "");
 264
 265
 266     DocDeclStr(
 267         virtual void , SetDepth(int depth),
 268         "Set the depth property (does not affect the existing bitmap data).", "");
 269
 270
 271     %extend {
 272         DocStr(SetSize, "Set the bitmap size (does not affect the existing bitmap data).", "");
 273         void SetSize(const wxSize& size) {
 274             self->SetWidth(size.x);
 275             self->SetHeight(size.y);
 276         }
 277     }
 278
 279 #ifdef __WXMSW__
 280     bool CopyFromCursor(const wxCursor& cursor);
 281     int GetQuality();
 282     void SetQuality(int q);
 283 #endif
 284
 285     %pythoncode { def __nonzero__(self): return self.Ok() }
 286
 287     %extend {
 288         bool __eq__(const wxBitmap* other) { return other ? (*self == *other) : false; }
 289         bool __ne__(const wxBitmap* other) { return other ? (*self != *other) : true;  }
 290     }
 291 };
 292
 293
 294 //---------------------------------------------------------------------------
 295
 296 DocStr(wxMask,
 297 "This class encapsulates a monochrome mask bitmap, where the masked
 298 area is black and the unmasked area is white. When associated with a
 299 bitmap and drawn in a device context, the unmasked area of the bitmap
 300 will be drawn, and the masked area will not be drawn.
 301
 302 A mask may be associated with a `wx.Bitmap`. It is used in
 303 `wx.DC.DrawBitmap` or `wx.DC.Blit` when the source device context is a
 304 `wx.MemoryDC` with a `wx.Bitmap` selected into it that contains a
 305 mask.", "");
 306
 307 MustHaveApp(wxMask);
 308
 309 class wxMask : public wxObject {
 310 public:
 311
 312     DocStr(wxMask,
 313            "Constructs a mask from a `wx.Bitmap` and a `wx.Colour` in that bitmap
 314 that indicates the transparent portions of the mask.  In other words,
 315 the pixels in ``bitmap`` that match ``colour`` will be the transparent
 316 portions of the mask.  If no ``colour`` or an invalid ``colour`` is
 317 passed then BLACK is used.
 318
 319 :see: `wx.Bitmap`, `wx.Colour`", "");
 320
 321     %extend {
 322         wxMask(const wxBitmap& bitmap, const wxColour& colour = wxNullColour) {
 323             if ( !colour.Ok() )
 324                 return new wxMask(bitmap, *wxBLACK);
 325             else
 326                 return new wxMask(bitmap, colour);
 327         }
 328     }
 329
 330     //~wxMask();
 331 };
 332
 333 %pythoncode { MaskColour = wx._deprecated(Mask, "wx.MaskColour is deprecated, use `wx.Mask` instead.") }
 334
 335 //---------------------------------------------------------------------------
 336 //---------------------------------------------------------------------------