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

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.

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.

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

The supported subset of SVG

The renderer does not support text or images, only paths. From the shape elements of SVG, only <circle>, <ellipse>, <rect> and <path> are supported, leaving out <line>, <polyline> and <polygon>.

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

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.

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, connect to the GtkSvg::error signal.

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

Available since: 4.22