RsvgHandle

## RsvgHandle RsvgHandle — Create and manipulate SVG objects |

## Synopsis

    enum                RsvgError;
    #define             RSVG_ERROR
    GQuark              rsvg_error_quark                    (void);
                        RsvgHandle;
    typedef             RsvgHandlePrivate;
    struct              RsvgHandleClass;
    struct              RsvgDimensionData;
    struct              RsvgPositionData;
    void                rsvg_cleanup                        (void);
    void                rsvg_set_default_dpi                (double dpi);
    void                rsvg_set_default_dpi_x_y            (double dpi_x,
                                                             double dpi_y);
    void                rsvg_handle_set_dpi                 (RsvgHandle *handle,
                                                             double dpi);
    void                rsvg_handle_set_dpi_x_y             (RsvgHandle *handle,
                                                             double dpi_x,
                                                             double dpi_y);
    RsvgHandle *        rsvg_handle_new                     (void);
    RsvgHandle *        rsvg_handle_new_with_flags          (RsvgHandleFlags flags);
    gboolean            rsvg_handle_write                   (RsvgHandle *handle,
                                                             const guchar *buf,
                                                             gsize count,
                                                             GError **error);
    gboolean            rsvg_handle_close                   (RsvgHandle *handle,
                                                             GError **error);
    const char *        rsvg_handle_get_base_uri            (RsvgHandle *handle);
    void                rsvg_handle_set_base_uri            (RsvgHandle *handle,
                                                             const char *base_uri);
    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);
    const char *        rsvg_handle_get_title               (RsvgHandle *handle);
    const char *        rsvg_handle_get_desc                (RsvgHandle *handle);
    const char *        rsvg_handle_get_metadata            (RsvgHandle *handle);
    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);
    GType               rsvg_error_get_type                 (void);
    #define             RSVG_TYPE_ERROR

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

## Object Hierarchy

      GEnum
       +----RsvgError

      GObject
       +----RsvgHandle

## Properties

      "base-uri"                 gchar*                : Read / Write / Construct
      "desc"                     gchar*                : Read
      "dpi-x"                    gdouble               : Read / Write / Construct
      "dpi-y"                    gdouble               : Read / Write / Construct
      "em"                       gdouble               : Read
      "ex"                       gdouble               : Read
      "flags"                    RsvgHandleFlags       : Read / Write / Construct Only
      "height"                   gint                  : Read
      "metadata"                 gchar*                : Read
      "title"                    gchar*                : Read
      "width"                    gint                  : Read

## 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;

An enumeration representing possible error domains

`RSVG_ERROR_FAILED` |

### RSVG_ERROR

    #define RSVG_ERROR (rsvg_error_quark ())

### rsvg_error_quark ()

    GQuark              rsvg_error_quark                    (void);

The error domain for RSVG

Returns : | The error domain

### RsvgHandle

    typedef struct _RsvgHandle RsvgHandle;

The RsvgHandle is an object representing the parsed form of a SVG

### RsvgHandlePrivate

    typedef struct RsvgHandlePrivate RsvgHandlePrivate;

### struct RsvgHandleClass

    struct RsvgHandleClass {
        GObjectClass parent;

        gpointer _abi_padding[15];
    };

### struct RsvgDimensionData

    struct RsvgDimensionData {
        int width;
        int height;
        gdouble em;
        gdouble ex;
    };

int `width`; | SVG's width, in pixels
int `height`; | SVG's height, in pixels
gdouble `em`; | em
gdouble `ex`; | ex

### struct RsvgPositionData

    struct RsvgPositionData {
        int x;
        int y;
    };

### 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.

`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_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_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_new_with_flags ()

    RsvgHandle *        rsvg_handle_new_with_flags          (RsvgHandleFlags flags);

Creates a new RsvgHandle with flags `flags`.

`flags` : | flags from RsvgHandleFlags
Returns : | a new RsvgHandle. [transfer full]

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.

`handle` : | an RsvgHandle
`buf` : | pointer to svg data. [array length=count][element-type guint8]
`count` : | length of the `buf` buffer in bytes
`error` : | a location to store a GError, or `NULL`. [allow-none]
Returns : | `TRUE` on success, or `FALSE` on 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 location to store a GError, or `NULL`. [allow-none]
Returns : | `TRUE` on success, or `FALSE` on error

### 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.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.

`handle` : | A RsvgHandle
`base_uri` : | The base uri

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.

`handle` : | A RsvgHandle
`dimension_data` : | A place to store the SVG's size. [out]

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. [out]
`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.

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. [out]
`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.

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

### rsvg_handle_get_title ()

    const char *        rsvg_handle_get_title               (RsvgHandle *handle);

### Warning

`rsvg_handle_get_title` is deprecated and should not be used in newly-written code. 2.36

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);

### Warning

`rsvg_handle_get_desc` is deprecated and should not be used in newly-written code. 2.36

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_metadata ()

    const char *        rsvg_handle_get_metadata            (RsvgHandle *handle);

### Warning

`rsvg_handle_get_metadata` is deprecated and should not be used in newly-written code. 2.36

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.

`handle` : | An RsvgHandle
Returns : | The SVG's title

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.

`data` : | The SVG data. [array length=data_len]
`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

### rsvg_error_get_type ()

    GType               rsvg_error_get_type                 (void);

### RSVG_TYPE_ERROR

    #define RSVG_TYPE_ERROR (rsvg_error_get_type())

### rsvg_init ()

    void                rsvg_init                           (void);

### Warning

`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);

### Warning

`rsvg_term` is deprecated and should not be used in newly-written code. 2.36

This function does nothing.

Since 2.9

### 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_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`

## Property Details

### The `"base-uri"` property

      "base-uri"                 gchar*                : Read / Write / Construct

Base URI.

Default value: NULL

### The `"desc"` property

      "desc"                     gchar*                : Read

### Warning

`RsvgHandle:desc` is deprecated and should not be used in newly-written code. 2.36

SVG's description

Default value: NULL

### The `"dpi-x"` property

      "dpi-x"                    gdouble               : Read / Write / Construct

Horizontal resolution.

Allowed values: >= 0

Default value: 90

### The `"dpi-y"` property

      "dpi-y"                    gdouble               : Read / Write / Construct

Vertical resolution.

Allowed values: >= 0

Default value: 90

### The `"em"` property

      "em"                       gdouble               : Read

em.

Allowed values: >= 0

Default value: 0

### The `"ex"` property

      "ex"                       gdouble               : Read

ex.

Allowed values: >= 0

Default value: 0

### The `"flags"` property

      "flags"                    RsvgHandleFlags       : Read / Write / Construct Only

Flags from RsvgHandleFlags.

Since 2.36

### The `"height"` property

      "height"                   gint                  : Read

Image height.

Allowed values: >= 0

Default value: 0

### The `"metadata"` property

      "metadata"                 gchar*                : Read

### Warning

`RsvgHandle:metadata` is deprecated and should not be used in newly-written code. 2.36

SVG's description

Default value: NULL

### The `"title"` property

      "title"                    gchar*                : Read

### Warning

`RsvgHandle:title` is deprecated and should not be used in newly-written code. 2.36

SVG's description

Default value: NULL

### The `"width"` property

      "width"                    gint                  : Read

Image width.

Allowed values: >= 0

Default value: 0