interface/bitmap.h

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