Svg#

Added in version 4.22.

class Svg(**properties: Any)#

Superclasses: Object

Implemented Interfaces: Paintable, 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 set_frame_clock to connect the paintable to a frame clock, and call play after loading the SVG. The animation can be paused using pause.

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

For parsing errors in the GTK_SVG_ERROR domain, the functions get_start, get_end, get_element and 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``,``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.

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#

class Svg

classmethod new() → Svg#: Creates a new, empty SVG paintable.

Added in version 4.22.

classmethod new_from_bytes(bytes: Bytes) → Svg#

Parses the SVG data in bytes and creates a paintable.

Added in version 4.22.

Parameters:: bytes – the data

classmethod new_from_resource(path: str) → Svg#

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

Added in version 4.22.

Parameters:: path – the resource path

Methods#

class Svg

get_features() → SvgFeatures#: Returns the currently enabled features.

Added in version 4.22.

get_state() → int#: Gets the current state of the paintable.

Added in version 4.22.

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.

Added in version 4.22.

get_weight() → float#: Gets the value of the weight property.

Added in version 4.22.

load_from_bytes(bytes: Bytes) → None#

Loads SVG content into an existing SVG paintable.

To track errors while loading SVG content, connect to the error signal.

This clears any previously loaded content.

Added in version 4.22.

Parameters:: bytes – the data to load

load_from_resource(path: str) → None#

Loads SVG content into an existing SVG paintable.

To track errors while loading SVG content, connect to the error signal.

This clears any previously loaded content.

Added in version 4.22.

Parameters:: path – the resource path

pause() → None#

Stop any playing animations and state transitions.

Animations can be paused and started repeatedly.

Added in version 4.22.

play() → None#

Start playing animations and state transitions.

Animations can be paused and started repeatedly.

Added in version 4.22.

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

Added in version 4.22.

set_features(features: 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.

Added in version 4.22.

Parameters:: features – features to enable

set_frame_clock(clock: FrameClock) → None#

Sets a frame clock.

Without a frame clock, GtkSvg will not advance animations.

Added in version 4.22.

Parameters:: clock – the frame clock

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.

Added in version 4.22.

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

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.

Added in version 4.22.

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

write_to_file(filename: str) → bool#

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

Added in version 4.22.

Parameters:: filename – the file to save to

Properties#

class Svg

props.features: SvgFeatures#: The type of the None singleton.

Added in version 4.22.

props.playing: bool#: The type of the None singleton.

Added in version 4.22.

props.resource: str#: The type of the None singleton.

Added in version 4.22.

props.state: int#: The type of the None singleton.

Added in version 4.22.

props.weight: float#: The type of the None singleton.

Added in version 4.22.

Signals#

class Svg.signals

error(error: GError) → None#

The type of the None singleton.

Added in version 4.22.

Parameters:: error – the error