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