GtkSvg

A paintable implementation that renders (a subset of) SVG, with animations.

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

The 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 animation, and the transition between different states can also be animated.

To find out what states a GtkSvg has, use gtk_svg_get_n_states(). To set the current state, use gtk_svg_set_state().

To play the animations in an SVG file, use gtk_svg_set_frame_clock() to connect the paintable to a frame clock, and then use gtk_svg_play() to start the animation.

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 rednering, 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 does not support text or images, only shapes and paths.

In <defs>, only <clipPath>, <mask>, gradients and shapes are supported, not <filter>, <pattern> or other things.

Gradient templating is not implemented.

The support for filters is limited to filter functions minus drop-shadow() plus a custom alpha-level() function, which implements one particular case of feComponentTransfer.

The transform-origin and transform-box attributes are not supported.

The 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 by, min and max attributes are not supported.

Lastly, there is no CSS support, 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 assume a pathLengh value of 1. Setting pathLength 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 gpa:fill and gpa:stroke, 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