Struct Svg 

pub struct Svg { /* private fields */ }

Available on crate feature v4_22 only.

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

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

The Svg 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 Svg has, use n_states(). To set the current state, use set_state().

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

Error handling

Loading an SVG into Svg 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 error signal.

For parsing errors in the GTK_SVG_ERROR domain, the functions Gtk::SvgError::get_start(), Gtk::SvgError::get_end(), Gtk::SvgError::get_element() and Gtk::SvgError::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>.

Properties

playing

Whether the paintable is currently animating its content.

To set this property, use the Svg::play() and Svg::pause() functions.

Readable | Writeable

resource

Construct-only property to create a paintable from a resource in ui files.

Writeable | Construct Only

state

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.

Readable | Writeable

weight

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

Readable | Writeable

Signals

error

Signals that an error occurred.

Errors can occur both during parsing and during rendering.

The expected error values are in the 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.

Paintable

invalidate-contents

Emitted when the contents of the @paintable change.

Examples for such an event would be videos changing to the next frame or the icon theme for an icon changing.

invalidate-size

Emitted when the intrinsic size of the @paintable changes.

This means the values reported by at least one of [PaintableExtManual::intrinsic_width()][crate::gdk::prelude::PaintableExtManual::intrinsic_width()], [PaintableExtManual::intrinsic_height()][crate::gdk::prelude::PaintableExtManual::intrinsic_height()] or [PaintableExtManual::intrinsic_aspect_ratio()][crate::gdk::prelude::PaintableExtManual::intrinsic_aspect_ratio()] has changed.

Examples for such an event would be a paintable displaying the contents of a toplevel surface being resized.

Implements

[trait@glib::ObjectExt], gdk::prelude::PaintableExt, SymbolicPaintableExt

GLib type: GObject with reference counted clone semantics.

Implementations

impl Svg

pub fn new() -> Svg

Creates a new, empty SVG paintable.

Returns

the paintable

pub fn from_bytes(bytes: &Bytes) -> Svg

Parses the SVG data in @bytes and creates a paintable.

bytes

the data

Returns

the paintable

pub fn from_resource(path: &str) -> Svg

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

path

the resource path

Returns

the paintable

pub fn n_states(&self) -> u32

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.

Returns

the number of states

pub fn state(&self) -> u32

Gets the current state of the paintable.

Returns

the state

pub fn weight(&self) -> f64

Gets the value of the weight property.

Returns

the weight

pub fn load_from_bytes(&self, bytes: &Bytes)

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.

bytes

the data to load

pub fn pause(&self)

Stop any playing animations.

Animations can be paused and started repeatedly.

pub fn play(&self)

Start playing animations.

Note that this is necessary for state changes as well.

pub fn serialize(&self) -> 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.

Returns

the serialized contents

pub fn set_frame_clock(&self, clock: &FrameClock)

Sets a frame clock.

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

clock

the frame clock

pub fn set_state(&self, state: u32)

Sets the state of the paintable.

Use n_states() to find out what states @self has.

Note that play() must have been called for the SVG paintable to react to state changes.

state

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

pub fn set_weight(&self, weight: f64)

Sets the weight that is used when rendering.

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

weight

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

pub fn write_to_file(&self, filename: &str) -> Result<(), Error>

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

filename

the file to save to

Returns

true, unless an error occurred

pub fn is_playing(&self) -> bool

Whether the paintable is currently animating its content.

To set this property, use the play() and pause() functions.

pub fn set_playing(&self, playing: bool)

Whether the paintable is currently animating its content.

To set this property, use the play() and pause() functions.

pub fn connect_error<F: Fn(&Self, &Error) + 'static>( &self, f: F, ) -> SignalHandlerId

Signals that an error occurred.

Errors can occur both during parsing and during rendering.

The expected error values are in the 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.

error

the error

pub fn connect_playing_notify<F: Fn(&Self) + 'static>( &self, f: F, ) -> SignalHandlerId

pub fn connect_state_notify<F: Fn(&Self) + 'static>( &self, f: F, ) -> SignalHandlerId

pub fn connect_weight_notify<F: Fn(&Self) + 'static>( &self, f: F, ) -> SignalHandlerId

Trait Implementations

impl Clone for Svg

fn clone(&self) -> Self

Makes a clone of this shared reference.

This increments the strong reference count of the object. Dropping the object will decrement it again.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Svg

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Svg

fn default() -> Self

Returns the “default value” for a type.

impl HasParamSpec for Svg

type ParamSpec = ParamSpecObject

type SetValue = Svg

Preferred value to be used as setter for the associated ParamSpec.

type BuilderFn = fn(&str) -> ParamSpecObjectBuilder<'_, Svg>

fn param_spec_builder() -> Self::BuilderFn

impl Hash for Svg

fn hash<H>(&self, state: &mut H)

where H: Hasher,

Hashes the memory address of this object.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Svg

fn cmp(&self, other: &Self) -> Ordering

Comparison for two GObjects.

Compares the memory addresses of the provided objects.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl ParentClassIs for Svg

type Parent = Object

impl<OT: ObjectType> PartialEq<OT> for Svg

fn eq(&self, other: &OT) -> bool

Equality for two GObjects.

Two GObjects are equal if their memory addresses are equal.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<OT: ObjectType> PartialOrd<OT> for Svg

fn partial_cmp(&self, other: &OT) -> Option<Ordering>

Partial comparison for two GObjects.

Compares the memory addresses of the provided objects.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl StaticType for Svg

fn static_type() -> Type

Returns the type identifier of Self.

impl Eq for Svg

impl IsA<Paintable> for Svg

impl IsA<SymbolicPaintable> for Svg