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