]> git.saurik.com Git - wxWidgets.git/blame - interface/wx/bitmap.h
Document that throwing exceptions from wxTimer::Notify() is unsupported.
[wxWidgets.git] / interface / wx / bitmap.h
CommitLineData
23324ae1
FM
1/////////////////////////////////////////////////////////////////////////////
2// Name: bitmap.h
698d17c3 3// Purpose: interface of wxBitmap* classes
23324ae1
FM
4// Author: wxWidgets team
5// RCS-ID: $Id$
6// Licence: wxWindows license
7/////////////////////////////////////////////////////////////////////////////
8
8024723d
FM
9
10/**
11 In wxBitmap and wxBitmapHandler context this value means: "use the screen depth".
12*/
13#define wxBITMAP_SCREEN_DEPTH (-1)
14
23324ae1
FM
15/**
16 @class wxBitmapHandler
7c913512 17
698d17c3
FM
18 This is the base class for implementing bitmap file loading/saving, and
19 bitmap creation from data.
23324ae1 20 It is used within wxBitmap and is not normally seen by the application.
7c913512 21
23324ae1 22 If you wish to extend the capabilities of wxBitmap, derive a class from
1413ac04 23 wxBitmapHandler and add the handler using wxBitmap::AddHandler() in your
c83d207b 24 application initialization.
7c913512 25
427c415b
FM
26 Note that all wxBitmapHandlers provided by wxWidgets are part of the
27 @ref page_libs_wxcore library.
28 For details about the default handlers, please see the note in the
29 wxBitmap class documentation.
30
23324ae1 31 @library{wxcore}
3c99e2fd 32 @category{gdi}
7c913512 33
698d17c3 34 @see @ref overview_bitmap, wxBitmap, wxIcon, wxCursor
23324ae1
FM
35*/
36class wxBitmapHandler : public wxObject
37{
38public:
39 /**
698d17c3
FM
40 Default constructor.
41
42 In your own default constructor, initialise the members m_name,
43 m_extension and m_type.
23324ae1
FM
44 */
45 wxBitmapHandler();
46
47 /**
48 Destroys the wxBitmapHandler object.
49 */
d2aa927a 50 virtual ~wxBitmapHandler();
23324ae1
FM
51
52 /**
698d17c3
FM
53 Creates a bitmap from the given data, which can be of arbitrary type.
54 The wxBitmap object @a bitmap is manipulated by this function.
55
7c913512 56 @param bitmap
4cc4bfaf 57 The wxBitmap object.
7c913512 58 @param width
4cc4bfaf 59 The width of the bitmap in pixels.
7c913512 60 @param height
4cc4bfaf 61 The height of the bitmap in pixels.
7c913512 62 @param depth
8024723d
FM
63 The depth of the bitmap in pixels.
64 If this is ::wxBITMAP_SCREEN_DEPTH, the screen depth is used.
7c913512 65 @param data
4cc4bfaf 66 Data whose type depends on the value of type.
7c913512 67 @param type
698d17c3 68 A bitmap type identifier - see ::wxBitmapType for a list
4cc4bfaf 69 of possible values.
698d17c3 70
d29a9a8a 71 @return @true if the call succeeded, @false otherwise (the default).
23324ae1 72 */
8024723d 73 virtual bool Create(wxBitmap* bitmap, const void* data, wxBitmapType type,
1413ac04 74 int width, int height, int depth = 1);
23324ae1
FM
75
76 /**
77 Gets the file extension associated with this handler.
78 */
8024723d 79 const wxString& GetExtension() const;
23324ae1
FM
80
81 /**
82 Gets the name of this handler.
83 */
8024723d 84 const wxString& GetName() const;
23324ae1
FM
85
86 /**
87 Gets the bitmap type associated with this handler.
88 */
8024723d 89 wxBitmapType GetType() const;
23324ae1
FM
90
91 /**
698d17c3
FM
92 Loads a bitmap from a file or resource, putting the resulting data into
93 @a bitmap.
94
7c913512 95 @param bitmap
4cc4bfaf 96 The bitmap object which is to be affected by this operation.
7c913512 97 @param name
4cc4bfaf
FM
98 Either a filename or a Windows resource name.
99 The meaning of name is determined by the type parameter.
7c913512 100 @param type
8024723d 101 See ::wxBitmapType for values this can take.
2fd0ada5
FM
102 @param desiredWidth
103 The desired width for the loaded bitmap.
104 @param desiredHeight
105 The desired height for the loaded bitmap.
698d17c3 106
d29a9a8a 107 @return @true if the operation succeeded, @false otherwise.
698d17c3 108
4cc4bfaf 109 @see wxBitmap::LoadFile, wxBitmap::SaveFile, SaveFile()
23324ae1 110 */
1413ac04
FM
111 virtual bool LoadFile(wxBitmap* bitmap, const wxString& name, wxBitmapType type,
112 int desiredWidth, int desiredHeight);
23324ae1
FM
113
114 /**
115 Saves a bitmap in the named file.
698d17c3 116
7c913512 117 @param bitmap
4cc4bfaf 118 The bitmap object which is to be affected by this operation.
7c913512 119 @param name
4cc4bfaf 120 A filename. The meaning of name is determined by the type parameter.
7c913512 121 @param type
8024723d 122 See ::wxBitmapType for values this can take.
7c913512 123 @param palette
4cc4bfaf 124 An optional palette used for saving the bitmap.
698d17c3 125
d29a9a8a 126 @return @true if the operation succeeded, @false otherwise.
698d17c3 127
4cc4bfaf 128 @see wxBitmap::LoadFile, wxBitmap::SaveFile, LoadFile()
23324ae1 129 */
1413ac04 130 virtual bool SaveFile(const wxBitmap* bitmap, const wxString& name, wxBitmapType type,
2fd0ada5 131 const wxPalette* palette = NULL) const;
23324ae1
FM
132
133 /**
134 Sets the handler extension.
698d17c3 135
7c913512 136 @param extension
4cc4bfaf 137 Handler extension.
23324ae1
FM
138 */
139 void SetExtension(const wxString& extension);
140
141 /**
142 Sets the handler name.
698d17c3 143
7c913512 144 @param name
4cc4bfaf 145 Handler name.
23324ae1
FM
146 */
147 void SetName(const wxString& name);
148
149 /**
150 Sets the handler type.
698d17c3 151
698d17c3 152 @param type
4cc4bfaf 153 Handler type.
23324ae1 154 */
8024723d 155 void SetType(wxBitmapType type);
23324ae1
FM
156};
157
158
159/**
160 @class wxBitmap
7c913512 161
23324ae1
FM
162 This class encapsulates the concept of a platform-dependent bitmap,
163 either monochrome or colour or colour with alpha channel support.
cbea3ec6 164
de022e4f
RR
165 If you need direct access the bitmap data instead going through
166 drawing to it using wxMemoryDC you need to use the wxPixelData
167 class (either wxNativePixelData for RGB bitmaps or wxAlphaPixelData
168 for bitmaps with an additionaly alpha channel).
7c913512 169
c83d207b
FM
170 Note that many wxBitmap functions take a @e type parameter, which is a
171 value of the ::wxBitmapType enumeration.
698d17c3
FM
172 The validity of those values depends however on the platform where your program
173 is running and from the wxWidgets configuration.
c83d207b
FM
174 If all possible wxWidgets settings are used:
175 - wxMSW supports BMP and ICO files, BMP and ICO resources;
176 - wxGTK supports XPM files;
177 - wxMac supports PICT resources;
178 - wxX11 supports XPM files, XPM data, XBM data;
179
180 In addition, wxBitmap can load and save all formats that wxImage can; see wxImage
181 for more info. Of course, you must have loaded the wxImage handlers
182 (see ::wxInitAllImageHandlers() and wxImage::AddHandler).
183 Note that all available wxBitmapHandlers for a given wxWidgets port are
184 automatically loaded at startup so you won't need to use wxBitmap::AddHandler.
698d17c3 185
23324ae1
FM
186 @library{wxcore}
187 @category{gdi}
7c913512 188
23324ae1 189 @stdobjects
698d17c3 190 ::wxNullBitmap
7c913512 191
698d17c3 192 @see @ref overview_bitmap, @ref overview_bitmap_supportedformats,
de022e4f 193 wxDC::Blit, wxIcon, wxCursor, wxMemoryDC, wxImage, wxPixelData
23324ae1
FM
194*/
195class wxBitmap : public wxGDIObject
196{
197public:
23324ae1 198 /**
698d17c3
FM
199 Default constructor.
200
201 Constructs a bitmap object with no data; an assignment or another member
202 function such as Create() or LoadFile() must be called subsequently.
203 */
204 wxBitmap();
205
206 /**
207 Copy constructor, uses @ref overview_refcount "reference counting".
208 To make a real copy, you can use:
209
210 @code
211 wxBitmap newBitmap = oldBitmap.GetSubBitmap(
212 wxRect(0, 0, oldBitmap.GetWidth(), oldBitmap.GetHeight()));
213 @endcode
214 */
215 wxBitmap(const wxBitmap& bitmap);
216
8024723d
FM
217
218 /*
698d17c3
FM
219 Creates a bitmap from the given @a data which is interpreted in
220 platform-dependent manner.
221
222 @param data
223 Specifies the bitmap data in a platform-dependent format.
224 @param type
225 May be one of the ::wxBitmapType values and indicates which type of
226 bitmap does @a data contains. See the note in the class
227 detailed description.
228 @param width
229 Specifies the width of the bitmap.
230 @param height
231 Specifies the height of the bitmap.
232 @param depth
233 Specifies the depth of the bitmap.
234 If this is omitted, the display depth of the screen is used.
8024723d 235 wxBitmap(const void* data, int type, int width, int height, int depth = -1);
698d17c3 236
698d17c3 237
1413ac04 238 NOTE: this ctor is not implemented by all ports, is somewhat useless
8024723d
FM
239 without further description of the "data" supported formats and
240 uses 'int type' instead of wxBitmapType, so don't document it.
698d17c3 241 */
698d17c3
FM
242
243 /**
244 Creates a bitmap from the given array @a bits.
245 You should only use this function for monochrome bitmaps (depth 1) in
246 portable programs: in this case the bits parameter should contain an XBM image.
247
248 For other bit depths, the behaviour is platform dependent: under Windows,
249 the data is passed without any changes to the underlying CreateBitmap() API.
8024723d
FM
250 Under other platforms, only monochrome bitmaps may be created using this
251 constructor and wxImage should be used for creating colour bitmaps from
252 static data.
698d17c3 253
7c913512 254 @param bits
4cc4bfaf 255 Specifies an array of pixel values.
7c913512 256 @param width
4cc4bfaf 257 Specifies the width of the bitmap.
7c913512 258 @param height
4cc4bfaf 259 Specifies the height of the bitmap.
7c913512 260 @param depth
698d17c3 261 Specifies the depth of the bitmap.
8024723d 262 If this is omitted, then a value of 1 (monochrome bitmap) is used.
1058f652
MB
263
264 @beginWxPerlOnly
265 In wxPerl use Wx::Bitmap->newFromBits(bits, width, height, depth).
266 @endWxPerlOnly
698d17c3
FM
267 */
268 wxBitmap(const char bits[], int width, int height, int depth = 1);
269
270 /**
8024723d
FM
271 Creates a new bitmap. A depth of ::wxBITMAP_SCREEN_DEPTH indicates the
272 depth of the current screen or visual.
1413ac04 273
8024723d 274 Some platforms only support 1 for monochrome and ::wxBITMAP_SCREEN_DEPTH for
698d17c3
FM
275 the current colour setting.
276
277 A depth of 32 including an alpha channel is supported under MSW, Mac and GTK+.
278 */
8024723d 279 wxBitmap(int width, int height, int depth = wxBITMAP_SCREEN_DEPTH);
732d8c74
FM
280
281 /**
282 @overload
283 */
284 wxBitmap(const wxSize& sz, int depth = wxBITMAP_SCREEN_DEPTH);
698d17c3
FM
285
286 /**
287 Creates a bitmap from XPM data.
1058f652
MB
288
289 @beginWxPerlOnly
290 In wxPerl use Wx::Bitmap->newFromXPM(data).
291 @endWxPerlOnly
698d17c3
FM
292 */
293 wxBitmap(const char* const* bits);
294
295 /**
296 Loads a bitmap from a file or resource.
297
7c913512 298 @param name
698d17c3
FM
299 This can refer to a resource name or a filename under MS Windows and X.
300 Its meaning is determined by the @a type parameter.
7c913512 301 @param type
698d17c3
FM
302 May be one of the ::wxBitmapType values and indicates which type of
303 bitmap should be loaded. See the note in the class detailed description.
cbea3ec6
FM
304 Note that the wxBITMAP_DEFAULT_TYPE constant has different value under
305 different wxWidgets ports. See the bitmap.h header for the value it takes
306 for a specific port.
698d17c3 307
4cc4bfaf 308 @see LoadFile()
23324ae1 309 */
cbea3ec6 310 wxBitmap(const wxString& name, wxBitmapType type = wxBITMAP_DEFAULT_TYPE);
698d17c3
FM
311
312 /**
8024723d
FM
313 Creates this bitmap object from the given image.
314 This has to be done to actually display an image as you cannot draw an
315 image directly on a window.
698d17c3
FM
316
317 The resulting bitmap will use the provided colour depth (or that of the
8024723d
FM
318 current system if depth is ::wxBITMAP_SCREEN_DEPTH) which entails that a
319 colour reduction may take place.
698d17c3
FM
320
321 When in 8-bit mode (PseudoColour mode), the GTK port will use a color cube
322 created on program start-up to look up colors. This ensures a very fast conversion,
323 but the image quality won't be perfect (and could be better for photo images using
324 more sophisticated dithering algorithms).
325
326 On Windows, if there is a palette present (set with SetPalette), it will be
327 used when creating the wxBitmap (most useful in 8-bit display mode).
328 On other platforms, the palette is currently ignored.
329
330 @param img
331 Platform-independent wxImage object.
332 @param depth
333 Specifies the depth of the bitmap.
334 If this is omitted, the display depth of the screen is used.
335 */
8024723d 336 wxBitmap(const wxImage& img, int depth = wxBITMAP_SCREEN_DEPTH);
23324ae1
FM
337
338 /**
339 Destructor.
698d17c3
FM
340 See @ref overview_refcount_destruct for more info.
341
23324ae1
FM
342 If the application omits to delete the bitmap explicitly, the bitmap will be
343 destroyed automatically by wxWidgets when the application exits.
698d17c3
FM
344
345 @warning
23324ae1
FM
346 Do not delete a bitmap that is selected into a memory device context.
347 */
d2aa927a 348 virtual ~wxBitmap();
23324ae1
FM
349
350 /**
351 Adds a handler to the end of the static list of format handlers.
698d17c3 352
7c913512 353 @param handler
4cc4bfaf
FM
354 A new bitmap format handler object. There is usually only one instance
355 of a given handler class in an application session.
c83d207b
FM
356
357 Note that unlike wxImage::AddHandler, there's no documented list of
358 the wxBitmapHandlers available in wxWidgets.
359 This is because they are platform-specific and most important, they are
360 all automatically loaded at startup.
361
362 If you want to be sure that wxBitmap can load a certain type of image,
363 you'd better use wxImage::AddHandler.
698d17c3 364
4cc4bfaf 365 @see wxBitmapHandler
23324ae1
FM
366 */
367 static void AddHandler(wxBitmapHandler* handler);
368
369 /**
370 Deletes all bitmap handlers.
23324ae1
FM
371 This function is called by wxWidgets on exit.
372 */
373 static void CleanUpHandlers();
374
375 /**
376 Creates an image from a platform-dependent bitmap. This preserves
377 mask information so that bitmaps and images can be converted back
378 and forth without loss in that respect.
379 */
1413ac04 380 virtual wxImage ConvertToImage() const;
23324ae1
FM
381
382 /**
383 Creates the bitmap from an icon.
384 */
1413ac04 385 virtual bool CopyFromIcon(const wxIcon& icon);
23324ae1 386
698d17c3
FM
387 /**
388 Creates a fresh bitmap.
389 If the final argument is omitted, the display depth of the screen is used.
732d8c74
FM
390
391 @return @true if the creation was successful.
698d17c3 392 */
1413ac04 393 virtual bool Create(int width, int height, int depth = wxBITMAP_SCREEN_DEPTH);
732d8c74
FM
394
395 /**
396 @overload
397 */
398 virtual bool Create(const wxSize& sz, int depth = wxBITMAP_SCREEN_DEPTH);
698d17c3 399
8024723d 400 /*
23324ae1 401 Creates a bitmap from the given data, which can be of arbitrary type.
698d17c3
FM
402
403 @param data
404 Data whose type depends on the value of type.
405 @param type
406 A bitmap type identifier; see ::wxBitmapType for the list of values.
407 See the note in the class detailed description for more info.
7c913512 408 @param width
4cc4bfaf 409 The width of the bitmap in pixels.
7c913512 410 @param height
4cc4bfaf 411 The height of the bitmap in pixels.
7c913512 412 @param depth
4cc4bfaf 413 The depth of the bitmap in pixels. If this is -1, the screen depth is used.
698d17c3 414
d29a9a8a 415 @return @true if the call succeeded, @false otherwise.
698d17c3
FM
416
417 This overload depends on the @a type of data.
698d17c3 418
7c913512 419 virtual bool Create(const void* data, int type, int width,
698d17c3 420 int height, int depth = -1);
23324ae1 421
8024723d
FM
422 NOTE: leave this undoc for the same reason of the relative ctor.
423 */
424
23324ae1 425 /**
698d17c3
FM
426 Finds the handler with the given @a name.
427
d29a9a8a 428 @return A pointer to the handler if found, @NULL otherwise.
698d17c3
FM
429 */
430 static wxBitmapHandler* FindHandler(const wxString& name);
431
432 /**
433 Finds the handler associated with the given @a extension and @a type.
434
7c913512 435 @param extension
698d17c3 436 The file extension, such as "bmp" (without the dot).
7c913512 437 @param bitmapType
698d17c3
FM
438 The bitmap type managed by the handler, see ::wxBitmapType.
439
d29a9a8a 440 @return A pointer to the handler if found, @NULL otherwise.
23324ae1 441 */
7c913512
FM
442 static wxBitmapHandler* FindHandler(const wxString& extension,
443 wxBitmapType bitmapType);
698d17c3
FM
444
445 /**
446 Finds the handler associated with the given bitmap type.
447
448 @param bitmapType
449 The bitmap type managed by the handler, see ::wxBitmapType.
450
d29a9a8a 451 @return A pointer to the handler if found, @NULL otherwise.
698d17c3
FM
452
453 @see wxBitmapHandler
454 */
455
7c913512 456 static wxBitmapHandler* FindHandler(wxBitmapType bitmapType);
23324ae1
FM
457
458 /**
8024723d
FM
459 Gets the colour depth of the bitmap.
460 A value of 1 indicates a monochrome bitmap.
23324ae1 461 */
1413ac04 462 virtual int GetDepth() const;
23324ae1
FM
463
464 /**
465 Returns the static list of bitmap format handlers.
698d17c3 466
4cc4bfaf 467 @see wxBitmapHandler
23324ae1 468 */
382f12e4 469 static wxList& GetHandlers();
23324ae1
FM
470
471 /**
472 Gets the height of the bitmap in pixels.
c74b07ac
FM
473
474 @see GetWidth(), GetSize()
23324ae1 475 */
1413ac04 476 virtual int GetHeight() const;
23324ae1
FM
477
478 /**
479 Gets the associated mask (if any) which may have been loaded from a file
480 or set for the bitmap.
698d17c3 481
4cc4bfaf 482 @see SetMask(), wxMask
23324ae1 483 */
1413ac04 484 virtual wxMask* GetMask() const;
23324ae1
FM
485
486 /**
487 Gets the associated palette (if any) which may have been loaded from a file
488 or set for the bitmap.
698d17c3 489
4cc4bfaf 490 @see wxPalette
23324ae1 491 */
1413ac04 492 virtual wxPalette* GetPalette() const;
23324ae1
FM
493
494 /**
495 Returns a sub bitmap of the current one as long as the rect belongs entirely to
496 the bitmap. This function preserves bit depth and mask information.
497 */
1413ac04 498 virtual wxBitmap GetSubBitmap(const wxRect& rect) const;
23324ae1 499
c74b07ac
FM
500 /**
501 Returns the size of the bitmap in pixels.
502
503 @since 2.9.0
504
505 @see GetHeight(), GetWidth()
506 */
507 wxSize GetSize() const;
508
198c264d
JS
509 /**
510 Returns disabled (dimmed) version of the bitmap.
511 @since 2.9.0
512 */
513 wxBitmap ConvertToDisabled(unsigned char brightness = 255) const;
514
23324ae1
FM
515 /**
516 Gets the width of the bitmap in pixels.
698d17c3 517
c74b07ac 518 @see GetHeight(), GetSize()
23324ae1 519 */
1413ac04 520 virtual int GetWidth() const;
23324ae1
FM
521
522 /**
523 Adds the standard bitmap format handlers, which, depending on wxWidgets
698d17c3
FM
524 configuration, can be handlers for Windows bitmap, Windows bitmap resource,
525 and XPM.
526
23324ae1 527 This function is called by wxWidgets on startup.
698d17c3 528
4cc4bfaf 529 @see wxBitmapHandler
23324ae1
FM
530 */
531 static void InitStandardHandlers();
532
533 /**
534 Adds a handler at the start of the static list of format handlers.
698d17c3 535
7c913512 536 @param handler
4cc4bfaf
FM
537 A new bitmap format handler object. There is usually only one instance
538 of a given handler class in an application session.
698d17c3 539
4cc4bfaf 540 @see wxBitmapHandler
23324ae1
FM
541 */
542 static void InsertHandler(wxBitmapHandler* handler);
543
544 /**
545 Returns @true if bitmap data is present.
546 */
0004982c 547 virtual bool IsOk() const;
23324ae1
FM
548
549 /**
550 Loads a bitmap from a file or resource.
698d17c3 551
7c913512 552 @param name
4cc4bfaf 553 Either a filename or a Windows resource name.
698d17c3 554 The meaning of name is determined by the @a type parameter.
7c913512 555 @param type
698d17c3
FM
556 One of the ::wxBitmapType values; see the note in the class
557 detailed description.
cbea3ec6
FM
558 Note that the wxBITMAP_DEFAULT_TYPE constant has different value under
559 different wxWidgets ports. See the bitmap.h header for the value it takes
560 for a specific port.
698d17c3 561
d29a9a8a 562 @return @true if the operation succeeded, @false otherwise.
698d17c3 563
23324ae1 564 @remarks A palette may be associated with the bitmap if one exists
4cc4bfaf
FM
565 (especially for colour Windows bitmaps), and if the
566 code supports it. You can check if one has been created
698d17c3
FM
567 by using the GetPalette() member.
568
4cc4bfaf 569 @see SaveFile()
23324ae1 570 */
cbea3ec6 571 virtual bool LoadFile(const wxString& name, wxBitmapType type = wxBITMAP_DEFAULT_TYPE);
23324ae1
FM
572
573 /**
698d17c3
FM
574 Finds the handler with the given name, and removes it.
575 The handler is not deleted.
576
7c913512 577 @param name
4cc4bfaf 578 The handler name.
698d17c3 579
d29a9a8a 580 @return @true if the handler was found and removed, @false otherwise.
698d17c3 581
4cc4bfaf 582 @see wxBitmapHandler
23324ae1
FM
583 */
584 static bool RemoveHandler(const wxString& name);
585
586 /**
587 Saves a bitmap in the named file.
698d17c3 588
7c913512 589 @param name
4cc4bfaf 590 A filename. The meaning of name is determined by the type parameter.
7c913512 591 @param type
698d17c3
FM
592 One of the ::wxBitmapType values; see the note in the class
593 detailed description.
7c913512 594 @param palette
4cc4bfaf 595 An optional palette used for saving the bitmap.
698d17c3 596
d29a9a8a 597 @return @true if the operation succeeded, @false otherwise.
698d17c3 598
23324ae1 599 @remarks Depending on how wxWidgets has been configured, not all formats
4cc4bfaf 600 may be available.
698d17c3 601
4cc4bfaf 602 @see LoadFile()
23324ae1 603 */
1413ac04
FM
604 virtual bool SaveFile(const wxString& name, wxBitmapType type,
605 const wxPalette* palette = NULL) const;
23324ae1
FM
606
607 /**
608 Sets the depth member (does not affect the bitmap data).
698d17c3
FM
609
610 @todo since these functions do not affect the bitmap data,
611 why they exist??
612
7c913512 613 @param depth
4cc4bfaf 614 Bitmap depth.
23324ae1 615 */
1413ac04 616 virtual void SetDepth(int depth);
23324ae1
FM
617
618 /**
619 Sets the height member (does not affect the bitmap data).
698d17c3 620
7c913512 621 @param height
4cc4bfaf 622 Bitmap height in pixels.
23324ae1 623 */
1413ac04 624 virtual void SetHeight(int height);
23324ae1
FM
625
626 /**
627 Sets the mask for this bitmap.
698d17c3 628
23324ae1 629 @remarks The bitmap object owns the mask once this has been called.
698d17c3 630
4cc4bfaf 631 @see GetMask(), wxMask
23324ae1 632 */
1413ac04 633 virtual void SetMask(wxMask* mask);
23324ae1
FM
634
635 /**
636 Sets the associated palette. (Not implemented under GTK+).
698d17c3 637
7c913512 638 @param palette
4cc4bfaf 639 The palette to set.
698d17c3 640
4cc4bfaf 641 @see wxPalette
23324ae1 642 */
1413ac04 643 virtual void SetPalette(const wxPalette& palette);
23324ae1
FM
644
645 /**
646 Sets the width member (does not affect the bitmap data).
698d17c3 647
7c913512 648 @param width
4cc4bfaf 649 Bitmap width in pixels.
23324ae1 650 */
1413ac04 651 virtual void SetWidth(int width);
23324ae1
FM
652};
653
e54c96f1 654/**
698d17c3 655 An empty wxBitmap object.
e54c96f1
FM
656*/
657wxBitmap wxNullBitmap;
658
659
660
661
23324ae1
FM
662/**
663 @class wxMask
7c913512 664
23324ae1 665 This class encapsulates a monochrome mask bitmap, where the masked area is
698d17c3
FM
666 black and the unmasked area is white.
667
668 When associated with a bitmap and drawn in a device context, the unmasked
669 area of the bitmap will be drawn, and the masked area will not be drawn.
7c913512 670
23324ae1
FM
671 @library{wxcore}
672 @category{gdi}
7c913512 673
e54c96f1 674 @see wxBitmap, wxDC::Blit, wxMemoryDC
23324ae1
FM
675*/
676class wxMask : public wxObject
677{
678public:
698d17c3
FM
679
680 /**
681 Default constructor.
682 */
683 wxMask();
684
23324ae1
FM
685 /**
686 Constructs a mask from a bitmap and a palette index that indicates the
698d17c3
FM
687 background.
688 Not yet implemented for GTK.
689
7c913512 690 @param bitmap
4cc4bfaf 691 A valid bitmap.
7c913512 692 @param index
4cc4bfaf 693 Index into a palette, specifying the transparency colour.
23324ae1 694 */
7c913512 695 wxMask(const wxBitmap& bitmap, int index);
698d17c3
FM
696
697 /**
698 Constructs a mask from a monochrome bitmap.
699
700 @beginWxPythonOnly
701 This is the default constructor for wxMask in wxPython.
702 @endWxPythonOnly
703 */
704 wxMask(const wxBitmap& bitmap);
705
706 /**
707 Constructs a mask from a bitmap and a colour that indicates the background.
708
709 @beginWxPythonOnly
710 wxPython has an alternate wxMask constructor matching this form called wxMaskColour.
711 @endWxPythonOnly
712 */
713 wxMask(const wxBitmap& bitmap, const wxColour& colour);
23324ae1
FM
714
715 /**
716 Destroys the wxMask object and the underlying bitmap data.
717 */
d2aa927a 718 virtual ~wxMask();
23324ae1 719
23324ae1
FM
720 /**
721 Constructs a mask from a bitmap and a palette index that indicates the
698d17c3
FM
722 background.
723 Not yet implemented for GTK.
724
7c913512 725 @param bitmap
4cc4bfaf 726 A valid bitmap.
7c913512 727 @param index
4cc4bfaf 728 Index into a palette, specifying the transparency colour.
23324ae1 729 */
698d17c3
FM
730 bool Create(const wxBitmap& bitmap, int index);
731
732 /**
733 Constructs a mask from a monochrome bitmap.
734 */
23324ae1 735 bool Create(const wxBitmap& bitmap);
698d17c3
FM
736
737 /**
738 Constructs a mask from a bitmap and a colour that indicates the background.
739 */
7c913512 740 bool Create(const wxBitmap& bitmap, const wxColour& colour);
23324ae1 741};
e54c96f1 742