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. The special ‘empty’ state is always available. 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 find out what states a GtkSvg has, use gtk_svg_get_n_states(). 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, <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 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 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.

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.

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>.

Available since: 4.22