Gtk.Svg

Subclasses:

None

Methods

Inherited:

GObject.Object (37), Gdk.Paintable (10), Gtk.SymbolicPaintable (2)

Structs:

GObject.ObjectClass (5)

class	new ()
class	new_from_bytes (bytes)
class	new_from_resource (path)
	get_features ()
	get_n_states ()
	get_state ()
	get_weight ()
	load_from_bytes (bytes)
	load_from_resource (path)
	pause ()
	play ()
	serialize ()
	set_features (features)
	set_frame_clock (clock)
	set_state (state)
	set_weight (weight)
	write_to_file (filename)

Virtual Methods

Inherited:

GObject.Object (7), Gdk.Paintable (6), Gtk.SymbolicPaintable (2)

Properties

Name	Type	Flags	Short Description
features	Gtk.SvgFeatures	r/w/en
playing	bool	r/w/en
resource	str	r/w/en
state	int	r/w/en
weight	float	r/w/en

Signals

Inherited:

GObject.Object (1), Gdk.Paintable (2)

Name	Short Description
error	Signals that an error occurred.

Fields

Inherited:

GObject.Object (1), Gdk.Paintable (2)

Class Details

class Gtk.Svg(**kwargs)

Bases:

GObject.Object, Gdk.Paintable, Gtk.SymbolicPaintable

Abstract:

No

Structure:

Gtk.SvgClass

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 [method`Gtk`.Svg.get_n_states]. To set the current state, use [method`Gtk`.Svg.set_state].

To play the animations in an SVG file, use [method`Gtk`.Svg.set_frame_clock] to connect the paintable to a frame clock, and then use [method`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 rendering, connect to the [signal`Gtk`.Svg::error] signal.

For parsing errors in the GTK_SVG_ERROR domain, the functions [func`Gtk`.SvgError.get_start], [func`Gtk`.SvgError.get_end], [func`Gtk`.SvgError.get_element] and [func`Gtk`.SvgError.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, some notable exceptions.

Among the graphical elements, <textPath> and <foreignObject> are not supported.

Among the structural elements, <a>, <switch> and <view> are not supported.

All filter functions are supported, plus a custom alpha-level() function, which implements one particular case of feComponentTransfer.

In the <filter> element, the following primitives are not supported: feConvolveMatrix, feDiffuseLighting, feMorphology, feSpecularLighting and feTurbulence.

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

<image src=”svg-renderer1.svg”>

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.

<image src=”svg-renderer2.svg”>

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

New in version 4.22.

classmethod new()

Returns:

the paintable

Return type:

Gtk.Svg

Creates a new, empty SVG paintable.

New in version 4.22.

classmethod new_from_bytes(bytes)

Parameters:

bytes (GLib.Bytes) – the data

Returns:

the paintable

Return type:

Gtk.Svg

Parses the SVG data in bytes and creates a paintable.

New in version 4.22.

classmethod new_from_resource(path)

Parameters:

path (str) – the resource path

Returns:

the paintable

Return type:

Gtk.Svg

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

New in version 4.22.

get_features()

Returns:

the enabled features

Return type:

Gtk.SvgFeatures

Returns the currently enabled features.

New in version 4.22.

get_n_states()

Returns:

the number of states

Return type:

int

Gets the number of states defined in the SVG.

Note that there is always an empty state, which does not count towards this number. If this function returns the value N, the meaningful states of the SVG are 0, 1, …, N - 1 and GTK_SVG_STATE_EMPTY.

New in version 4.22.

get_state()

Returns:

the state

Return type:

int

Gets the current state of the paintable.

New in version 4.22.

get_weight()

Returns:

the weight

Return type:

float

Gets the value of the weight property.

New in version 4.22.

load_from_bytes(bytes)

Parameters:

bytes (GLib.Bytes) – the data to load

Loads SVG content into an existing SVG paintable.

To track errors while loading SVG content, connect to the [signal`Gtk`.Svg::error] signal.

This clears any previously loaded content.

New in version 4.22.

load_from_resource(path)

Parameters:

path (str) – the resource path

Loads SVG content into an existing SVG paintable.

To track errors while loading SVG content, connect to the [signal`Gtk`.Svg::error] signal.

This clears any previously loaded content.

New in version 4.22.

pause()

Stop any playing animations.

Animations can be paused and started repeatedly.

New in version 4.22.

play()

Start playing animations.

Note that this is necessary for state changes as well.

New in version 4.22.

serialize()

Returns:

the serialized contents

Return type:

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

New in version 4.22.

set_features(features)

Parameters:

features (Gtk.SvgFeatures) – features to enable

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.

New in version 4.22.

set_frame_clock(clock)

Parameters:

clock (Gdk.FrameClock) – the frame clock

Sets a frame clock.

Without a frame clock, GTK has to rely on simple timeouts to run animations.

New in version 4.22.

set_state(state)

Parameters:

state (int) – the state to set, as a value between 0 and 63, or (unsigned int) -1

Sets the state of the paintable.

Use [method`Gtk`.Svg.get_n_states] to find out what states self has.

Note that [method`Gtk`.Svg.play] must have been called for the SVG paintable to react to state changes.

New in version 4.22.

set_weight(weight)

Parameters:

weight (float) – the font weight, as a value between -1 and 1000

Sets the weight that is used when rendering.

The default value of -1 means to use the font weight from CSS.

New in version 4.22.

write_to_file(filename)

Parameters:

filename (str) – the file to save to

Raises:

GLib.Error

Returns:

true, unless an error occurred

Return type:

bool

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

New in version 4.22.

Signal Details

Gtk.Svg.signals.error(svg, error)

Signal Name:

error

Flags:

RUN_LAST

Parameters:

• svg (Gtk.Svg) – The object which received the signal

• error (GLib.Error) – the error

Signals that an error occurred.

Errors can occur both during parsing and during rendering.

The expected error values are in the [error`Gtk`.SvgError] enumeration, context information about the location of parsing errors can be obtained with the various gtk_svg_error functions.

Parsing errors are never fatal, so the parsing will resume after the error. Errors may however cause parts of the given data or even all of it to not be parsed at all. So it is a useful idea to check that the parsing succeeds by connecting to this signal.

::: note This signal is emitted in the middle of parsing or rendering, and if you handle it, you must be careful. Logging the errors you receive is fine, but modifying the widget hierarchy or changing the paintable state definitively isn’t.

If in doubt, defer to an idle.

New in version 4.22.

Property Details

Gtk.Svg.props.features

Name:

features

Type:

Gtk.SvgFeatures

Default Value:

Gtk.SvgFeatures.ANIMATIONS | Gtk.SvgFeatures.SYSTEM_RESOURCES | Gtk.SvgFeatures.EXTERNAL_RESOURCES | Gtk.SvgFeatures.EXTENSIONS

Flags:

READABLE, WRITABLE, EXPLICIT_NOTIFY

Enabled features for this paintable.

Note that features have to be set before loading SVG data to take effect.

New in version 4.22.

Gtk.Svg.props.playing

Name:

playing

Type:

bool

Default Value:

False

Flags:

READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether the paintable is currently animating its content.

To set this property, use the [method`Gtk`.Svg.play] and [method`Gtk`.Svg.pause] functions.

New in version 4.22.

Gtk.Svg.props.resource

Name:

resource

Type:

str

Default Value:

None

Flags:

READABLE, WRITABLE, EXPLICIT_NOTIFY

Resource to load SVG data from.

This property is meant to create a paintable from a resource in ui files.

New in version 4.22.

Gtk.Svg.props.state

Name:

state

Type:

int

Default Value:

4294967295

Flags:

READABLE, WRITABLE, EXPLICIT_NOTIFY

The current state of the renderer.

This can be a number between 0 and 63, or the special value (unsigned int) -1 to indicate the ‘empty’ state in which nothing is drawn.

New in version 4.22.

Gtk.Svg.props.weight

Name:

weight

Type:

float

Default Value:

-1.0

Flags:

READABLE, WRITABLE, EXPLICIT_NOTIFY

If not set to -1, this value overrides the weight used when rendering the paintable.

New in version 4.22.