Copyright | Will Thompson and Iñaki García Etxebarria |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria |
Safe Haskell | Safe-Inferred |
Language | Haskell2010 |
- Exported types
- Methods
- close
- free
- getBaseUri
- getDesc
- getDimensions
- getDimensionsSub
- getGeometryForElement
- getGeometryForLayer
- getIntrinsicDimensions
- getIntrinsicSizeInPixels
- getMetadata
- getPixbuf
- getPixbufSub
- getPositionSub
- getTitle
- hasSub
- internalSetTesting
- new
- newFromData
- newFromFile
- newFromGfileSync
- newFromStreamSync
- newWithFlags
- readStreamSync
- renderCairo
- renderCairoSub
- renderDocument
- renderElement
- renderLayer
- setBaseGfile
- setBaseUri
- setDpi
- setDpiXY
- setSizeCallback
- setStylesheet
- write
- Properties
Handle
loads an SVG document into memory.
This is the main entry point into the librsvg library. An Handle
is an
object that represents SVG data in memory. Your program creates an
Handle
from an SVG file, or from a memory buffer that contains SVG data,
or in the most general form, from a GInputStream
that will provide SVG data.
Librsvg can load SVG images and render them to Cairo surfaces, using a mixture of SVG's [static mode] and [secure static mode]. Librsvg does not do animation nor scripting, and can load references to external data only in some situations; see below.
Librsvg supports reading SVG 1.1 data, and is gradually adding support for features in SVG 2. Librsvg also supports SVGZ files, which are just an SVG stream compressed with the GZIP algorithm.
- static mode
- https://www.w3.org/TR/SVG2/conform.html
static
-mode - secure static mode
- https://www.w3.org/TR/SVG2/conform.html
secure
-static-mode
The "base file" and resolving references to external files
When you load an SVG, librsvg needs to know the location of the "base file"
for it. This is so that librsvg can determine the location of referenced
entities. For example, say you have an SVG in /foo/bar/foo.svg
and that it has an image element like this:
<image href="resources/foo.png" .../>
In this case, librsvg needs to know the location of the toplevel
/foo/bar/foo.svg
so that it can generate the appropriate
reference to /foo/bar/resources/foo.png
.
Security and locations of referenced files
When processing an SVG, librsvg will only load referenced files if they are
in the same directory as the base file, or in a subdirectory of it. That is,
if the base file is /foo/bar/baz.svg
, then librsvg will
only try to load referenced files (from SVG's
<image>
element, for example, or from content
included through XML entities) if those files are in /foo/bar/<anything>
or in /foo/bar/<anything>\/.../<anything>
.
This is so that malicious SVG files cannot include files that are in a directory above.
The full set of rules for deciding which URLs may be loaded is as follows; they are applied in order. A referenced URL will not be loaded as soon as one of these rules fails:
- All
data:
URLs may be loaded. These are sometimes used to include raster image data, encoded as base-64, directly in an SVG file. - All other URL schemes in references require a base URL. For
example, this means that if you load an SVG with
handleNewFromData
without callinghandleSetBaseUri
, then any referenced files will not be allowed (e.g. raster images to be loaded from other files will not work). - If referenced URLs are absolute, rather than relative, then they must
have the same scheme as the base URL. For example, if the base URL has a
file
scheme, then all URL references inside the SVG must also have thefile
scheme, or be relative references which will be resolved against the base URL. - If referenced URLs have a
resource
scheme, that is, if they are included into your binary program with GLib's resource mechanism, they are allowed to be loaded (provided that the base URL is also aresource
, per the previous rule). - Otherwise, non-
file
schemes are not allowed. For example, librsvg will not loadhttp
resources, to keep malicious SVG data from "phoning home". - A relative URL must resolve to the same directory as the base URL, or to one of its subdirectories. Librsvg will canonicalize filenames, by removing ".." path components and resolving symbolic links, to decide whether files meet these conditions.
Loading an SVG with GIO
This is the easiest and most resource-efficient way of loading SVG data into
an Handle
.
If you have a GFile
that stands for an SVG file, you can simply call
handleNewFromGfileSync
to load an Handle
from it.
Alternatively, if you have a GInputStream
, you can use
handleNewFromStreamSync
.
Both of those methods allow specifying a GCancellable
, so the loading
process can be cancelled from another thread.
Loading an SVG from memory
If you already have SVG data in a byte buffer in memory, you can create a
memory input stream with memoryInputStreamNewFromData
and feed that
to handleNewFromStreamSync
.
Note that in this case, it is important that you specify the base_file for the in-memory SVG data. Librsvg uses the base_file to resolve links to external content, like raster images.
Loading an SVG without GIO
You can load an Handle
from a simple filename or URI with
handleNewFromFile
. Note that this is a blocking operation; there
is no way to cancel it if loading a remote URI takes a long time. Also, note that
this method does not let you specify [flagsrsvg
.HandleFlags].
Otherwise, loading an SVG without GIO is not recommended, since librsvg will
need to buffer your entire data internally before actually being able to
parse it. The deprecated way of doing this is by creating a handle with
handleNew
or handleNewWithFlags
, and then using
handleWrite
and handleClose
to feed the handle with SVG data.
Still, please try to use the GIO stream functions instead.
Resolution of the rendered image (dots per inch, or DPI)
SVG images can contain dimensions like "5cm
" or
"2pt
" that must be converted from physical units into
device units. To do this, librsvg needs to know the actual dots per inch
(DPI) of your target device. You can call handleSetDpi
or
handleSetDpiXY
on an Handle
to set the DPI before rendering
it.
Rendering
The preferred way to render a whole SVG document is to use
handleRenderDocument
. Please see its documentation for
details.
API ordering
Due to the way the librsvg API evolved over time, an Handle
object is available
for use as soon as it is constructed. However, not all of its methods can be
called at any time. For example, an Handle
just constructed with handleNew
is not loaded yet, and it does not make sense to call handleRenderDocument
on it
just at that point.
The documentation for the available methods in Handle
may mention that a particular
method is only callable on a "fully loaded handle". This means either:
- The handle was loaded with
handleWrite
andhandleClose
, and those functions returned no errors. - The handle was loaded with
handleReadStreamSync
and that function returned no errors.
Before librsvg 2.46, the library did not fully verify that a handle was in a
fully loaded state for the methods that require it. To preserve
compatibility with old code which inadvertently called the API without
checking for errors, or which called some methods outside of the expected
order, librsvg will just emit a g_critical()
message in those cases.
New methods introduced in librsvg 2.46 and later will check for the correct ordering, and panic if they are called out of order. This will abort the program as if it had a failed assertion.
Synopsis
- newtype Handle = Handle (ManagedPtr Handle)
- class (GObject o, IsDescendantOf Handle o) => IsHandle o
- toHandle :: (MonadIO m, IsHandle o) => o -> m Handle
- handleClose :: (HasCallStack, MonadIO m, IsHandle a) => a -> m ()
- handleFree :: (HasCallStack, MonadIO m, IsHandle a) => a -> m ()
- handleGetBaseUri :: (HasCallStack, MonadIO m, IsHandle a) => a -> m Text
- handleGetDesc :: (HasCallStack, MonadIO m, IsHandle a) => a -> m (Maybe Text)
- handleGetDimensions :: (HasCallStack, MonadIO m, IsHandle a) => a -> m DimensionData
- handleGetDimensionsSub :: (HasCallStack, MonadIO m, IsHandle a) => a -> Maybe Text -> m (Bool, DimensionData)
- handleGetGeometryForElement :: (HasCallStack, MonadIO m, IsHandle a) => a -> Maybe Text -> m (Rectangle, Rectangle)
- handleGetGeometryForLayer :: (HasCallStack, MonadIO m, IsHandle a) => a -> Maybe Text -> Rectangle -> m (Rectangle, Rectangle)
- handleGetIntrinsicDimensions :: (HasCallStack, MonadIO m, IsHandle a) => a -> m (Bool, Length, Bool, Length, Bool, Rectangle)
- handleGetIntrinsicSizeInPixels :: (HasCallStack, MonadIO m, IsHandle a) => a -> m (Bool, Double, Double)
- handleGetMetadata :: (HasCallStack, MonadIO m, IsHandle a) => a -> m (Maybe Text)
- handleGetPixbuf :: (HasCallStack, MonadIO m, IsHandle a) => a -> m (Maybe Pixbuf)
- handleGetPixbufSub :: (HasCallStack, MonadIO m, IsHandle a) => a -> Maybe Text -> m (Maybe Pixbuf)
- handleGetPositionSub :: (HasCallStack, MonadIO m, IsHandle a) => a -> Maybe Text -> m (Bool, PositionData)
- handleGetTitle :: (HasCallStack, MonadIO m, IsHandle a) => a -> m (Maybe Text)
- handleHasSub :: (HasCallStack, MonadIO m, IsHandle a) => a -> Text -> m Bool
- handleInternalSetTesting :: (HasCallStack, MonadIO m, IsHandle a) => a -> Bool -> m ()
- handleNew :: (HasCallStack, MonadIO m) => m Handle
- handleNewFromData :: (HasCallStack, MonadIO m) => ByteString -> m (Maybe Handle)
- handleNewFromFile :: (HasCallStack, MonadIO m) => Text -> m (Maybe Handle)
- handleNewFromGfileSync :: (HasCallStack, MonadIO m, IsFile a, IsCancellable b) => a -> [HandleFlags] -> Maybe b -> m (Maybe Handle)
- handleNewFromStreamSync :: (HasCallStack, MonadIO m, IsInputStream a, IsFile b, IsCancellable c) => a -> Maybe b -> [HandleFlags] -> Maybe c -> m (Maybe Handle)
- handleNewWithFlags :: (HasCallStack, MonadIO m) => [HandleFlags] -> m Handle
- handleReadStreamSync :: (HasCallStack, MonadIO m, IsHandle a, IsInputStream b, IsCancellable c) => a -> b -> Maybe c -> m ()
- handleRenderCairo :: (HasCallStack, MonadIO m, IsHandle a) => a -> Context -> m Bool
- handleRenderCairoSub :: (HasCallStack, MonadIO m, IsHandle a) => a -> Context -> Maybe Text -> m Bool
- handleRenderDocument :: (HasCallStack, MonadIO m, IsHandle a) => a -> Context -> Rectangle -> m ()
- handleRenderElement :: (HasCallStack, MonadIO m, IsHandle a) => a -> Context -> Maybe Text -> Rectangle -> m ()
- handleRenderLayer :: (HasCallStack, MonadIO m, IsHandle a) => a -> Context -> Maybe Text -> Rectangle -> m ()
- handleSetBaseGfile :: (HasCallStack, MonadIO m, IsHandle a, IsFile b) => a -> b -> m ()
- handleSetBaseUri :: (HasCallStack, MonadIO m, IsHandle a) => a -> Text -> m ()
- handleSetDpi :: (HasCallStack, MonadIO m, IsHandle a) => a -> Double -> m ()
- handleSetDpiXY :: (HasCallStack, MonadIO m, IsHandle a) => a -> Double -> Double -> m ()
- handleSetSizeCallback :: (HasCallStack, MonadIO m, IsHandle a) => a -> Maybe SizeFunc -> m ()
- handleSetStylesheet :: (HasCallStack, MonadIO m, IsHandle a) => a -> ByteString -> m ()
- handleWrite :: (HasCallStack, MonadIO m, IsHandle a) => a -> ByteString -> m ()
- constructHandleBaseUri :: (IsHandle o, MonadIO m) => Text -> m (GValueConstruct o)
- getHandleBaseUri :: (MonadIO m, IsHandle o) => o -> m Text
- setHandleBaseUri :: (MonadIO m, IsHandle o) => o -> Text -> m ()
- getHandleDesc :: (MonadIO m, IsHandle o) => o -> m (Maybe Text)
- constructHandleDpiX :: (IsHandle o, MonadIO m) => Double -> m (GValueConstruct o)
- getHandleDpiX :: (MonadIO m, IsHandle o) => o -> m Double
- setHandleDpiX :: (MonadIO m, IsHandle o) => o -> Double -> m ()
- constructHandleDpiY :: (IsHandle o, MonadIO m) => Double -> m (GValueConstruct o)
- getHandleDpiY :: (MonadIO m, IsHandle o) => o -> m Double
- setHandleDpiY :: (MonadIO m, IsHandle o) => o -> Double -> m ()
- getHandleEm :: (MonadIO m, IsHandle o) => o -> m Double
- getHandleEx :: (MonadIO m, IsHandle o) => o -> m Double
- constructHandleFlags :: (IsHandle o, MonadIO m) => [HandleFlags] -> m (GValueConstruct o)
- getHandleFlags :: (MonadIO m, IsHandle o) => o -> m [HandleFlags]
- getHandleHeight :: (MonadIO m, IsHandle o) => o -> m Int32
- getHandleMetadata :: (MonadIO m, IsHandle o) => o -> m (Maybe Text)
- getHandleTitle :: (MonadIO m, IsHandle o) => o -> m (Maybe Text)
- getHandleWidth :: (MonadIO m, IsHandle o) => o -> m Int32
Exported types
Memory-managed wrapper type.
Instances
Eq Handle Source # | |
GObject Handle Source # | |
Defined in GI.Rsvg.Objects.Handle | |
ManagedPtrNewtype Handle Source # | |
Defined in GI.Rsvg.Objects.Handle toManagedPtr :: Handle -> ManagedPtr Handle | |
TypedObject Handle Source # | |
Defined in GI.Rsvg.Objects.Handle | |
HasParentTypes Handle Source # | |
Defined in GI.Rsvg.Objects.Handle | |
IsGValue (Maybe Handle) Source # | Convert |
Defined in GI.Rsvg.Objects.Handle gvalueGType_ :: IO GType gvalueSet_ :: Ptr GValue -> Maybe Handle -> IO () gvalueGet_ :: Ptr GValue -> IO (Maybe Handle) | |
type ParentTypes Handle Source # | |
Defined in GI.Rsvg.Objects.Handle type ParentTypes Handle = '[Object] |
class (GObject o, IsDescendantOf Handle o) => IsHandle o Source #
Instances
(GObject o, IsDescendantOf Handle o) => IsHandle o Source # | |
Defined in GI.Rsvg.Objects.Handle |
Methods
Click to display all available methods, including inherited ones
Methods
bindProperty, bindPropertyFull, close, forceFloating, free, freezeNotify, getv, hasSub, internalSetTesting, isFloating, notify, notifyByPspec, readStreamSync, ref, refSink, renderCairo, renderCairoSub, renderDocument, renderElement, renderLayer, runDispose, stealData, stealQdata, thawNotify, unref, watchClosure, write.
Getters
getBaseUri, getData, getDesc, getDimensions, getDimensionsSub, getGeometryForElement, getGeometryForLayer, getIntrinsicDimensions, getIntrinsicSizeInPixels, getMetadata, getPixbuf, getPixbufSub, getPositionSub, getProperty, getQdata, getTitle.
Setters
setBaseGfile, setBaseUri, setData, setDataFull, setDpi, setDpiXY, setProperty, setSizeCallback, setStylesheet.
close
:: (HasCallStack, MonadIO m, IsHandle a) | |
=> a |
|
-> m () | (Can throw |
Deprecated: (Since version 2.46.)Use handleReadStreamSync
or the constructorfunctions handleNewFromGfileSync
orhandleNewFromStreamSync
. See the deprecation notes forhandleWrite
for more information.
This is used after calling handleWrite
to indicate that there is no more data
to consume, and to start the actual parsing of the SVG document. The only reason to
call this function is if you use use handleWrite
to feed data into the handle
;
if you use the other methods like handleNewFromFile
or
handleReadStreamSync
, then you do not need to call this function.
This will return TRUE
if the loader closed successfully and the
SVG data was parsed correctly. Note that handle
isn't freed until
objectUnref
is called.
free
:: (HasCallStack, MonadIO m, IsHandle a) | |
=> a |
|
-> m () |
Deprecated: Use objectUnref
instead.
Frees handle
.
getBaseUri
:: (HasCallStack, MonadIO m, IsHandle a) | |
=> a |
|
-> m Text | Returns: the base uri, possibly null |
Gets the base uri for this Handle
.
Since: 2.8
getDesc
:: (HasCallStack, MonadIO m, IsHandle a) | |
=> a |
|
-> m (Maybe Text) | Returns: This function always returns |
Deprecated: (Since version 2.36.)Librsvg does not read the metadata/desc/title elements;this function always returns NULL
.
No description available in the introspection data.
Since: 2.4
getDimensions
:: (HasCallStack, MonadIO m, IsHandle a) | |
=> a |
|
-> m DimensionData |
Deprecated: (Since version 2.52.)Use handleGetIntrinsicSizeInPixels
instead. Thisfunction is deprecated because it is not able to return exact fractional dimensions,only integer pixels.
Get the SVG's size. Do not call from within the size_func callback, because an infinite loop will occur.
This function depends on the Handle
's DPI to compute dimensions in
pixels, so you should call handleSetDpi
beforehand.
Since: 2.14
getDimensionsSub
handleGetDimensionsSub Source #
:: (HasCallStack, MonadIO m, IsHandle a) | |
=> a |
|
-> Maybe Text |
|
-> m (Bool, DimensionData) | Returns: |
Deprecated: (Since version 2.46.)Use handleGetGeometryForLayer
instead.
Get the size of a subelement of the SVG file. Do not call from within the size_func callback, because an infinite loop will occur.
This function depends on the Handle
's DPI to compute dimensions in
pixels, so you should call handleSetDpi
beforehand.
Element IDs should look like an URL fragment identifier; for example, pass
#foo
(hash foo
) to get the geometry of the element that
has an id="foo"
attribute.
Since: 2.22
getGeometryForElement
handleGetGeometryForElement Source #
:: (HasCallStack, MonadIO m, IsHandle a) | |
=> a |
|
-> Maybe Text |
|
-> m (Rectangle, Rectangle) | (Can throw |
Computes the ink rectangle and logical rectangle of a single SVG element.
While rsvg_handle_get_geometry_for_layer
computes the geometry of an SVG element subtree with
its transformation matrix, this other function will compute the element's geometry
as if it were being rendered under an identity transformation by itself. That is,
the resulting geometry is as if the element got extracted by itself from the SVG.
This function is the counterpart to rsvg_handle_render_element
.
Element IDs should look like an URL fragment identifier; for example, pass
#foo
(hash foo
) to get the geometry of the element that
has an id="foo"
attribute.
The "ink rectangle" is the bounding box that would be painted for fully- stroked and filled elements.
The "logical rectangle" just takes into account the unstroked paths and text outlines.
Note that these bounds are not minimum bounds; for example, clipping paths are not taken into account.
You can pass NULL
for the id
if you want to measure all
the elements in the SVG, i.e. to measure everything from the
root element.
This operation is not constant-time, as it involves going through all the child elements.
Since: 2.46
getGeometryForLayer
handleGetGeometryForLayer Source #
:: (HasCallStack, MonadIO m, IsHandle a) | |
=> a |
|
-> Maybe Text |
|
-> Rectangle |
|
-> m (Rectangle, Rectangle) | (Can throw |
Computes the ink rectangle and logical rectangle of an SVG element, or the whole SVG, as if the whole SVG were rendered to a specific viewport.
Element IDs should look like an URL fragment identifier; for example, pass
#foo
(hash foo
) to get the geometry of the element that
has an id="foo"
attribute.
The "ink rectangle" is the bounding box that would be painted for fully-stroked and filled elements.
The "logical rectangle" just takes into account the unstroked paths and text outlines.
Note that these bounds are not minimum bounds; for example, clipping paths are not taken into account.
You can pass NULL
for the id
if you want to measure all
the elements in the SVG, i.e. to measure everything from the
root element.
This operation is not constant-time, as it involves going through all the child elements.
Since: 2.46
getIntrinsicDimensions
handleGetIntrinsicDimensions Source #
:: (HasCallStack, MonadIO m, IsHandle a) | |
=> a |
|
-> m (Bool, Length, Bool, Length, Bool, Rectangle) |
In simple terms, queries the width
, height
, and viewBox
attributes in an SVG document.
If you are calling this function to compute a scaling factor to render the SVG,
consider simply using handleRenderDocument
instead; it will do the
scaling computations automatically.
Before librsvg 2.54.0, the out_has_width
and out_has_height
arguments would be set to true or false
depending on whether the SVG document actually had width
and height
attributes, respectively.
However, since librsvg 2.54.0, width
and height
are now <https://www.w3.org/TR/SVG2/geometry.html geometry
properties> per the SVG2 specification; they
are not plain attributes. SVG2 made it so that the initial value of those properties
is auto
, which is equivalent to specifing a value of 100%
. In this sense, even SVG
documents which lack width
or height
attributes semantically have to make them
default to 100%
. This is why since librsvg 2.54.0, out_has_width
and
out_has_heigth
are always returned as TRUE
, since with SVG2 all documents *have* a
default width and height of 100%
.
As an example, the following SVG element has a width
of 100 pixels and a height
of 400 pixels, but no viewBox
. This
function will return those sizes in out_width
and out_height
, and set out_has_viewbox
to FALSE
.
<svg xmlns="http://www.w3.org/2000/svg" width="100" height="400">
Conversely, the following element has a viewBox
, but no width
or height
. This function will
set out_has_viewbox
to TRUE
, and it will also set out_has_width
and out_has_height
to TRUE
but
return both length values as 100%
.
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 400">
Note that the RsvgLength
return values have RsvgUnits
in them; you should
not assume that they are always in pixels. For example, the following SVG element
will return width and height values whose units
fields are RSVG_UNIT_MM
.
<svg xmlns="http://www.w3.org/2000/svg" width="210mm" height="297mm">
API ordering: This function must be called on a fully-loaded handle
. See
the section "API ordering" for details.
Panics: this function will panic if the handle
is not fully-loaded.
Since: 2.46
getIntrinsicSizeInPixels
handleGetIntrinsicSizeInPixels Source #
:: (HasCallStack, MonadIO m, IsHandle a) | |
=> a |
|
-> m (Bool, Double, Double) | Returns: |
Converts an SVG document's intrinsic dimensions to pixels, and returns the result.
This function is able to extract the size in pixels from an SVG document if the
document has both width
and height
attributes
with physical units (px, in, cm, mm, pt, pc) or font-based units (em, ex). For
physical units, the dimensions are normalized to pixels using the dots-per-inch (DPI)
value set previously with handleSetDpi
. For font-based units, this function
uses the computed value of the font-size
property for the toplevel
<svg>
element. In those cases, this function returns TRUE
.
This function is not able to extract the size in pixels directly from the intrinsic
dimensions of the SVG document if the width
or
height
are in percentage units (or if they do not exist, in which
case the SVG spec mandates that they default to 100%), as these require a
<firstterm>viewport</firstterm> to be resolved to a final size. In this case, the
function returns FALSE
.
For example, the following document fragment has intrinsic dimensions that will resolve to 20x30 pixels.
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="30"/>
Similarly, if the DPI is set to 96, this document will resolve to 192×288 pixels (i.e. 96×2 × 96×3).
<svg xmlns="http://www.w3.org/2000/svg" width="2in" height="3in"/>
The dimensions of the following documents cannot be resolved to pixels directly, and
this function would return FALSE
for them:
<!-- Needs a viewport against which to compute the percentages. --> <svg xmlns="http://www.w3.org/2000/svg" width="100%" height="100%"/> <!-- Does not have intrinsic width/height, just a 1:2 aspect ratio which needs to be fitted within a viewport. --> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 200"/>
Instead of querying an SVG document's size, applications are encouraged to render SVG
documents to a size chosen by the application, by passing a suitably-sized viewport to
handleRenderDocument
.
Since: 2.52
getMetadata
:: (HasCallStack, MonadIO m, IsHandle a) | |
=> a |
|
-> m (Maybe Text) | Returns: This function always returns |
Deprecated: (Since version 2.36.)Librsvg does not read the metadata/desc/title elements;this function always returns NULL
.
No description available in the introspection data.
Since: 2.9
getPixbuf
:: (HasCallStack, MonadIO m, IsHandle a) | |
=> a |
|
-> m (Maybe Pixbuf) | Returns: A pixbuf, or |
Returns the pixbuf loaded by handle
. The pixbuf returned will be reffed, so
the caller of this function must assume that ref.
API ordering: This function must be called on a fully-loaded handle
. See
the section "API ordering" for details.
This function depends on the Handle
's dots-per-inch value (DPI) to compute the
"natural size" of the document in pixels, so you should call handleSetDpi
beforehand.
getPixbufSub
:: (HasCallStack, MonadIO m, IsHandle a) | |
=> a |
|
-> Maybe Text |
|
-> m (Maybe Pixbuf) | Returns: a pixbuf, or |
Creates a GdkPixbuf
the same size as the entire SVG loaded into handle
, but
only renders the sub-element that has the specified id
(and all its
sub-sub-elements recursively). If id
is NULL
, this function renders the
whole SVG.
This function depends on the Handle
's dots-per-inch value (DPI) to compute the
"natural size" of the document in pixels, so you should call handleSetDpi
beforehand.
If you need to render an image which is only big enough to fit a particular
sub-element of the SVG, consider using handleRenderElement
.
Element IDs should look like an URL fragment identifier; for example, pass
#foo
(hash foo
) to get the geometry of the element that
has an id="foo"
attribute.
API ordering: This function must be called on a fully-loaded handle
. See
the section "API ordering" for details.
Since: 2.14
getPositionSub
:: (HasCallStack, MonadIO m, IsHandle a) | |
=> a |
|
-> Maybe Text |
|
-> m (Bool, PositionData) | Returns: |
Deprecated: (Since version 2.46.)Use handleGetGeometryForLayer
instead. This function isdeprecated since it is not able to return exact floating-point positions, only integerpixels.
Get the position of a subelement of the SVG file. Do not call from within the size_func callback, because an infinite loop will occur.
This function depends on the Handle
's DPI to compute dimensions in
pixels, so you should call handleSetDpi
beforehand.
Element IDs should look like an URL fragment identifier; for example, pass
#foo
(hash foo
) to get the geometry of the element that
has an id="foo"
attribute.
Since: 2.22
getTitle
:: (HasCallStack, MonadIO m, IsHandle a) | |
=> a |
|
-> m (Maybe Text) | Returns: This function always returns |
Deprecated: (Since version 2.36.)Librsvg does not read the metadata/desc/title elements;this function always returns NULL
.
No description available in the introspection data.
Since: 2.4
hasSub
:: (HasCallStack, MonadIO m, IsHandle a) | |
=> a |
|
-> Text |
|
-> m Bool | Returns: |
Checks whether the element id
exists in the SVG document.
Element IDs should look like an URL fragment identifier; for example, pass
#foo
(hash foo
) to get the geometry of the element that
has an id="foo"
attribute.
Since: 2.22
internalSetTesting
handleInternalSetTesting Source #
:: (HasCallStack, MonadIO m, IsHandle a) | |
=> a |
|
-> Bool |
|
-> m () |
Do not call this function. This is intended for librsvg's internal test suite only.
new
:: (HasCallStack, MonadIO m) | |
=> m Handle | Returns: A new |
Returns a new rsvg handle. Must be freed with objectUnref
. This
handle can be used to load an image.
The preferred way of loading SVG data into the returned Handle
is with
handleReadStreamSync
.
The deprecated way of loading SVG data is with handleWrite
and
handleClose
; note that these require buffering the entire file
internally, and for this reason it is better to use the stream functions:
handleNewFromStreamSync
, handleReadStreamSync
, or
handleNewFromGfileSync
.
After loading the Handle
with data, you can render it using Cairo or get
a GdkPixbuf from it. When finished, free the handle with objectUnref
. No
more than one image can be loaded with one handle.
Note that this function creates an Handle
with no flags set. If you
require any of [flagsrsvg
.HandleFlags] to be set, use any of
handleNewWithFlags
, handleNewFromStreamSync
, or
handleNewFromGfileSync
.
newFromData
:: (HasCallStack, MonadIO m) | |
=> ByteString |
|
-> m (Maybe Handle) | Returns: A |
Loads the SVG specified by data
. Note that this function creates an
Handle
without a base URL, and without any [flagsrsvg
.HandleFlags]. If you
need these, use handleNewFromStreamSync
instead by creating
a MemoryInputStream
from your data.
Since: 2.14
newFromFile
:: (HasCallStack, MonadIO m) | |
=> Text |
|
-> m (Maybe Handle) | Returns: A |
Loads the SVG specified by fileName
. Note that this function, like
handleNew
, does not specify any loading flags for the resulting
handle. If you require the use of [flagsrsvg
.HandleFlags], use
handleNewFromGfileSync
.
Since: 2.14
newFromGfileSync
handleNewFromGfileSync Source #
:: (HasCallStack, MonadIO m, IsFile a, IsCancellable b) | |
=> a |
|
-> [HandleFlags] |
|
-> Maybe b |
|
-> m (Maybe Handle) | Returns: a new |
Creates a new Handle
for file
.
This function sets the "base file" of the handle to be file
itself, so SVG
elements like <image>
which reference external
resources will be resolved relative to the location of file
.
If cancellable
is not NULL
, then the operation can be cancelled by
triggering the cancellable object from another thread. If the
operation was cancelled, the error G_IO_ERROR_CANCELLED
will be
returned in error
.
Since: 2.32
newFromStreamSync
handleNewFromStreamSync Source #
:: (HasCallStack, MonadIO m, IsInputStream a, IsFile b, IsCancellable c) | |
=> a |
|
-> Maybe b |
|
-> [HandleFlags] |
|
-> Maybe c |
|
-> m (Maybe Handle) | Returns: a new |
Creates a new Handle
for stream
.
This function sets the "base file" of the handle to be baseFile
if
provided. SVG elements like <image>
which reference
external resources will be resolved relative to the location of baseFile
.
If cancellable
is not NULL
, then the operation can be cancelled by
triggering the cancellable object from another thread. If the
operation was cancelled, the error G_IO_ERROR_CANCELLED
will be
returned in error
.
Since: 2.32
newWithFlags
:: (HasCallStack, MonadIO m) | |
=> [HandleFlags] |
|
-> m Handle | Returns: a new |
Creates a new Handle
with flags flags
. After calling this function,
you can feed the resulting handle with SVG data by using
handleReadStreamSync
.
Since: 2.36
readStreamSync
:: (HasCallStack, MonadIO m, IsHandle a, IsInputStream b, IsCancellable c) | |
=> a |
|
-> b |
|
-> Maybe c |
|
-> m () | (Can throw |
Reads stream
and writes the data from it to handle
.
Before calling this function, you may need to call handleSetBaseUri
or handleSetBaseGfile
to set the "base file" for resolving
references to external resources. SVG elements like
<image>
which reference external resources will be
resolved relative to the location you specify with those functions.
If cancellable
is not NULL
, then the operation can be cancelled by
triggering the cancellable object from another thread. If the
operation was cancelled, the error G_IO_ERROR_CANCELLED
will be
returned.
Since: 2.32
renderCairo
:: (HasCallStack, MonadIO m, IsHandle a) | |
=> a |
|
-> Context |
|
-> m Bool | Returns: |
Deprecated: (Since version 2.52.)Please use handleRenderDocument
instead; that function letsyou pass a viewport and obtain a good error message.
Draws a loaded SVG handle to a Cairo context. Please try to use
handleRenderDocument
instead, which allows you to pick the size
at which the document will be rendered.
Historically this function has picked a size by itself, based on the following rules:
- If the SVG document has both
width
andheight
attributes with physical units (px, in, cm, mm, pt, pc) or font-based units (em, ex), the function computes the size directly based on the dots-per-inch (DPI) you have configured withhandleSetDpi
. This is the same approach ashandleGetIntrinsicSizeInPixels
. - Otherwise, if there is a
viewBox
attribute and bothwidth
andheight
are set to100%
(or if they don't exist at all and thus default to 100%), the function uses the width and height of theviewBox
as a pixel size. This produces a rendered document with the correct aspect ratio. - Otherwise, this function computes the extents of every graphical object in the SVG document to find the total extents. This is moderately expensive, but no more expensive than rendering the whole document, for example.
- This function cannot deal with percentage-based units for
width
andheight
because there is no viewport against which they could be resolved; that is why it will compute the extents of objects in that case. This is why we recommend that you usehandleRenderDocument
instead, which takes in a viewport and follows the sizing policy from the web platform.
Drawing will occur with respect to the cr
's current transformation: for example, if
the cr
has a rotated current transformation matrix, the whole SVG will be rotated in
the rendered version.
This function depends on the Handle
's DPI to compute dimensions in
pixels, so you should call handleSetDpi
beforehand.
Note that cr
must be a Cairo context that is not in an error state, that is,
cairo_status()
must return CAIRO_STATUS_SUCCESS
for it. Cairo can set a
context to be in an error state in various situations, for example, if it was
passed an invalid matrix or if it was created for an invalid surface.
Since: 2.14
renderCairoSub
:: (HasCallStack, MonadIO m, IsHandle a) | |
=> a |
|
-> Context |
|
-> Maybe Text |
|
-> m Bool | Returns: |
Deprecated: (Since version 2.52.)Please use handleRenderLayer
instead; that function letsyou pass a viewport and obtain a good error message.
Renders a single SVG element in the same place as for a whole SVG document (a "subset"
of the document). Please try to use handleRenderLayer
instead, which allows
you to pick the size at which the document with the layer will be rendered.
This is equivalent to handleRenderCairo
, but it renders only a single
element and its children, as if they composed an individual layer in the SVG.
Historically this function has picked a size for the whole document by itself, based on the following rules:
- If the SVG document has both
width
andheight
attributes with physical units (px, in, cm, mm, pt, pc) or font-based units (em, ex), the function computes the size directly based on the dots-per-inch (DPI) you have configured withhandleSetDpi
. This is the same approach ashandleGetIntrinsicSizeInPixels
. - Otherwise, if there is a
viewBox
attribute and bothwidth
andheight
are set to100%
(or if they don't exist at all and thus default to 100%), the function uses the width and height of theviewBox
as a pixel size. This produces a rendered document with the correct aspect ratio. - Otherwise, this function computes the extents of every graphical object in the SVG document to find the total extents. This is moderately expensive, but no more expensive than rendering the whole document, for example.
- This function cannot deal with percentage-based units for
width
andheight
because there is no viewport against which they could be resolved; that is why it will compute the extents of objects in that case. This is why we recommend that you usehandleRenderLayer
instead, which takes in a viewport and follows the sizing policy from the web platform.
Drawing will occur with respect to the cr
's current transformation: for example, if
the cr
has a rotated current transformation matrix, the whole SVG will be rotated in
the rendered version.
This function depends on the Handle
's DPI to compute dimensions in
pixels, so you should call handleSetDpi
beforehand.
Note that cr
must be a Cairo context that is not in an error state, that is,
cairo_status()
must return CAIRO_STATUS_SUCCESS
for it. Cairo can set a
context to be in an error state in various situations, for example, if it was
passed an invalid matrix or if it was created for an invalid surface.
Element IDs should look like an URL fragment identifier; for example, pass
#foo
(hash foo
) to get the geometry of the element that
has an id="foo"
attribute.
Since: 2.14
renderDocument
:: (HasCallStack, MonadIO m, IsHandle a) | |
=> a |
|
-> Context |
|
-> Rectangle |
|
-> m () | (Can throw |
Renders the whole SVG document fitted to a viewport.
The viewport
gives the position and size at which the whole SVG document will be
rendered. The document is scaled proportionally to fit into this viewport.
The cr
must be in a CAIRO_STATUS_SUCCESS
state, or this function will not
render anything, and instead will return an error.
Since: 2.46
renderElement
:: (HasCallStack, MonadIO m, IsHandle a) | |
=> a |
|
-> Context |
|
-> Maybe Text |
|
-> Rectangle |
|
-> m () | (Can throw |
Renders a single SVG element to a given viewport.
This function can be used to extract individual element subtrees and render them,
scaled to a given elementViewport
. This is useful for applications which have
reusable objects in an SVG and want to render them individually; for example, an
SVG full of icons that are meant to be be rendered independently of each other.
Element IDs should look like an URL fragment identifier; for example, pass
#foo
(hash foo
) to get the geometry of the element that
has an id="foo"
attribute.
You can pass NULL
for the id
if you want to render all
the elements in the SVG, i.e. to render everything from the
root element.
The element_viewport
gives the position and size at which the named element will
be rendered. FIXME: mention proportional scaling.
Since: 2.46
renderLayer
:: (HasCallStack, MonadIO m, IsHandle a) | |
=> a |
|
-> Context |
|
-> Maybe Text |
|
-> Rectangle |
|
-> m () | (Can throw |
Renders a single SVG element in the same place as for a whole SVG document.
The viewport
gives the position and size at which the whole SVG document would be
rendered. The document is scaled proportionally to fit into this viewport; hence the
individual layer may be smaller than this.
This is equivalent to handleRenderDocument
, but it renders only a
single element and its children, as if they composed an individual layer in
the SVG. The element is rendered with the same transformation matrix as it
has within the whole SVG document. Applications can use this to re-render a
single element and repaint it on top of a previously-rendered document, for
example.
Element IDs should look like an URL fragment identifier; for example, pass
#foo
(hash foo
) to get the geometry of the element that
has an id="foo"
attribute.
You can pass NULL
for the id
if you want to render all
the elements in the SVG, i.e. to render everything from the
root element.
Since: 2.46
setBaseGfile
:: (HasCallStack, MonadIO m, IsHandle a, IsFile b) | |
=> a |
|
-> b |
|
-> m () |
Set the base URI for handle
from file
.
Note: This function may only be called before handleWrite
or
handleReadStreamSync
have been called.
Since: 2.32
setBaseUri
:: (HasCallStack, MonadIO m, IsHandle a) | |
=> a |
|
-> Text |
|
-> m () |
Set the base URI for this SVG.
Note: This function may only be called before handleWrite
or
handleReadStreamSync
have been called.
Since: 2.9
setDpi
:: (HasCallStack, MonadIO m, IsHandle a) | |
=> a |
|
-> Double |
|
-> m () |
Sets the DPI at which the handle
will be rendered. Common values are
75, 90, and 300 DPI.
Passing a number <= 0 to dpi
will reset the DPI to whatever the default
value happens to be, but since setDefaultDpi
is deprecated, please
do not pass values <= 0 to this function.
Since: 2.8
setDpiXY
:: (HasCallStack, MonadIO m, IsHandle a) | |
=> a |
|
-> Double |
|
-> Double |
|
-> m () |
Sets the DPI at which the handle
will be rendered. Common values are
75, 90, and 300 DPI.
Passing a number <= 0 to dpi
will reset the DPI to whatever the default
value happens to be, but since setDefaultDpiXY
is deprecated,
please do not pass values <= 0 to this function.
Since: 2.8
setSizeCallback
handleSetSizeCallback Source #
:: (HasCallStack, MonadIO m, IsHandle a) | |
=> a |
|
-> Maybe SizeFunc |
|
-> m () |
Deprecated: (Since version 2.14.)Use handleRenderDocument
instead.This function was deprecated because when the sizeFunc
is used, it makes itunclear when the librsvg functions which call the sizeFunc
will use thesize computed originally, or the callback-specified size, or whether itrefers to the whole SVG or to just a sub-element of it. It is easier, andunambiguous, to use code similar to the example above.
Sets the sizing function for the handle
, which can be used to override the
size that librsvg computes for SVG images. The sizeFunc
is called from the
following functions:
Librsvg computes the size of the SVG being rendered, and passes it to the
sizeFunc
, which may then modify these values to set the final size of the
generated image.
setStylesheet
:: (HasCallStack, MonadIO m, IsHandle a) | |
=> a |
|
-> ByteString |
|
-> m () | (Can throw |
Sets a CSS stylesheet to use for an SVG document.
The cssLen
argument is mandatory; this function will not compute the length
of the css
string. This is because a provided stylesheet, which the calling
program could read from a file, can have nul characters in it.
During the CSS cascade, the specified stylesheet will be used with a "User" origin.
Note that @import
rules will not be resolved, except for data:
URLs.
Since: 2.48
write
:: (HasCallStack, MonadIO m, IsHandle a) | |
=> a |
|
-> ByteString |
|
-> m () | (Can throw |
Deprecated: (Since version 2.46.)Use handleReadStreamSync
or the constructorfunctions handleNewFromGfileSync
orhandleNewFromStreamSync
. This function is deprecated because itwill accumulate data from the buf
in memory until handleClose
getscalled. To avoid a big temporary buffer, use the suggested functions, whichtake a GFile
or a GInputStream
and do not require a temporary buffer.
Loads the next count
bytes of the image. You can call this function multiple
times until the whole document is consumed; then you must call handleClose
to actually parse the document.
Before calling this function for the first time, you may need to call
handleSetBaseUri
or handleSetBaseGfile
to set the "base
file" for resolving references to external resources. SVG elements like
<image>
which reference external resources will be
resolved relative to the location you specify with those functions.
Properties
baseUri
Base URI, to be used to resolve relative references for resources. See the section "Security and locations of referenced files" for details.
constructHandleBaseUri :: (IsHandle o, MonadIO m) => Text -> m (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “base-uri
” property. This is rarely needed directly, but it is used by new
.
getHandleBaseUri :: (MonadIO m, IsHandle o) => o -> m Text Source #
Get the value of the “base-uri
” property.
When overloading is enabled, this is equivalent to
get
handle #baseUri
setHandleBaseUri :: (MonadIO m, IsHandle o) => o -> Text -> m () Source #
Set the value of the “base-uri
” property.
When overloading is enabled, this is equivalent to
set
handle [ #baseUri:=
value ]
desc
SVG's description.
getHandleDesc :: (MonadIO m, IsHandle o) => o -> m (Maybe Text) Source #
Get the value of the “desc
” property.
When overloading is enabled, this is equivalent to
get
handle #desc
dpiX
Horizontal resolution in dots per inch.
constructHandleDpiX :: (IsHandle o, MonadIO m) => Double -> m (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “dpi-x
” property. This is rarely needed directly, but it is used by new
.
getHandleDpiX :: (MonadIO m, IsHandle o) => o -> m Double Source #
Get the value of the “dpi-x
” property.
When overloading is enabled, this is equivalent to
get
handle #dpiX
setHandleDpiX :: (MonadIO m, IsHandle o) => o -> Double -> m () Source #
Set the value of the “dpi-x
” property.
When overloading is enabled, this is equivalent to
set
handle [ #dpiX:=
value ]
dpiY
Horizontal resolution in dots per inch.
constructHandleDpiY :: (IsHandle o, MonadIO m) => Double -> m (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “dpi-y
” property. This is rarely needed directly, but it is used by new
.
getHandleDpiY :: (MonadIO m, IsHandle o) => o -> m Double Source #
Get the value of the “dpi-y
” property.
When overloading is enabled, this is equivalent to
get
handle #dpiY
setHandleDpiY :: (MonadIO m, IsHandle o) => o -> Double -> m () Source #
Set the value of the “dpi-y
” property.
When overloading is enabled, this is equivalent to
set
handle [ #dpiY:=
value ]
em
Exact width, in pixels, of the rendered SVG before calling the size callback
as specified by handleSetSizeCallback
.
getHandleEm :: (MonadIO m, IsHandle o) => o -> m Double Source #
Get the value of the “em
” property.
When overloading is enabled, this is equivalent to
get
handle #em
ex
Exact height, in pixels, of the rendered SVG before calling the size callback
as specified by handleSetSizeCallback
.
getHandleEx :: (MonadIO m, IsHandle o) => o -> m Double Source #
Get the value of the “ex
” property.
When overloading is enabled, this is equivalent to
get
handle #ex
flags
Flags from [flagsrsvg
.HandleFlags].
Since: 2.36
constructHandleFlags :: (IsHandle o, MonadIO m) => [HandleFlags] -> m (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “flags
” property. This is rarely needed directly, but it is used by new
.
getHandleFlags :: (MonadIO m, IsHandle o) => o -> m [HandleFlags] Source #
Get the value of the “flags
” property.
When overloading is enabled, this is equivalent to
get
handle #flags
height
Height, in pixels, of the rendered SVG after calling the size callback
as specified by handleSetSizeCallback
.
getHandleHeight :: (MonadIO m, IsHandle o) => o -> m Int32 Source #
Get the value of the “height
” property.
When overloading is enabled, this is equivalent to
get
handle #height
metadata
SVG's metadata
getHandleMetadata :: (MonadIO m, IsHandle o) => o -> m (Maybe Text) Source #
Get the value of the “metadata
” property.
When overloading is enabled, this is equivalent to
get
handle #metadata
title
SVG's title.
getHandleTitle :: (MonadIO m, IsHandle o) => o -> m (Maybe Text) Source #
Get the value of the “title
” property.
When overloading is enabled, this is equivalent to
get
handle #title
width
Width, in pixels, of the rendered SVG after calling the size callback
as specified by handleSetSizeCallback
.
getHandleWidth :: (MonadIO m, IsHandle o) => o -> m Int32 Source #
Get the value of the “width
” property.
When overloading is enabled, this is equivalent to
get
handle #width