.. wxPython Phoenix documentation

   This file was generated by Phoenix's sphinx generator and associated
   tools, do not edit by hand.

   Copyright: (c) 2011-2020 by Total Control Software
   License:   wxWindows License

.. include:: headings.inc



.. _wx.svg:

==========================================================================================================================================
|phoenix_title|  **wx.svg**
==========================================================================================================================================

The classes in this package facilitate the parsing, normalizing, drawing and
rasterizing of Scalable Vector Graphics (SVG) images. The primary interface to
this functionality is via the :class:`wx.svg.SVGimage` class, which provides
various integrations with wxPython. It, in turn, uses a set of wrappers around
the NanoSVG library (https://github.com/memononen/nanosvg) to do the low-level
work. There are a few features defined in the SVG spec that are not supported,
but all the commonly used ones seem to be there.

Example 1
---------
Drawing an SVG image to a window, scaled to fit the size of the window and using
a :class:`wx.GraphicsContext` can be done like this::

    def __init__(self, ...):
        ...
        self.img = wx.svg.SVGimage.CreateFromFile(svg_filename)
        self.Bind(wx.EVT_PAINT, self.OnPaint)

    def OnPaint(self, event):
        dc = wx.PaintDC(self)
        dc.SetBackground(wx.Brush('white'))
        dc.Clear()

        dcdim = min(self.Size.width, self.Size.height)
        imgdim = min(self.img.width, self.img.height)
        scale = dcdim / imgdim
        width = int(self.img.width * scale)
        height = int(self.img.height * scale)

        ctx = wx.GraphicsContext.Create(dc)
        self.img.RenderToGC(ctx, scale)

Since it is drawing the SVG shapes and paths using the equivalent GC primitives
then any existing transformations that may be active on the context will be
applied automatically to the SVG shapes.

Note that not all GraphicsContext backends are created equal. Specifically, the
GDI+ backend (the default on Windows) simply can not support some features that
are commonly used in SVG images, such as applying transforms to gradients. The
Direct2D backend on Windows does much better, and the Cairo backend on Windows
is also very good. The default backends on OSX and Linux do very good as well.

Example 2
---------
If you're not already using a ``wx.GraphicsContext`` then a :class:`wx.Bitmap`
can easily be created instead. For example, the last 2 lines in the code above
could be replaced by the following, and accomplish basically the same thing::

    bmp = self.img.ConvertToBitmap(scale=scale, width=width, height=height)
    dc.DrawBitmap(bmp, 0, 0)

Example 3
---------
The ``ConvertToBitmap`` shown above gives a lot of control around scaling,
translating and sizing the SVG image into a bitmap, but most of the time you
probably just want to get a bitmap of a certain size to use as an icon or
similar. The ``ConvertToScaledBitmap`` provides an easier API to do just that
for you. It automatically scales the SVG image into the requested size in
pixels.::

    bmp = img.ConvertToScaledBitmap(wx.Size(24,24))

Optionally, it can accept a window parameter that will automatically adjust the
size according to the Content Scale Factor of that window, if supported by the
platform and if the window is located on a HiDPI display the the bitmap's size
will be adjusted accordingly.::

    bmp = img.ConvertToScaledBitmap(wx.Size(24,24), self)


|module_summary| Modules Summary
================================

================================================================================ ================================================================================
:mod:`~wx.svg._nanosvg`                                                          NanoSVG is a "simple stupid single-header-file SVG parser" from
================================================================================ ================================================================================


|


|class_summary| Classes Summary
===============================

================================================================================ ================================================================================
`~wx.svg.SVGimage`                                                               The SVGimage class provides various ways to load and use SVG images
================================================================================ ================================================================================


|


.. toctree::
   :maxdepth: 1
   :hidden:

   wx.svg._nanosvg
   wx.svg.SVGimage