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