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