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     wxBitmap(const char bits[], int width, int height, int depth = 1);
 265
 266     /**
 267         Creates a new bitmap. A depth of ::wxBITMAP_SCREEN_DEPTH indicates the
 268         depth of the current screen or visual.
 269
 270         Some platforms only support 1 for monochrome and ::wxBITMAP_SCREEN_DEPTH for
 271         the current colour setting.
 272
 273         A depth of 32 including an alpha channel is supported under MSW, Mac and GTK+.
 274     */
 275     wxBitmap(int width, int height, int depth = wxBITMAP_SCREEN_DEPTH);
 276
 277     /**
 278         Creates a bitmap from XPM data.
 279     */
 280     wxBitmap(const char* const* bits);
 281
 282     /**
 283         Loads a bitmap from a file or resource.
 284
 285         @param name
 286             This can refer to a resource name or a filename under MS Windows and X.
 287             Its meaning is determined by the @a type parameter.
 288         @param type
 289             May be one of the ::wxBitmapType values and indicates which type of
 290             bitmap should be loaded. See the note in the class detailed description.
 291             Note that the wxBITMAP_DEFAULT_TYPE constant has different value under
 292             different wxWidgets ports. See the bitmap.h header for the value it takes
 293             for a specific port.
 294
 295         @see LoadFile()
 296     */
 297     wxBitmap(const wxString& name, wxBitmapType type = wxBITMAP_DEFAULT_TYPE);
 298
 299     /**
 300         Creates this bitmap object from the given image.
 301         This has to be done to actually display an image as you cannot draw an
 302         image directly on a window.
 303
 304         The resulting bitmap will use the provided colour depth (or that of the
 305         current system if depth is ::wxBITMAP_SCREEN_DEPTH) which entails that a
 306         colour reduction may take place.
 307
 308         When in 8-bit mode (PseudoColour mode), the GTK port will use a color cube
 309         created on program start-up to look up colors. This ensures a very fast conversion,
 310         but the image quality won't be perfect (and could be better for photo images using
 311         more sophisticated dithering algorithms).
 312
 313         On Windows, if there is a palette present (set with SetPalette), it will be
 314         used when creating the wxBitmap (most useful in 8-bit display mode).
 315         On other platforms, the palette is currently ignored.
 316
 317         @param img
 318             Platform-independent wxImage object.
 319         @param depth
 320             Specifies the depth of the bitmap.
 321             If this is omitted, the display depth of the screen is used.
 322     */
 323     wxBitmap(const wxImage& img, int depth = wxBITMAP_SCREEN_DEPTH);
 324
 325     /**
 326         Destructor.
 327         See @ref overview_refcount_destruct for more info.
 328
 329         If the application omits to delete the bitmap explicitly, the bitmap will be
 330         destroyed automatically by wxWidgets when the application exits.
 331
 332         @warning
 333         Do not delete a bitmap that is selected into a memory device context.
 334     */
 335     virtual ~wxBitmap();
 336
 337     /**
 338         Adds a handler to the end of the static list of format handlers.
 339
 340         @param handler
 341             A new bitmap format handler object. There is usually only one instance
 342             of a given handler class in an application session.
 343
 344         Note that unlike wxImage::AddHandler, there's no documented list of
 345         the wxBitmapHandlers available in wxWidgets.
 346         This is because they are platform-specific and most important, they are
 347         all automatically loaded at startup.
 348
 349         If you want to be sure that wxBitmap can load a certain type of image,
 350         you'd better use wxImage::AddHandler.
 351
 352         @see wxBitmapHandler
 353     */
 354     static void AddHandler(wxBitmapHandler* handler);
 355
 356     /**
 357         Deletes all bitmap handlers.
 358         This function is called by wxWidgets on exit.
 359     */
 360     static void CleanUpHandlers();
 361
 362     /**
 363         Creates an image from a platform-dependent bitmap. This preserves
 364         mask information so that bitmaps and images can be converted back
 365         and forth without loss in that respect.
 366     */
 367     virtual wxImage ConvertToImage() const;
 368
 369     /**
 370         Creates the bitmap from an icon.
 371     */
 372     virtual bool CopyFromIcon(const wxIcon& icon);
 373
 374     /**
 375         Creates a fresh bitmap.
 376         If the final argument is omitted, the display depth of the screen is used.
 377
 378         This overload works on all platforms.
 379     */
 380     virtual bool Create(int width, int height, int depth = wxBITMAP_SCREEN_DEPTH);
 381
 382     /*
 383         Creates a bitmap from the given data, which can be of arbitrary type.
 384
 385         @param data
 386             Data whose type depends on the value of type.
 387         @param type
 388             A bitmap type identifier; see ::wxBitmapType for the list of values.
 389             See the note in the class detailed description for more info.
 390         @param width
 391             The width of the bitmap in pixels.
 392         @param height
 393             The height of the bitmap in pixels.
 394         @param depth
 395             The depth of the bitmap in pixels. If this is -1, the screen depth is used.
 396
 397         @return @true if the call succeeded, @false otherwise.
 398
 399         This overload depends on the @a type of data.
 400
 401     virtual bool Create(const void* data, int type, int width,
 402                         int height, int depth = -1);
 403
 404         NOTE: leave this undoc for the same reason of the relative ctor.
 405     */
 406
 407     /**
 408         Finds the handler with the given @a name.
 409
 410         @return A pointer to the handler if found, @NULL otherwise.
 411     */
 412     static wxBitmapHandler* FindHandler(const wxString& name);
 413
 414     /**
 415         Finds the handler associated with the given @a extension and @a type.
 416
 417         @param extension
 418             The file extension, such as "bmp" (without the dot).
 419         @param bitmapType
 420             The bitmap type managed by the handler, see ::wxBitmapType.
 421
 422         @return A pointer to the handler if found, @NULL otherwise.
 423     */
 424     static wxBitmapHandler* FindHandler(const wxString& extension,
 425                                         wxBitmapType bitmapType);
 426
 427     /**
 428         Finds the handler associated with the given bitmap type.
 429
 430         @param bitmapType
 431             The bitmap type managed by the handler, see ::wxBitmapType.
 432
 433         @return A pointer to the handler if found, @NULL otherwise.
 434
 435         @see wxBitmapHandler
 436     */
 437
 438     static wxBitmapHandler* FindHandler(wxBitmapType bitmapType);
 439
 440     /**
 441         Gets the colour depth of the bitmap.
 442         A value of 1 indicates a monochrome bitmap.
 443     */
 444     virtual int GetDepth() const;
 445
 446     /**
 447         Returns the static list of bitmap format handlers.
 448
 449         @see wxBitmapHandler
 450     */
 451     static wxList& GetHandlers();
 452
 453     /**
 454         Gets the height of the bitmap in pixels.
 455
 456         @see GetWidth(), GetSize()
 457     */
 458     virtual int GetHeight() const;
 459
 460     /**
 461         Gets the associated mask (if any) which may have been loaded from a file
 462         or set for the bitmap.
 463
 464         @see SetMask(), wxMask
 465     */
 466     virtual wxMask* GetMask() const;
 467
 468     /**
 469         Gets the associated palette (if any) which may have been loaded from a file
 470         or set for the bitmap.
 471
 472         @see wxPalette
 473     */
 474     virtual wxPalette* GetPalette() const;
 475
 476     /**
 477         Returns a sub bitmap of the current one as long as the rect belongs entirely to
 478         the bitmap. This function preserves bit depth and mask information.
 479     */
 480     virtual wxBitmap GetSubBitmap(const wxRect& rect) const;
 481
 482     /**
 483         Returns the size of the bitmap in pixels.
 484
 485         @since 2.9.0
 486
 487         @see GetHeight(), GetWidth()
 488     */
 489     wxSize GetSize() const;
 490
 491     /**
 492         Gets the width of the bitmap in pixels.
 493
 494         @see GetHeight(), GetSize()
 495     */
 496     virtual int GetWidth() const;
 497
 498     /**
 499         Adds the standard bitmap format handlers, which, depending on wxWidgets
 500         configuration, can be handlers for Windows bitmap, Windows bitmap resource,
 501         and XPM.
 502
 503         This function is called by wxWidgets on startup.
 504
 505         @see wxBitmapHandler
 506     */
 507     static void InitStandardHandlers();
 508
 509     /**
 510         Adds a handler at the start of the static list of format handlers.
 511
 512         @param handler
 513             A new bitmap format handler object. There is usually only one instance
 514             of a given handler class in an application session.
 515
 516         @see wxBitmapHandler
 517     */
 518     static void InsertHandler(wxBitmapHandler* handler);
 519
 520     /**
 521         Returns @true if bitmap data is present.
 522     */
 523     virtual bool IsOk() const;
 524
 525     /**
 526         Loads a bitmap from a file or resource.
 527
 528         @param name
 529             Either a filename or a Windows resource name.
 530             The meaning of name is determined by the @a type parameter.
 531         @param type
 532             One of the ::wxBitmapType values; see the note in the class
 533             detailed description.
 534             Note that the wxBITMAP_DEFAULT_TYPE constant has different value under
 535             different wxWidgets ports. See the bitmap.h header for the value it takes
 536             for a specific port.
 537
 538         @return @true if the operation succeeded, @false otherwise.
 539
 540         @remarks A palette may be associated with the bitmap if one exists
 541                  (especially for colour Windows bitmaps), and if the
 542                  code supports it. You can check if one has been created
 543                  by using the GetPalette() member.
 544
 545         @see SaveFile()
 546     */
 547     virtual bool LoadFile(const wxString& name, wxBitmapType type = wxBITMAP_DEFAULT_TYPE);
 548
 549     /**
 550         Finds the handler with the given name, and removes it.
 551         The handler is not deleted.
 552
 553         @param name
 554             The handler name.
 555
 556         @return @true if the handler was found and removed, @false otherwise.
 557
 558         @see wxBitmapHandler
 559     */
 560     static bool RemoveHandler(const wxString& name);
 561
 562     /**
 563         Saves a bitmap in the named file.
 564
 565         @param name
 566             A filename. The meaning of name is determined by the type parameter.
 567         @param type
 568             One of the ::wxBitmapType values; see the note in the class
 569             detailed description.
 570         @param palette
 571             An optional palette used for saving the bitmap.
 572
 573         @return @true if the operation succeeded, @false otherwise.
 574
 575         @remarks Depending on how wxWidgets has been configured, not all formats
 576                  may be available.
 577
 578         @see LoadFile()
 579     */
 580     virtual bool SaveFile(const wxString& name, wxBitmapType type,
 581                           const wxPalette* palette = NULL) const;
 582
 583     /**
 584         Sets the depth member (does not affect the bitmap data).
 585
 586         @todo since these functions do not affect the bitmap data,
 587               why they exist??
 588
 589         @param depth
 590             Bitmap depth.
 591     */
 592     virtual void SetDepth(int depth);
 593
 594     /**
 595         Sets the height member (does not affect the bitmap data).
 596
 597         @param height
 598             Bitmap height in pixels.
 599     */
 600     virtual void SetHeight(int height);
 601
 602     /**
 603         Sets the mask for this bitmap.
 604
 605         @remarks The bitmap object owns the mask once this has been called.
 606
 607         @see GetMask(), wxMask
 608     */
 609     virtual void SetMask(wxMask* mask);
 610
 611     /**
 612         Sets the associated palette. (Not implemented under GTK+).
 613
 614         @param palette
 615             The palette to set.
 616
 617         @see wxPalette
 618     */
 619     virtual void SetPalette(const wxPalette& palette);
 620
 621     /**
 622         Sets the width member (does not affect the bitmap data).
 623
 624         @param width
 625             Bitmap width in pixels.
 626     */
 627     virtual void SetWidth(int width);
 628 };
 629
 630 /**
 631     An empty wxBitmap object.
 632 */
 633 wxBitmap wxNullBitmap;
 634
 635
 636
 637
 638 /**
 639     @class wxMask
 640
 641     This class encapsulates a monochrome mask bitmap, where the masked area is
 642     black and the unmasked area is white.
 643
 644     When associated with a bitmap and drawn in a device context, the unmasked
 645     area of the bitmap will be drawn, and the masked area will not be drawn.
 646
 647     @library{wxcore}
 648     @category{gdi}
 649
 650     @see wxBitmap, wxDC::Blit, wxMemoryDC
 651 */
 652 class wxMask : public wxObject
 653 {
 654 public:
 655
 656     /**
 657         Default constructor.
 658     */
 659     wxMask();
 660
 661     /**
 662         Constructs a mask from a bitmap and a palette index that indicates the
 663         background.
 664         Not yet implemented for GTK.
 665
 666         @param bitmap
 667             A valid bitmap.
 668         @param index
 669             Index into a palette, specifying the transparency colour.
 670     */
 671     wxMask(const wxBitmap& bitmap, int index);
 672
 673     /**
 674         Constructs a mask from a monochrome bitmap.
 675
 676         @beginWxPythonOnly
 677         This is the default constructor for wxMask in wxPython.
 678         @endWxPythonOnly
 679     */
 680     wxMask(const wxBitmap& bitmap);
 681
 682     /**
 683         Constructs a mask from a bitmap and a colour that indicates the background.
 684
 685         @beginWxPythonOnly
 686         wxPython has an alternate wxMask constructor matching this form called wxMaskColour.
 687         @endWxPythonOnly
 688     */
 689     wxMask(const wxBitmap& bitmap, const wxColour& colour);
 690
 691     /**
 692         Destroys the wxMask object and the underlying bitmap data.
 693     */
 694     virtual ~wxMask();
 695
 696     /**
 697         Constructs a mask from a bitmap and a palette index that indicates the
 698         background.
 699         Not yet implemented for GTK.
 700
 701         @param bitmap
 702             A valid bitmap.
 703         @param index
 704             Index into a palette, specifying the transparency colour.
 705     */
 706     bool Create(const wxBitmap& bitmap, int index);
 707
 708     /**
 709         Constructs a mask from a monochrome bitmap.
 710     */
 711     bool Create(const wxBitmap& bitmap);
 712
 713     /**
 714         Constructs a mask from a bitmap and a colour that indicates the background.
 715     */
 716     bool Create(const wxBitmap& bitmap, const wxColour& colour);
 717 };
 718