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