X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/427c415b933075ab9be91d7116c6db80858e0b78..9e9574fe45b176ee74bba8fad7574cf9906145d1:/interface/wx/bitmap.h

diff --git a/interface/wx/bitmap.h b/interface/wx/bitmap.h
index 68c3ed8bc5..d6f603b907 100644
--- a/interface/wx/bitmap.h
+++ b/interface/wx/bitmap.h
@@ -2,8 +2,7 @@
 // Name:        bitmap.h
 // Purpose:     interface of wxBitmap* classes
 // Author:      wxWidgets team
-// RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 
@@ -21,7 +20,7 @@
 
     If you wish to extend the capabilities of wxBitmap, derive a class from
     wxBitmapHandler and add the handler using wxBitmap::AddHandler() in your
-    application initialisation.
+    application initialization.
 
     Note that all wxBitmapHandlers provided by wxWidgets are part of the
     @ref page_libs_wxcore library.
@@ -29,7 +28,7 @@
     wxBitmap class documentation.
 
     @library{wxcore}
-    @category{misc}
+    @category{gdi}
 
     @see @ref overview_bitmap, wxBitmap, wxIcon, wxCursor
 */
@@ -92,6 +91,12 @@ public:
         Loads a bitmap from a file or resource, putting the resulting data into
         @a bitmap.
 
+        @note Under MSW, when loading a bitmap from resources (i.e. using @c
+            wxBITMAP_TYPE_BMP_RESOURCE as @a type), the light grey colour is
+            considered to be transparent, for historical reasons. If you want
+            to handle the light grey pixels normally instead, call
+            SetMask(NULL) after loading the bitmap.
+
         @param bitmap
             The bitmap object which is to be affected by this operation.
         @param name
@@ -165,19 +170,34 @@ public:
     If you need direct access the bitmap data instead going through
     drawing to it using wxMemoryDC you need to use the wxPixelData
     class (either wxNativePixelData for RGB bitmaps or wxAlphaPixelData
-    for bitmaps with an additionaly alpha channel).
+    for bitmaps with an additionally alpha channel).
 
-    @note
-    Many wxBitmap functions take a @e type parameter, which is a value of the
-    ::wxBitmapType enumeration.
+    Note that many wxBitmap functions take a @e type parameter, which is a 
+    value of the ::wxBitmapType enumeration.
     The validity of those values depends however on the platform where your program
     is running and from the wxWidgets configuration.
-    If all possible wxWidgets settings are used, the Windows platform supports BMP file,
-    BMP resource, XPM data, and XPM.
-    Under wxGTK, the available formats are BMP file, XPM data, XPM file, and PNG file.
-    Under wxMotif, the available formats are XBM data, XBM file, XPM data, XPM file.
-    In addition, wxBitmap can load and save all formats that wxImage; see wxImage for
-    more info. Of course, you must have wxImage handlers loaded.
+    If all possible wxWidgets settings are used:
+    - wxMSW supports BMP and ICO files, BMP and ICO resources;
+    - wxGTK supports XPM files;
+    - wxMac supports PICT resources;
+    - wxX11 supports XPM files, XPM data, XBM data;
+
+    In addition, wxBitmap can load and save all formats that wxImage can; see wxImage
+    for more info. Of course, you must have loaded the wxImage handlers 
+    (see ::wxInitAllImageHandlers() and wxImage::AddHandler).
+    Note that all available wxBitmapHandlers for a given wxWidgets port are 
+    automatically loaded at startup so you won't need to use wxBitmap::AddHandler.
+
+    More on the difference between wxImage and wxBitmap: wxImage is just a
+    buffer of RGB bytes with an optional buffer for the alpha bytes. It is all
+    generic, platform independent and image file format independent code. It
+    includes generic code for scaling, resizing, clipping, and other manipulations
+    of the image data. OTOH, wxBitmap is intended to be a wrapper of whatever is
+    the native image format that is quickest/easiest to draw to a DC or to be the
+    target of the drawing operations performed on a wxMemoryDC. By splitting the
+    responsibilities between wxImage/wxBitmap like this then it's easier to use
+    generic code shared by all platforms and image types for generic operations and
+    platform specific code where performance or compatibility is needed.
 
     @library{wxcore}
     @category{gdi}
@@ -256,6 +276,10 @@ public:
         @param depth
             Specifies the depth of the bitmap.
             If this is omitted, then a value of 1 (monochrome bitmap) is used.
+
+        @beginWxPerlOnly
+        In wxPerl use Wx::Bitmap->newFromBits(bits, width, height, depth).
+        @endWxPerlOnly
     */
     wxBitmap(const char bits[], int width, int height, int depth = 1);
 
@@ -269,9 +293,18 @@ public:
         A depth of 32 including an alpha channel is supported under MSW, Mac and GTK+.
     */
     wxBitmap(int width, int height, int depth = wxBITMAP_SCREEN_DEPTH);
+    
+    /**
+        @overload
+    */
+    wxBitmap(const wxSize& sz, int depth = wxBITMAP_SCREEN_DEPTH);
 
     /**
         Creates a bitmap from XPM data.
+
+        @beginWxPerlOnly
+        In wxPerl use Wx::Bitmap->newFromXPM(data).
+        @endWxPerlOnly
     */
     wxBitmap(const char* const* bits);
 
@@ -336,6 +369,14 @@ public:
         @param handler
             A new bitmap format handler object. There is usually only one instance
             of a given handler class in an application session.
+            
+        Note that unlike wxImage::AddHandler, there's no documented list of
+        the wxBitmapHandlers available in wxWidgets.
+        This is because they are platform-specific and most important, they are 
+        all automatically loaded at startup.
+        
+        If you want to be sure that wxBitmap can load a certain type of image,
+        you'd better use wxImage::AddHandler.
 
         @see wxBitmapHandler
     */
@@ -362,10 +403,15 @@ public:
     /**
         Creates a fresh bitmap.
         If the final argument is omitted, the display depth of the screen is used.
-
-        This overload works on all platforms.
+        
+        @return @true if the creation was successful.
     */
     virtual bool Create(int width, int height, int depth = wxBITMAP_SCREEN_DEPTH);
+    
+    /**
+        @overload
+    */
+    virtual bool Create(const wxSize& sz, int depth = wxBITMAP_SCREEN_DEPTH);
 
     /*
         Creates a bitmap from the given data, which can be of arbitrary type.
@@ -436,10 +482,12 @@ public:
 
         @see wxBitmapHandler
     */
-    static wxList GetHandlers();
+    static wxList& GetHandlers();
 
     /**
         Gets the height of the bitmap in pixels.
+
+        @see GetWidth(), GetSize()
     */
     virtual int GetHeight() const;
 
@@ -465,10 +513,28 @@ public:
     */
     virtual wxBitmap GetSubBitmap(const wxRect& rect) const;
 
+    /**
+        Returns the size of the bitmap in pixels.
+
+        @since 2.9.0
+
+        @see GetHeight(), GetWidth()
+    */
+    wxSize GetSize() const;
+
+    /**
+        Returns disabled (dimmed) version of the bitmap.
+
+        This method is not available when <code>wxUSE_IMAGE == 0</code>.
+
+        @since 2.9.0
+    */
+    wxBitmap ConvertToDisabled(unsigned char brightness = 255) const;
+
     /**
         Gets the width of the bitmap in pixels.
 
-        @see GetHeight()
+        @see GetHeight(), GetSize()
     */
     virtual int GetWidth() const;
 
@@ -523,6 +589,31 @@ public:
     */
     virtual bool LoadFile(const wxString& name, wxBitmapType type = wxBITMAP_DEFAULT_TYPE);
 
+    /**
+        Loads a bitmap from the memory containing image data in PNG format.
+
+        This helper function provides the simplest way to create a wxBitmap
+        from PNG image data. On most platforms, it's simply a wrapper around
+        wxImage loading functions and so requires the PNG image handler to be
+        registered by either calling wxInitAllImageHandlers() which also
+        registers all the other image formats or including the necessary
+        header:
+        @code
+            #include <wx/imagpng.h>
+        @endcode
+        and calling
+        @code
+            wxImage::AddHandler(new wxPNGHandler);
+        @endcode
+        in your application startup code.
+
+        However under OS X this function uses native image loading and so
+        doesn't require wxWidgets PNG support.
+
+        @since 2.9.5
+     */
+    static wxBitmap NewFromPNGData(const void* data, size_t size);
+
     /**
         Finds the handler with the given name, and removes it.
         The handler is not deleted.
@@ -649,19 +740,11 @@ public:
 
     /**
         Constructs a mask from a monochrome bitmap.
-
-        @beginWxPythonOnly
-        This is the default constructor for wxMask in wxPython.
-        @endWxPythonOnly
     */
     wxMask(const wxBitmap& bitmap);
 
     /**
         Constructs a mask from a bitmap and a colour that indicates the background.
-
-        @beginWxPythonOnly
-        wxPython has an alternate wxMask constructor matching this form called wxMaskColour.
-        @endWxPythonOnly
     */
     wxMask(const wxBitmap& bitmap, const wxColour& colour);
 
@@ -691,5 +774,13 @@ public:
         Constructs a mask from a bitmap and a colour that indicates the background.
     */
     bool Create(const wxBitmap& bitmap, const wxColour& colour);
+
+    /**
+        Returns the mask as a monochrome bitmap.
+        Currently this method is implemented in wxMSW, wxGTK and wxOSX.
+
+        @since 2.9.5
+    */
+    wxBitmap GetBitmap() const;
 };