Core API

Core API —

Create and manipulate SVG objects

Synopsis

enum                RsvgError;
#define             RSVG_ERROR
GQuark              rsvg_error_quark                    (void);
void                rsvg_init                           (void);
void                rsvg_term                           (void);
void                rsvg_set_default_dpi                (double dpi);
void                rsvg_set_default_dpi_x_y            (double dpi_x,
                                                         double dpi_y);
RsvgHandle*         rsvg_handle_new                     (void);
void                rsvg_handle_free                    (RsvgHandle *handle);
void                rsvg_handle_set_dpi                 (RsvgHandle *handle,
                                                         double dpi);
void                rsvg_handle_set_dpi_x_y             (RsvgHandle *handle,
                                                         double dpi_x,
                                                         double dpi_y);
gboolean            rsvg_handle_write                   (RsvgHandle *handle,
                                                         const guchar *buf,
                                                         gsize count,
                                                         GError **error);
gboolean            rsvg_handle_close                   (RsvgHandle *handle,
                                                         GError **error);
RsvgHandle*         rsvg_handle_new_from_data           (const guint8 *data,
                                                         gsize data_len,
                                                         GError **error);
RsvgHandle*         rsvg_handle_new_from_file           (const gchar *file_name,
                                                         GError **error);
                    RsvgDimensionData;
void                (*RsvgSizeFunc)                     (gint *width,
                                                         gint *height,
                                                         gpointer user_data);
void                rsvg_handle_set_size_callback       (RsvgHandle *handle,
                                                         RsvgSizeFunc size_func,
                                                         gpointer user_data,
                                                         GDestroyNotify user_data_destroy);
const char*         rsvg_handle_get_base_uri            (RsvgHandle *handle);
void                rsvg_handle_set_base_uri            (RsvgHandle *handle,
                                                         const char *base_uri);
const char*         rsvg_handle_get_title               (RsvgHandle *handle);
const char*         rsvg_handle_get_desc                (RsvgHandle *handle);
void                rsvg_handle_get_dimensions          (RsvgHandle *handle,
                                                         RsvgDimensionData *dimension_data);
gboolean            rsvg_handle_get_dimensions_sub      (RsvgHandle *handle,
                                                         RsvgDimensionData *dimension_data,
                                                         const char *id);
gboolean            rsvg_handle_get_position_sub        (RsvgHandle *handle,
                                                         RsvgPositionData *position_data,
                                                         const char *id);
gboolean            rsvg_handle_has_sub                 (RsvgHandle *handle,
                                                         const char *id);

Description

librsvg is a component used within software applications to enable support for SVG-format scalable graphics. In contrast to raster formats, scalable vector graphics provide users and artists a way to create, view, and provide imagery that is not limited to the pixel or dot density that an output device is capable of.

Many software developers use the librsvg library to render SVG graphics. It is lightweight and portable.

Details

enum RsvgError

typedef enum {
    RSVG_ERROR_FAILED
} RsvgError;


RSVG_ERROR

#define             RSVG_ERROR


rsvg_error_quark ()

GQuark              rsvg_error_quark                    (void);

The error domain for RSVG

Returns :

The error domain

rsvg_init ()

void                rsvg_init                           (void);

Initializes librsvg

Since 2.9


rsvg_term ()

void                rsvg_term                           (void);

De-initializes librsvg

Since 2.9


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.

dpi :

Dots Per Inch (aka Pixels Per Inch)

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.

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.

Returns :

A new RsvgHandle

rsvg_handle_free ()

void                rsvg_handle_free                    (RsvgHandle *handle);

Warning

rsvg_handle_free is deprecated and should not be used in newly-written code. Use g_object_unref() instead.

Frees handle.

handle :

An RsvgHandle

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.

handle :

An RsvgHandle

dpi :

Dots Per Inch (aka Pixels Per Inch)

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.

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_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 RSVG_ERROR domain.

handle :

An RsvgHandle

buf :

Pointer to svg data

count :

length of the buf buffer in bytes

error :

return location for errors

Returns :

TRUE if the write was successful, or FALSE if there was an error.

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.

handle :

A RsvgHandle

error :

A GError

Returns :

TRUE if the loader closed successfully, or FALSE if there was an error.

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.

data :

The SVG data

data_len :

The length of data, in bytes

error :

return location for errors

Returns :

A RsvgHandle or NULL if an error occurs.

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.

file_name :

The file name to load. If built with gnome-vfs, can be a URI.

error :

return location for errors

Returns :

A RsvgHandle or NULL if an error occurs.

Since 2.14


RsvgDimensionData

typedef struct {
        /**
	 * SVG's width, in pixels
	 */
    int width;

        /**
	 * SVG's height, in pixels
	 */
    int height;

        /**
	 * em
	 */
    gdouble em;

        /**
	 * ex
	 */
    gdouble ex;
} RsvgDimensionData;


RsvgSizeFunc ()

void                (*RsvgSizeFunc)                     (gint *width,
                                                         gint *height,
                                                         gpointer user_data);

Warning

RsvgSizeFunc is deprecated and should not be used in newly-written code. Set up a cairo matrix and use rsvg_handle_render_cairo() instead.

Function to let a user of the library specify the SVG's dimensions width: the ouput width the SVG should be height: the output height the SVG should be user_data: user data

width :

Pointer to where to set/store the width

height :

Pointer to where to set/store the height

user_data :

User data pointer

rsvg_handle_set_size_callback ()

void                rsvg_handle_set_size_callback       (RsvgHandle *handle,
                                                         RsvgSizeFunc size_func,
                                                         gpointer user_data,
                                                         GDestroyNotify user_data_destroy);

Warning

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.

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.

handle :

An RsvgHandle

size_func :

A sizing function, or NULL

user_data :

User data to pass to size_func, or NULL

user_data_destroy :

Destroy function for user_data, or NULL

rsvg_handle_get_base_uri ()

const char*         rsvg_handle_get_base_uri            (RsvgHandle *handle);

Gets the base uri for this RsvgHandle.

handle :

A RsvgHandle

Returns :

the base uri, possibly null

Since 2.9 (really present in 2.8 as well)


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.

handle :

A RsvgHandle

base_uri :

The base uri

Since 2.9


rsvg_handle_get_title ()

const char*         rsvg_handle_get_title               (RsvgHandle *handle);

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.

handle :

An RsvgHandle

Returns :

The SVG's title

Since 2.4


rsvg_handle_get_desc ()

const char*         rsvg_handle_get_desc                (RsvgHandle *handle);

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.

handle :

An RsvgHandle

Returns :

The SVG's description

Since 2.4


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.

handle :

A RsvgHandle

dimension_data :

A place to store the SVG's size

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.

handle :

A RsvgHandle

dimension_data :

A place to store the SVG's size

id :

An element's id within the SVG, or NULL to get the dimension of the whole SVG. For example, if you have a layer called "layer1" for that you want to get the dimension, pass "layer1" as the id.

Returns :

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.

handle :

A RsvgHandle

position_data :

A place to store the SVG fragment's position.

id :

An element's id within the SVG. For example, if you have a layer called "layer1" for that you want to get the position, pass "layer1" as the id.

Returns :

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.

handle :

a RsvgHandle

id :

an element's id within the SVG

Returns :

TRUE if id exists in the SVG document

Since 2.22