Make wxBitmapBundleImpl public and show how to use it

Show how a custom implementation of wxBitmapBundleImpl can be defined in
the toolbar sample.

include/wx/bmpbndl.h

@@ -149,4 +149,34 @@ wxBitmapBundle wxBitmapBundle::FromImage(const wxImage& image)
     return FromBitmap(wxBitmap(image));
 }
 
+// ----------------------------------------------------------------------------
+// wxBitmapBundleImpl is the base class for all wxBitmapBundle implementations
+// ----------------------------------------------------------------------------
+
+// This class inherits from wxRefCounter to make it possible to use it with
+// wxObjectDataPtr in wxBitmapBundle.
+//
+// It doesn't need to be used directly, but may be inherited from in order to
+// implement custom bitmap bundles.
+class wxBitmapBundleImpl : public wxRefCounter
+{
+public:
+    // Return the size of the bitmaps represented by this bundle in the default
+    // DPI (a.k.a. 100% resolution).
+    //
+    // Must always return a valid size.
+    virtual wxSize GetDefaultSize() const = 0;
+
+    // Retrieve the bitmap of exactly the given size.
+    //
+    // Note that this function is non-const because it may generate the bitmap
+    // on demand and cache it.
+    virtual wxBitmap GetBitmap(const wxSize size) = 0;
+
+#ifdef __WXOSX__
+    // returns the native representation of the bitmap bundle
+    virtual WXImage OSXGetImage() const { return NULL; }
+#endif
+};
+
 #endif // _WX_BMPBNDL_H_

include/wx/private/bmpbndl.h

@@ -10,34 +10,7 @@
 #ifndef _WX_PRIVATE_BMPBNDL_H_
 #define _WX_PRIVATE_BMPBNDL_H_
 
-#include "wx/object.h"
+#include "wx/bmpbndl.h"
-
-// ----------------------------------------------------------------------------
-// wxBitmapBundleImpl is the base class for all wxBitmapBundle implementations
-// ----------------------------------------------------------------------------
-
-// This class inherits from wxRefCounter to make it possible to use it with
-// wxObjectDataPtr in wxBitmapBundle.
-class wxBitmapBundleImpl : public wxRefCounter
-{
-public:
-    // Return the size of the bitmaps represented by this bundle in the default
-    // DPI (a.k.a. 100% resolution).
-    //
-    // Must always return a valid size.
-    virtual wxSize GetDefaultSize() const = 0;
-
-    // Retrieve the bitmap of exactly the given size.
-    //
-    // Note that this function is non-const because it may generate the bitmap
-    // on demand and cache it.
-    virtual wxBitmap GetBitmap(const wxSize size) = 0;
-
-#ifdef __WXOSX__
-    // returns the native representation of the bitmap bundle
-    virtual WXImage OSXGetImage() const { return NULL; }
-#endif
-};
 
 #ifdef __WXOSX__
 

interface/wx/bmpbndl.h

@@ -161,6 +161,20 @@ public:
      */
     static wxBitmapBundle FromImage(const wxImage& image);
 
+    /**
+        Create a bundle from a custom bitmap bundle implementation.
+
+        This function can be used to create bundles implementing custom logic
+        for creating the bitmaps, e.g. creating them on the fly rather than
+        using predefined bitmaps.
+
+        See wxBitmapBundleImpl.
+
+        @param impl A valid, i.e. non-null, pointer. This function takes
+            ownership of it, so the caller must @e not call DecRef() on it.
+     */
+    static wxBitmapBundle FromImpl(wxBitmapBundleImpl* impl);
+
     /**
         Create a bundle from the bitmaps in the application resources.
 
@@ -243,6 +257,64 @@ public:
     wxBitmap GetBitmap(const wxSize size) const;
 };
 
+/**
+    Base class for custom implementations of wxBitmapBundle.
+
+    This class shouldn't be used directly in the application code, but may be
+    derived from to implement custom bitmap bundles.
+
+    Example of use:
+    @code
+        class MyCustomBitmapBundleImpl : public wxBitmapBundleImpl
+        {
+        public:
+            MyCustomBitmapBundleImpl()
+            {
+            }
+
+            wxSize GetDefaultSize() const wxOVERRIDE
+            {
+                ... determine the minimum/default size for bitmap to use ...
+            }
+
+            wxBitmap GetBitmap(const wxSize size) wxOVERRIDE
+            {
+                ... get the bitmap of the requested size from somewhere and
+                    cache it if necessary, i.e. if getting it is expensive ...
+            }
+        };
+
+        toolBar->AddTool(wxID_OPEN, wxBitmapBundle::FromImpl(new MyCustomBitmapBundleImpl());
+    @endcode
+
+    Full (but still very simple) example of using it can be found in the
+    toolbar sample code.
+
+    @library{wxcore}
+    @category{gdi}
+
+    @since 3.1.6
+*/
+class wxBitmapBundleImpl : public wxRefCounter
+{
+public:
+    /**
+        Return the size of the bitmaps represented by this bundle in the default
+        DPI.
+
+        Must always return a valid size.
+     */
+    virtual wxSize GetDefaultSize() const = 0;
+
+    /**
+        Retrieve the bitmap of exactly the given size.
+
+        Note that this function is non-const because it may generate the bitmap
+        on demand and cache it.
+     */
+    virtual wxBitmap GetBitmap(const wxSize size) = 0;
+};
+
 /**
     Creates a wxBitmapBundle from resources on the platforms supporting them or
     from two embedded bitmaps otherwise.

samples/toolbar/toolbar.cpp

@@ -499,15 +499,61 @@ void MyFrame::PopulateToolbar(wxToolBarBase* toolBar)
 
     if ( !m_pathBmp.empty() )
     {
-        // create a tool with a custom bitmap for testing
+        wxImage image(m_pathBmp);
-        wxImage img(m_pathBmp);
+        if ( image.IsOk() )
-        if ( img.IsOk() )
         {
-            if ( img.GetWidth() > sizeBitmap.x && img.GetHeight() > sizeBitmap.y )
+            // create a custom bitmap bundle for testing
-                img = img.GetSubImage(wxRect(0, 0, sizeBitmap.x, sizeBitmap.y));
+            class MyCustomBitmapBundleImpl : public wxBitmapBundleImpl
+            {
+            public:
+                MyCustomBitmapBundleImpl(const wxImage& image,
+                                         const wxSize& sizeDef)
+                    : m_image(image),
+                      m_sizeDef(sizeDef)
+                {
+                }
+
+                wxSize GetDefaultSize() const wxOVERRIDE
+                {
+                    return m_sizeDef;
+                }
+
+                wxBitmap GetBitmap(const wxSize size) wxOVERRIDE
+                {
+                    // In this simple implementation we don't bother caching
+                    // anything.
+                    wxImage image = m_image;
+                    if ( image.GetSize() != size )
+                        image.Rescale(size.x, size.y, wxIMAGE_QUALITY_HIGH);
+
+                    // This is required under MSW in order to be able to draw
+                    // over the bitmap using wxDC. For full alpha support,
+                    // wxGraphicsContext should be used.
+                    if ( image.HasAlpha() )
+                        image.ClearAlpha();
+
+                    wxBitmap bitmap(image);
+
+                    // This is the custom part: we show the size of the bitmap
+                    // being used in the bitmap itself.
+                    wxMemoryDC dc(bitmap);
+                    dc.SetTextForeground(*wxRED);
+                    dc.SetFont(wxFontInfo(wxSize(size.x/4, size.y/2)).Bold());
+                    dc.DrawText(wxString::Format("%d", size.y), size.x/4, size.y/4);
+
+                    return bitmap;
+                }
+
+            private:
+                const wxImage m_image;
+                const wxSize m_sizeDef;
+            };
+
+            wxBitmapBundleImpl* const
+                impl = new MyCustomBitmapBundleImpl(image, sizeBitmap);
 
             toolBar->AddSeparator();
-            toolBar->AddTool(wxID_ANY, "Custom", img);
+            toolBar->AddTool(wxID_ANY, "Custom", wxBitmapBundle::FromImpl(impl));
         }
     }