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