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 additionally 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     More on the difference between wxImage and wxBitmap: wxImage is just a
 187     buffer of RGB bytes with an optional buffer for the alpha bytes. It is all
 188     generic, platform independent and image file format independent code. It
 189     includes generic code for scaling, resizing, clipping, and other manipulations
 190     of the image data. OTOH, wxBitmap is intended to be a wrapper of whatever is
 191     the native image format that is quickest/easiest to draw to a DC or to be the
 192     target of the drawing operations performed on a wxMemoryDC. By splitting the
 193     responsibilities between wxImage/wxBitmap like this then it's easier to use
 194     generic code shared by all platforms and image types for generic operations and
 195     platform specific code where performance or compatibility is needed.
 196
 197     @library{wxcore}
 198     @category{gdi}
 199
 200     @stdobjects
 201     ::wxNullBitmap
 202
 203     @see @ref overview_bitmap, @ref overview_bitmap_supportedformats,
 204          wxDC::Blit, wxIcon, wxCursor, wxMemoryDC, wxImage, wxPixelData
 205 */
 206 class wxBitmap : public wxGDIObject
 207 {
 208 public:
 209     /**
 210         Default constructor.
 211
 212         Constructs a bitmap object with no data; an assignment or another member
 213         function such as Create() or LoadFile() must be called subsequently.
 214     */
 215     wxBitmap();
 216
 217     /**
 218         Copy constructor, uses @ref overview_refcount "reference counting".
 219         To make a real copy, you can use:
 220
 221         @code
 222         wxBitmap newBitmap = oldBitmap.GetSubBitmap(
 223                              wxRect(0, 0, oldBitmap.GetWidth(), oldBitmap.GetHeight()));
 224         @endcode
 225     */
 226     wxBitmap(const wxBitmap& bitmap);
 227
 228
 229     /*
 230         Creates a bitmap from the given @a data which is interpreted in
 231         platform-dependent manner.
 232
 233         @param data
 234             Specifies the bitmap data in a platform-dependent format.
 235         @param type
 236             May be one of the ::wxBitmapType values and indicates which type of
 237             bitmap does @a data contains. See the note in the class
 238             detailed description.
 239         @param width
 240             Specifies the width of the bitmap.
 241         @param height
 242             Specifies the height of the bitmap.
 243         @param depth
 244             Specifies the depth of the bitmap.
 245             If this is omitted, the display depth of the screen is used.
 246     wxBitmap(const void* data, int type, int width, int height, int depth = -1);
 247
 248
 249         NOTE: this ctor is not implemented by all ports, is somewhat useless
 250               without further description of the "data" supported formats and
 251               uses 'int type' instead of wxBitmapType, so don't document it.
 252     */
 253
 254     /**
 255         Creates a bitmap from the given array @a bits.
 256         You should only use this function for monochrome bitmaps (depth 1) in
 257         portable programs: in this case the bits parameter should contain an XBM image.
 258
 259         For other bit depths, the behaviour is platform dependent: under Windows,
 260         the data is passed without any changes to the underlying CreateBitmap() API.
 261         Under other platforms, only monochrome bitmaps may be created using this
 262         constructor and wxImage should be used for creating colour bitmaps from
 263         static data.
 264
 265         @param bits
 266             Specifies an array of pixel values.
 267         @param width
 268             Specifies the width of the bitmap.
 269         @param height
 270             Specifies the height of the bitmap.
 271         @param depth
 272             Specifies the depth of the bitmap.
 273             If this is omitted, then a value of 1 (monochrome bitmap) is used.
 274
 275         @beginWxPerlOnly
 276         In wxPerl use Wx::Bitmap->newFromBits(bits, width, height, depth).
 277         @endWxPerlOnly
 278     */
 279     wxBitmap(const char bits[], int width, int height, int depth = 1);
 280
 281     /**
 282         Creates a new bitmap. A depth of ::wxBITMAP_SCREEN_DEPTH indicates the
 283         depth of the current screen or visual.
 284
 285         Some platforms only support 1 for monochrome and ::wxBITMAP_SCREEN_DEPTH for
 286         the current colour setting.
 287
 288         A depth of 32 including an alpha channel is supported under MSW, Mac and GTK+.
 289     */
 290     wxBitmap(int width, int height, int depth = wxBITMAP_SCREEN_DEPTH);
 291
 292     /**
 293         @overload
 294     */
 295     wxBitmap(const wxSize& sz, int depth = wxBITMAP_SCREEN_DEPTH);
 296
 297     /**
 298         Creates a bitmap from XPM data.
 299
 300         @beginWxPerlOnly
 301         In wxPerl use Wx::Bitmap->newFromXPM(data).
 302         @endWxPerlOnly
 303     */
 304     wxBitmap(const char* const* bits);
 305
 306     /**
 307         Loads a bitmap from a file or resource.
 308
 309         @param name
 310             This can refer to a resource name or a filename under MS Windows and X.
 311             Its meaning is determined by the @a type parameter.
 312         @param type
 313             May be one of the ::wxBitmapType values and indicates which type of
 314             bitmap should be loaded. See the note in the class detailed description.
 315             Note that the wxBITMAP_DEFAULT_TYPE constant has different value under
 316             different wxWidgets ports. See the bitmap.h header for the value it takes
 317             for a specific port.
 318
 319         @see LoadFile()
 320     */
 321     wxBitmap(const wxString& name, wxBitmapType type = wxBITMAP_DEFAULT_TYPE);
 322
 323     /**
 324         Creates this bitmap object from the given image.
 325         This has to be done to actually display an image as you cannot draw an
 326         image directly on a window.
 327
 328         The resulting bitmap will use the provided colour depth (or that of the
 329         current system if depth is ::wxBITMAP_SCREEN_DEPTH) which entails that a
 330         colour reduction may take place.
 331
 332         When in 8-bit mode (PseudoColour mode), the GTK port will use a color cube
 333         created on program start-up to look up colors. This ensures a very fast conversion,
 334         but the image quality won't be perfect (and could be better for photo images using
 335         more sophisticated dithering algorithms).
 336
 337         On Windows, if there is a palette present (set with SetPalette), it will be
 338         used when creating the wxBitmap (most useful in 8-bit display mode).
 339         On other platforms, the palette is currently ignored.
 340
 341         @param img
 342             Platform-independent wxImage object.
 343         @param depth
 344             Specifies the depth of the bitmap.
 345             If this is omitted, the display depth of the screen is used.
 346     */
 347     wxBitmap(const wxImage& img, int depth = wxBITMAP_SCREEN_DEPTH);
 348
 349     /**
 350         Destructor.
 351         See @ref overview_refcount_destruct for more info.
 352
 353         If the application omits to delete the bitmap explicitly, the bitmap will be
 354         destroyed automatically by wxWidgets when the application exits.
 355
 356         @warning
 357         Do not delete a bitmap that is selected into a memory device context.
 358     */
 359     virtual ~wxBitmap();
 360
 361     /**
 362         Adds a handler to the end of the static list of format handlers.
 363
 364         @param handler
 365             A new bitmap format handler object. There is usually only one instance
 366             of a given handler class in an application session.
 367
 368         Note that unlike wxImage::AddHandler, there's no documented list of
 369         the wxBitmapHandlers available in wxWidgets.
 370         This is because they are platform-specific and most important, they are
 371         all automatically loaded at startup.
 372
 373         If you want to be sure that wxBitmap can load a certain type of image,
 374         you'd better use wxImage::AddHandler.
 375
 376         @see wxBitmapHandler
 377     */
 378     static void AddHandler(wxBitmapHandler* handler);
 379
 380     /**
 381         Deletes all bitmap handlers.
 382         This function is called by wxWidgets on exit.
 383     */
 384     static void CleanUpHandlers();
 385
 386     /**
 387         Creates an image from a platform-dependent bitmap. This preserves
 388         mask information so that bitmaps and images can be converted back
 389         and forth without loss in that respect.
 390     */
 391     virtual wxImage ConvertToImage() const;
 392
 393     /**
 394         Creates the bitmap from an icon.
 395     */
 396     virtual bool CopyFromIcon(const wxIcon& icon);
 397
 398     /**
 399         Creates a fresh bitmap.
 400         If the final argument is omitted, the display depth of the screen is used.
 401
 402         @return @true if the creation was successful.
 403     */
 404     virtual bool Create(int width, int height, int depth = wxBITMAP_SCREEN_DEPTH);
 405
 406     /**
 407         @overload
 408     */
 409     virtual bool Create(const wxSize& sz, int depth = wxBITMAP_SCREEN_DEPTH);
 410
 411     /*
 412         Creates a bitmap from the given data, which can be of arbitrary type.
 413
 414         @param data
 415             Data whose type depends on the value of type.
 416         @param type
 417             A bitmap type identifier; see ::wxBitmapType for the list of values.
 418             See the note in the class detailed description for more info.
 419         @param width
 420             The width of the bitmap in pixels.
 421         @param height
 422             The height of the bitmap in pixels.
 423         @param depth
 424             The depth of the bitmap in pixels. If this is -1, the screen depth is used.
 425
 426         @return @true if the call succeeded, @false otherwise.
 427
 428         This overload depends on the @a type of data.
 429
 430     virtual bool Create(const void* data, int type, int width,
 431                         int height, int depth = -1);
 432
 433         NOTE: leave this undoc for the same reason of the relative ctor.
 434     */
 435
 436     /**
 437         Finds the handler with the given @a name.
 438
 439         @return A pointer to the handler if found, @NULL otherwise.
 440     */
 441     static wxBitmapHandler* FindHandler(const wxString& name);
 442
 443     /**
 444         Finds the handler associated with the given @a extension and @a type.
 445
 446         @param extension
 447             The file extension, such as "bmp" (without the dot).
 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     static wxBitmapHandler* FindHandler(const wxString& extension,
 454                                         wxBitmapType bitmapType);
 455
 456     /**
 457         Finds the handler associated with the given bitmap type.
 458
 459         @param bitmapType
 460             The bitmap type managed by the handler, see ::wxBitmapType.
 461
 462         @return A pointer to the handler if found, @NULL otherwise.
 463
 464         @see wxBitmapHandler
 465     */
 466
 467     static wxBitmapHandler* FindHandler(wxBitmapType bitmapType);
 468
 469     /**
 470         Gets the colour depth of the bitmap.
 471         A value of 1 indicates a monochrome bitmap.
 472     */
 473     virtual int GetDepth() const;
 474
 475     /**
 476         Returns the static list of bitmap format handlers.
 477
 478         @see wxBitmapHandler
 479     */
 480     static wxList& GetHandlers();
 481
 482     /**
 483         Gets the height of the bitmap in pixels.
 484
 485         @see GetWidth(), GetSize()
 486     */
 487     virtual int GetHeight() const;
 488
 489     /**
 490         Gets the associated mask (if any) which may have been loaded from a file
 491         or set for the bitmap.
 492
 493         @see SetMask(), wxMask
 494     */
 495     virtual wxMask* GetMask() const;
 496
 497     /**
 498         Gets the associated palette (if any) which may have been loaded from a file
 499         or set for the bitmap.
 500
 501         @see wxPalette
 502     */
 503     virtual wxPalette* GetPalette() const;
 504
 505     /**
 506         Returns a sub bitmap of the current one as long as the rect belongs entirely to
 507         the bitmap. This function preserves bit depth and mask information.
 508     */
 509     virtual wxBitmap GetSubBitmap(const wxRect& rect) const;
 510
 511     /**
 512         Returns the size of the bitmap in pixels.
 513
 514         @since 2.9.0
 515
 516         @see GetHeight(), GetWidth()
 517     */
 518     wxSize GetSize() const;
 519
 520     /**
 521         Returns disabled (dimmed) version of the bitmap.
 522
 523         This method is not available when <code>wxUSE_IMAGE == 0</code>.
 524
 525         @since 2.9.0
 526     */
 527     wxBitmap ConvertToDisabled(unsigned char brightness = 255) const;
 528
 529     /**
 530         Gets the width of the bitmap in pixels.
 531
 532         @see GetHeight(), GetSize()
 533     */
 534     virtual int GetWidth() const;
 535
 536     /**
 537         Adds the standard bitmap format handlers, which, depending on wxWidgets
 538         configuration, can be handlers for Windows bitmap, Windows bitmap resource,
 539         and XPM.
 540
 541         This function is called by wxWidgets on startup.
 542
 543         @see wxBitmapHandler
 544     */
 545     static void InitStandardHandlers();
 546
 547     /**
 548         Adds a handler at the start of the static list of format handlers.
 549
 550         @param handler
 551             A new bitmap format handler object. There is usually only one instance
 552             of a given handler class in an application session.
 553
 554         @see wxBitmapHandler
 555     */
 556     static void InsertHandler(wxBitmapHandler* handler);
 557
 558     /**
 559         Returns @true if bitmap data is present.
 560     */
 561     virtual bool IsOk() const;
 562
 563     /**
 564         Loads a bitmap from a file or resource.
 565
 566         @param name
 567             Either a filename or a Windows resource name.
 568             The meaning of name is determined by the @a type parameter.
 569         @param type
 570             One of the ::wxBitmapType values; see the note in the class
 571             detailed description.
 572             Note that the wxBITMAP_DEFAULT_TYPE constant has different value under
 573             different wxWidgets ports. See the bitmap.h header for the value it takes
 574             for a specific port.
 575
 576         @return @true if the operation succeeded, @false otherwise.
 577
 578         @remarks A palette may be associated with the bitmap if one exists
 579                  (especially for colour Windows bitmaps), and if the
 580                  code supports it. You can check if one has been created
 581                  by using the GetPalette() member.
 582
 583         @see SaveFile()
 584     */
 585     virtual bool LoadFile(const wxString& name, wxBitmapType type = wxBITMAP_DEFAULT_TYPE);
 586
 587     /**
 588         Finds the handler with the given name, and removes it.
 589         The handler is not deleted.
 590
 591         @param name
 592             The handler name.
 593
 594         @return @true if the handler was found and removed, @false otherwise.
 595
 596         @see wxBitmapHandler
 597     */
 598     static bool RemoveHandler(const wxString& name);
 599
 600     /**
 601         Saves a bitmap in the named file.
 602
 603         @param name
 604             A filename. The meaning of name is determined by the type parameter.
 605         @param type
 606             One of the ::wxBitmapType values; see the note in the class
 607             detailed description.
 608         @param palette
 609             An optional palette used for saving the bitmap.
 610
 611         @return @true if the operation succeeded, @false otherwise.
 612
 613         @remarks Depending on how wxWidgets has been configured, not all formats
 614                  may be available.
 615
 616         @see LoadFile()
 617     */
 618     virtual bool SaveFile(const wxString& name, wxBitmapType type,
 619                           const wxPalette* palette = NULL) const;
 620
 621     /**
 622         Sets the depth member (does not affect the bitmap data).
 623
 624         @todo since these functions do not affect the bitmap data,
 625               why they exist??
 626
 627         @param depth
 628             Bitmap depth.
 629     */
 630     virtual void SetDepth(int depth);
 631
 632     /**
 633         Sets the height member (does not affect the bitmap data).
 634
 635         @param height
 636             Bitmap height in pixels.
 637     */
 638     virtual void SetHeight(int height);
 639
 640     /**
 641         Sets the mask for this bitmap.
 642
 643         @remarks The bitmap object owns the mask once this has been called.
 644
 645         @see GetMask(), wxMask
 646     */
 647     virtual void SetMask(wxMask* mask);
 648
 649     /**
 650         Sets the associated palette. (Not implemented under GTK+).
 651
 652         @param palette
 653             The palette to set.
 654
 655         @see wxPalette
 656     */
 657     virtual void SetPalette(const wxPalette& palette);
 658
 659     /**
 660         Sets the width member (does not affect the bitmap data).
 661
 662         @param width
 663             Bitmap width in pixels.
 664     */
 665     virtual void SetWidth(int width);
 666 };
 667
 668 /**
 669     An empty wxBitmap object.
 670 */
 671 wxBitmap wxNullBitmap;
 672
 673
 674
 675
 676 /**
 677     @class wxMask
 678
 679     This class encapsulates a monochrome mask bitmap, where the masked area is
 680     black and the unmasked area is white.
 681
 682     When associated with a bitmap and drawn in a device context, the unmasked
 683     area of the bitmap will be drawn, and the masked area will not be drawn.
 684
 685     @library{wxcore}
 686     @category{gdi}
 687
 688     @see wxBitmap, wxDC::Blit, wxMemoryDC
 689 */
 690 class wxMask : public wxObject
 691 {
 692 public:
 693
 694     /**
 695         Default constructor.
 696     */
 697     wxMask();
 698
 699     /**
 700         Constructs a mask from a bitmap and a palette index that indicates the
 701         background.
 702         Not yet implemented for GTK.
 703
 704         @param bitmap
 705             A valid bitmap.
 706         @param index
 707             Index into a palette, specifying the transparency colour.
 708     */
 709     wxMask(const wxBitmap& bitmap, int index);
 710
 711     /**
 712         Constructs a mask from a monochrome bitmap.
 713     */
 714     wxMask(const wxBitmap& bitmap);
 715
 716     /**
 717         Constructs a mask from a bitmap and a colour that indicates the background.
 718     */
 719     wxMask(const wxBitmap& bitmap, const wxColour& colour);
 720
 721     /**
 722         Destroys the wxMask object and the underlying bitmap data.
 723     */
 724     virtual ~wxMask();
 725
 726     /**
 727         Constructs a mask from a bitmap and a palette index that indicates the
 728         background.
 729         Not yet implemented for GTK.
 730
 731         @param bitmap
 732             A valid bitmap.
 733         @param index
 734             Index into a palette, specifying the transparency colour.
 735     */
 736     bool Create(const wxBitmap& bitmap, int index);
 737
 738     /**
 739         Constructs a mask from a monochrome bitmap.
 740     */
 741     bool Create(const wxBitmap& bitmap);
 742
 743     /**
 744         Constructs a mask from a bitmap and a colour that indicates the background.
 745     */
 746     bool Create(const wxBitmap& bitmap, const wxColour& colour);
 747 };
 748