interface/wx/bitmap.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        bitmap.h
   3 // Purpose:     interface of wxBitmap* classes
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10 /**
  11     In wxBitmap and wxBitmapHandler context this value means: "use the screen depth".
  12 */
  13 #define wxBITMAP_SCREEN_DEPTH       (-1)
  14
  15 /**
  16     @class wxBitmapHandler
  17
  18     This is the base class for implementing bitmap file loading/saving, and
  19     bitmap creation from data.
  20     It is used within wxBitmap and is not normally seen by the application.
  21
  22     If you wish to extend the capabilities of wxBitmap, derive a class from
  23     wxBitmapHandler and add the handler using wxBitmap::AddHandler() in your
  24     application initialization.
  25
  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
  31     @library{wxcore}
  32     @category{gdi}
  33
  34     @see @ref overview_bitmap, wxBitmap, wxIcon, wxCursor
  35 */
  36 class wxBitmapHandler : public wxObject
  37 {
  38 public:
  39     /**
  40         Default constructor.
  41
  42         In your own default constructor, initialise the members m_name,
  43         m_extension and m_type.
  44     */
  45     wxBitmapHandler();
  46
  47     /**
  48         Destroys the wxBitmapHandler object.
  49     */
  50     virtual ~wxBitmapHandler();
  51
  52     /**
  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
  56         @param bitmap
  57             The wxBitmap object.
  58         @param width
  59             The width of the bitmap in pixels.
  60         @param height
  61             The height of the bitmap in pixels.
  62         @param depth
  63             The depth of the bitmap in pixels.
  64             If this is ::wxBITMAP_SCREEN_DEPTH, the screen depth is used.
  65         @param data
  66             Data whose type depends on the value of type.
  67         @param type
  68             A bitmap type identifier - see ::wxBitmapType for a list
  69             of possible values.
  70
  71         @return @true if the call succeeded, @false otherwise (the default).
  72     */
  73     virtual bool Create(wxBitmap* bitmap, const void* data, wxBitmapType type,
  74                         int width, int height, int depth = 1);
  75
  76     /**
  77         Gets the file extension associated with this handler.
  78     */
  79     const wxString& GetExtension() const;
  80
  81     /**
  82         Gets the name of this handler.
  83     */
  84     const wxString& GetName() const;
  85
  86     /**
  87         Gets the bitmap type associated with this handler.
  88     */
  89     wxBitmapType GetType() const;
  90
  91     /**
  92         Loads a bitmap from a file or resource, putting the resulting data into
  93         @a bitmap.
  94
  95         @param bitmap
  96             The bitmap object which is to be affected by this operation.
  97         @param name
  98             Either a filename or a Windows resource name.
  99             The meaning of name is determined by the type parameter.
 100         @param type
 101             See ::wxBitmapType for values this can take.
 102         @param desiredWidth
 103             The desired width for the loaded bitmap.
 104         @param desiredHeight
 105             The desired height for the loaded bitmap.
 106
 107         @return @true if the operation succeeded, @false otherwise.
 108
 109         @see wxBitmap::LoadFile, wxBitmap::SaveFile, SaveFile()
 110     */
 111     virtual bool LoadFile(wxBitmap* bitmap, const wxString& name, wxBitmapType type,
 112                           int desiredWidth, int desiredHeight);
 113
 114     /**
 115         Saves a bitmap in the named file.
 116
 117         @param bitmap
 118             The bitmap object which is to be affected by this operation.
 119         @param name
 120             A filename. The meaning of name is determined by the type parameter.
 121         @param type
 122             See ::wxBitmapType for values this can take.
 123         @param palette
 124             An optional palette used for saving the bitmap.
 125
 126         @return @true if the operation succeeded, @false otherwise.
 127
 128         @see wxBitmap::LoadFile, wxBitmap::SaveFile, LoadFile()
 129     */
 130     virtual bool SaveFile(const wxBitmap* bitmap, const wxString& name, wxBitmapType type,
 131                           const wxPalette* palette = NULL) const;
 132
 133     /**
 134         Sets the handler extension.
 135
 136         @param extension
 137             Handler extension.
 138     */
 139     void SetExtension(const wxString& extension);
 140
 141     /**
 142         Sets the handler name.
 143
 144         @param name
 145             Handler name.
 146     */
 147     void SetName(const wxString& name);
 148
 149     /**
 150         Sets the handler type.
 151
 152         @param type
 153             Handler type.
 154     */
 155     void SetType(wxBitmapType type);
 156 };
 157
 158
 159 /**
 160     @class wxBitmap
 161
 162     This class encapsulates the concept of a platform-dependent bitmap,
 163     either monochrome or colour or colour with alpha channel support.
 164
 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).
 169
 170     Note that many wxBitmap functions take a @e type parameter, which is a
 171     value of the ::wxBitmapType enumeration.
 172     The validity of those values depends however on the platform where your program
 173     is running and from the wxWidgets configuration.
 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.
 185
 186     @library{wxcore}
 187     @category{gdi}
 188
 189     @stdobjects
 190     ::wxNullBitmap
 191
 192     @see @ref overview_bitmap, @ref overview_bitmap_supportedformats,
 193          wxDC::Blit, wxIcon, wxCursor, wxMemoryDC, wxImage, wxPixelData
 194 */
 195 class wxBitmap : public wxGDIObject
 196 {
 197 public:
 198     /**
 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
 217
 218     /*
 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.
 235     wxBitmap(const void* data, int type, int width, int height, int depth = -1);
 236
 237
 238         NOTE: this ctor is not implemented by all ports, is somewhat useless
 239               without further description of the "data" supported formats and
 240               uses 'int type' instead of wxBitmapType, so don't document it.
 241     */
 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.
 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.
 253
 254         @param bits
 255             Specifies an array of pixel values.
 256         @param width
 257             Specifies the width of the bitmap.
 258         @param height
 259             Specifies the height of the bitmap.
 260         @param depth
 261             Specifies the depth of the bitmap.
 262             If this is omitted, then a value of 1 (monochrome bitmap) is used.
 263
 264         @beginWxPerlOnly
 265         In wxPerl use Wx::Bitmap->newFromBits(bits, width, height, depth).
 266         @endWxPerlOnly
 267     */
 268     wxBitmap(const char bits[], int width, int height, int depth = 1);
 269
 270     /**
 271         Creates a new bitmap. A depth of ::wxBITMAP_SCREEN_DEPTH indicates the
 272         depth of the current screen or visual.
 273
 274         Some platforms only support 1 for monochrome and ::wxBITMAP_SCREEN_DEPTH for
 275         the current colour setting.
 276
 277         A depth of 32 including an alpha channel is supported under MSW, Mac and GTK+.
 278     */
 279     wxBitmap(int width, int height, int depth = wxBITMAP_SCREEN_DEPTH);
 280
 281     /**
 282         @overload
 283     */
 284     wxBitmap(const wxSize& sz, int depth = wxBITMAP_SCREEN_DEPTH);
 285
 286     /**
 287         Creates a bitmap from XPM data.
 288
 289         @beginWxPerlOnly
 290         In wxPerl use Wx::Bitmap->newFromXPM(data).
 291         @endWxPerlOnly
 292     */
 293     wxBitmap(const char* const* bits);
 294
 295     /**
 296         Loads a bitmap from a file or resource.
 297
 298         @param name
 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.
 301         @param type
 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.
 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.
 307
 308         @see LoadFile()
 309     */
 310     wxBitmap(const wxString& name, wxBitmapType type = wxBITMAP_DEFAULT_TYPE);
 311
 312     /**
 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.
 316
 317         The resulting bitmap will use the provided colour depth (or that of the
 318         current system if depth is ::wxBITMAP_SCREEN_DEPTH) which entails that a
 319         colour reduction may take place.
 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     */
 336     wxBitmap(const wxImage& img, int depth = wxBITMAP_SCREEN_DEPTH);
 337
 338     /**
 339         Destructor.
 340         See @ref overview_refcount_destruct for more info.
 341
 342         If the application omits to delete the bitmap explicitly, the bitmap will be
 343         destroyed automatically by wxWidgets when the application exits.
 344
 345         @warning
 346         Do not delete a bitmap that is selected into a memory device context.
 347     */
 348     virtual ~wxBitmap();
 349
 350     /**
 351         Adds a handler to the end of the static list of format handlers.
 352
 353         @param handler
 354             A new bitmap format handler object. There is usually only one instance
 355             of a given handler class in an application session.
 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.
 364
 365         @see wxBitmapHandler
 366     */
 367     static void AddHandler(wxBitmapHandler* handler);
 368
 369     /**
 370         Deletes all bitmap handlers.
 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     */
 380     virtual wxImage ConvertToImage() const;
 381
 382     /**
 383         Creates the bitmap from an icon.
 384     */
 385     virtual bool CopyFromIcon(const wxIcon& icon);
 386
 387     /**
 388         Creates a fresh bitmap.
 389         If the final argument is omitted, the display depth of the screen is used.
 390
 391         @return @true if the creation was successful.
 392     */
 393     virtual bool Create(int width, int height, int depth = wxBITMAP_SCREEN_DEPTH);
 394
 395     /**
 396         @overload
 397     */
 398     virtual bool Create(const wxSize& sz, int depth = wxBITMAP_SCREEN_DEPTH);
 399
 400     /*
 401         Creates a bitmap from the given data, which can be of arbitrary type.
 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.
 408         @param width
 409             The width of the bitmap in pixels.
 410         @param height
 411             The height of the bitmap in pixels.
 412         @param depth
 413             The depth of the bitmap in pixels. If this is -1, the screen depth is used.
 414
 415         @return @true if the call succeeded, @false otherwise.
 416
 417         This overload depends on the @a type of data.
 418
 419     virtual bool Create(const void* data, int type, int width,
 420                         int height, int depth = -1);
 421
 422         NOTE: leave this undoc for the same reason of the relative ctor.
 423     */
 424
 425     /**
 426         Finds the handler with the given @a name.
 427
 428         @return A pointer to the handler if found, @NULL otherwise.
 429     */
 430     static wxBitmapHandler* FindHandler(const wxString& name);
 431
 432     /**
 433         Finds the handler associated with the given @a extension and @a type.
 434
 435         @param extension
 436             The file extension, such as "bmp" (without the dot).
 437         @param bitmapType
 438             The bitmap type managed by the handler, see ::wxBitmapType.
 439
 440         @return A pointer to the handler if found, @NULL otherwise.
 441     */
 442     static wxBitmapHandler* FindHandler(const wxString& extension,
 443                                         wxBitmapType bitmapType);
 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
 451         @return A pointer to the handler if found, @NULL otherwise.
 452
 453         @see wxBitmapHandler
 454     */
 455
 456     static wxBitmapHandler* FindHandler(wxBitmapType bitmapType);
 457
 458     /**
 459         Gets the colour depth of the bitmap.
 460         A value of 1 indicates a monochrome bitmap.
 461     */
 462     virtual int GetDepth() const;
 463
 464     /**
 465         Returns the static list of bitmap format handlers.
 466
 467         @see wxBitmapHandler
 468     */
 469     static wxList& GetHandlers();
 470
 471     /**
 472         Gets the height of the bitmap in pixels.
 473
 474         @see GetWidth(), GetSize()
 475     */
 476     virtual int GetHeight() const;
 477
 478     /**
 479         Gets the associated mask (if any) which may have been loaded from a file
 480         or set for the bitmap.
 481
 482         @see SetMask(), wxMask
 483     */
 484     virtual wxMask* GetMask() const;
 485
 486     /**
 487         Gets the associated palette (if any) which may have been loaded from a file
 488         or set for the bitmap.
 489
 490         @see wxPalette
 491     */
 492     virtual wxPalette* GetPalette() const;
 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     */
 498     virtual wxBitmap GetSubBitmap(const wxRect& rect) const;
 499
 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
 509     /**
 510         Returns disabled (dimmed) version of the bitmap.
 511         @since 2.9.0
 512     */
 513     wxBitmap ConvertToDisabled(unsigned char brightness = 255) const;
 514
 515     /**
 516         Gets the width of the bitmap in pixels.
 517
 518         @see GetHeight(), GetSize()
 519     */
 520     virtual int GetWidth() const;
 521
 522     /**
 523         Adds the standard bitmap format handlers, which, depending on wxWidgets
 524         configuration, can be handlers for Windows bitmap, Windows bitmap resource,
 525         and XPM.
 526
 527         This function is called by wxWidgets on startup.
 528
 529         @see wxBitmapHandler
 530     */
 531     static void InitStandardHandlers();
 532
 533     /**
 534         Adds a handler at the start of the static list of format handlers.
 535
 536         @param handler
 537             A new bitmap format handler object. There is usually only one instance
 538             of a given handler class in an application session.
 539
 540         @see wxBitmapHandler
 541     */
 542     static void InsertHandler(wxBitmapHandler* handler);
 543
 544     /**
 545         Returns @true if bitmap data is present.
 546     */
 547     virtual bool IsOk() const;
 548
 549     /**
 550         Loads a bitmap from a file or resource.
 551
 552         @param name
 553             Either a filename or a Windows resource name.
 554             The meaning of name is determined by the @a type parameter.
 555         @param type
 556             One of the ::wxBitmapType values; see the note in the class
 557             detailed description.
 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.
 561
 562         @return @true if the operation succeeded, @false otherwise.
 563
 564         @remarks A palette may be associated with the bitmap if one exists
 565                  (especially for colour Windows bitmaps), and if the
 566                  code supports it. You can check if one has been created
 567                  by using the GetPalette() member.
 568
 569         @see SaveFile()
 570     */
 571     virtual bool LoadFile(const wxString& name, wxBitmapType type = wxBITMAP_DEFAULT_TYPE);
 572
 573     /**
 574         Finds the handler with the given name, and removes it.
 575         The handler is not deleted.
 576
 577         @param name
 578             The handler name.
 579
 580         @return @true if the handler was found and removed, @false otherwise.
 581
 582         @see wxBitmapHandler
 583     */
 584     static bool RemoveHandler(const wxString& name);
 585
 586     /**
 587         Saves a bitmap in the named file.
 588
 589         @param name
 590             A filename. The meaning of name is determined by the type parameter.
 591         @param type
 592             One of the ::wxBitmapType values; see the note in the class
 593             detailed description.
 594         @param palette
 595             An optional palette used for saving the bitmap.
 596
 597         @return @true if the operation succeeded, @false otherwise.
 598
 599         @remarks Depending on how wxWidgets has been configured, not all formats
 600                  may be available.
 601
 602         @see LoadFile()
 603     */
 604     virtual bool SaveFile(const wxString& name, wxBitmapType type,
 605                           const wxPalette* palette = NULL) const;
 606
 607     /**
 608         Sets the depth member (does not affect the bitmap data).
 609
 610         @todo since these functions do not affect the bitmap data,
 611               why they exist??
 612
 613         @param depth
 614             Bitmap depth.
 615     */
 616     virtual void SetDepth(int depth);
 617
 618     /**
 619         Sets the height member (does not affect the bitmap data).
 620
 621         @param height
 622             Bitmap height in pixels.
 623     */
 624     virtual void SetHeight(int height);
 625
 626     /**
 627         Sets the mask for this bitmap.
 628
 629         @remarks The bitmap object owns the mask once this has been called.
 630
 631         @see GetMask(), wxMask
 632     */
 633     virtual void SetMask(wxMask* mask);
 634
 635     /**
 636         Sets the associated palette. (Not implemented under GTK+).
 637
 638         @param palette
 639             The palette to set.
 640
 641         @see wxPalette
 642     */
 643     virtual void SetPalette(const wxPalette& palette);
 644
 645     /**
 646         Sets the width member (does not affect the bitmap data).
 647
 648         @param width
 649             Bitmap width in pixels.
 650     */
 651     virtual void SetWidth(int width);
 652 };
 653
 654 /**
 655     An empty wxBitmap object.
 656 */
 657 wxBitmap wxNullBitmap;
 658
 659
 660
 661
 662 /**
 663     @class wxMask
 664
 665     This class encapsulates a monochrome mask bitmap, where the masked area is
 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.
 670
 671     @library{wxcore}
 672     @category{gdi}
 673
 674     @see wxBitmap, wxDC::Blit, wxMemoryDC
 675 */
 676 class wxMask : public wxObject
 677 {
 678 public:
 679
 680     /**
 681         Default constructor.
 682     */
 683     wxMask();
 684
 685     /**
 686         Constructs a mask from a bitmap and a palette index that indicates the
 687         background.
 688         Not yet implemented for GTK.
 689
 690         @param bitmap
 691             A valid bitmap.
 692         @param index
 693             Index into a palette, specifying the transparency colour.
 694     */
 695     wxMask(const wxBitmap& bitmap, int index);
 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);
 714
 715     /**
 716         Destroys the wxMask object and the underlying bitmap data.
 717     */
 718     virtual ~wxMask();
 719
 720     /**
 721         Constructs a mask from a bitmap and a palette index that indicates the
 722         background.
 723         Not yet implemented for GTK.
 724
 725         @param bitmap
 726             A valid bitmap.
 727         @param index
 728             Index into a palette, specifying the transparency colour.
 729     */
 730     bool Create(const wxBitmap& bitmap, int index);
 731
 732     /**
 733         Constructs a mask from a monochrome bitmap.
 734     */
 735     bool Create(const wxBitmap& bitmap);
 736
 737     /**
 738         Constructs a mask from a bitmap and a colour that indicates the background.
 739     */
 740     bool Create(const wxBitmap& bitmap, const wxColour& colour);
 741 };
 742