Allow customizing bitmap handling in wxSVGFileDC.

Provide a built-in alternative for using external files for the bitmaps in
SVG: allow embedding them inside the SVG itself using "data:" URI.

And also allow to define custom handlers to make the behaviour even more
flexible.

Closes #15968.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@75981 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

interface/wx/dcsvg.h

@@ -21,9 +21,12 @@
     is a write-only class.
 
     As the wxSVGFileDC is a vector format, raster operations like GetPixel()
-    are unlikely to be supported. However, the SVG specification allows for PNG
-    format raster files to be embedded in the SVG, and so bitmaps, icons and
-    blit operations in wxSVGFileDC are supported.
+    are unlikely to be supported. However, the SVG specification allows for
+    raster files to be embedded in the SVG, and so bitmaps, icons and blit
+    operations in wxSVGFileDC are supported. By default only PNG format bitmaps
+    are supported and these are saved as separate files in the same folder
+    as the SVG file, however it is possible to change this behaviour by
+    replacing the built in bitmap handler using wxSVGFileDC::SetBitmapHandler().
 
     A more substantial SVG library (for reading and writing) is available at
     the wxArt2D website <http://wxart2d.sourceforge.net/>.
@@ -31,6 +34,7 @@
     @library{wxcore}
     @category{dc}
 */
+
 class wxSVGFileDC : public wxDC
 {
 public:
@@ -60,6 +64,28 @@ public:
     */
     void Clear();
 
+    /**
+        Replaces the default bitmap handler with @a handler.
+
+        By default, an object of wxSVGBitmapFileHandler class is used as bitmap
+        handler. You may want to replace it with an object of predefined
+        wxSVGBitmapEmbedHandler class to embed the bitmaps in the generated SVG
+        instead of storing them in separate files like this:
+        @code
+        mySVGFileDC->SetBitmapHandler(new wxSVGBitmapEmbedHandler());
+        @endcode
+
+        or derive your own bitmap handler class and use it if you need to
+        customize the bitmap handling further.
+
+        @param handler The new bitmap handler. If non-NULL, this object takes
+            ownership of this handler and will delete it when it is not needed
+            any more.
+
+        @since 3.1.0
+    */
+    void SetBitmapHandler(wxSVGBitmapHandler* handler);
+
     /**
         Does the same as wxDC::SetLogicalFunction(), except that only wxCOPY is
         available. Trying to set one of the other values will fail.
@@ -117,3 +143,79 @@ public:
     //@}
 };
 
+/**
+    Abstract base class for handling bitmaps inside a wxSVGFileDC.
+
+    To use it you need to derive a new class from it and override
+    ProcessBitmap() to generate a properly a formed SVG image element (see
+    http://www.w3.org/TR/SVG/struct.html#ImageElement).
+
+    Two example bitmap handlers are provided in wx/dcsvg.h. The first (default)
+    handler will create PNG files in the same folder as the SVG file and uses
+    links to them in the SVG. The second handler (wxSVGBitmapEmbedHandler) will
+    embed the PNG image in the SVG file using base 64 encoding.
+
+    The handler can be changed by calling wxSVGFileDC::SetBitmapHandler().
+
+    @library{wxcore}
+    @category{dc}
+
+    @since 3.1.0
+*/
+class wxSVGBitmapHandler
+{
+public:
+    /**
+        Writes the bitmap representation as SVG to the given stream.
+
+        The XML generated by this function will be inserted into the SVG file
+        inline with the XML generated by the main wxSVGFileDC class so it is
+        important that the XML is properly formed.
+
+        @param bitmap A valid bitmap to add to SVG.
+        @param x Horizontal position of the bitmap.
+        @param y Vertical position of the bitmap.
+        @param stream The stream to write SVG contents to.
+    */
+    virtual bool ProcessBitmap(const wxBitmap& bitmap,
+                               wxCoord x, wxCoord y,
+                               wxOutputStream& stream) const = 0;
+};
+
+/**
+    Handler embedding bitmaps as base64-encoded PNGs into the SVG.
+
+    @see wxSVGFileDC::SetBitmapHandler().
+
+    @library{wxcore}
+    @category{dc}
+
+    @since 3.1.0
+*/
+class wxSVGBitmapEmbedHandler : public wxSVGBitmapHandler
+{
+public:
+    virtual bool ProcessBitmap(const wxBitmap& bitmap,
+                               wxCoord x, wxCoord y,
+                               wxOutputStream& stream) const;
+};
+
+/**
+    Handler saving a bitmap to an external file and linking to it from the SVG.
+
+    This handler is used by default by wxSVGFileDC.
+
+    @see wxSVGFileDC::SetBitmapHandler().
+
+    @library{wxcore}
+    @category{dc}
+
+    @since 3.1.0
+*/
+class wxSVGBitmapFileHandler : public wxSVGBitmapHandler
+{
+public:
+    virtual bool ProcessBitmap(const wxBitmap& bitmap,
+                               wxCoord x, wxCoord y,
+                               wxOutputStream& stream) const;
+};