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