GtkSvg

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 gtk_svg_set_frame_clock() to connect the paintable to a frame clock, and call gtk_svg_play() after loading the SVG. The animation can be paused using gtk_svg_pause().

To set the current state, use 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 GtkSvg::error signal.

For parsing errors in the GTK_SVG_ERROR domain, the functions gtk_svg_error_get_start(), gtk_svg_error_get_end(), gtk_svg_error_get_element() and gtk_svg_error_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, <view> is 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 no interactivity, so links can’t be activated and pseudo-classes like :hover have no effect in CSS.

SVG Extensions

The paintable supports a number of custom attributes 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.

Note that the generated animations are implemented using standard SVG attributes (visibility, stroke-dasharray,stroke-dashoffset,pathLengthandfilter`). 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 StateChange(...) condition in the begin and end attributes of SVG animation elements. For example,

<animate href='path1'
         attributeName='fill'
         begin='StateChange(1 2 3, 0)'
         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 from states 1, 2, or 3.

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

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

will start a fade-out of path1 300ms before a transition from state 0 to 1, 2 or 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'

GtkSvg also allows to refer to symbolic colors like system colors in CSS, with names like SymbolicForeground, SymbolicSuccess, etc. These can be used whenever a color is required.

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

Available since: 4.22