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