diff options
author | Federico Mena Quintero <federico@gnome.org> | 2019-07-24 12:37:20 -0500 |
---|---|---|
committer | Federico Mena Quintero <federico@gnome.org> | 2019-07-24 12:37:20 -0500 |
commit | 15b76e0d6dda850dc8ea4617812ad636926c022a (patch) | |
tree | d064d6a4b0bcc461cede911c5317c994e0f82efd /librsvg/rsvg-handle.c | |
parent | a0409e5024b75bb86908af8951bdd943f0fc940c (diff) | |
download | librsvg-15b76e0d6dda850dc8ea4617812ad636926c022a.tar.gz |
Be more explicit at how to pass fragment ids for the _sub() functions
Diffstat (limited to 'librsvg/rsvg-handle.c')
-rw-r--r-- | librsvg/rsvg-handle.c | 60 |
1 files changed, 43 insertions, 17 deletions
diff --git a/librsvg/rsvg-handle.c b/librsvg/rsvg-handle.c index bfa6ccd3..f8c02e19 100644 --- a/librsvg/rsvg-handle.c +++ b/librsvg/rsvg-handle.c @@ -787,9 +787,9 @@ rsvg_handle_get_desc (RsvgHandle *handle) * rsvg_handle_render_cairo_sub: * @handle: A #RsvgHandle * @cr: A Cairo context - * @id: (nullable): An element's id within the SVG, or %NULL to render - * the whole SVG. For example, if you have a layer called "layer1" - * that you wish to render, pass "##layer1" as the id. + * @id: (nullable): 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. * * Draws a subset of a loaded SVG handle to a Cairo context. Drawing will occur with * respect to the @cr's current transformation: for example, if the @cr has a @@ -801,6 +801,10 @@ rsvg_handle_get_desc (RsvgHandle *handle) * 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 <literal>foo</literal>) to get the geometry of the element that + * has an <literal>id="foo"</literal> attribute. + * * Returns: %TRUE if drawing succeeded; %FALSE otherwise. * Since: 2.14 */ @@ -859,12 +863,17 @@ rsvg_handle_get_dimensions (RsvgHandle *handle, RsvgDimensionData *dimension_dat * rsvg_handle_get_dimensions_sub: * @handle: A #RsvgHandle * @dimension_data: (out): A place to store the SVG's size - * @id: (nullable): An element's id within the SVG, starting with "##", for - * example, "##layer1"; or %NULL to use the whole SVG. + * @id: (nullable): 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 use the whole SVG. * * 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. * + * Element IDs should look like an URL fragment identifier; for example, pass + * "##foo" (hash <literal>foo</literal>) to get the geometry of the element that + * has an <literal>id="foo"</literal> attribute. + * * Deprecated: 2.46. Use rsvg_handle_get_geometry_for_element() instead. * * Since: 2.22 @@ -884,12 +893,17 @@ rsvg_handle_get_dimensions_sub (RsvgHandle *handle, * rsvg_handle_get_position_sub: * @handle: A #RsvgHandle * @position_data: (out): A place to store the SVG fragment's position. - * @id: (nullable): An element's id within the SVG, starting with "##", for - * example, "##layer1"; or %NULL to use the whole SVG. + * @id: (nullable): 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 use the whole SVG. * * 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. * + * Element IDs should look like an URL fragment identifier; for example, pass + * "##foo" (hash <literal>foo</literal>) to get the geometry of the element that + * has an <literal>id="foo"</literal> attribute. + * * Deprecated: 2.46. Use rsvg_handle_get_geometry_for_element() instead. * * Since: 2.22 @@ -908,11 +922,17 @@ rsvg_handle_get_position_sub (RsvgHandle *handle, /** * rsvg_handle_has_sub: * @handle: a #RsvgHandle - * @id: an element's id within the SVG, starting with "##", for example, "##layer1". + * @id: 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. * * Checks whether the element @id exists in the SVG document. * - * Returns: %TRUE if @id exists in the SVG document + * Element IDs should look like an URL fragment identifier; for example, pass + * "##foo" (hash <literal>foo</literal>) to get the geometry of the element that + * has an <literal>id="foo"</literal> attribute. + * + * Returns: %TRUE if @id exists in the SVG document, %FALSE otherwise. * * Since: 2.22 */ @@ -927,8 +947,9 @@ rsvg_handle_has_sub (RsvgHandle *handle, const char *id) /** * rsvg_handle_get_pixbuf_sub: * @handle: An #RsvgHandle - * @id: (nullable): An element's id within the SVG, starting with "##", for - * example, "##layer1"; or %NULL to use the whole SVG. + * @id: (nullable): 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 use the whole SVG. * * 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 @@ -941,6 +962,10 @@ rsvg_handle_has_sub (RsvgHandle *handle, const char *id) * You will need to offset the rendering by the amount returned in * rsvg_handle_get_position_sub(). * + * Element IDs should look like an URL fragment identifier; for example, pass + * "##foo" (hash <literal>foo</literal>) to get the geometry of the element that + * has an <literal>id="foo"</literal> attribute. + * * Returns: (transfer full) (nullable): a pixbuf, or %NULL if an error occurs * during rendering. * @@ -1146,9 +1171,10 @@ rsvg_handle_get_intrinsic_dimensions (RsvgHandle *handle, /** * rsvg_handle_get_geometry_for_element: * @handle: An #RsvgHandle - * @id: (nullable): An element's id within the SVG, or %NULL to compute - * the geometry for the whole SVG. For example, if you have a layer called "layer1" - * that you wish to render, pass "##layer1" as the id. + * @id: (nullable): 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: Viewport size at which the whole SVG would be fitted. * @out_ink_rect: (out)(optional): Place to store the ink rectangle of the element. * @out_logical_rect: (out)(optional): Place to store the logical rectangle of the element. @@ -1157,9 +1183,9 @@ rsvg_handle_get_intrinsic_dimensions (RsvgHandle *handle, * 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" to get the geometry of the - * element that has an <literal>id="foo"</literal> attribute. + * Element IDs should look like an URL fragment identifier; for example, pass + * "##foo" (hash <literal>foo</literal>) to get the geometry of the element that + * has an <literal>id="foo"</literal> attribute. * * The "ink rectangle" is the bounding box that would be painted * for fully- stroked and filled elements. |