RSVG Libary Reference Manual: RsvgHandle

## RsvgHandle RsvgHandle — Create and manipulate SVG objects |

## Functions

#define | RSVG_ERROR
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 ()
#define | RSVG_TYPE_ERROR
void | rsvg_init ()
void | rsvg_term ()
void | rsvg_handle_free ()
void | rsvg_handle_set_size_callback ()

## Properties

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

## Types and Values

enum | RsvgError
struct | RsvgHandle
typedef | RsvgHandlePrivate
struct | RsvgHandleClass
struct | RsvgDimensionData
struct | RsvgPositionData

## Object Hierarchy

        GEnum
        ╰── RsvgError
        GObject
        ╰── RsvgHandle

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

## Functions

### RSVG_ERROR

    #define             RSVG_ERROR

### rsvg_error_quark ()

    GQuark
    rsvg_error_quark (void);

The error domain for RSVG

#### Returns

The error domain

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

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

#### Returns

A new RsvgHandle

### rsvg_handle_new_with_flags ()

    RsvgHandle *
    rsvg_handle_new_with_flags (RsvgHandleFlags flags);

Creates a new RsvgHandle with flags `flags` .

#### Parameters

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.

#### Parameters

handle | an RsvgHandle |
buf | pointer to svg data. | [array length=count][element-type guchar]
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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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

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

#### Parameters

handle | An RsvgHandle |

#### Returns

The SVG's title.

[nullable]

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.

#### Parameters

handle | An RsvgHandle |

#### Returns

The SVG's description.

[nullable]

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.

#### Parameters

handle | An RsvgHandle |

#### Returns

The SVG's title.

[nullable]

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

#### Parameters

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

#### Parameters

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

`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 `NULL`. | [nullable]
user_data | User data to pass to `size_func` , or `NULL` |
user_data_destroy | Destroy function for `user_data` , or `NULL` |

## Types and Values

### enum RsvgError

An enumeration representing possible errors

#### Members

RSVG_ERROR_FAILED | the request failed |

### struct RsvgHandle

    struct RsvgHandle;

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

### RsvgHandlePrivate

### struct RsvgHandleClass

    struct RsvgHandleClass {
        GObjectClass parent;
    };

Class structure for RsvgHandle

#### Members

GObjectClass `parent`; | parent class |

### struct RsvgDimensionData

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

#### Members

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

Position of an SVG fragment.

#### Members

int `x`; | position on the x axis |
int `y`; | position on the y axis |

## Property Details

### The `“base-uri”` property

      “base-uri”                 gchar *

Base URI.

Flags: Read / Write / Construct

Default value: NULL

### The `“desc”` property

      “desc”                     gchar *

SVG's description

`RsvgHandle:desc` has been deprecated since version 2.36 and should not be used in newly-written code.

Flags: Read

Default value: NULL

### The `“dpi-x”` property

      “dpi-x”                    gdouble

Horizontal resolution.

Flags: Read / Write / Construct

Allowed values: >= 0

Default value: 90

### The `“dpi-y”` property

      “dpi-y”                    gdouble

Vertical resolution.

Flags: Read / Write / Construct

Allowed values: >= 0

Default value: 90

### The `“em”` property

      “em”                       gdouble

em.

Flags: Read

Allowed values: >= 0

Default value: 0

### The `“ex”` property

      “ex”                       gdouble

ex.

Flags: Read

Allowed values: >= 0

Default value: 0

### The `“flags”` property

      “flags”                    RsvgHandleFlags

Flags from RsvgHandleFlags.

Flags: Read / Write / Construct Only

Since 2.36

### The `“height”` property

      “height”                   gint

Image height.

Flags: Read

Allowed values: >= 0

Default value: 0

### The `“metadata”` property

      “metadata”                 gchar *

SVG's description

`RsvgHandle:metadata` has been deprecated since version 2.36 and should not be used in newly-written code.

Flags: Read

Default value: NULL

### The `“title”` property

      “title”                    gchar *

SVG's description

`RsvgHandle:title` has been deprecated since version 2.36 and should not be used in newly-written code.

Flags: Read

Default value: NULL

### The `“width”` property

      “width”                    gint

Image width.

Flags: Read

Allowed values: >= 0

Default value: 0