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