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