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