A paintable implementation that renders (a subset of) SVG, with animations. More...
#include <gtkmm/svg.h>
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 sigc::trackable | |
| typedef internal::func_destroy_notify | func_destroy_notify |
| Public Types inherited from sigc::notifiable | |
| typedef internal::func_destroy_notify | func_destroy_notify |
| 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... | |
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. | |
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,
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,
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.
Constructor & Destructor Documentation
◆ Svg() [1/2]
|
noexcept |
◆ ~Svg()
|
overridenoexcept |
◆ Svg() [2/2]
|
protected |
Member Function Documentation
◆ create() [1/3]
|
static |
Creates a new, empty SVG paintable.
◆ create() [2/3]
|
static |
Parses the SVG data in bytes and creates a paintable.
- Parameters
-
bytes The data.
- Returns
- The paintable.
◆ create() [3/3]
|
static |
Parses the SVG data in the resource and creates a paintable.
- Parameters
-
path The resource path.
- Returns
- The paintable.
◆ get_features()
| Features Gtk::Svg::get_features | ( | ) | const |
◆ 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.
- Returns
- The number of states.
◆ get_state()
| unsigned int Gtk::Svg::get_state | ( | ) | const |
◆ 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 |
◆ gobj() [1/2]
|
inline |
Provides access to the underlying C GObject.
◆ gobj() [2/2]
◆ 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.
- 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.
- Parameters
-
path The resource path.
◆ operator=()
◆ pause()
| void Gtk::Svg::pause | ( | ) |
◆ play()
| void Gtk::Svg::play | ( | ) |
◆ 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
- Returns
- The serialized contents.
◆ set_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.
- 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.
- Parameters
-
clock The frame clock.
◆ set_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.
- Parameters
-
state The state to set, as a value between 0 and 63, or (unsigned int) -1.
◆ set_weight()
Sets the weight that is used when rendering.
The default value of -1 means to use the font weight from CSS.
- 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.
- 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.
- Parameters
-
filename The file to save to.
- Exceptions
-
Glib::Error
Friends And Related Symbol Documentation
◆ wrap()
|
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.
