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