Svg

Object Hierarchy:

Description:

[ CCode ( type_id = "gtk_svg_get_type ()" ) ]
[ Version ( since = "4.22" ) ]
public sealed class Svg : Object, 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 [method@Gtk.Svg.set_frame_clock] to connect the paintable to a frame clock, and call [method@Gtk.Svg.play] after loading the SVG. The animation can be paused using [method@Gtk.Svg.pause].

To set the current state, use [method@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 [signal@Gtk.Svg:GtkSvg: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, 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](icon-format.html) that offer a convenient way to define states, transitions and animations. For example,

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,

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,

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:

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

Namespace: Gtk

Package: gtk4

Content:

Properties:

public SvgFeatures features { get; set; }
Enabled features for this paintable.
public bool playing { get; set; }
Whether the paintable is currently animating its content.
public string resource { owned get; set; }
Resource to load SVG data from.
public uint state { get; set; }
The current state of the renderer.
public double weight { get; set; }
If not set to -1, this value overrides the weight used when rendering the paintable.

Creation methods:

public Svg ()
Creates a new, empty SVG paintable.
public Svg.from_bytes (Bytes bytes)
Parses the SVG data in bytes and creates a paintable.
public Svg.from_resource (string path)
Parses the SVG data in the resource and creates a paintable.

Methods:

public SvgFeatures get_features ()
Returns the currently enabled features.
public uint get_state ()
Gets the current state of the paintable.
public unowned string[]? get_state_names (out uint length)
Returns a `NULL`-terminated array of state names, if available.
public double get_weight ()
Gets the value of the weight property.
public void load_from_bytes (Bytes bytes)
Loads SVG content into an existing SVG paintable.
public void load_from_resource (string path)
Loads SVG content into an existing SVG paintable.
public void pause ()
Stop any playing animations and state transitions.
public void play ()
Start playing animations and state transitions.
public Bytes serialize ()
Serializes the content of the renderer as SVG.
public void set_features (SvgFeatures features)
Enables or disables features of the SVG paintable.
public void set_frame_clock (FrameClock clock)
Sets a frame clock.
public void set_state (uint state)
Sets the state of the paintable.
public void set_weight (double weight)
Sets the weight that is used when rendering.
public bool write_to_file (string filename) throws Error
Serializes the paintable, and saves the result to a file.

Signals:

public signal void error (Error error)
Signals that an error occurred.

Inherited Members:

All known members inherited from class GLib.Object

All known members inherited from interface Gdk.Paintable

All known members inherited from interface Gtk.SymbolicPaintable

snapshot_symbolic

snapshot_with_weight