Class: Rsvg::Handle

Inherits:
Object
  • Object
show all
Defined in:
lib/rsvg2/handle.rb

Overview

Class structure for [classRsvg.Handle].

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Rsvg::Handle

Creates a new [classRsvg.Handle] with flags flags. After calling this function, you can feed the resulting handle with SVG data by using [methodRsvg.Handle.read_stream_sync].

Parameters:



32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
 
# File 'lib/rsvg2/handle.rb', line 32

def initialize(options={})
  flags = options[:flags]
  path = options[:path] || options[:file]
  data = options[:data]

  if path
    if flags
      Gio::File.open(:path => path) do |file|
        initialize_new_from_gfile_sync(file, flags)
      end
    else
      initialize_new_from_file(path)
    end
  elsif data
    initialize_new_from_data(data)
  else
    initialize_raw
  end
end

Class Method Details

.new_from_data(data) ⇒ Object

For backward compatibility



21
22
23
 
# File 'lib/rsvg2/handle.rb', line 21

def new_from_data(data)
  new(:data => data)
end

.new_from_file(file_name, options = {}) ⇒ Object

For backward compatibility



26
27
28
 
# File 'lib/rsvg2/handle.rb', line 26

def new_from_file(file_name, options={})
  new(options.merge(:file => file_name))
end

Instance Method Details

#base_gfile=(base_file) ⇒ nil

Set the base URI for handle from file.

Note: This function may only be called before [methodRsvg.Handle.write] or [methodRsvg.Handle.read_stream_sync] have been called.

Parameters:

  • base_file (Gio::File) —

    a GFile

Returns:

  • (nil)

#base_uri ⇒ String

Base URI, to be used to resolve relative references for resources. See the section "Security and locations of referenced files" for details.

Returns:

  • (String) —

    base-uri

#base_uri=(base_uri) ⇒ String

Base URI, to be used to resolve relative references for resources. See the section "Security and locations of referenced files" for details.

Parameters:

  • base_uri (String)

Returns:

  • (String) —

    base-uri

  • (String) —

    base-uri

#close ⇒ Boolean

This is used after calling [methodRsvg.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 [methodRsvg.Handle.write] to feed data into the handle; if you use the other methods like [ctorRsvg.Handle.new_from_file] or [methodRsvg.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 [methodGObject.Object.unref] is called.

Returns:

  • (Boolean) —

    TRUE on success, or FALSE on error.

#desc ⇒ String

SVG's description.

Returns:

  • (String) —

    desc

#desc=(desc) ⇒ String

SVG's description.

Parameters:

  • desc (String)

Returns:

  • (String) —

    desc

  • (String) —

    desc

#dpi=(dpi) ⇒ nil

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 [idrsvg_set_default_dpi] is deprecated, please do not pass values <= 0 to this function.

Parameters:

  • dpi (Float) —

    Dots Per Inch (i.e. as Pixels Per Inch)

Returns:

  • (nil)

#dpi_x ⇒ Float

Horizontal resolution in dots per inch.

Returns:

  • (Float) —

    dpi-x

#dpi_x=(dpi_x) ⇒ Float

Horizontal resolution in dots per inch.

Parameters:

  • dpi_x (Float)

Returns:

  • (Float) —

    dpi-x

  • (Float) —

    dpi-x

#dpi_y ⇒ Float

Horizontal resolution in dots per inch.

Returns:

  • (Float) —

    dpi-y

#dpi_y=(dpi_y) ⇒ Float

Horizontal resolution in dots per inch.

Parameters:

  • dpi_y (Float)

Returns:

  • (Float) —

    dpi-y

  • (Float) —

    dpi-y

#em ⇒ Float

Exact width, in pixels, of the rendered SVG before calling the size callback as specified by [methodRsvg.Handle.set_size_callback].

Returns:

  • (Float) —

    em

#em=(em) ⇒ Float

Exact width, in pixels, of the rendered SVG before calling the size callback as specified by [methodRsvg.Handle.set_size_callback].

Parameters:

  • em (Float)

Returns:

  • (Float) —

    em

  • (Float) —

    em

#ex ⇒ Float

Exact height, in pixels, of the rendered SVG before calling the size callback as specified by [methodRsvg.Handle.set_size_callback].

Returns:

  • (Float) —

    ex

#ex=(ex) ⇒ Float

Exact height, in pixels, of the rendered SVG before calling the size callback as specified by [methodRsvg.Handle.set_size_callback].

Parameters:

  • ex (Float)

Returns:

  • (Float) —

    ex

  • (Float) —

    ex

#flags ⇒ Rsvg::HandleFlags

Flags from [flagsRsvg.HandleFlags].

Returns:

#flags=(flags) ⇒ Rsvg::HandleFlags

Flags from [flagsRsvg.HandleFlags].

Parameters:

Returns:

#free ⇒ nil

Frees handle.

Returns:

  • (nil)

#get_dimensions(dimension_data) ⇒ nil

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 [classRsvg.Handle]'s DPI to compute dimensions in pixels, so you should call [methodRsvg.Handle.set_dpi] beforehand.

Parameters:

Returns:

  • (nil)

#get_dimensions_sub(dimension_data, id) ⇒ Boolean

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 [classRsvg.Handle]'s DPI to compute dimensions in pixels, so you should call [methodRsvg.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. hash character), for example, #layer1. This notation corresponds to a URL's fragment ID. Alternatively, pass NULL to use the whole SVG.

Parameters:

  • dimension_data (Rsvg::DimensionData) —

    A place to store the SVG's size

  • id (String) —

    An element's id within the SVG, starting with "#" (a single

Returns:

  • (Boolean) —

    TRUE if the dimensions could be obtained, FALSE if there was an error.

#get_geometry_for_element(id, out_ink_rect, out_logical_rect) ⇒ Boolean

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

Parameters:

  • id (String) —

    An element's id within the SVG, starting with "#" (a single

  • out_ink_rect (Rsvg::Rectangle) —

    Place to store the ink rectangle of the element.

  • out_logical_rect (Rsvg::Rectangle) —

    Place to store the logical rectangle of the element.

Returns:

  • (Boolean) —

    TRUE if the geometry could be obtained, or FALSE on error. Errors

#get_geometry_for_layer(id, viewport, out_ink_rect, out_logical_rect) ⇒ Boolean

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

Parameters:

  • id (String) —

    An element's id within the SVG, starting with "#" (a single

  • viewport (Rsvg::Rectangle) —

    Viewport size at which the whole SVG would be fitted.

  • out_ink_rect (Rsvg::Rectangle) —

    Place to store the ink rectangle of the element.

  • out_logical_rect (Rsvg::Rectangle) —

    Place to store the logical rectangle of the element.

Returns:

  • (Boolean) —

    TRUE if the geometry could be obtained, or FALSE on error. Errors

#get_intrinsic_dimensions(out_has_width, out_width, out_has_height, out_height, out_has_viewbox, out_viewbox) ⇒ nil

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

Parameters:

  • out_has_width (Boolean) —

    Will be set to TRUE; see below.

  • out_width (Rsvg::Length) —

    Will be set to the computed value of the width property in the toplevel SVG.

  • out_has_height (Boolean) —

    Will be set to TRUE; see below.

  • out_height (Rsvg::Length) —

    Will be set to the computed value of the height property in the toplevel SVG.

  • out_has_viewbox (Boolean) —

    Will be set to TRUE if the toplevel SVG has a viewBox attribute

  • out_viewbox (Rsvg::Rectangle) —

    Will be set to the value of the viewBox attribute in the toplevel SVG

Returns:

  • (nil)

#get_intrinsic_size_in_pixels(out_width, out_height) ⇒ Boolean

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

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 viewport to be resolved to a final size. In this case, the function returns 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 [methodRsvg.Handle.render_document]. 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.

Parameters:

  • out_width (Float) —

    Will be set to the computed width; you should round this up to get integer pixels.

  • out_height (Float) —

    Will be set to the computed height; you should round this up to get integer pixels.

Returns:

  • (Boolean) —

    TRUE if the dimensions could be converted directly to pixels; in this case

#get_pixbuf_sub(id) ⇒ GdkPixbuf::Pixbuf

Creates a GdkPixbuf 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 [classRsvg.Handle]'s dots-per-inch value (DPI) to compute the "natural size" of the document in pixels, so you should call [methodRsvg.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 [methodRsvg.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. hash character), for example, #layer1. This notation corresponds to a URL's fragment ID. Alternatively, pass NULL to use the whole SVG. during rendering.

Parameters:

  • id (String) —

    An element's id within the SVG, starting with "#" (a single

Returns:

  • (GdkPixbuf::Pixbuf) —

    a pixbuf, or NULL if an error occurs

#get_position_sub(position_data, id) ⇒ Boolean

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 [classRsvg.Handle]'s DPI to compute dimensions in pixels, so you should call [methodRsvg.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. hash character), for example, #layer1. This notation corresponds to a URL's fragment ID. Alternatively, pass nil to use the whole SVG.

Parameters:

  • position_data (Rsvg::PositionData) —

    A place to store the SVG fragment's position.

  • id (String) —

    An element's id within the SVG, starting with "#" (a single

Returns:

  • (Boolean) —

    TRUE if the position could be obtained, FALSE if there was an error.

#has_sub(id) ⇒ Boolean

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. character), for example, #layer1. This notation corresponds to a URL's fragment ID.

Parameters:

  • id (String) —

    An element's id within the SVG, starting with "#" (a single hash

Returns:

  • (Boolean) —

    TRUE if id exists in the SVG document, FALSE otherwise.

#height ⇒ Integer

Height, in pixels, of the rendered SVG after calling the size callback as specified by [methodRsvg.Handle.set_size_callback].

Returns:

  • (Integer) —

    height

#height=(height) ⇒ Integer

Height, in pixels, of the rendered SVG after calling the size callback as specified by [methodRsvg.Handle.set_size_callback].

Parameters:

  • height (Integer)

Returns:

  • (Integer) —

    height

  • (Integer) —

    height

#initialize_raw ⇒ Rsvg::Handle

Creates a new [classRsvg.Handle] with flags flags. After calling this function, you can feed the resulting handle with SVG data by using [methodRsvg.Handle.read_stream_sync].

Parameters:

Returns:




# File 'lib/rsvg2/handle.rb', line 31

#internal_set_testing(testing) ⇒ nil

Do not call this function. This is intended for librsvg's internal test suite only.

Parameters:

  • testing (Boolean) —

    Whether to enable testing mode

Returns:

  • (nil)

#metadata ⇒ String

SVG's metadata

Returns:

  • (String) —

    metadata

#metadata=(metadata) ⇒ String

SVG's metadata

Parameters:

  • metadata (String)

Returns:

  • (String) —

    metadata

  • (String) —

    metadata

#pixbuf ⇒ GdkPixbuf::Pixbuf

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 [classRsvg.Handle]'s dots-per-inch value (DPI) to compute the "natural size" of the document in pixels, so you should call [methodRsvg.Handle.set_dpi] beforehand. during rendering.

Returns:

  • (GdkPixbuf::Pixbuf) —

    A pixbuf, or nil on error.

#read_stream_sync(stream, cancellable) ⇒ Boolean

Reads stream and writes the data from it to handle.

Before calling this function, you may need to call [methodRsvg.Handle.set_base_uri] or [methodRsvg.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.

Parameters:

  • stream (Gio::InputStream) —

    a GInputStream

  • cancellable (Gio::Cancellable) —

    a GCancellable, or NULL

Returns:

  • (Boolean) —

    TRUE if reading stream succeeded, or FALSE otherwise with error filled in

#render_cairo(cr) ⇒ Boolean

Draws a loaded SVG handle to a Cairo context. Please try to use [methodRsvg.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 [methodRsvg.Handle.set_dpi]. This is the same approach as [methodRsvg.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 [methodRsvg.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 [classRsvg.Handle]'s DPI to compute dimensions in pixels, so you should call [methodRsvg.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. if a rendering error occurs.

Parameters:

  • cr (cairo::Context) —

    A Cairo context

Returns:

  • (Boolean) —

    TRUE if drawing succeeded; FALSE otherwise. This function will emit a g_warning()

#render_cairo_sub(cr, id) ⇒ Boolean

Renders a single SVG element in the same place as for a whole SVG document (a "subset" of the document). Please try to use [methodRsvg.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 [methodRsvg.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 [methodRsvg.Handle.set_dpi]. This is the same approach as [methodRsvg.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 [methodRsvg.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 [classRsvg.Handle]'s DPI to compute dimensions in pixels, so you should call [methodRsvg.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. hash character), for example, #layer1. This notation corresponds to a URL's fragment ID. Alternatively, pass NULL to render the whole SVG. if a rendering error occurs.

Parameters:

  • cr (cairo::Context) —

    A Cairo context

  • id (String) —

    An element's id within the SVG, starting with "#" (a single

Returns:

  • (Boolean) —

    TRUE if drawing succeeded; FALSE otherwise. This function will emit a g_warning()

#render_document(cr, viewport) ⇒ Boolean

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

Parameters:

  • cr (cairo::Context) —

    A Cairo context

  • viewport (Rsvg::Rectangle) —

    Viewport size at which the whole SVG would be fitted.

Returns:

  • (Boolean) —

    TRUE on success, FALSE on error. Errors are returned

#render_element(cr, id, element_viewport) ⇒ Boolean

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. hash character), for example, #layer1. This notation corresponds to a URL's fragment ID. Alternatively, pass NULL to render the whole SVG document tree. 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.

Parameters:

  • cr (cairo::Context) —

    A Cairo context

  • id (String) —

    An element's id within the SVG, starting with "#" (a single

  • element_viewport (Rsvg::Rectangle) —

    Viewport size in which to fit the element

Returns:

  • (Boolean) —

    TRUE on success, FALSE on error. Errors are returned

#render_layer(cr, id, viewport) ⇒ Boolean

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 [methodRsvg.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. hash character), for example, #layer1. This notation corresponds to a URL's fragment ID. Alternatively, pass NULL to render the whole SVG document tree. 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.

Parameters:

  • cr (cairo::Context) —

    A Cairo context

  • id (String) —

    An element's id within the SVG, starting with "#" (a single

  • viewport (Rsvg::Rectangle) —

    Viewport size at which the whole SVG would be fitted.

Returns:

  • (Boolean) —

    TRUE on success, FALSE on error. Errors are returned

#set_dpi_x_y(dpi_x, dpi_y) ⇒ nil

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 [idrsvg_set_default_dpi_x_y] is deprecated, please do not pass values <= 0 to this function.

Parameters:

  • dpi_x (Float) —

    Dots Per Inch (i.e. Pixels Per Inch)

  • dpi_y (Float) —

    Dots Per Inch (i.e. Pixels Per Inch)

Returns:

  • (nil)

#set_size_callback(size_func, user_data, user_data_destroy) ⇒ nil

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:

  • [methodRsvg.Handle.get_dimensions]
  • [methodRsvg.Handle.get_dimensions_sub]
  • [methodRsvg.Handle.get_position_sub]
  • [methodRsvg.Handle.render_cairo]
  • [methodRsvg.Handle.render_cairo_sub]

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.

Parameters:

  • size_func (Rsvg::SizeFunc) —

    A sizing function, or NULL

  • user_data (GObject) —

    User data to pass to size_func, or NULL

  • user_data_destroy (GLib::DestroyNotify) —

    Function to be called to destroy the data passed in user_data, or NULL.

Returns:

  • (nil)

#set_stylesheet(css, css_len) ⇒ Boolean

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 <b>import</b> rules will not be resolved, except for data: URLs. in the error argument.

Parameters:

  • css (Array<Integer>) —

    String with CSS data; must be valid UTF-8.

  • css_len (Integer) —

    Length of the css data in bytes.

Returns:

  • (Boolean) —

    TRUE on success, FALSE on error. Errors are returned

#title ⇒ String

SVG's title.

Returns:

  • (String) —

    title

#title=(title) ⇒ String

SVG's title.

Parameters:

  • title (String)

Returns:

  • (String) —

    title

  • (String) —

    title

#width ⇒ Integer

Width, in pixels, of the rendered SVG after calling the size callback as specified by [methodRsvg.Handle.set_size_callback].

Returns:

  • (Integer) —

    width

#width=(width) ⇒ Integer

Width, in pixels, of the rendered SVG after calling the size callback as specified by [methodRsvg.Handle.set_size_callback].

Parameters:

  • width (Integer)

Returns:

  • (Integer) —

    width

  • (Integer) —

    width

#write(buf, count) ⇒ Boolean

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 [methodRsvg.Handle.close] to actually parse the document.

Before calling this function for the first time, you may need to call [methodRsvg.Handle.set_base_uri] or [methodRsvg.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.

Parameters:

  • buf (Array<Integer>) —

    pointer to svg data

  • count (Integer) —

    length of the buf buffer in bytes

Returns:

  • (Boolean) —

    TRUE on success, or FALSE on error.