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