Top |
Functions
GQuark | rsvg_error_quark () |
void | rsvg_cleanup () |
void | rsvg_set_default_dpi () |
void | rsvg_set_default_dpi_x_y () |
void | rsvg_handle_set_dpi () |
void | rsvg_handle_set_dpi_x_y () |
RsvgHandle * | rsvg_handle_new () |
RsvgHandle * | rsvg_handle_new_with_flags () |
gboolean | rsvg_handle_write () |
gboolean | rsvg_handle_close () |
const char * | rsvg_handle_get_base_uri () |
void | rsvg_handle_set_base_uri () |
void | rsvg_handle_get_dimensions () |
gboolean | rsvg_handle_get_dimensions_sub () |
gboolean | rsvg_handle_get_position_sub () |
gboolean | rsvg_handle_has_sub () |
const char * | rsvg_handle_get_title () |
const char * | rsvg_handle_get_desc () |
const char * | rsvg_handle_get_metadata () |
RsvgHandle * | rsvg_handle_new_from_data () |
RsvgHandle * | rsvg_handle_new_from_file () |
GType | rsvg_error_get_type () |
void | rsvg_init () |
void | rsvg_term () |
void | rsvg_handle_free () |
void | rsvg_handle_set_size_callback () |
Types and Values
enum | RsvgError |
#define | RSVG_ERROR |
struct | RsvgHandle |
typedef | RsvgHandlePrivate |
struct | RsvgHandleClass |
struct | RsvgDimensionData |
struct | RsvgPositionData |
#define | RSVG_TYPE_ERROR |
Description
This is the main entry point into the librsvg library. An RsvgHandle is an object that represents SVG data in memory. Your program creates an RsvgHandle 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 supports reading SVG 1.1 data. It also supports SVGZ files, which is just an SVG stream compressed with the GZIP algorithm.
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 xlink: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/*
or in
/foo/bar/*/.../*
. This is so that malicious
SVG files cannot include files that are in a directory above.
Loading an SVG with GIO
If you have a GFile that stands for an SVG file, you can simply call
rsvg_handle_new_from_gfile_sync()
to load an RsvgHandle from it.
Alternatively, if you have a GInputStream, you can use
rsvg_handle_new_from_stream_sync()
.
Both of those methods allow specifying a GCancellable, so the loading process can be cancelled from another thread.
Loading an SVG without GIO
You can load an RsvgHandle from a simple filename or URI with
rsvg_handle_new_from_file()
. Note that this is a blocking operation; there
is no way to cancel it if loading a remote URI takes a long time.
Alternatively, you can create an empty RsvgHandle with rsvg_handle_new()
or
rsvg_handle_new_with_flags()
. The first function is equivalent to using
RSVG_HANDLE_FLAGS_NONE on the second one. These functions give you back an
empty RsvgHandle, which is ready for you to feed it SVG data. You can do
this with rsvg_handle_write()
and rsvg_handle_close()
.
Resolution of the rendered image (dots per inch, or DPI)
SVG images can contain dimensions like "5 cm
" or
"2 pt
" 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.
The recommended way to set the DPI is to use rsvg_handle_set_dpi()
or
rsvg_handle_set_dpi_x_y()
on an RsvgHandle before rendering it.
Alternatively, you can use rsvg_set_default_dpi()
or
rsvg_set_default_dpi_x_y()
before creating any
RsvgHandle objects. These functions will make RsvgHandle objects created
afterwards to have the default DPI value you specified.
Rendering
The preferred way to render an already-loaded RsvgHandle is to use
rsvg_handle_render_cairo()
. Please see its documentation for details.
Alternatively, you can use rsvg_handle_get_pixbuf()
to directly obtain a
GdkPixbuf with the rendered image. This is simple, but it does not let you
control the size at which the SVG will be rendered. It will just be rendered
at the size which rsvg_handle_get_dimensions()
would return, which depends on
the dimensions that librsvg is able to compute from the SVG data.
Functions
rsvg_cleanup ()
void
rsvg_cleanup (void
);
This function should not be called from normal programs.
See xmlCleanupParser()
for more information.
Since: 2.36
rsvg_set_default_dpi ()
void
rsvg_set_default_dpi (double dpi
);
Sets the DPI for the all future outgoing pixbufs. 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.
Since: 2.8
rsvg_set_default_dpi_x_y ()
void rsvg_set_default_dpi_x_y (double dpi_x
,double dpi_y
);
Sets the DPI for the all future outgoing pixbufs. 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.
Since: 2.8
rsvg_handle_set_dpi ()
void rsvg_handle_set_dpi (RsvgHandle *handle
,double dpi
);
Sets the DPI for the outgoing pixbuf. 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.
Since: 2.8
rsvg_handle_set_dpi_x_y ()
void rsvg_handle_set_dpi_x_y (RsvgHandle *handle
,double dpi_x
,double dpi_y
);
Sets the DPI for the outgoing pixbuf. Common values are
75, 90, and 300 DPI. Passing a number <= 0 to dpi_x or dpi_y
will
reset the DPI to whatever the default value happens to be.
Parameters
handle |
An RsvgHandle |
|
dpi_x |
Dots Per Inch (aka Pixels Per Inch) |
|
dpi_y |
Dots Per Inch (aka Pixels Per Inch) |
Since: 2.8
rsvg_handle_new ()
RsvgHandle *
rsvg_handle_new (void
);
Returns a new rsvg handle. Must be freed with g_object_unref
. This
handle can be used for dynamically loading an image. You need to feed it
data using rsvg_handle_write
, then call rsvg_handle_close
when done.
Afterwords, you can render it using Cairo or get a GdkPixbuf from it. When
finished, free with g_object_unref()
. No more than one image can be loaded
with one handle.
rsvg_handle_new_with_flags ()
RsvgHandle *
rsvg_handle_new_with_flags (RsvgHandleFlags flags
);
Creates a new RsvgHandle with flags flags
.
Since: 2.36
rsvg_handle_write ()
gboolean rsvg_handle_write (RsvgHandle *handle
,const guchar *buf
,gsize count
,GError **error
);
Loads the next count
bytes of the image. This will return TRUE
if the data
was loaded successful, and FALSE
if an error occurred. In the latter case,
the loader will be closed, and will not accept further writes. If FALSE
is
returned, error
will be set to an error from the RsvgError domain. Errors
from GIOErrorEnum are also possible.
Parameters
handle |
an RsvgHandle |
|
buf |
pointer to svg data. |
[array length=count][element-type guchar] |
count |
length of the |
|
error |
[allow-none] |
rsvg_handle_close ()
gboolean rsvg_handle_close (RsvgHandle *handle
,GError **error
);
Closes handle
, to indicate that loading the image is complete. This will
return TRUE
if the loader closed successfully. Note that handle
isn't
freed until g_object_unref
is called.
rsvg_handle_get_base_uri ()
const char *
rsvg_handle_get_base_uri (RsvgHandle *handle
);
Gets the base uri for this RsvgHandle.
Since: 2.8
rsvg_handle_set_base_uri ()
void rsvg_handle_set_base_uri (RsvgHandle *handle
,const char *base_uri
);
Set the base URI for this SVG. This can only be called before rsvg_handle_write()
has been called.
Since: 2.9
rsvg_handle_get_dimensions ()
void rsvg_handle_get_dimensions (RsvgHandle *handle
,RsvgDimensionData *dimension_data
);
Get the SVG's size. Do not call from within the size_func callback, because an infinite loop will occur.
Since: 2.14
rsvg_handle_get_dimensions_sub ()
gboolean rsvg_handle_get_dimensions_sub (RsvgHandle *handle
,RsvgDimensionData *dimension_data
,const char *id
);
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.
Parameters
handle |
||
dimension_data |
A place to store the SVG's size. |
[out] |
id |
An element's id within the SVG, starting with "##", for
example, "#layer1"; or |
[nullable] |
Since: 2.22
rsvg_handle_get_position_sub ()
gboolean rsvg_handle_get_position_sub (RsvgHandle *handle
,RsvgPositionData *position_data
,const char *id
);
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.
Parameters
handle |
||
position_data |
A place to store the SVG fragment's position. |
[out] |
id |
An element's id within the SVG, starting with "##", for
example, "#layer1"; or |
[nullable] |
Since: 2.22
rsvg_handle_has_sub ()
gboolean rsvg_handle_has_sub (RsvgHandle *handle
,const char *id
);
Checks whether the element id
exists in the SVG document.
Since: 2.22
rsvg_handle_get_title ()
const char *
rsvg_handle_get_title (RsvgHandle *handle
);
rsvg_handle_get_title
has been deprecated since version 2.36 and should not be used in newly-written code.
Returns the SVG's title in UTF-8 or NULL
. You must make a copy
of this title if you wish to use it after handle
has been freed.
Since: 2.4
rsvg_handle_get_desc ()
const char *
rsvg_handle_get_desc (RsvgHandle *handle
);
rsvg_handle_get_desc
has been deprecated since version 2.36 and should not be used in newly-written code.
Returns the SVG's description in UTF-8 or NULL
. You must make a copy
of this description if you wish to use it after handle
has been freed.
Since: 2.4
rsvg_handle_get_metadata ()
const char *
rsvg_handle_get_metadata (RsvgHandle *handle
);
rsvg_handle_get_metadata
has been deprecated since version 2.36 and should not be used in newly-written code.
Returns the SVG's metadata in UTF-8 or NULL
. You must make a copy
of this metadata if you wish to use it after handle
has been freed.
Since: 2.9
rsvg_handle_new_from_data ()
RsvgHandle * rsvg_handle_new_from_data (const guint8 *data
,gsize data_len
,GError **error
);
Loads the SVG specified by data
.
Parameters
data |
The SVG data. |
[array length=data_len] |
data_len |
The length of |
|
error |
return location for errors |
Since: 2.14
rsvg_handle_new_from_file ()
RsvgHandle * rsvg_handle_new_from_file (const gchar *file_name
,GError **error
);
Loads the SVG specified by file_name
.
Parameters
file_name |
The file name to load. If built with gnome-vfs, can be a URI. |
|
error |
return location for errors |
Since: 2.14
rsvg_init ()
void
rsvg_init (void
);
rsvg_init
has been deprecated since version 2.36 and should not be used in newly-written code.
Use g_type_init()
Initializes librsvg
Since: 2.9
rsvg_term ()
void
rsvg_term (void
);
rsvg_term
has been deprecated since version 2.36 and should not be used in newly-written code.
This function does nothing.
Since: 2.9
rsvg_handle_free ()
void
rsvg_handle_free (RsvgHandle *handle
);
rsvg_handle_free
is deprecated and should not be used in newly-written code.
Use g_object_unref()
instead.
Frees handle
.
rsvg_handle_set_size_callback ()
void rsvg_handle_set_size_callback (RsvgHandle *handle
,RsvgSizeFunc size_func
,gpointer user_data
,GDestroyNotify user_data_destroy
);
rsvg_handle_set_size_callback
is deprecated and should not be used in newly-written code.
Set up a cairo matrix and use rsvg_handle_render_cairo()
instead.
You can call rsvg_handle_get_dimensions()
to figure out the size of your SVG,
and then scale it to the desired size via Cairo. For example, the following
code renders an SVG at a specified size, scaled proportionally from whatever
original size it may have had:
void render_scaled_proportionally (RsvgHandle *handle, cairo_t cr, int width, int height) { RsvgDimensionData dimensions; double x_factor, y_factor; double scale_factor; rsvg_handle_get_dimensions (handle, &dimensions); x_factor = (double) width / dimensions.width; y_factor = (double) height / dimensions.height; scale_factor = MIN (x_factor, y_factor); cairo_scale (cr, scale_factor, scale_factor); rsvg_handle_render_cairo (handle, cr); }
Sets the sizing function for the handle
. This function is called right
after the size of the image has been loaded. The size of the image is passed
in to the function, which may then modify these values to set the real size
of the generated pixbuf. If the image has no associated size, then the size
arguments are set to -1.
Parameters
handle |
An RsvgHandle |
|
size_func |
A sizing function, or |
[nullable] |
user_data |
User data to pass to |
|
user_data_destroy |
Destroy function for |
Types and Values
struct RsvgHandleClass
struct RsvgHandleClass { GObjectClass parent; };
Class structure for RsvgHandle.
struct RsvgDimensionData
struct RsvgDimensionData { int width; int height; gdouble em; gdouble ex; };