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