Optionalproperties: Partial<Rsvg.Handle.ConstructorProps>Internal$signalsCompile-time signal type information.
This instance property is generated only for TypeScript type checking. It is not defined at runtime and should not be accessed in JS code.
Static$gtypeBase URI, to be used to resolve relative references for resources. See the section "Security and locations of referenced files" for details.
Base URI, to be used to resolve relative references for resources. See the section "Security and locations of referenced files" for details.
Read-OnlydescHorizontal resolution in dots per inch.
The default is 90. Note that current CSS assumes a default of 96,
so you may want to set it to 96.0 before rendering the handle.
Horizontal resolution in dots per inch.
The default is 90. Note that current CSS assumes a default of 96,
so you may want to set it to 96.0 before rendering the handle.
Horizontal resolution in dots per inch.
The default is 90. Note that current CSS assumes a default of 96,
so you may want to set it to 96.0 before rendering the handle.
Horizontal resolution in dots per inch.
The default is 90. Note that current CSS assumes a default of 96,
so you may want to set it to 96.0 before rendering the handle.
Read-OnlyemExact width, in pixels, of the rendered SVG before calling the size callback as specified by Rsvg.Handle.set_size_callback.
since 2.46.: Reading each of the size properties causes the size of the SVG to be recomputed, so reading both the em and ex properties will cause two such computations. Please use Rsvg.Handle.get_intrinsic_dimensions instead.
Read-OnlyexExact height, in pixels, of the rendered SVG before calling the size callback as specified by Rsvg.Handle.set_size_callback.
since 2.46.: Reading each of the size properties causes the size of the SVG to be recomputed, so reading both the em and ex properties will cause two such computations. Please use Rsvg.Handle.get_intrinsic_dimensions instead.
Construct OnlySince 2.36flagsRead-OnlyheightHeight, in pixels, of the rendered SVG after calling the size callback as specified by Rsvg.Handle.set_size_callback.
since 2.46.: For historical reasons, this property is of integer type, which cannot give the exact size of SVG images that are not pixel-aligned. Moreover, reading each of the size properties causes the size of the SVG to be recomputed, so reading both the width and height properties will cause two such computations. Please use Rsvg.Handle.get_intrinsic_dimensions instead.
Read-OnlymetadataRead-OnlytitleRead-OnlywidthWidth, in pixels, of the rendered SVG after calling the size callback as specified by Rsvg.Handle.set_size_callback.
since 2.46.: For historical reasons, this property is of integer type, which cannot give the exact size of SVG images that are not pixel-aligned. Moreover, reading each of the size properties causes the size of the SVG to be recomputed, so reading both the width and height properties will cause two such computations. Please use Rsvg.Handle.get_intrinsic_dimensions instead.
This is used after calling Rsvg.Handle.write 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 Rsvg.Handle.write to feed data into the handle;
if you use the other methods like Rsvg.Handle.new_from_file or
Rsvg.Handle.read_stream_sync, 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
GObject.Object.unref is called.
TRUE on success, or FALSE on error.
SignalconnectSignalconnect_SignalemitFrees handle.
This function always returns NULL.
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 Rsvg.Handle's DPI to compute dimensions in pixels, so you should call Rsvg.Handle.set_dpi beforehand.
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 Rsvg.Handle's DPI to compute dimensions in pixels, so you should call Rsvg.Handle.set_dpi 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.
Optionalid: stringAn element's id within the SVG, starting with "#" (a single hash character), for example, #layer1. This notation corresponds to a URL's fragment ID. Alternatively, pass NULL to use the whole SVG.
TRUE if the dimensions could be obtained, FALSE if there was an error.
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.
Optionalid: stringAn element's id within the SVG, starting with "#" (a single hash character), for example, #layer1. This notation corresponds to a URL's fragment ID. Alternatively, pass NULL to compute the geometry for the whole SVG.
TRUE if the geometry could be obtained, or FALSE on error. Errors are returned in the error argument. 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.
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.
An element's id within the SVG, starting with "#" (a single hash character), for example, #layer1. This notation corresponds to a URL's fragment ID. Alternatively, pass NULL to compute the geometry for the whole SVG.
Viewport size at which the whole SVG would be fitted.
TRUE if the geometry could be obtained, or FALSE on error. Errors are returned in the error argument. 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.
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 Rsvg.Handle.render_document 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 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 Rsvg.Length 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.
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 Rsvg.Handle.set_dpi. 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.
For historical reasons, the default DPI is 90. Current CSS assumes a default DPI of 96, so you may want to set the DPI of a Rsvg.Handle immediately after creating it with Rsvg.Handle.set_dpi.
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
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 Rsvg.Handle.render_document.
TRUE if the dimensions could be converted directly to pixels; in this case out_width and out_height will be set accordingly. Note that the dimensions are floating-point numbers, so your application can know the exact size of an SVG document. To get integer dimensions, you should use ceil() to round up to the nearest integer (just using round(), may may chop off pixels with fractional coverage). If the dimensions cannot be converted to pixels, returns FALSE and puts 0.0 in both out_width and out_height.
This function always returns NULL.
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 Rsvg.Handle's dots-per-inch value (DPI) to compute the "natural size" of the document in pixels, so you should call Rsvg.Handle.set_dpi beforehand.
A pixbuf, or null on error during rendering.
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 Rsvg.Handle's dots-per-inch value (DPI) to compute the "natural size" of the document in pixels, so you should call Rsvg.Handle.set_dpi beforehand.
A pixbuf, or null on error during rendering.
Creates a GdkPixbuf.Pixbuf 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 Rsvg.Handle's dots-per-inch value (DPI) to compute the "natural size" of the document in pixels, so you should call Rsvg.Handle.set_dpi beforehand.
If you need to render an image which is only big enough to fit a particular sub-element of the SVG, consider using 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.
API ordering: This function must be called on a fully-loaded handle. See
the section "API ordering" for details.
Optionalid: stringAn element's id within the SVG, starting with "#" (a single hash character), for example, #layer1. This notation corresponds to a URL's fragment ID. Alternatively, pass NULL to use the whole SVG.
a pixbuf, or NULL if an error occurs during rendering.
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 Rsvg.Handle's DPI to compute dimensions in pixels, so you should call Rsvg.Handle.set_dpi 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.
Optionalid: stringAn element's id within the SVG, starting with "#" (a single hash character), for example, #layer1. This notation corresponds to a URL's fragment ID. Alternatively, pass null to use the whole SVG.
TRUE if the position could be obtained, FALSE if there was an error.
This function always returns NULL.
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.
An element's id within the SVG, starting with "#" (a single hash character), for example, #layer1. This notation corresponds to a URL's fragment ID.
TRUE if id exists in the SVG document, FALSE otherwise.
Do not call this function. This is intended for librsvg's internal test suite only.
Whether to enable testing mode
Reads stream and writes the data from it to handle.
Before calling this function, you may need to call Rsvg.Handle.set_base_uri
or Rsvg.Handle.set_base_gfile 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.
Optionalcancellable: Gio.Cancellablea Gio.Cancellable, or NULL
TRUE if reading stream succeeded, or FALSE otherwise with error filled in
Draws a loaded SVG handle to a Cairo context. Please try to use Rsvg.Handle.render_document 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 and height
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 with Rsvg.Handle.set_dpi. This is the same approach as
Rsvg.Handle.get_intrinsic_size_in_pixels.
Otherwise, if there is a viewBox attribute and both
width and height are set to
100% (or if they don't exist at all and thus default to 100%),
the function uses the width and height of the viewBox 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
and height 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 use Rsvg.Handle.render_document 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 Rsvg.Handle's DPI to compute dimensions in pixels, so you should call Rsvg.Handle.set_dpi 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.
TRUE if drawing succeeded; FALSE otherwise. This function will emit a g_warning() if a rendering error occurs.
Renders a single SVG element in the same place as for a whole SVG document (a "subset" of the document). Please try to use Rsvg.Handle.render_layer instead, which allows you to pick the size at which the document with the layer will be rendered.
This is equivalent to Rsvg.Handle.render_cairo, 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 and height
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 with Rsvg.Handle.set_dpi. This is the same approach as
Rsvg.Handle.get_intrinsic_size_in_pixels.
Otherwise, if there is a viewBox attribute and both
width and height are set to
100% (or if they don't exist at all and thus default to 100%),
the function uses the width and height of the viewBox 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
and height 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 use Rsvg.Handle.render_layer 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 Rsvg.Handle's DPI to compute dimensions in pixels, so you should call Rsvg.Handle.set_dpi 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.
TRUE if drawing succeeded; FALSE otherwise. This function will emit a g_warning() if a rendering error occurs.
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.
TRUE on success, FALSE on error. Errors are returned in the error argument. 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.
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 element_viewport. 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.
A Cairo context
An element's id within the SVG, starting with "#" (a single hash character), for example, #layer1. This notation corresponds to a URL's fragment ID. Alternatively, pass NULL to render the whole SVG document tree.
Viewport size in which to fit the element
TRUE on success, FALSE on error. Errors are returned in the error argument. 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.
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 Rsvg.Handle.render_document, 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.
A Cairo context
An element's id within the SVG, starting with "#" (a single hash character), for example, #layer1. This notation corresponds to a URL's fragment ID. Alternatively, pass NULL to render the whole SVG document tree.
Viewport size at which the whole SVG would be fitted.
TRUE on success, FALSE on error. Errors are returned in the error argument. 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.
Set the base URI for handle from file.
Note: This function may only be called before Rsvg.Handle.write or Rsvg.Handle.read_stream_sync have been called.
Set the base URI for this SVG.
Note: This function may only be called before Rsvg.Handle.write or Rsvg.Handle.read_stream_sync have been called.
The base uri
Sets a cancellable object that can be used to interrupt rendering
while the handle is being rendered in another thread. For example,
you can set a cancellable from your main thread, spawn a thread to
do the rendering, and interrupt the rendering from the main thread
by calling g_cancellable_cancel().
If rendering is interrupted, the corresponding call to
rsvg_handle_render_document() (or any of the other rendering
functions) will return an error with domain G_IO_ERROR, and code
G_IO_ERROR_CANCELLED.
Optionalcancellable: Gio.CancellableA Gio.Cancellable or NULL.
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 rsvg_set_default_dpi is deprecated, please
do not pass values <= 0 to this function.
Dots Per Inch (i.e. as Pixels Per Inch)
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 rsvg_set_default_dpi_x_y is deprecated,
please do not pass values <= 0 to this function.
Dots Per Inch (i.e. Pixels Per Inch)
Dots Per Inch (i.e. Pixels Per Inch)
Sets the sizing function for the handle, which can be used to override the
size that librsvg computes for SVG images. The size_func is called from the
following functions:
Librsvg computes the size of the SVG being rendered, and passes it to the
size_func, which may then modify these values to set the final size of the
generated image.
Optionalsize_func: SizeFuncA sizing function, or NULL
Sets a CSS stylesheet to use for an SVG document.
The css_len 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.
String with CSS data; must be valid UTF-8.
TRUE on success, FALSE on error. Errors are returned in the error argument.
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 Rsvg.Handle.close
to actually parse the document.
Before calling this function for the first time, you may need to call
Rsvg.Handle.set_base_uri or Rsvg.Handle.set_base_gfile 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.
pointer to svg data
TRUE on success, or FALSE on error.
StaticnewStaticnew_Staticnew_Staticnew_Optionalcancellable: Gio.CancellableStaticnew_Optionalcancellable: Gio.CancellableStaticnew_Creates a binding between source_property on source and target_property
on target.
Whenever the source_property is changed the target_property is
updated using the same value. For instance:
g_object_bind_property (action, "active", widget, "sensitive", 0);
Will result in the "sensitive" property of the widget GObject.Object instance to be updated with the same value of the "active" property of the action GObject.Object instance.
If flags contains GObject.BindingFlags.BIDIRECTIONAL then the binding will be mutual:
if target_property on target changes then the source_property on source
will be updated as well.
The binding will automatically be removed when either the source or the
target instances are finalized. To remove the binding without affecting the
source and the target you can just call g_object_unref() on the returned
GObject.Binding instance.
Removing the binding by calling g_object_unref() on it must only be done if
the binding, source and target are only used from a single thread and it
is clear that both source and target outlive the binding. Especially it
is not safe to rely on this if the binding, source or target can be
finalized from different threads. Keep another reference to the binding and
use g_binding_unbind() instead to be on the safe side.
A GObject.Object can have multiple bindings.
the property on source to bind
the target GObject.Object
the property on target to bind
flags to pass to GObject.Binding
the GObject.Binding instance representing the binding between the two GObject.Object instances. The binding is released whenever the GObject.Binding reference count reaches zero.
Complete version of g_object_bind_property().
Creates a binding between source_property on source and target_property
on target, allowing you to set the transformation functions to be used by
the binding.
If flags contains GObject.BindingFlags.BIDIRECTIONAL then the binding will be mutual:
if target_property on target changes then the source_property on source
will be updated as well. The transform_from function is only used in case
of bidirectional bindings, otherwise it will be ignored
The binding will automatically be removed when either the source or the
target instances are finalized. This will release the reference that is
being held on the GObject.Binding instance; if you want to hold on to the
GObject.Binding instance, you will need to hold a reference to it.
To remove the binding, call g_binding_unbind().
A GObject.Object can have multiple bindings.
The same user_data parameter will be used for both transform_to
and transform_from transformation functions; the notify function will
be called once, when the binding is removed. If you need different data
for each transformation function, please use
g_object_bind_property_with_closures() instead.
the property on source to bind
the target GObject.Object
the property on target to bind
flags to pass to GObject.Binding
Optionaltransform_to: BindingTransformFuncthe transformation function from the source to the target, or null to use the default
Optionaltransform_from: BindingTransformFuncthe transformation function from the target to the source, or null to use the default
Optionalnotify: DestroyNotifya function to call when disposing the binding, to free resources used by the transformation functions, or null if not required
the GObject.Binding instance representing the binding between the two GObject.Object instances. The binding is released whenever the GObject.Binding reference count reaches zero.
Creates a binding between source_property on source and target_property
on target, allowing you to set the transformation functions to be used by
the binding.
This function is the language bindings friendly version of
g_object_bind_property_full(), using GClosures instead of
function pointers.
the property on source to bind
the target GObject.Object
the property on target to bind
flags to pass to GObject.Binding
a GObject.Closure wrapping the transformation function from the source to the target, or null to use the default
a GObject.Closure wrapping the transformation function from the target to the source, or null to use the default
the GObject.Binding instance representing the binding between the two GObject.Object instances. The binding is released whenever the GObject.Binding reference count reaches zero.
Blocks a handler of an instance so it will not be called during any signal emissions
Handler ID of the handler to be blocked
Disconnects a handler from an instance so it will not be called during any future or currently ongoing emissions of the signal it has been connected to.
Handler ID of the handler to be disconnected
This function is intended for GObject.Object implementations to re-enforce
a [floating][floating-ref] object reference. Doing this is seldom
required: all GInitiallyUnowneds are created with a floating reference
which usually just needs to be sunken by calling g_object_ref_sink().
Increases the freeze count on object. If the freeze count is
non-zero, the emission of "notify" signals on object is
stopped. The signals are queued until the freeze count is decreased
to zero. Duplicate notifications are squashed so that at most one
GObject.Object::notify signal is emitted for each property modified while the
object is frozen.
This is necessary for accessors that modify multiple properties to prevent premature notification while the object is still being modified.
Gets a named field from the objects table of associations (see g_object_set_data()).
name of the key for that association
the data if found, or null if no such data exists.
Gets a property of an object.
The value can be:
In general, a copy is made of the property contents and the caller is responsible for freeing the memory by calling GObject.Value.unset.
Note that GObject.Object.get_property is really intended for language bindings, GObject.Object.get is much more convenient for C programming.
The name of the property to get
Return location for the property value. Can be an empty GObject.Value initialized by G_VALUE_INIT (auto-initialized with expected type since GLib 2.60), a GObject.Value initialized with the expected property type, or a GObject.Value initialized with a transformable type
This function gets back user data pointers stored via
g_object_set_qdata().
A GLib.Quark, naming the user data pointer
The user data pointer set, or null
Gets n_properties properties for an object.
Obtained properties will be set to values. All properties must be valid.
Warnings will be emitted and undefined behaviour may result if invalid
properties are passed in.
the names of each property to get
the values of each property to get
Checks whether object has a [floating][floating-ref] reference.
true if object has a floating reference
Emits a "notify" signal for the property property_name on object.
When possible, eg. when signaling a property change from within the class
that registered the property, you should use g_object_notify_by_pspec()
instead.
Note that emission of the notify signal may be blocked with
g_object_freeze_notify(). In this case, the signal emissions are queued
and will be emitted (in reverse order) when g_object_thaw_notify() is
called.
the name of a property installed on the class of object.
Emits a "notify" signal for the property specified by pspec on object.
This function omits the property name lookup, hence it is faster than
g_object_notify().
One way to avoid using g_object_notify() from within the
class that registered the properties, and using g_object_notify_by_pspec()
instead, is to store the GParamSpec used with
g_object_class_install_property() inside a static array, e.g.:
typedef enum
{
PROP_FOO = 1,
PROP_LAST
} MyObjectProperty;
static GParamSpec *properties[PROP_LAST];
static void
my_object_class_init (MyObjectClass *klass)
{
properties[PROP_FOO] = g_param_spec_int ("foo", NULL, NULL,
0, 100,
50,
G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
g_object_class_install_property (gobject_class,
PROP_FOO,
properties[PROP_FOO]);
}
and then notify a change on the "foo" property with:
g_object_notify_by_pspec (self, properties[PROP_FOO]);
the GObject.ParamSpec of a property installed on the class of object.
Increases the reference count of object.
Since GLib 2.56, if GLIB_VERSION_MAX_ALLOWED is 2.56 or greater, the type
of object will be propagated to the return type (using the GCC typeof()
extension), so any casting the caller needs to do on the return type must be
explicit.
the same object
Increase the reference count of object, and possibly remove the
[floating][floating-ref] reference, if object has a floating reference.
In other words, if the object is floating, then this call "assumes ownership" of the floating reference, converting it to a normal reference by clearing the floating flag while leaving the reference count unchanged. If the object is not floating, then this call adds a new normal reference increasing the reference count by one.
Since GLib 2.56, the type of object will be propagated to the return type
under the same conditions as for g_object_ref().
object
Releases all references to other objects. This can be used to break reference cycles.
This function should only be called from object system implementations.
Sets multiple properties of an object at once. The properties argument should be a dictionary mapping property names to values.
Object containing the properties to set
Each object carries around a table of associations from strings to pointers. This function lets you set an association.
If the object already had an association with that name, the old association will be destroyed.
Internally, the key is converted to a GLib.Quark using g_quark_from_string().
This means a copy of key is kept permanently (even after object has been
finalized) — so it is recommended to only use a small, bounded set of values
for key in your program, to avoid the GLib.Quark storage growing unbounded.
name of the key
Optionaldata: anydata to associate with that key
Sets a property on an object.
The name of the property to set
The value to set the property to
Remove a specified datum from the object's data associations, without invoking the association's destroy handler.
name of the key
the data if found, or null if no such data exists.
This function gets back user data pointers stored via
g_object_set_qdata() and removes the data from object
without invoking its destroy() function (if any was
set).
Usually, calling this function is only required to update
user data pointers with a destroy notifier, for example:
void
object_add_to_user_list (GObject *object,
const gchar *new_string)
{
// the quark, naming the object data
GQuark quark_string_list = g_quark_from_static_string ("my-string-list");
// retrieve the old string list
GList *list = g_object_steal_qdata (object, quark_string_list);
// prepend new string
list = g_list_prepend (list, g_strdup (new_string));
// this changed 'list', so we need to set it again
g_object_set_qdata_full (object, quark_string_list, list, free_string_list);
}
static void
free_string_list (gpointer data)
{
GList *node, *list = data;
for (node = list; node; node = node->next)
g_free (node->data);
g_list_free (list);
}
Using g_object_get_qdata() in the above example, instead of
g_object_steal_qdata() would have left the destroy function set,
and thus the partial string list would have been freed upon
g_object_set_qdata_full().
A GLib.Quark, naming the user data pointer
The user data pointer set, or null
Stops a signal's emission by the given signal name. This will prevent the default handler and any subsequent signal handlers from being invoked.
Name of the signal to stop emission of
Reverts the effect of a previous call to
g_object_freeze_notify(). The freeze count is decreased on object
and when it reaches zero, queued "notify" signals are emitted.
Duplicate notifications for each property are squashed so that at most one GObject.Object::notify signal is emitted for each property, in the reverse order in which they have been queued.
It is an error to call this function when the freeze count is zero.
Unblocks a handler so it will be called again during any signal emissions
Handler ID of the handler to be unblocked
Decreases the reference count of object. When its reference count
drops to 0, the object is finalized (i.e. its memory is freed).
If the pointer to the GObject.Object may be reused in future (for example, if it is
an instance variable of another object), it is recommended to clear the
pointer to null rather than retain a dangling pointer to a potentially
invalid GObject.Object instance. Use g_clear_object() for this.
Virtualvfunc_the constructed function is called by g_object_new() as the
final step of the object creation process. At the point of the call, all
construction properties have been set on the object. The purpose of this
call is to allow for object initialisation steps that can only be performed
after construction properties have been set. constructed implementors
should chain up to the constructed call of their parent class to allow it
to complete its initialisation.
Virtualvfunc_Virtualvfunc_the dispose function is supposed to drop all references to other
objects, but keep the instance otherwise intact, so that client method
invocations still work. It may be run multiple times (due to reference
loops). Before returning, dispose should chain up to the dispose method
of the parent class.
Virtualvfunc_instance finalization function, should finish the finalization of
the instance begun in dispose and chain up to the finalize method of the
parent class.
Virtualvfunc_Virtualvfunc_Emits a "notify" signal for the property property_name on object.
When possible, eg. when signaling a property change from within the class
that registered the property, you should use g_object_notify_by_pspec()
instead.
Note that emission of the notify signal may be blocked with
g_object_freeze_notify(). In this case, the signal emissions are queued
and will be emitted (in reverse order) when g_object_thaw_notify() is
called.
Virtualvfunc_the generic setter for all properties of this type. Should be
overridden for every type with properties. If implementations of
set_property don't emit property change notification explicitly, this will
be done implicitly by the type system. However, if the notify signal is
emitted explicitly, the type system will not emit it a second time.
This function essentially limits the life time of the closure to
the life time of the object. That is, when the object is finalized,
the closure is invalidated by calling g_closure_invalidate() on
it, in order to prevent invocations of the closure with a finalized
(nonexisting) object. Also, g_object_ref() and g_object_unref() are
added as marshal guards to the closure, to ensure that an extra
reference count is held on object during invocation of the
closure. Usually, this function will be called on closures that
use this object as closure data.
GObject.Closure to watch
Static_Staticcompat_Optionaldata: anyStaticfind_Staticinstall_Staticinstall_the id for the new property
the GObject.ParamSpec for the new property
Staticinterface_Find the GObject.ParamSpec with the given name for an
interface. Generally, the interface vtable passed in as g_iface
will be the default vtable from g_type_default_interface_ref(), or,
if you know the interface has already been loaded,
g_type_default_interface_peek().
any interface vtable for the interface, or the default vtable for the interface
name of a property to look up.
Staticinterface_Add a property to an interface; this is only useful for interfaces
that are added to GObject-derived types. Adding a property to an
interface forces all objects classes with that interface to have a
compatible property. The compatible property could be a newly
created GObject.ParamSpec, but normally
g_object_class_override_property() will be used so that the object
class only needs to provide an implementation and inherits the
property description, default value, bounds, and so forth from the
interface property.
This function is meant to be called from the interface's default
vtable initialization function (the class_init member of
GObject.TypeInfo.) It must not be called after after class_init has
been called for any object types implementing this interface.
If pspec is a floating reference, it will be consumed.
any interface vtable for the interface, or the default vtable for the interface.
the GObject.ParamSpec for the new property
Staticinterface_Lists the properties of an interface.Generally, the interface
vtable passed in as g_iface will be the default vtable from
g_type_default_interface_ref(), or, if you know the interface has
already been loaded, g_type_default_interface_peek().
any interface vtable for the interface, or the default vtable for the interface
Staticlist_StaticnewvStaticoverride_the new property ID
the name of a property registered in a parent class or in an interface of this class.
Rsvg.Handle loads an SVG document into memory.
This is the main entry point into the librsvg library. An Rsvg.Handle is an object that represents SVG data in memory. Your program creates an Rsvg.Handle from an SVG file, or from a memory buffer that contains SVG data, or in the most general form, from a Gio.InputStream 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.
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.svgand that it has an image element like this:In this case, librsvg needs to know the location of the toplevel
/foo/bar/foo.svgso 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.URLs with queries ("?") or fragment identifiers ("#") are not allowed.
All URL schemes other than data: in references require a base URL. For example, this means that if you load an SVG with Rsvg.Handle.new_from_data without calling Rsvg.Handle.set_base_uri, 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
filescheme, then all URL references inside the SVG must also have thefilescheme, or be relative references which will be resolved against the base URL.If referenced URLs have a
resourcescheme, 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-
fileschemes are not allowed. For example, librsvg will not loadhttpresources, to keep malicious SVG data from "phoning home".URLs with a
filescheme are rejected if they contain a hostname, as infile://hostname/some/directory/foo.svg. Windows UNC paths with a hostname are also rejected. This is to prevent documents from trying to access resources on other machines.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 Rsvg.Handle.
If you have a Gio.File that stands for an SVG file, you can simply call Rsvg.Handle.new_from_gfile_sync to load an Rsvg.Handle from it.
Alternatively, if you have a Gio.InputStream, you can use Rsvg.Handle.new_from_stream_sync.
Both of those methods allow specifying a Gio.Cancellable, 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 Gio.MemoryInputStream.new_from_data and feed that to Rsvg.Handle.new_from_stream_sync.
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 Rsvg.Handle 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. Also, note that this method does not let you specify Rsvg.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 Rsvg.Handle.new or Rsvg.Handle.new_with_flags, and then using Rsvg.Handle.write and Rsvg.Handle.close 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 Rsvg.Handle.set_dpi or Rsvg.Handle.set_dpi_x_y on an Rsvg.Handle to set the DPI before rendering it.For historical reasons, the default DPI is 90. Current CSS assumes a default DPI of 96, so you may want to set the DPI of a Rsvg.Handle immediately after creating it with Rsvg.Handle.set_dpi.
Rendering
The preferred way to render a whole SVG document is to use Rsvg.Handle.render_document. Please see its documentation for details.
API ordering
Due to the way the librsvg API evolved over time, an Rsvg.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 Rsvg.Handle just constructed with Rsvg.Handle.new is not loaded yet, and it does not make sense to call Rsvg.Handle.render_document on it just at that point.
The documentation for the available methods in Rsvg.Handle may mention that a particular method is only callable on a "fully loaded handle". This means either:
The handle was loaded with Rsvg.Handle.write and Rsvg.Handle.close, and those functions returned no errors.
The handle was loaded with Rsvg.Handle.read_stream_sync 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.