]> git.saurik.com Git - wxWidgets.git/blob - wxPython/src/_bitmap.i
8aa329e133610ff35cb5d84b92aec9051419b4b4
[wxWidgets.git] / 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 #include <wx/rawbmp.h>
17 %}
18
19 //---------------------------------------------------------------------------
20
21 %{
22 #include <wx/image.h>
23
24 static char** ConvertListOfStrings(PyObject* listOfStrings) {
25 char** cArray = NULL;
26 int count;
27
28 if (!PyList_Check(listOfStrings)) {
29 PyErr_SetString(PyExc_TypeError, "Expected a list of strings.");
30 return NULL;
31 }
32 count = PyList_Size(listOfStrings);
33 cArray = new char*[count];
34
35 for(int x=0; x<count; x++) {
36 // TODO: Need some validation and error checking here
37 cArray[x] = PyString_AsString(PyList_GET_ITEM(listOfStrings, x));
38 }
39 return cArray;
40 }
41
42 %}
43
44 //---------------------------------------------------------------------------
45
46 // TODO: When the API stabalizes and is available on other platforms, add
47 // wrappers for the new wxBitmap, wxRawBitmap, wxDIB stuff...
48
49 DocStr(wxBitmap,
50 "The wx.Bitmap class encapsulates the concept of a platform-dependent
51 bitmap. It can be either monochrome or colour, and either loaded from
52 a file or created dynamically. A bitmap can be selected into a memory
53 device context (instance of `wx.MemoryDC`). This enables the bitmap to
54 be copied to a window or memory device context using `wx.DC.Blit`, or
55 to be used as a drawing surface.", "
56
57 The BMP and XMP image file formats are supported on all platforms by
58 wx.Bitmap. Other formats are automatically loaded by `wx.Image` and
59 converted to a wx.Bitmap, so any image file format supported by
60 `wx.Image` can be used.
61
62 :todo: Add wrappers and support for raw bitmap data access. Can this
63 be be put into Python without losing the speed benefits of the
64 teplates and iterators in rawbmp.h?
65
66 :todo: Find a way to do very efficient PIL Image <--> wx.Bitmap
67 converstions.
68
69 :see: `wx.EmptyBitmap`, `wx.BitmapFromIcon`, `wx.BitmapFromImage`,
70 `wx.BitmapFromXPMData`, `wx.BitmapFromBits`, `wx.BitmapFromBuffer`,
71 `wx.BitmapFromBufferRGBA`, `wx.Image`
72 ");
73
74
75 MustHaveApp(wxBitmap);
76
77 class wxBitmap : public wxGDIObject
78 {
79 public:
80 DocCtorStr(
81 wxBitmap(const wxString& name, wxBitmapType type=wxBITMAP_TYPE_ANY),
82 "Loads a bitmap from a file.",
83 "
84 :param name: Name of the file to load the bitmap from.
85 :param type: The type of image to expect. Can be one of the following
86 constants (assuming that the neccessary `wx.Image` handlers are
87 loaded):
88
89 * wx.BITMAP_TYPE_ANY
90 * wx.BITMAP_TYPE_BMP
91 * wx.BITMAP_TYPE_ICO
92 * wx.BITMAP_TYPE_CUR
93 * wx.BITMAP_TYPE_XBM
94 * wx.BITMAP_TYPE_XPM
95 * wx.BITMAP_TYPE_TIF
96 * wx.BITMAP_TYPE_GIF
97 * wx.BITMAP_TYPE_PNG
98 * wx.BITMAP_TYPE_JPEG
99 * wx.BITMAP_TYPE_PNM
100 * wx.BITMAP_TYPE_PCX
101 * wx.BITMAP_TYPE_PICT
102 * wx.BITMAP_TYPE_ICON
103 * wx.BITMAP_TYPE_ANI
104 * wx.BITMAP_TYPE_IFF
105
106 :see: Alternate constructors `wx.EmptyBitmap`, `wx.BitmapFromIcon`,
107 `wx.BitmapFromImage`, `wx.BitmapFromXPMData`,
108 `wx.BitmapFromBits`
109 ");
110
111 ~wxBitmap();
112
113 DocCtorStrName(
114 wxBitmap(int width, int height, int depth=-1),
115 "Creates a new bitmap of the given size. A depth of -1 indicates the
116 depth of the current screen or visual. Some platforms only support 1
117 for monochrome and -1 for the current display depth.", "",
118 EmptyBitmap);
119
120 DocCtorStrName(
121 wxBitmap(const wxIcon& icon),
122 "Create a new bitmap from a `wx.Icon` object.", "",
123 BitmapFromIcon);
124
125 DocCtorStrName(
126 wxBitmap(const wxImage& image, int depth=-1),
127 "Creates bitmap object from a `wx.Image`. This has to be done to
128 actually display a `wx.Image` as you cannot draw an image directly on
129 a window. The resulting bitmap will use the provided colour depth (or
130 that of the current screen colour depth if depth is -1) which entails
131 that a colour reduction may have to take place.", "",
132 BitmapFromImage);
133
134
135 %extend {
136 %RenameDocCtor(
137 BitmapFromXPMData,
138 "Construct a Bitmap from a list of strings formatted as XPM data.", "",
139 wxBitmap(PyObject* listOfStrings))
140 {
141 char** cArray = NULL;
142 wxBitmap* bmp;
143
144 cArray = ConvertListOfStrings(listOfStrings);
145 if (! cArray)
146 return NULL;
147 bmp = new wxBitmap(cArray);
148 delete [] cArray;
149 return bmp;
150 }
151
152
153 %RenameDocCtor(
154 BitmapFromBits,
155 "Creates a bitmap from an array of bits. You should only use this
156 function for monochrome bitmaps (depth 1) in portable programs: in
157 this case the bits parameter should contain an XBM image. For other
158 bit depths, the behaviour is platform dependent.", "",
159 wxBitmap(PyObject* bits, int width, int height, int depth=1 ))
160 {
161 char* buf;
162 Py_ssize_t length;
163 PyString_AsStringAndSize(bits, &buf, &length);
164 return new wxBitmap(buf, width, height, depth);
165 }
166 }
167
168
169 // wxGDIImage methods
170 #ifdef __WXMSW__
171 long GetHandle();
172 %extend {
173 void SetHandle(long handle) { self->SetHandle((WXHANDLE)handle); }
174 }
175 #endif
176
177 bool Ok();
178
179 DocDeclStr(
180 int , GetWidth(),
181 "Gets the width of the bitmap in pixels.", "");
182
183
184 DocDeclStr(
185 int , GetHeight(),
186 "Gets the height of the bitmap in pixels.", "");
187
188
189 DocDeclStr(
190 int , GetDepth(),
191 "Gets the colour depth of the bitmap. A value of 1 indicates a
192 monochrome bitmap.", "");
193
194
195
196 %extend {
197 DocStr(GetSize, "Get the size of the bitmap.", "");
198 wxSize GetSize() {
199 wxSize size(self->GetWidth(), self->GetHeight());
200 return size;
201 }
202 }
203
204
205 DocDeclStr(
206 virtual wxImage , ConvertToImage() const,
207 "Creates a platform-independent image from a platform-dependent
208 bitmap. This preserves mask information so that bitmaps and images can
209 be converted back and forth without loss in that respect.", "");
210
211
212
213 DocDeclStr(
214 virtual wxMask* , GetMask() const,
215 "Gets the associated mask (if any) which may have been loaded from a
216 file or explpicitly set for the bitmap.
217
218 :see: `SetMask`, `wx.Mask`
219 ", "");
220
221 // MSW only? wxBitmap GetMaskBitmap() const;
222
223 %disownarg(wxMask*);
224 DocDeclStr(
225 virtual void , SetMask(wxMask* mask),
226 "Sets the mask for this bitmap.
227
228 :see: `GetMask`, `wx.Mask`
229 ", "");
230 %cleardisown(wxMask*);
231
232 %extend {
233 DocStr(SetMaskColour,
234 "Create a Mask based on a specified colour in the Bitmap.", "");
235 void SetMaskColour(const wxColour& colour) {
236 wxMask *mask = new wxMask(*self, colour);
237 self->SetMask(mask);
238 }
239 }
240
241
242 DocDeclStr(
243 virtual wxBitmap , GetSubBitmap(const wxRect& rect) const,
244 "Returns a sub-bitmap of the current one as long as the rect belongs
245 entirely to the bitmap. This function preserves bit depth and mask
246 information.", "");
247
248
249 DocDeclStr(
250 virtual bool , SaveFile(const wxString &name, wxBitmapType type,
251 wxPalette *palette = NULL),
252 "Saves a bitmap in the named file. See `__init__` for a description of
253 the ``type`` parameter.", "");
254
255
256 DocDeclStr(
257 virtual bool , LoadFile(const wxString &name, wxBitmapType type),
258 "Loads a bitmap from a file. See `__init__` for a description of the
259 ``type`` parameter.", "");
260
261
262
263 virtual wxPalette *GetPalette() const;
264 #ifdef __WXMSW__
265 virtual void SetPalette(const wxPalette& palette);
266 #endif
267
268
269 virtual bool CopyFromIcon(const wxIcon& icon);
270
271 DocDeclStr(
272 virtual void , SetHeight(int height),
273 "Set the height property (does not affect the existing bitmap data).", "");
274
275
276 DocDeclStr(
277 virtual void , SetWidth(int width),
278 "Set the width property (does not affect the existing bitmap data).", "");
279
280
281 DocDeclStr(
282 virtual void , SetDepth(int depth),
283 "Set the depth property (does not affect the existing bitmap data).", "");
284
285
286 %extend {
287 DocStr(SetSize, "Set the bitmap size (does not affect the existing bitmap data).", "");
288 void SetSize(const wxSize& size) {
289 self->SetWidth(size.x);
290 self->SetHeight(size.y);
291 }
292 }
293
294 #ifdef __WXMSW__
295 bool CopyFromCursor(const wxCursor& cursor);
296
297 // WXWIN_COMPATIBILITY_2_4
298 #if 0
299 int GetQuality();
300 void SetQuality(int q);
301 %pythoncode { GetQuality = wx._deprecated(GetQuality) }
302 %pythoncode { SetQuality = wx._deprecated(SetQuality) }
303 #endif
304 #endif
305
306 %pythoncode { def __nonzero__(self): return self.Ok() }
307
308 %extend {
309 bool __eq__(const wxBitmap* other) { return other ? (*self == *other) : false; }
310 bool __ne__(const wxBitmap* other) { return other ? (*self != *other) : true; }
311 }
312 };
313
314
315 //---------------------------------------------------------------------------
316 // Factory functions for creating wxBitmaps from Python buffer objects. They
317 // use the Abstract Pixel API to be able to set RGB and A bytes directly into
318 // the wxBitmap's pixel buffer.
319
320 %newobject _BitmapFromBufferAlpha;
321 %newobject _BitmapFromBuffer;
322 %inline %{
323 wxBitmap* _BitmapFromBufferAlpha(int width, int height,
324 buffer data, int DATASIZE,
325 buffer alpha, int ALPHASIZE)
326 {
327 if (DATASIZE != width*height*3) {
328 wxPyErr_SetString(PyExc_ValueError, "Invalid data buffer size.");
329 return NULL;
330 }
331
332 if (ALPHASIZE != width*height) {
333 wxPyErr_SetString(PyExc_ValueError, "Invalid alpha buffer size.");
334 return NULL;
335 }
336
337 wxBitmap* bmp = new wxBitmap(width, height, 32);
338 wxAlphaPixelData pixels(*bmp, wxPoint(0,0), wxSize(width,height));
339 if (! pixels) {
340 // raise an exception...
341 wxPyErr_SetString(PyExc_RuntimeError,
342 "Failed to gain raw access to bitmap data.");
343 return NULL;
344 }
345
346 pixels.UseAlpha();
347 wxAlphaPixelData::Iterator p(pixels);
348 for (int y=0; y<height; y++) {
349 wxAlphaPixelData::Iterator rowStart = p;
350 for (int x=0; x<width; x++) {
351 p.Red() = *(data++);
352 p.Green() = *(data++);
353 p.Blue() = *(data++);
354 p.Alpha() = *(alpha++);
355 ++p;
356 }
357 p = rowStart;
358 p.OffsetY(pixels, 1);
359 }
360 return bmp;
361 }
362
363 wxBitmap* _BitmapFromBuffer(int width, int height, buffer data, int DATASIZE)
364 {
365 if (DATASIZE != width*height*3) {
366 wxPyErr_SetString(PyExc_ValueError, "Invalid data buffer size.");
367 return NULL;
368 }
369
370 wxBitmap* bmp = new wxBitmap(width, height, 24);
371 wxNativePixelData pixels(*bmp, wxPoint(0,0), wxSize(width,height));
372 if (! pixels) {
373 // raise an exception...
374 wxPyErr_SetString(PyExc_RuntimeError,
375 "Failed to gain raw access to bitmap data.");
376 return NULL;
377 }
378
379 wxNativePixelData::Iterator p(pixels);
380 for (int y=0; y<height; y++) {
381 wxNativePixelData::Iterator rowStart = p;
382 for (int x=0; x<width; x++) {
383 p.Red() = *(data++);
384 p.Green() = *(data++);
385 p.Blue() = *(data++);
386 ++p;
387 }
388 p = rowStart;
389 p.OffsetY(pixels, 1);
390 }
391 return bmp;
392 }
393 %}
394
395
396 %pythoncode {
397 def BitmapFromBuffer(width, height, dataBuffer, alphaBuffer=None):
398 """
399 Creates a `wx.Bitmap` from the data in dataBuffer. The dataBuffer
400 parameter must be a Python object that implements the buffer interface, or
401 is convertable to a buffer object, such as a string, array, etc. The
402 dataBuffer object is expected to contain a series of RGB bytes and be
403 width*height*3 bytes long. A buffer object can optionally be supplied for
404 the image's alpha channel data, and it is expected to be width*height
405 bytes long.
406
407 Unlike `wx.ImageFromBuffer` the bitmap created with this function does not
408 share the memory buffer with the buffer object. This is because the
409 native pixel buffer format varies on different platforms, and so instead
410 an efficient as possible copy of the data is made from the buffer objects
411 to the bitmap's native pixel buffer. For direct access to a bitmap's
412 pixel buffer see `wx.NativePixelData` and `wx.AlphaPixelData`.
413
414 :see: `wx.Bitmap`, `wx.BitmapFromBufferRGBA`, `wx.NativePixelData`,
415 `wx.AlphaPixelData`, `wx.ImageFromBuffer`
416 """
417 if not isinstance(dataBuffer, buffer):
418 dataBuffer = buffer(dataBuffer)
419 if alphaBuffer is not None and not isinstance(alphaBuffer, buffer):
420 alphaBuffer = buffer(alphaBuffer)
421 if alphaBuffer is not None:
422 return _gdi_._BitmapFromBufferAlpha(width, height, dataBuffer, alphaBuffer)
423 else:
424 return _gdi_._BitmapFromBuffer(width, height, dataBuffer)
425 }
426
427
428
429 %newobject _BitmapFromBufferRGBA;
430 %inline %{
431 wxBitmap* _BitmapFromBufferRGBA(int width, int height, buffer data, int DATASIZE)
432 {
433 if (DATASIZE != width*height*4) {
434 wxPyErr_SetString(PyExc_ValueError, "Invalid data buffer size.");
435 return NULL;
436 }
437
438 wxBitmap* bmp = new wxBitmap(width, height, 32);
439 wxAlphaPixelData pixels(*bmp, wxPoint(0,0), wxSize(width,height));
440 if (! pixels) {
441 // raise an exception...
442 wxPyErr_SetString(PyExc_RuntimeError,
443 "Failed to gain raw access to bitmap data.");
444 return NULL;
445 }
446
447 pixels.UseAlpha();
448 wxAlphaPixelData::Iterator p(pixels);
449 for (int y=0; y<height; y++) {
450 wxAlphaPixelData::Iterator rowStart = p;
451 for (int x=0; x<width; x++) {
452 p.Red() = *(data++);
453 p.Green() = *(data++);
454 p.Blue() = *(data++);
455 p.Alpha() = *(data++);
456 ++p;
457 }
458 p = rowStart;
459 p.OffsetY(pixels, 1);
460 }
461 return bmp;
462 }
463 %}
464
465 %pythoncode {
466 def BitmapFromBufferRGBA(width, height, dataBuffer):
467 """
468 Creates a `wx.Bitmap` from the data in dataBuffer. The dataBuffer
469 parameter must be a Python object that implements the buffer interface, or
470 is convertable to a buffer object, such as a string, array, etc. The
471 dataBuffer object is expected to contain a series of RGBA bytes (red,
472 gree, blue and alpha) and be width*height*4 bytes long.
473
474 Unlike `wx.ImageFromBuffer` the bitmap created with this function does not
475 share the memory buffer with the buffer object. This is because the
476 native pixel buffer format varies on different platforms, and so instead
477 an efficient as possible copy of the data is made from the buffer object
478 to the bitmap's native pixel buffer. For direct access to a bitmap's
479 pixel buffer see `wx.NativePixelData` and `wx.AlphaPixelData`.
480
481 :see: `wx.Bitmap`, `wx.BitmapFromBuffer`, `wx.NativePixelData`,
482 `wx.AlphaPixelData`, `wx.ImageFromBuffer`
483 """
484 if not isinstance(dataBuffer, buffer):
485 dataBuffer = buffer(dataBuffer)
486 return _gdi_._BitmapFromBufferRGBA(width, height, dataBuffer)
487 }
488
489
490 //---------------------------------------------------------------------------
491
492 DocStr(wxMask,
493 "This class encapsulates a monochrome mask bitmap, where the masked
494 area is black and the unmasked area is white. When associated with a
495 bitmap and drawn in a device context, the unmasked area of the bitmap
496 will be drawn, and the masked area will not be drawn.
497
498 A mask may be associated with a `wx.Bitmap`. It is used in
499 `wx.DC.DrawBitmap` or `wx.DC.Blit` when the source device context is a
500 `wx.MemoryDC` with a `wx.Bitmap` selected into it that contains a
501 mask.", "");
502
503 MustHaveApp(wxMask);
504
505 class wxMask : public wxObject {
506 public:
507
508 DocStr(wxMask,
509 "Constructs a mask from a `wx.Bitmap` and a `wx.Colour` in that bitmap
510 that indicates the transparent portions of the mask. In other words,
511 the pixels in ``bitmap`` that match ``colour`` will be the transparent
512 portions of the mask. If no ``colour`` or an invalid ``colour`` is
513 passed then BLACK is used.
514
515 :see: `wx.Bitmap`, `wx.Colour`", "");
516
517 %extend {
518 wxMask(const wxBitmap& bitmap, const wxColour& colour = wxNullColour) {
519 if ( !colour.Ok() )
520 return new wxMask(bitmap, *wxBLACK);
521 else
522 return new wxMask(bitmap, colour);
523 }
524 }
525
526 ~wxMask();
527 };
528
529 %pythoncode { MaskColour = wx._deprecated(Mask, "wx.MaskColour is deprecated, use `wx.Mask` instead.") }
530
531 //---------------------------------------------------------------------------
532 //---------------------------------------------------------------------------