Copyright	Will Thompson and Iñaki García Etxebarria
License	LGPL-2.1
Maintainer	Iñaki García Etxebarria
Safe Haskell	None
Language	Haskell2010

GI.Gtk.Objects.Svg

Contents

Exported types
Methods
Properties
Signals
- error

Description

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 svgGetNStates. To set the current state, use svgSetState.

To play the animations in an SVG file, use svgSetFrameClock to connect the paintable to a frame clock, and then use svgPlay 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 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 rednering, connect to the Svg::error signal.

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

Since: 4.22

Synopsis

newtype Svg = Svg (ManagedPtr Svg)
class (GObject o, IsDescendantOf Svg o) => IsSvg o
toSvg :: (MonadIO m, IsSvg o) => o -> m Svg
svgGetNStates :: (HasCallStack, MonadIO m, IsSvg a) => a -> m Word32
svgGetState :: (HasCallStack, MonadIO m, IsSvg a) => a -> m Word32
svgGetWeight :: (HasCallStack, MonadIO m, IsSvg a) => a -> m Double
svgLoadFromBytes :: (HasCallStack, MonadIO m, IsSvg a) => a -> Bytes -> m ()
svgNew :: (HasCallStack, MonadIO m) => m Svg
svgNewFromBytes :: (HasCallStack, MonadIO m) => Bytes -> m Svg
svgNewFromResource :: (HasCallStack, MonadIO m) => Text -> m Svg
svgPause :: (HasCallStack, MonadIO m, IsSvg a) => a -> m ()
svgPlay :: (HasCallStack, MonadIO m, IsSvg a) => a -> m ()
svgSerialize :: (HasCallStack, MonadIO m, IsSvg a) => a -> m Bytes
svgSetFrameClock :: (HasCallStack, MonadIO m, IsSvg a, IsFrameClock b) => a -> b -> m ()
svgSetState :: (HasCallStack, MonadIO m, IsSvg a) => a -> Word32 -> m ()
svgSetWeight :: (HasCallStack, MonadIO m, IsSvg a) => a -> Double -> m ()
svgWriteToFile :: (HasCallStack, MonadIO m, IsSvg a) => a -> Text -> m ()
constructSvgPlaying :: (IsSvg o, MonadIO m) => Bool -> m (GValueConstruct o)
getSvgPlaying :: (MonadIO m, IsSvg o) => o -> m Bool
setSvgPlaying :: (MonadIO m, IsSvg o) => o -> Bool -> m ()
constructSvgResource :: (IsSvg o, MonadIO m) => Text -> m (GValueConstruct o)
constructSvgState :: (IsSvg o, MonadIO m) => Word32 -> m (GValueConstruct o)
getSvgState :: (MonadIO m, IsSvg o) => o -> m Word32
setSvgState :: (MonadIO m, IsSvg o) => o -> Word32 -> m ()
constructSvgWeight :: (IsSvg o, MonadIO m) => Double -> m (GValueConstruct o)
getSvgWeight :: (MonadIO m, IsSvg o) => o -> m Double
setSvgWeight :: (MonadIO m, IsSvg o) => o -> Double -> m ()
type SvgErrorCallback = GError -> IO ()
afterSvgError :: (IsSvg a, MonadIO m) => a -> ((?self :: a) => SvgErrorCallback) -> m SignalHandlerId
onSvgError :: (IsSvg a, MonadIO m) => a -> ((?self :: a) => SvgErrorCallback) -> m SignalHandlerId

Exported types

newtype Svg Source #

Memory-managed wrapper type.

Constructors

Svg (ManagedPtr Svg)

Instances

Instances details

Eq Svg Source #
Instance details Defined in GI.Gtk.Objects.Svg Methods (==) :: Svg -> Svg -> Bool (/=) :: Svg -> Svg -> Bool
GObject Svg Source #
Instance details Defined in GI.Gtk.Objects.Svg
ManagedPtrNewtype Svg Source #
Instance details Defined in GI.Gtk.Objects.Svg Methods toManagedPtr :: Svg -> ManagedPtr Svg #
TypedObject Svg Source #
Instance details Defined in GI.Gtk.Objects.Svg Methods glibType :: IO GType #
HasParentTypes Svg Source #
Instance details Defined in GI.Gtk.Objects.Svg
IsGValue (Maybe Svg) Source #	Convert `Svg` to and from `GValue`. See `toGValue` and `fromGValue`.
Instance details Defined in GI.Gtk.Objects.Svg Methods gvalueGType_ :: IO GType # gvalueSet_ :: Ptr GValue -> Maybe Svg -> IO () # gvalueGet_ :: Ptr GValue -> IO (Maybe Svg) #
type ParentTypes Svg Source #
Instance details Defined in GI.Gtk.Objects.Svg type ParentTypes Svg = '[Object, Paintable, SymbolicPaintable]

class (GObject o, IsDescendantOf Svg o) => IsSvg o Source #

Type class for types which can be safely cast to Svg, for instance with toSvg.

Instances

Instances details

(GObject o, IsDescendantOf Svg o) => IsSvg o Source #
Instance details Defined in GI.Gtk.Objects.Svg

toSvg :: (MonadIO m, IsSvg o) => o -> m Svg Source #

Cast to Svg, for types for which this is known to be safe. For general casts, use castTo.

Methods

Click to display all available methods, including inherited ones

Expand

getNStates

svgGetNStates Source #

Arguments

:: (HasCallStack, MonadIO m, IsSvg a)
=> a	`self`: an SVG paintable
-> m Word32	Returns: the number of states

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: 4.22

getState

svgGetState Source #

Arguments

:: (HasCallStack, MonadIO m, IsSvg a)
=> a	`self`: an SVG paintable
-> m Word32	Returns: the state

Gets the current state of the paintable.

Since: 4.22

getWeight

svgGetWeight Source #

Arguments

:: (HasCallStack, MonadIO m, IsSvg a)
=> a	`self`: an SVG paintable
-> m Double	Returns: the weight

Gets the value of the weight property.

Since: 4.22

loadFromBytes

svgLoadFromBytes Source #

Arguments

:: (HasCallStack, MonadIO m, IsSvg a)
=> a	`self`: an SVG paintable
-> Bytes	`bytes`: the data to load
-> m ()

Loads SVG content into an existing SVG paintable.

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

This clears any previously loaded content.

Since: 4.22

new

svgNew Source #

Arguments

:: (HasCallStack, MonadIO m)
=> m Svg	Returns: the paintable

Creates a new, empty SVG paintable.

Since: 4.22

newFromBytes

svgNewFromBytes Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Bytes	`bytes`: the data
-> m Svg	Returns: the paintable

Parses the SVG data in bytes and creates a paintable.

Since: 4.22

newFromResource

svgNewFromResource Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`path`: the resource path
-> m Svg	Returns: the paintable

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

Since: 4.22

pause

svgPause Source #

Arguments

:: (HasCallStack, MonadIO m, IsSvg a)
=> a	`self`: an SVG paintable
-> m ()

Stop any playing animations.

Animations can be paused and started repeatedly.

Since: 4.22

play

svgPlay Source #

Arguments

:: (HasCallStack, MonadIO m, IsSvg a)
=> a	`self`: an SVG paintable
-> m ()

Start playing animations.

Note that this is necessary for state changes as well.

Since: 4.22

serialize

svgSerialize Source #

Arguments

:: (HasCallStack, MonadIO m, IsSvg a)
=> a	`self`: an SVG paintable
-> m Bytes	Returns: the serialized contents

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: 4.22

setFrameClock

svgSetFrameClock Source #

Arguments

:: (HasCallStack, MonadIO m, IsSvg a, IsFrameClock b)
=> a	`self`: an SVG paintable
-> b	`clock`: the frame clock
-> m ()

Sets a frame clock.

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

Since: 4.22

setState

svgSetState Source #

Arguments

:: (HasCallStack, MonadIO m, IsSvg a)
=> a	`self`: an SVG paintable
-> Word32	`state`: the state to set, as a value between 0 and 63, or `(unsigned int) -1`
-> m ()

Sets the state of the paintable.

Use svgGetNStates to find out what states self has.

Note that svgPlay must have been called for the SVG paintable to react to state changes.

Since: 4.22

setWeight

svgSetWeight Source #

Arguments

:: (HasCallStack, MonadIO m, IsSvg a)
=> a	`self`: an SVG paintable
-> Double	`weight`: the font weight, as a value between -1 and 1000
-> m ()

Sets the weight that is used when rendering.

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

Since: 4.22

writeToFile

svgWriteToFile Source #

Arguments

:: (HasCallStack, MonadIO m, IsSvg a)
=> a	`self`: an SVG paintable
-> Text	`filename`: the file to save to
-> m ()	(Can throw `GError`)

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

Since: 4.22

Properties

playing

Whether the paintable is currently animating its content.

To set this property, use the svgPlay and svgPause functions.

Since: 4.22

constructSvgPlaying :: (IsSvg o, MonadIO m) => Bool -> m (GValueConstruct o) Source #

Construct a GValueConstruct with valid value for the “playing” property. This is rarely needed directly, but it is used by new.

getSvgPlaying :: (MonadIO m, IsSvg o) => o -> m Bool Source #

Get the value of the “playing” property. When overloading is enabled, this is equivalent to

get svg #playing

setSvgPlaying :: (MonadIO m, IsSvg o) => o -> Bool -> m () Source #

Set the value of the “playing” property. When overloading is enabled, this is equivalent to

set svg [ #playing := value ]

resource

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

Since: 4.22

constructSvgResource :: (IsSvg o, MonadIO m) => Text -> m (GValueConstruct o) Source #

Construct a GValueConstruct with valid value for the “resource” property. This is rarely needed directly, but it is used by new.

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: 4.22

constructSvgState :: (IsSvg o, MonadIO m) => Word32 -> m (GValueConstruct o) Source #

Construct a GValueConstruct with valid value for the “state” property. This is rarely needed directly, but it is used by new.

getSvgState :: (MonadIO m, IsSvg o) => o -> m Word32 Source #

Get the value of the “state” property. When overloading is enabled, this is equivalent to

get svg #state

setSvgState :: (MonadIO m, IsSvg o) => o -> Word32 -> m () Source #

Set the value of the “state” property. When overloading is enabled, this is equivalent to

set svg [ #state := value ]

weight

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

Since: 4.22

constructSvgWeight :: (IsSvg o, MonadIO m) => Double -> m (GValueConstruct o) Source #

Construct a GValueConstruct with valid value for the “weight” property. This is rarely needed directly, but it is used by new.

getSvgWeight :: (MonadIO m, IsSvg o) => o -> m Double Source #

Get the value of the “weight” property. When overloading is enabled, this is equivalent to

get svg #weight

setSvgWeight :: (MonadIO m, IsSvg o) => o -> Double -> m () Source #

Set the value of the “weight” property. When overloading is enabled, this is equivalent to

set svg [ #weight := value ]

Signals

error

type SvgErrorCallback Source #

Arguments

= GError	`error`: the error
-> IO ()

Signals that an error occurred.

Errors can occur both during parsing and during rendering.

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

afterSvgError :: (IsSvg a, MonadIO m) => a -> ((?self :: a) => SvgErrorCallback) -> m SignalHandlerId Source #

Connect a signal handler for the error signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after svg #error callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onSvgError :: (IsSvg a, MonadIO m) => a -> ((?self :: a) => SvgErrorCallback) -> m SignalHandlerId Source #

Connect a signal handler for the error signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on svg #error callback

SVG Extensions

The supported subset of SVG

Error handling

Exported types

Instances

Instances

Methods

Click to display all available methods, including inherited ones

Methods

Getters

Setters

getNStates

getState

getWeight

loadFromBytes

new

newFromBytes

newFromResource

pause

play

serialize

setFrameClock

setState

setWeight

writeToFile

Properties

playing

resource

state

weight

Signals

error