:right-sidebar: True

Svg
===================================================================

.. currentmodule:: gi.repository.Gtk


.. versionadded:: 4.22




.. class:: Svg(**properties: ~typing.Any)
   :no-contents-entry:


Superclasses: :class:`~gi.repository.GObject.Object`



Implemented Interfaces: :class:`~gi.repository.Gdk.Paintable`, :class:`~gi.repository.Gtk.SymbolicPaintable`



A paintable implementation that renders SVG, with animations.

``GtkSvg`` objects are created by parsing a subset of SVG,
including SVG animations.

``GtkSvg`` fills or strokes paths with symbolic or fixed colors.
It can have multiple states, and paths can be included in a subset
of the states. States can have animations, and the transition
between different states can also be animated.

To show a static SVG image, it is enough to load the
the SVG and use it like any other paintable.

To play an SVG animation, use :obj:`~gi.repository.Gtk.Svg.set_frame_clock`
to connect the paintable to a frame clock, and call
:obj:`~gi.repository.Gtk.Svg.play` after loading the SVG. The animation can
be paused using :obj:`~gi.repository.Gtk.Svg.pause`\.

To set the current state, use :obj:`~gi.repository.Gtk.Svg.set_state`\.

Error handling
--------------------------------------------------------------------------------

Loading an SVG into ``GtkSvg`` will always produce a (possibly empty)
paintable. GTK will drop things that it can't handle and try to make
sense of the rest.

To track errors during parsing or rendering, connect to the
:obj:`~gi.repository.Gtk.Svg.signals.error` signal.

For parsing errors in the ``GTK_SVG_ERROR`` domain, the functions
:obj:`~gi.repository.Gtk.SvgError.get_start`\, :obj:`~gi.repository.Gtk.SvgError.get_end`\,
:obj:`~gi.repository.Gtk.SvgError.get_element` and :obj:`~gi.repository.Gtk.SvgError.get_attribute`
can be used to obtain information about where the error occurred.

The supported subset of SVG
--------------------------------------------------------------------------------

The paintable supports much of SVG 2, with some exceptions.

Among the graphical elements, ``<textPath>`` and ``<foreignObject>``
are not supported.

Among the structural elements, ``<a>`` and ``<view>`` are not supported.

In the ``<filter>`` element, the following primitives are not
supported: feConvolveMatrix, feDiffuseLighting,
feMorphology, feSpecularLighting and feTurbulence.

Support for the ``mask`` attribute is limited to just a url
referring to the ``<mask>`` element by ID.

In animation elements, the parsing of ``begin`` and ``end`` attributes
is limited, and the ``min`` and ``max`` attributes are not supported.

Lastly, there is only minimal CSS support (the style attribute,
but not ``<style>``\), and no interactivity.

SVG Extensions
--------------------------------------------------------------------------------

The paintable supports a number of `custom attributes <icon-format.html>`__
that offer a convenient way to define states, transitions and animations.
For example,

<circle cx='5' cy='5' r='5'
            gpa:states='0 1'
            gpa:animation-type='automatic'
            gpa:animation-direction='segment'
            gpa:animation-duration='600ms'/>

defines the circle to be shown in states 0 and 1, and animates a segment
of the circle.

<image src="svg-renderer1.svg">

Note that the generated animations are implemented using standard
SVG attributes (``visibility``\, ``stroke-dasharray,``\stroke-dashoffset``,``\pathLength``and``\filter`). Setting these attributes in your SVG
is therefore going to interfere with generated animations.

To connect general SVG animations to the states of the paintable,
use the custom ``gpa:states(...)`` condition in the ``begin`` and ``end``
attributes of SVG animation elements. For example,

<animate href='path1'
             attributeName='fill'
             begin='gpa:states(0).begin'
             dur='300ms'
             fill='freeze'
             from='black'
             to='magenta'/>

will make the fill color of path1 transition from black to
magenta when the renderer enters state 0.

<image src="svg-renderer2.svg">

The ``gpa:states(...)`` condition triggers for upcoming state changes
as well, to support fade-out transitions. For example,

<animate href='path1'
             attributeName='opacity'
             begin='gpa:states(0).end -300ms'
             dur='300ms'
             fill='freeze'
             from='1'
             to='0'/>

will start a fade-out of path1 300ms before state 0 ends.

A variant of the ``gpa:states(...)`` condition allows specifying
both before and after states:

<animate href='path1'
             attributeName='opacity'
             begin='gpa:states(0, 1 2)'
             dur='300ms'
             fill='freeze'
             from='1'
             to='0'/>

will start the animation when the state changes from 0 to 1 or
from 0 to 2, but not when it changes from 0 to 3.

In addition to the ``gpa:fill`` and ``gpa:stroke`` attributes, symbolic
colors can also be specified as a custom paint server reference,
like this: ``url(#gpa:warning)``\. This works in ``fill`` and ``stroke``
attributes, but also when specifying colors in SVG animation
attributes like ``to`` or ``values``\.

Note that the SVG syntax allows for a fallback RGB color to be
specified after the url, for compatibility with other SVG consumers:

fill='url(``gpa``:warning) orange'

In contrast to SVG 1.1 and 2.0, we allow the ``transform`` attribute
to be animated with ``<animate>``\.


Constructors
------------

.. rst-class:: interim-class

.. class:: Svg
   :no-index:


   .. classmethod:: new() -> ~gi.repository.Gtk.Svg

      Creates a new, empty SVG paintable.


      .. versionadded:: 4.22








   .. classmethod:: new_from_bytes(bytes: ~gi.repository.GLib.Bytes) -> ~gi.repository.Gtk.Svg

      Parses the SVG data in ``bytes`` and creates a paintable.


      .. versionadded:: 4.22





      :param bytes: the data




   .. classmethod:: new_from_resource(path: str) -> ~gi.repository.Gtk.Svg

      Parses the SVG data in the resource and creates a paintable.


      .. versionadded:: 4.22





      :param path: the resource path








Methods
-------

.. rst-class:: interim-class

.. class:: Svg
   :no-index:


   .. method:: get_features() -> ~gi.repository.Gtk.SvgFeatures

      Returns the currently enabled features.



      .. versionadded:: 4.22








   .. method:: get_state() -> int

      Gets the current state of the paintable.



      .. versionadded:: 4.22








   .. method:: get_state_names() -> tuple[list[str] | None, int]

      Returns a ``NULL``\-terminated array of
      state names, if available.

      Note that the returned array and the strings
      contained in it will only be valid until the
      ``GtkSvg`` is cleared or reloaded, so if you
      want to keep it around, you should make a copy.



      .. versionadded:: 4.22








   .. method:: get_weight() -> float

      Gets the value of the weight property.



      .. versionadded:: 4.22








   .. method:: load_from_bytes(bytes: ~gi.repository.GLib.Bytes) -> None

      Loads SVG content into an existing SVG paintable.

      To track errors while loading SVG content,
      connect to the :obj:`~gi.repository.Gtk.Svg.signals.error` signal.

      This clears any previously loaded content.



      .. versionadded:: 4.22





      :param bytes: the data to load




   .. method:: load_from_resource(path: str) -> None

      Loads SVG content into an existing SVG paintable.

      To track errors while loading SVG content,
      connect to the :obj:`~gi.repository.Gtk.Svg.signals.error` signal.

      This clears any previously loaded content.



      .. versionadded:: 4.22





      :param path: the resource path




   .. method:: pause() -> None

      Stop any playing animations and state transitions.

      Animations can be paused and started repeatedly.



      .. versionadded:: 4.22








   .. method:: play() -> None

      Start playing animations and state transitions.

      Animations can be paused and started repeatedly.



      .. versionadded:: 4.22








   .. method:: serialize() -> ~gi.repository.GLib.Bytes

      Serializes the content of the renderer as SVG.

      The SVG will be similar to the orignally loaded one,
      but is not guaranteed to be 100% identical.

      This function serializes the DOM, i.e. the results
      of parsing the SVG. It does not reflect the effect
      of applying animations.



      .. versionadded:: 4.22








   .. method:: set_features(features: ~gi.repository.Gtk.SvgFeatures) -> None

      Enables or disables features of the SVG paintable.

      By default, all features are enabled.

      Note that this call only has an effect before the
      SVG is loaded.



      .. versionadded:: 4.22





      :param features: features to enable




   .. method:: set_frame_clock(clock: ~gi.repository.Gdk.FrameClock) -> None

      Sets a frame clock.

      Without a frame clock, GtkSvg will not advance animations.



      .. versionadded:: 4.22





      :param clock: the frame clock




   .. method:: set_state(state: int) -> None

      Sets the state of the paintable.

      If the paintable is currently playing, the state change
      will apply transitions that are defined in the SVG. If
      the paintable is not playing, the state change will take
      effect instantaneously.



      .. versionadded:: 4.22





      :param state: the state to set, as a value between 0 and 63




   .. method:: set_weight(weight: float) -> None

      Sets the weight that is used when rendering.

      The weight affects the effective linewidth when stroking
      paths.

      The default value of -1 means to use the font weight
      from CSS.



      .. versionadded:: 4.22





      :param weight: the font weight, as a value between -1 and 1000




   .. method:: write_to_file(filename: str) -> bool

      Serializes the paintable, and saves the result to a file.



      .. versionadded:: 4.22





      :param filename: the file to save to








Properties
----------

.. rst-class:: interim-class

.. class:: Svg
   :no-index:
   

   .. attribute:: props.features
      :type: ~gi.repository.Gtk.SvgFeatures

      The type of the None singleton.



      .. versionadded:: 4.22





   .. attribute:: props.playing
      :type: bool

      The type of the None singleton.



      .. versionadded:: 4.22





   .. attribute:: props.resource
      :type: str

      The type of the None singleton.



      .. versionadded:: 4.22





   .. attribute:: props.state
      :type: int

      The type of the None singleton.



      .. versionadded:: 4.22





   .. attribute:: props.weight
      :type: float

      The type of the None singleton.



      .. versionadded:: 4.22









Signals
-------

.. rst-class:: interim-class

.. class:: Svg.signals
   :no-index:
   

   .. method:: error(error: ~gi.repository.GLib.GError) -> None

      The type of the None singleton.



      .. versionadded:: 4.22





      :param error: the error