Gtk::Svg Class Reference

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

#include <gtkmm/svg.h>

Inheritance diagram for Gtk::Svg:

Public Types
enum class	Features {   Features::ANIMATIONS = 1 << 0 ,   Features::SYSTEM_RESOURCES = 1 << 1 ,   Features::EXTERNAL_RESOURCES = 1 << 2 ,   Features::EXTENSIONS = 1 << 3 }
	Features of the SVG renderer that can be disabled. More...
Public Types inherited from Glib::Object
typedef void(*)(gpointer data	DestroyNotify)
Public Types inherited from Gdk::Paintable
enum class	Flags {   Flags::STATIC_SIZE = 1 << 0 ,   Flags::STATIC_CONTENTS = 1 << 1 }
	Flags about a paintable object. More...

Public Member Functions
	Svg (Svg && src) noexcept
Svg &	operator= (Svg && src) noexcept
	~Svg () noexcept override
GtkSvg *	gobj ()
	Provides access to the underlying C GObject.
const GtkSvg *	gobj () const
	Provides access to the underlying C GObject.
GtkSvg *	gobj_copy ()
	Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
void	load_from_bytes (const Glib::RefPtr< const Glib::Bytes > & bytes)
	Loads SVG content into an existing SVG paintable.
void	load_from_resource (const std::string & path)
	Loads SVG content into an existing SVG paintable.
Glib::RefPtr< Glib::Bytes >	serialize () const
	Serializes the content of the renderer as SVG.
void	write_to_file (const std::string & filename) const
	Serializes the paintable, and saves the result to a file.
void	set_weight (double weight)
	Sets the weight that is used when rendering.
double	get_weight () const
	Gets the value of the weight property.
void	set_state (unsigned int state)
	Sets the state of the paintable.
unsigned int	get_state () const
	Gets the current state of the paintable.
unsigned int	get_n_states () const
	Gets the number of states defined in the SVG.
void	set_frame_clock (const Glib::RefPtr< Gdk::FrameClock > & clock)
	Sets a frame clock.
void	play ()
	Start playing animations.
void	pause ()
	Stop any playing animations.
void	set_features (Features features)
	Enables or disables features of the SVG paintable.
Features	get_features () const
	Returns the currently enabled features.
Glib::SignalProxy< void(const SvgErrorExtra &)>	signal_error ()
Glib::PropertyProxy< std::string >	property_resource ()
	Resource to load SVG data from.
Glib::PropertyProxy_ReadOnly< std::string >	property_resource () const
	Resource to load SVG data from.
Glib::PropertyProxy< Features >	property_features ()
	Enabled features for this paintable.
Glib::PropertyProxy_ReadOnly< Features >	property_features () const
	Enabled features for this paintable.
Glib::PropertyProxy< bool >	property_playing ()
	Whether the paintable is currently animating its content.
Glib::PropertyProxy_ReadOnly< bool >	property_playing () const
	Whether the paintable is currently animating its content.
Glib::PropertyProxy< double >	property_weight ()
	If not set to -1, this value overrides the weight used when rendering the paintable.
Glib::PropertyProxy_ReadOnly< double >	property_weight () const
	If not set to -1, this value overrides the weight used when rendering the paintable.
Glib::PropertyProxy< unsigned int >	property_state ()
	The current state of the renderer.
Glib::PropertyProxy_ReadOnly< unsigned int >	property_state () const
	The current state of the renderer.
Public Member Functions inherited from Glib::Object
	Object (const Object &)=delete
Object &	operator= (const Object &)=delete
	Object (Object &&src) noexcept
Object &	operator= (Object &&src) noexcept
void *	get_data (const QueryQuark &key)
void	set_data (const Quark &key, void *data)
void	set_data_with_c_callback (const Quark &key, void *data, GDestroyNotify notify)
void	set_data (const Quark &key, void *data, DestroyNotify notify)
void	remove_data (const QueryQuark &quark)
void *	steal_data (const QueryQuark &quark)
Glib::RefPtr< Glib::Object >	wrap (GObject *object, bool take_copy=false)
Public Member Functions inherited from Glib::ObjectBase
	ObjectBase (const ObjectBase &)=delete
ObjectBase &	operator= (const ObjectBase &)=delete
void	set_property_value (const Glib::ustring &property_name, const Glib::ValueBase &value)
void	get_property_value (const Glib::ustring &property_name, Glib::ValueBase &value) const
void	set_property (const Glib::ustring &property_name, const PropertyType &value)
void	get_property (const Glib::ustring &property_name, PropertyType &value) const
PropertyType	get_property (const Glib::ustring &property_name) const
sigc::connection	connect_property_changed (const Glib::ustring &property_name, const sigc::slot< void()> &slot)
sigc::connection	connect_property_changed (const Glib::ustring &property_name, sigc::slot< void()> &&slot)
void	freeze_notify ()
void	thaw_notify ()
virtual void	reference () const
virtual void	unreference () const
GObject *	gobj ()
const GObject *	gobj () const
GObject *	gobj_copy () const
Public Member Functions inherited from Gdk::Paintable
	Paintable (Paintable && src) noexcept
Paintable &	operator= (Paintable && src) noexcept
	~Paintable () noexcept override
GdkPaintable *	gobj ()
	Provides access to the underlying C GObject.
const GdkPaintable *	gobj () const
	Provides access to the underlying C GObject.
void	snapshot (const Glib::RefPtr< Gdk::Snapshot > & snapshot, double width, double height)
	Snapshots the given paintable with the given width and height.
Glib::RefPtr< const Paintable >	get_current_image () const
	Gets an immutable paintable for the current contents displayed by paintable.
Flags	get_flags () const
	Get flags for the paintable.
int	get_intrinsic_width () const
	Gets the preferred width the paintable would like to be displayed at.
int	get_intrinsic_height () const
	Gets the preferred height the paintable would like to be displayed at.
double	get_intrinsic_aspect_ratio () const
	Gets the preferred aspect ratio the paintable would like to be displayed at.
void	compute_concrete_size (double specified_width, double specified_height, double default_width, double default_height, double & concrete_width, double & concrete_height) const
	Compute a concrete size for the Gdk::Paintable.
void	invalidate_contents ()
	Called by implementations of Gdk::Paintable to invalidate their contents.
void	invalidate_size ()
	Called by implementations of Gdk::Paintable to invalidate their size.
Glib::SignalProxy< void()>	signal_invalidate_contents ()
Glib::SignalProxy< void()>	signal_invalidate_size ()
Public Member Functions inherited from Glib::Interface
	Interface ()
	Interface (Interface &&src) noexcept
Interface &	operator= (Interface &&src) noexcept
	Interface (const Glib::Interface_Class &interface_class)
	Interface (GObject *castitem)
	~Interface () noexcept override
	Interface (const Interface &)=delete
Interface &	operator= (const Interface &)=delete
GObject *	gobj ()
const GObject *	gobj () const
Public Member Functions inherited from Gtk::SymbolicPaintable
	SymbolicPaintable (SymbolicPaintable && src) noexcept
SymbolicPaintable &	operator= (SymbolicPaintable && src) noexcept
	~SymbolicPaintable () noexcept override
GtkSymbolicPaintable *	gobj ()
	Provides access to the underlying C GObject.
const GtkSymbolicPaintable *	gobj () const
	Provides access to the underlying C GObject.
void	snapshot_symbolic (const Glib::RefPtr< Gdk::Snapshot > & snapshot, double width, double height, const std::vector< Gdk::RGBA > & colors)
	Snapshots the paintable with the given colors.
void	snapshot_with_weight (const Glib::RefPtr< Gdk::Snapshot > & snapshot, double width, double height, const std::vector< Gdk::RGBA > & colors, double weight)
	Snapshots the paintable with the given colors and weight.

Static Public Member Functions
static GType	get_type ()
	Get the GType for this class, for use with the underlying GObject type system.
static Glib::RefPtr< Svg >	create ()
	Creates a new, empty SVG paintable.
static Glib::RefPtr< Svg >	create (const Glib::RefPtr< const Glib::Bytes > & bytes)
	Parses the SVG data in bytes and creates a paintable.
static Glib::RefPtr< Svg >	create (const std::string & path)
	Parses the SVG data in the resource and creates a paintable.
Static Public Member Functions inherited from Gdk::Paintable
static void	add_interface (GType gtype_implementer)
static GType	get_type ()
	Get the GType for this class, for use with the underlying GObject type system.
Static Public Member Functions inherited from Gtk::SymbolicPaintable
static void	add_interface (GType gtype_implementer)
static GType	get_type ()
	Get the GType for this class, for use with the underlying GObject type system.

Protected Member Functions
	Svg ()
Protected Member Functions inherited from Glib::Object
	Object ()
	Object (const Glib::ConstructParams &construct_params)
	Object (GObject *castitem)
	~Object () noexcept override
Protected Member Functions inherited from Glib::ObjectBase
	ObjectBase ()
	ObjectBase (const char *custom_type_name)
	ObjectBase (const std::type_info &custom_type_info)
	ObjectBase (ObjectBase &&src) noexcept
ObjectBase &	operator= (ObjectBase &&src) noexcept
virtual	~ObjectBase () noexcept=0
void	initialize (GObject *castitem)
void	initialize_move (GObject *castitem, Glib::ObjectBase *previous_wrapper)
Protected Member Functions inherited from Gdk::Paintable
	Paintable ()
	You should derive from this class to use it.
virtual void	snapshot_vfunc (const Glib::RefPtr< Gdk::Snapshot > &snapshot, double width, double height)
virtual Glib::RefPtr< Paintable >	get_current_image_vfunc () const
virtual Flags	get_flags_vfunc () const
virtual int	get_intrinsic_width_vfunc () const
virtual int	get_intrinsic_height_vfunc () const
virtual double	get_intrinsic_aspect_ratio_vfunc () const
Protected Member Functions inherited from Gtk::SymbolicPaintable
	SymbolicPaintable ()
	You should derive from this class to use it.
virtual void	snapshot_symbolic_vfunc (const Glib::RefPtr< Gdk::Snapshot > & snapshot, double width, double height, const std::vector< Gdk::RGBA > & colors)

Related Symbols
(Note that these are not member symbols.)
Glib::RefPtr< Gtk::Svg >	wrap (GtkSvg * object, bool take_copy=false)
	A Glib::wrap() method for this object.
Related Symbols inherited from Gdk::Paintable
Glib::RefPtr< Gdk::Paintable >	wrap (GdkPaintable * object, bool take_copy=false)
	A Glib::wrap() method for this object.
Related Symbols inherited from Gtk::SymbolicPaintable
Glib::RefPtr< Gtk::SymbolicPaintable >	wrap (GtkSymbolicPaintable * object, bool take_copy=false)
	A Glib::wrap() method for this object.

Detailed Description

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

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

The Gtk::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 Gtk::Svg has, use get_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.

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

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>, gradients and shapes are supported, not <filter>, <pattern> or other things.

Gradient templating is not implemented, and radial gradients with fx,fy != cx,cy are not supported.

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 Gtk::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 rendering, connect to signal_error().

For parsing errors in the GTK_SVG_ERROR domain, the functions Gtk::SvgErrorExtra::get_start(), Gtk::SvgErrorExtra::get_end(), Gtk::SvgErrorExtra::get_element() and Gtk::SvgErrorExtra::get_attribute() can be used to obtain information about where the error occurred.

Since gtkmm 4.22

Constructor & Destructor Documentation

Svg() [1/2]

Gtk::Svg::Svg ( Svg && src )

noexcept

~Svg()

Gtk::Svg::~Svg ( )

overridenoexcept

Svg() [2/2]

Gtk::Svg::Svg ( )

protected

Member Function Documentation

create() [1/3]

Glib::RefPtr< Svg > Gtk::Svg::create ( )

static

Creates a new, empty SVG paintable.

create() [2/3]

Glib::RefPtr< Svg > Gtk::Svg::create ( const Glib::RefPtr< const Glib::Bytes > & bytes )

static

Parses the SVG data in bytes and creates a paintable.

Since gtkmm 4.22

Parameters

bytes

The data.

Returns

The paintable.

create() [3/3]

Glib::RefPtr< Svg > Gtk::Svg::create ( const std::string & path )

static

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

Since gtkmm 4.22

Parameters

path	The resource path.

Returns

The paintable.

get_features()

Features Gtk::Svg::get_features

(

)

const

Returns the currently enabled features.

Since gtkmm 4.22

Returns

The enabled features.

get_n_states()

unsigned int Gtk::Svg::get_n_states

(

)

const

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.

Since gtkmm 4.22

Returns

The number of states.

get_state()

unsigned int Gtk::Svg::get_state

(

)

const

Gets the current state of the paintable.

Since gtkmm 4.22

Returns

The state.

get_type()

GType Gtk::Svg::get_type ( )

static

Get the GType for this class, for use with the underlying GObject type system.

get_weight()

double Gtk::Svg::get_weight

(

)

const

Gets the value of the weight property.

Since gtkmm 4.22

Returns

The weight.

gobj() [1/2]

GtkSvg * Gtk::Svg::gobj ( )

inline

Provides access to the underlying C GObject.

gobj() [2/2]

const GtkSvg * Gtk::Svg::gobj ( ) const

inline

Provides access to the underlying C GObject.

gobj_copy()

GtkSvg * Gtk::Svg::gobj_copy

(

)

Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.

load_from_bytes()

void Gtk::Svg::load_from_bytes

(

const Glib::RefPtr< const Glib::Bytes > &

bytes

)

Loads SVG content into an existing SVG paintable.

To track errors while loading SVG content, connect to the signal_error() signal.

This clears any previously loaded content.

Since gtkmm 4.22

Parameters

bytes

The data to load.

load_from_resource()

void Gtk::Svg::load_from_resource

(

const std::string &

path

)

Loads SVG content into an existing SVG paintable.

To track errors while loading SVG content, connect to the signal_error() signal.

This clears any previously loaded content.

Since gtkmm 4.22

Parameters

path	The resource path.

operator=()

Svg & Gtk::Svg::operator= ( Svg && src )

noexcept

pause()

void Gtk::Svg::pause

(

)

Stop any playing animations.

Animations can be paused and started repeatedly.

Since gtkmm 4.22

play()

void Gtk::Svg::play

(

)

Start playing animations.

Note that this is necessary for state changes as well.

Since gtkmm 4.22

property_features() [1/2]

Glib::PropertyProxy< Features > Gtk::Svg::property_features

(

)

Enabled features for this paintable.

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

Since gtkmm 4.22

Default value: Gtk::Svg::Features::ANIMATIONS | Gtk::Svg::Features::SYSTEM_RESOURCES | Gtk::Svg::Features::EXTERNAL_RESOURCES | Gtk::Svg::Features::EXTENSIONS

Returns

A PropertyProxy that allows you to get or set the value of the property, or receive notification when the value of the property changes.

property_features() [2/2]

Glib::PropertyProxy_ReadOnly< Features > Gtk::Svg::property_features

(

)

const

Enabled features for this paintable.

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

Since gtkmm 4.22

Default value: Gtk::Svg::Features::ANIMATIONS | Gtk::Svg::Features::SYSTEM_RESOURCES | Gtk::Svg::Features::EXTERNAL_RESOURCES | Gtk::Svg::Features::EXTENSIONS

Returns

A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

property_playing() [1/2]

Glib::PropertyProxy< bool > Gtk::Svg::property_playing

(

)

Whether the paintable is currently animating its content.

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

Since gtkmm 4.22

Default value: false

Returns

A PropertyProxy that allows you to get or set the value of the property, or receive notification when the value of the property changes.

property_playing() [2/2]

Glib::PropertyProxy_ReadOnly< bool > Gtk::Svg::property_playing

(

)

const

Whether the paintable is currently animating its content.

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

Since gtkmm 4.22

Default value: false

Returns

A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

property_resource() [1/2]

Glib::PropertyProxy< std::string > Gtk::Svg::property_resource

(

)

Resource to load SVG data from.

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

Since gtkmm 4.22

Default value: ""

Returns

A PropertyProxy that allows you to get or set the value of the property, or receive notification when the value of the property changes.

property_resource() [2/2]

Glib::PropertyProxy_ReadOnly< std::string > Gtk::Svg::property_resource

(

)

const

Resource to load SVG data from.

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

Since gtkmm 4.22

Default value: ""

Returns

A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

property_state() [1/2]

Glib::PropertyProxy< unsigned int > Gtk::Svg::property_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.

Since gtkmm 4.22

Default value: 4294967295

Returns

A PropertyProxy that allows you to get or set the value of the property, or receive notification when the value of the property changes.

property_state() [2/2]

Glib::PropertyProxy_ReadOnly< unsigned int > Gtk::Svg::property_state

(

)

const

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.

Since gtkmm 4.22

Default value: 4294967295

Returns

A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

property_weight() [1/2]

Glib::PropertyProxy< double > Gtk::Svg::property_weight

(

)

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

Since gtkmm 4.22

Default value: -1

Returns

A PropertyProxy that allows you to get or set the value of the property, or receive notification when the value of the property changes.

property_weight() [2/2]

Glib::PropertyProxy_ReadOnly< double > Gtk::Svg::property_weight

(

)

const

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

Since gtkmm 4.22

Default value: -1

Returns

A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

serialize()

Glib::RefPtr< Glib::Bytes > Gtk::Svg::serialize

(

)

const

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.

Since gtkmm 4.22

Returns

The serialized contents.

set_features()

void Gtk::Svg::set_features

(

Features

features

)

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.

Since gtkmm 4.22

Parameters

features

Features to enable.

set_frame_clock()

void Gtk::Svg::set_frame_clock

(

const Glib::RefPtr< Gdk::FrameClock > &

clock

)

Sets a frame clock.

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

Since gtkmm 4.22

Parameters

clock

The frame clock.

set_state()

void Gtk::Svg::set_state

(

unsigned int

state

)

Sets the state of the paintable.

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

Since gtkmm 4.22

Parameters

state

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

set_weight()

void Gtk::Svg::set_weight

(

double

weight

)

Sets the weight that is used when rendering.

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

Since gtkmm 4.22

Parameters

weight

The font weight, as a value between -1 and 1000.

signal_error()

Glib::SignalProxy< void(const SvgErrorExtra &)> Gtk::Svg::signal_error

(

)

Slot Prototype:

void on_my_error(const SvgErrorExtra& error)

Flags: Run Last

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.

Since gtkmm 4.22

Parameters

error

The error.

write_to_file()

void Gtk::Svg::write_to_file

(

const std::string &

filename

)

const

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

Since gtkmm 4.22

Parameters

filename

The file to save to.

Exceptions

Glib::Error

Friends And Related Symbol Documentation

wrap()

Glib::RefPtr< Gtk::Svg > wrap ( GtkSvg * object, bool take_copy = false )

related

A Glib::wrap() method for this object.

Parameters

object	The C instance.
take_copy	False if the result should take ownership of the C instance. True if it should take a new copy or ref.

Returns

A C++ instance that wraps this C instance.