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 licence
   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
 512         This method is not available when <code>wxUSE_IMAGE == 0</code>.
 513
 514         @since 2.9.0
 515     */
 516     wxBitmap ConvertToDisabled(unsigned char brightness = 255) const;
 517
 518     /**
 519         Gets the width of the bitmap in pixels.
 520
 521         @see GetHeight(), GetSize()
 522     */
 523     virtual int GetWidth() const;
 524
 525     /**
 526         Adds the standard bitmap format handlers, which, depending on wxWidgets
 527         configuration, can be handlers for Windows bitmap, Windows bitmap resource,
 528         and XPM.
 529
 530         This function is called by wxWidgets on startup.
 531
 532         @see wxBitmapHandler
 533     */
 534     static void InitStandardHandlers();
 535
 536     /**
 537         Adds a handler at the start of the static list of format handlers.
 538
 539         @param handler
 540             A new bitmap format handler object. There is usually only one instance
 541             of a given handler class in an application session.
 542
 543         @see wxBitmapHandler
 544     */
 545     static void InsertHandler(wxBitmapHandler* handler);
 546
 547     /**
 548         Returns @true if bitmap data is present.
 549     */
 550     virtual bool IsOk() const;
 551
 552     /**
 553         Loads a bitmap from a file or resource.
 554
 555         @param name
 556             Either a filename or a Windows resource name.
 557             The meaning of name is determined by the @a type parameter.
 558         @param type
 559             One of the ::wxBitmapType values; see the note in the class
 560             detailed description.
 561             Note that the wxBITMAP_DEFAULT_TYPE constant has different value under
 562             different wxWidgets ports. See the bitmap.h header for the value it takes
 563             for a specific port.
 564
 565         @return @true if the operation succeeded, @false otherwise.
 566
 567         @remarks A palette may be associated with the bitmap if one exists
 568                  (especially for colour Windows bitmaps), and if the
 569                  code supports it. You can check if one has been created
 570                  by using the GetPalette() member.
 571
 572         @see SaveFile()
 573     */
 574     virtual bool LoadFile(const wxString& name, wxBitmapType type = wxBITMAP_DEFAULT_TYPE);
 575
 576     /**
 577         Finds the handler with the given name, and removes it.
 578         The handler is not deleted.
 579
 580         @param name
 581             The handler name.
 582
 583         @return @true if the handler was found and removed, @false otherwise.
 584
 585         @see wxBitmapHandler
 586     */
 587     static bool RemoveHandler(const wxString& name);
 588
 589     /**
 590         Saves a bitmap in the named file.
 591
 592         @param name
 593             A filename. The meaning of name is determined by the type parameter.
 594         @param type
 595             One of the ::wxBitmapType values; see the note in the class
 596             detailed description.
 597         @param palette
 598             An optional palette used for saving the bitmap.
 599
 600         @return @true if the operation succeeded, @false otherwise.
 601
 602         @remarks Depending on how wxWidgets has been configured, not all formats
 603                  may be available.
 604
 605         @see LoadFile()
 606     */
 607     virtual bool SaveFile(const wxString& name, wxBitmapType type,
 608                           const wxPalette* palette = NULL) const;
 609
 610     /**
 611         Sets the depth member (does not affect the bitmap data).
 612
 613         @todo since these functions do not affect the bitmap data,
 614               why they exist??
 615
 616         @param depth
 617             Bitmap depth.
 618     */
 619     virtual void SetDepth(int depth);
 620
 621     /**
 622         Sets the height member (does not affect the bitmap data).
 623
 624         @param height
 625             Bitmap height in pixels.
 626     */
 627     virtual void SetHeight(int height);
 628
 629     /**
 630         Sets the mask for this bitmap.
 631
 632         @remarks The bitmap object owns the mask once this has been called.
 633
 634         @see GetMask(), wxMask
 635     */
 636     virtual void SetMask(wxMask* mask);
 637
 638     /**
 639         Sets the associated palette. (Not implemented under GTK+).
 640
 641         @param palette
 642             The palette to set.
 643
 644         @see wxPalette
 645     */
 646     virtual void SetPalette(const wxPalette& palette);
 647
 648     /**
 649         Sets the width member (does not affect the bitmap data).
 650
 651         @param width
 652             Bitmap width in pixels.
 653     */
 654     virtual void SetWidth(int width);
 655 };
 656
 657 /**
 658     An empty wxBitmap object.
 659 */
 660 wxBitmap wxNullBitmap;
 661
 662
 663
 664
 665 /**
 666     @class wxMask
 667
 668     This class encapsulates a monochrome mask bitmap, where the masked area is
 669     black and the unmasked area is white.
 670
 671     When associated with a bitmap and drawn in a device context, the unmasked
 672     area of the bitmap will be drawn, and the masked area will not be drawn.
 673
 674     @library{wxcore}
 675     @category{gdi}
 676
 677     @see wxBitmap, wxDC::Blit, wxMemoryDC
 678 */
 679 class wxMask : public wxObject
 680 {
 681 public:
 682
 683     /**
 684         Default constructor.
 685     */
 686     wxMask();
 687
 688     /**
 689         Constructs a mask from a bitmap and a palette index that indicates the
 690         background.
 691         Not yet implemented for GTK.
 692
 693         @param bitmap
 694             A valid bitmap.
 695         @param index
 696             Index into a palette, specifying the transparency colour.
 697     */
 698     wxMask(const wxBitmap& bitmap, int index);
 699
 700     /**
 701         Constructs a mask from a monochrome bitmap.
 702
 703         @beginWxPythonOnly
 704         This is the default constructor for wxMask in wxPython.
 705         @endWxPythonOnly
 706     */
 707     wxMask(const wxBitmap& bitmap);
 708
 709     /**
 710         Constructs a mask from a bitmap and a colour that indicates the background.
 711
 712         @beginWxPythonOnly
 713         wxPython has an alternate wxMask constructor matching this form called wxMaskColour.
 714         @endWxPythonOnly
 715     */
 716     wxMask(const wxBitmap& bitmap, const wxColour& colour);
 717
 718     /**
 719         Destroys the wxMask object and the underlying bitmap data.
 720     */
 721     virtual ~wxMask();
 722
 723     /**
 724         Constructs a mask from a bitmap and a palette index that indicates the
 725         background.
 726         Not yet implemented for GTK.
 727
 728         @param bitmap
 729             A valid bitmap.
 730         @param index
 731             Index into a palette, specifying the transparency colour.
 732     */
 733     bool Create(const wxBitmap& bitmap, int index);
 734
 735     /**
 736         Constructs a mask from a monochrome bitmap.
 737     */
 738     bool Create(const wxBitmap& bitmap);
 739
 740     /**
 741         Constructs a mask from a bitmap and a colour that indicates the background.
 742     */
 743     bool Create(const wxBitmap& bitmap, const wxColour& colour);
 744 };
 745