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