interface/bitmap.h

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