Document that throwing exceptions from wxTimer::Notify() is unsupported.

[wxWidgets.git] / interface / wx / bitmap.h

diff --git a/interface/wx/bitmap.h b/interface/wx/bitmap.h
index 3d1ec2000eb637b01e7fc3889c66a4b900e1a8dc..6117072a0330872a5f5ea8a675af05ce117ee37a 100644 (file)
--- a/interface/wx/bitmap.h
+++ b/interface/wx/bitmap.h
@@ -21,7 +21,7 @@
 
     If you wish to extend the capabilities of wxBitmap, derive a class from
     wxBitmapHandler and add the handler using wxBitmap::AddHandler() in your
 
     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.
 
     Note that all wxBitmapHandlers provided by wxWidgets are part of the
     @ref page_libs_wxcore library.


@@ -29,7 +29,7 @@
     wxBitmap class documentation.
 
     @library{wxcore}
     wxBitmap class documentation.
 
     @library{wxcore}

-    @category{misc}
+    @category{gdi}

 
     @see @ref overview_bitmap, wxBitmap, wxIcon, wxCursor
 */
 
     @see @ref overview_bitmap, wxBitmap, wxIcon, wxCursor
 */


@@ -167,17 +167,21 @@ public:
     class (either wxNativePixelData for RGB bitmaps or wxAlphaPixelData
     for bitmaps with an additionaly alpha channel).
 
     class (either wxNativePixelData for RGB bitmaps or wxAlphaPixelData
     for bitmaps with an additionaly 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.
     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.

 
     @library{wxcore}
     @category{gdi}
 
     @library{wxcore}
     @category{gdi}


@@ -256,6 +260,10 @@ public:
         @param depth
             Specifies the depth of the bitmap.
             If this is omitted, then a value of 1 (monochrome bitmap) is used.
         @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);
 
     */
     wxBitmap(const char bits[], int width, int height, int depth = 1);
 


@@ -269,9 +277,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);
         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.
 
     /**
         Creates a bitmap from XPM data.

+
+        @beginWxPerlOnly
+        In wxPerl use Wx::Bitmap->newFromXPM(data).
+        @endWxPerlOnly

     */
     wxBitmap(const char* const* bits);
 
     */
     wxBitmap(const char* const* bits);
 


@@ -336,6 +353,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.
         @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
     */
 
         @see wxBitmapHandler
     */


@@ -362,10 +387,15 @@ public:
     /**
         Creates a fresh bitmap.
         If the final argument is omitted, the display depth of the screen is used.
     /**
         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);
     */
     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.
 
     /*
         Creates a bitmap from the given data, which can be of arbitrary type.


@@ -436,7 +466,7 @@ public:
 
         @see wxBitmapHandler
     */
 
         @see wxBitmapHandler
     */

-    static wxList GetHandlers();
+    static wxList& GetHandlers();

 
     /**
         Gets the height of the bitmap in pixels.
 
     /**
         Gets the height of the bitmap in pixels.


@@ -476,6 +506,12 @@ public:
     */
     wxSize GetSize() const;
 
     */
     wxSize GetSize() const;
 

+    /**
+        Returns disabled (dimmed) version of the bitmap.
+        @since 2.9.0
+    */
+    wxBitmap ConvertToDisabled(unsigned char brightness = 255) const;
+

     /**
         Gets the width of the bitmap in pixels.
 
     /**
         Gets the width of the bitmap in pixels.