[librsvg: 6/9] Clarify which functions require the base file to be set beforehand
- From: Federico Mena Quintero <federico src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [librsvg: 6/9] Clarify which functions require the base file to be set beforehand
- Date: Wed, 24 Jul 2019 17:56:54 +0000 (UTC)
commit 56d9a440a71665f6d5e4ee5e06ed15461a7f96a3
Author: Federico Mena Quintero <federico gnome org>
Date: Wed Jul 24 12:47:06 2019 -0500
Clarify which functions require the base file to be set beforehand
librsvg/rsvg-handle.c | 45 +++++++++++++++++++++++++++++++++++----------
1 file changed, 35 insertions(+), 10 deletions(-)
---
diff --git a/librsvg/rsvg-handle.c b/librsvg/rsvg-handle.c
index f8c02e19..365e29e0 100644
--- a/librsvg/rsvg-handle.c
+++ b/librsvg/rsvg-handle.c
@@ -521,6 +521,10 @@ rsvg_handle_new_with_flags (RsvgHandleFlags flags)
*
* Creates a new #RsvgHandle for @file.
*
+ * This function sets the "base file" of the handle to be @file itself, so SVG
+ * elements like <literal><image></literal> which reference external
+ * resources will be resolved relative to the location of @file.
+ *
* 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
@@ -553,6 +557,10 @@ rsvg_handle_new_from_gfile_sync (GFile *file,
*
* Creates a new #RsvgHandle for @stream.
*
+ * This function sets the "base file" of the handle to be @base_file if
+ * provided. SVG elements like <literal><image></literal> which reference
+ * external resources will be resolved relative to the location of @base_file.
+ *
* 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
@@ -590,14 +598,20 @@ rsvg_handle_new_from_stream_sync (GInputStream *input_stream,
*
* Loads the next @count bytes of the image.
*
+ * 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
+ * <literal><image></literal> which reference external resources will be
+ * resolved relative to the location you specify with those functions.
+ *
* Returns: %TRUE on success, or %FALSE on error.
*
* Deprecated: 2.46. Use rsvg_handle_read_stream_sync() or the constructor
- * functions rsvg_handle_new_from_gfile_sync() or rsvg_handle_new_from_stream_sync().
- *
- * Notes: This function will accumlate data from the @buf in memory until
- * rsvg_handle_close() gets called. To avoid a big temporary buffer, use the
- * funtions listed before, which take a #GFile or a #GInputStream.
+ * functions rsvg_handle_new_from_gfile_sync() or
+ * rsvg_handle_new_from_stream_sync(). This function is deprecated because it
+ * will accumlate data from the @buf in memory until rsvg_handle_close() gets
+ * called. To avoid a big temporary buffer, use the suggested funtions, which
+ * take a #GFile or a #GInputStream and do not require a temporary buffer.
**/
gboolean
rsvg_handle_write (RsvgHandle *handle, const guchar *buf, gsize count, GError **error)
@@ -622,7 +636,9 @@ rsvg_handle_write (RsvgHandle *handle, const guchar *buf, gsize count, GError **
* Returns: %TRUE on success, or %FALSE on error.
*
* Deprecated: 2.46. Use rsvg_handle_read_stream_sync() or the constructor
- * functions rsvg_handle_new_from_gfile_sync() or rsvg_handle_new_from_stream_sync().
+ * functions rsvg_handle_new_from_gfile_sync() or
+ * rsvg_handle_new_from_stream_sync(). See the deprecation notes for
+ * rsvg_handle_write() for more information.
**/
gboolean
rsvg_handle_close (RsvgHandle *handle, GError **error)
@@ -642,6 +658,12 @@ rsvg_handle_close (RsvgHandle *handle, GError **error)
*
* 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
+ * <literal><image></literal> 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
@@ -674,8 +696,10 @@ rsvg_handle_read_stream_sync (RsvgHandle *handle,
* @handle: A #RsvgHandle
* @base_uri: The base uri
*
- * Set the base URI for this SVG. This can only be called before rsvg_handle_write()
- * has 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.
*
* Since: 2.9
*/
@@ -694,8 +718,9 @@ rsvg_handle_set_base_uri (RsvgHandle *handle, const char *base_uri)
* @base_file: a #GFile
*
* 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() has been called.
+ *
+ * Note: This function may only be called before rsvg_handle_write() or
+ * rsvg_handle_read_stream_sync() have been called.
*
* Since: 2.32
*/
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]