From f2a11232efeb7372256634c5e0f8c8e2aa161f9e Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Sun, 21 Mar 2021 12:29:51 +0000 Subject: docs: Update gdk-pixbuf-io style --- gdk-pixbuf/gdk-pixbuf-io.c | 585 ++++++++++++++++++++++++--------------------- 1 file changed, 313 insertions(+), 272 deletions(-) (limited to 'gdk-pixbuf') diff --git a/gdk-pixbuf/gdk-pixbuf-io.c b/gdk-pixbuf/gdk-pixbuf-io.c index 13bf5af16..eb442e3bc 100644 --- a/gdk-pixbuf/gdk-pixbuf-io.c +++ b/gdk-pixbuf/gdk-pixbuf-io.c @@ -52,16 +52,16 @@ * @module_name: the name of the module, usually the same as the * usual file extension for images of this type, eg. "xpm", "jpeg" or "png". * @module_path: the path from which the module is loaded. - * @module: the loaded #GModule. - * @info: a #GdkPixbufFormat holding information about the module. + * @module: the loaded `GModule`. + * @info: a `GdkPixbufFormat` holding information about the module. * @load: loads an image from a file. * @load_xpm_data: loads an image from data in memory. * @begin_load: begins an incremental load. * @stop_load: stops an incremental load. * @load_increment: continues an incremental load. * @load_animation: loads an animation from a file. - * @save: saves a #GdkPixbuf to a file. - * @save_to_callback: saves a #GdkPixbuf by calling the given #GdkPixbufSaveFunc. + * @save: saves a `GdkPixbuf` to a file. + * @save_to_callback: saves a `GdkPixbuf` by calling the given `GdkPixbufSaveFunc`. * @is_save_option_supported: returns whether a save option key is supported by the module * * A `GdkPixbufModule` contains the necessary functions to load and save @@ -557,10 +557,10 @@ gdk_pixbuf_io_init_modules (const char *filename, /** * gdk_pixbuf_init_modules: - * @path: Path to directory where the loaders.cache is installed - * @error: return location for a #GError + * @path: Path to directory where the `loaders.cache` is installed + * @error: return location for a `GError` * - * Initalizes the gdk-pixbuf loader modules referenced by the loaders.cache + * Initalizes the gdk-pixbuf loader modules referenced by the `loaders.cache` * file present inside that directory. * * This is to be used by applications that want to ship certain loaders @@ -1080,20 +1080,26 @@ _gdk_pixbuf_generic_image_load (GdkPixbufModule *module, FILE *f, GError **error } /** - * gdk_pixbuf_new_from_file: + * gdk_pixbuf_new_from_file: (constructor) * @filename: (type filename): Name of file to load, in the GLib file - * name encoding - * @error: Return location for an error + * name encoding + * @error: (out): Return location for an error * - * Creates a new pixbuf by loading an image from a file. The file format is - * detected automatically. If %NULL is returned, then @error will be set. - * Possible errors are in the #GDK_PIXBUF_ERROR and #G_FILE_ERROR domains. + * Creates a new pixbuf by loading an image from a file. * - * Return value: A newly-created pixbuf with a reference count of 1, or %NULL if - * any of several error conditions occurred: the file could not be opened, - * there was no loader for the file's format, there was not enough memory to - * allocate the image buffer, or the image file contained invalid data. - **/ + * The file format is detected automatically. + * + * If `NULL` is returned, then @error will be set. Possible errors are: + * + * - the file could not be opened + * - there is no loader for the file's format + * - there is not enough memory to allocate the image buffer + * - the image buffer contains invalid data + * + * The error domains are `GDK_PIXBUF_ERROR` and `G_FILE_ERROR`. + * + * Return value: (transfer full) (nullable): A newly-created pixbuf + */ GdkPixbuf * gdk_pixbuf_new_from_file (const char *filename, GError **error) @@ -1179,7 +1185,7 @@ gdk_pixbuf_new_from_file (const char *filename, * * Same as gdk_pixbuf_new_from_file() * - * Return value: A newly-created pixbuf with a reference count of 1, or %NULL if + * Return value: A newly-created pixbuf with a reference count of 1, or `NULL` if * any of several error conditions occurred: the file could not be opened, * there was no loader for the file's format, there was not enough memory to * allocate the image buffer, or the image file contained invalid data. @@ -1195,29 +1201,33 @@ gdk_pixbuf_new_from_file_utf8 (const char *filename, /** - * gdk_pixbuf_new_from_file_at_size: + * gdk_pixbuf_new_from_file_at_size: (constructor) * @filename: (type filename): Name of file to load, in the GLib file * name encoding * @width: The width the image should have or -1 to not constrain the width * @height: The height the image should have or -1 to not constrain the height - * @error: Return location for an error + * @error: (out): Return location for an error + * + * Creates a new pixbuf by loading an image from a file. * - * Creates a new pixbuf by loading an image from a file. - * The file format is detected automatically. If %NULL is returned, then - * @error will be set. Possible errors are in the #GDK_PIXBUF_ERROR and - * #G_FILE_ERROR domains. + * The file format is detected automatically. + * + * If `NULL` is returned, then @error will be set. Possible errors are: + * + * - the file could not be opened + * - there is no loader for the file's format + * - there is not enough memory to allocate the image buffer + * - the image buffer contains invalid data + * + * The error domains are `GDK_PIXBUF_ERROR` and `G_FILE_ERROR`. * * The image will be scaled to fit in the requested size, preserving * the image's aspect ratio. Note that the returned pixbuf may be smaller - * than @width x @height, if the aspect ratio requires it. To load + * than `width` x `height`, if the aspect ratio requires it. To load * and image at the requested size, regardless of aspect ratio, use - * gdk_pixbuf_new_from_file_at_scale(). + * [ctor@GdkPixbuf.Pixbuf.new_from_file_at_scale]. * - * Return value: A newly-created pixbuf with a reference count of 1, or - * %NULL if any of several error conditions occurred: the file could not - * be opened, there was no loader for the file's format, there was not - * enough memory to allocate the image buffer, or the image file contained - * invalid data. + * Return value: (transfer full) (nullable): A newly-created pixbuf * * Since: 2.4 **/ @@ -1244,7 +1254,7 @@ gdk_pixbuf_new_from_file_at_size (const char *filename, * Same as gdk_pixbuf_new_from_file_at_size() * * Return value: A newly-created pixbuf with a reference count of 1, or - * %NULL if any of several error conditions occurred: the file could not + * `NULL` if any of several error conditions occurred: the file could not * be opened, there was no loader for the file's format, there was not * enough memory to allocate the image buffer, or the image file contained * invalid data. @@ -1318,31 +1328,38 @@ at_scale_size_prepared_cb (GdkPixbufLoader *loader, } /** - * gdk_pixbuf_new_from_file_at_scale: + * gdk_pixbuf_new_from_file_at_scale: (constructor) * @filename: (type filename): Name of file to load, in the GLib file * name encoding * @width: The width the image should have or -1 to not constrain the width * @height: The height the image should have or -1 to not constrain the height - * @preserve_aspect_ratio: %TRUE to preserve the image's aspect ratio + * @preserve_aspect_ratio: `TRUE` to preserve the image's aspect ratio * @error: Return location for an error * - * Creates a new pixbuf by loading an image from a file. The file format is - * detected automatically. If %NULL is returned, then @error will be set. - * Possible errors are in the #GDK_PIXBUF_ERROR and #G_FILE_ERROR domains. + * Creates a new pixbuf by loading an image from a file. + * + * The file format is detected automatically. + * + * If `NULL` is returned, then @error will be set. Possible errors are: + * + * - the file could not be opened + * - there is no loader for the file's format + * - there is not enough memory to allocate the image buffer + * - the image buffer contains invalid data + * + * The error domains are `GDK_PIXBUF_ERROR` and `G_FILE_ERROR`. + * * The image will be scaled to fit in the requested size, optionally preserving * the image's aspect ratio. * - * When preserving the aspect ratio, a @width of -1 will cause the image - * to be scaled to the exact given height, and a @height of -1 will cause + * When preserving the aspect ratio, a `width` of -1 will cause the image + * to be scaled to the exact given height, and a `height` of -1 will cause * the image to be scaled to the exact given width. When not preserving - * aspect ratio, a @width or @height of -1 means to not scale the image - * at all in that dimension. Negative values for @width and @height are + * aspect ratio, a `width` or `height` of -1 means to not scale the image + * at all in that dimension. Negative values for `width` and `height` are * allowed since 2.8. * - * Return value: A newly-created pixbuf with a reference count of 1, or %NULL - * if any of several error conditions occurred: the file could not be opened, - * there was no loader for the file's format, there was not enough memory to - * allocate the image buffer, or the image file contained invalid data. + * Return value: (transfer full) (nullable): A newly-created pixbuf * * Since: 2.6 **/ @@ -1447,12 +1464,12 @@ gdk_pixbuf_new_from_file_at_scale (const char *filename, * @filename: (type filename): Name of file to load, in the GLib file name encoding * @width: The width the image should have or -1 to not constrain the width * @height: The height the image should have or -1 to not constrain the height - * @preserve_aspect_ratio: %TRUE to preserve the image's aspect ratio + * @preserve_aspect_ratio: `TRUE` to preserve the image's aspect ratio * @error: Return location for an error * * Same as gdk_pixbuf_new_from_file_at_scale(). * - * Return value: A newly-created pixbuf with a reference count of 1, or %NULL + * Return value: A newly-created pixbuf with a reference count of 1, or `NULL` * if any of several error conditions occurred: the file could not be opened, * there was no loader for the file's format, there was not enough memory to * allocate the image buffer, or the image file contained invalid data. @@ -1517,40 +1534,37 @@ load_from_stream (GdkPixbufLoader *loader, /** - * gdk_pixbuf_new_from_stream_at_scale: - * @stream: a #GInputStream to load the pixbuf from + * gdk_pixbuf_new_from_stream_at_scale: (constructor) + * @stream: a `GInputStream` to load the pixbuf from * @width: The width the image should have or -1 to not constrain the width * @height: The height the image should have or -1 to not constrain the height - * @preserve_aspect_ratio: %TRUE to preserve the image's aspect ratio - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @preserve_aspect_ratio: `TRUE` to preserve the image's aspect ratio + * @cancellable: (allow-none): optional `GCancellable` object, `NULL` to ignore * @error: Return location for an error * * Creates a new pixbuf by loading an image from an input stream. * - * The file format is detected automatically. If %NULL is returned, then + * The file format is detected automatically. If `NULL` is returned, then * @error will be set. The @cancellable can be used to abort the operation * from another thread. If the operation was cancelled, the error - * %G_IO_ERROR_CANCELLED will be returned. Other possible errors are in - * the #GDK_PIXBUF_ERROR and %G_IO_ERROR domains. + * `G_IO_ERROR_CANCELLED` will be returned. Other possible errors are in + * the `GDK_PIXBUF_ERROR` and `G_IO_ERROR` domains. * * The image will be scaled to fit in the requested size, optionally * preserving the image's aspect ratio. * - * When preserving the aspect ratio, a @width of -1 will cause the image to be - * scaled to the exact given height, and a @height of -1 will cause the image - * to be scaled to the exact given width. If both @width and @height are + * When preserving the aspect ratio, a `width` of -1 will cause the image to be + * scaled to the exact given height, and a `height` of -1 will cause the image + * to be scaled to the exact given width. If both `width` and `height` are * given, this function will behave as if the smaller of the two values * is passed as -1. * - * When not preserving aspect ratio, a @width or @height of -1 means to not + * When not preserving aspect ratio, a `width` or `height` of -1 means to not * scale the image at all in that dimension. * * The stream is not closed. * - * Return value: A newly-created pixbuf, or %NULL if any of several error - * conditions occurred: the file could not be opened, the image format is - * not supported, there was not enough memory to allocate the image buffer, - * the stream contained invalid data, or the operation was cancelled. + * Return value: (transfer full) (nullable): A newly-created pixbuf * * Since: 2.14 */ @@ -1633,12 +1647,12 @@ out: /** * gdk_pixbuf_new_from_stream_at_scale_async: - * @stream: a #GInputStream from which to load the pixbuf + * @stream: a `GInputStream` from which to load the pixbuf * @width: the width the image should have or -1 to not constrain the width * @height: the height the image should have or -1 to not constrain the height - * @preserve_aspect_ratio: %TRUE to preserve the image's aspect ratio - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: a #GAsyncReadyCallback to call when the pixbuf is loaded + * @preserve_aspect_ratio: `TRUE` to preserve the image's aspect ratio + * @cancellable: (allow-none): optional `GCancellable` object, `NULL` to ignore + * @callback: a `GAsyncReadyCallback` to call when the pixbuf is loaded * @user_data: the data to pass to the callback function * * Creates a new pixbuf by asynchronously loading an image from an input stream. @@ -1694,25 +1708,25 @@ gdk_pixbuf_new_from_stream_at_scale_async (GInputStream *stream, } /** - * gdk_pixbuf_new_from_stream: - * @stream: a #GInputStream to load the pixbuf from - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * gdk_pixbuf_new_from_stream: (constructor) + * @stream: a `GInputStream` to load the pixbuf from + * @cancellable: (allow-none): optional `GCancellable` object, `NULL` to ignore * @error: Return location for an error * * Creates a new pixbuf by loading an image from an input stream. * - * The file format is detected automatically. If %NULL is returned, then - * @error will be set. The @cancellable can be used to abort the operation - * from another thread. If the operation was cancelled, the error - * %G_IO_ERROR_CANCELLED will be returned. Other possible errors are in - * the #GDK_PIXBUF_ERROR and %G_IO_ERROR domains. + * The file format is detected automatically. + * + * If `NULL` is returned, then `error` will be set. + * + * The `cancellable` can be used to abort the operation from another thread. + * If the operation was cancelled, the error `G_IO_ERROR_CANCELLED` will be + * returned. Other possible errors are in the `GDK_PIXBUF_ERROR` and + * `G_IO_ERROR` domains. * * The stream is not closed. * - * Return value: A newly-created pixbuf, or %NULL if any of several error - * conditions occurred: the file could not be opened, the image format is - * not supported, there was not enough memory to allocate the image buffer, - * the stream contained invalid data, or the operation was cancelled. + * Return value: (transfer full) (nullable): A newly-created pixbuf * * Since: 2.14 **/ @@ -1770,19 +1784,16 @@ G_GNUC_END_IGNORE_DEPRECATIONS } /** - * gdk_pixbuf_new_from_resource: + * gdk_pixbuf_new_from_resource: (constructor) * @resource_path: the path of the resource file * @error: Return location for an error * * Creates a new pixbuf by loading an image from an resource. * - * The file format is detected automatically. If %NULL is returned, then + * The file format is detected automatically. If `NULL` is returned, then * @error will be set. * - * Return value: A newly-created pixbuf, or %NULL if any of several error - * conditions occurred: the file could not be opened, the image format is - * not supported, there was not enough memory to allocate the image buffer, - * the stream contained invalid data, or the operation was cancelled. + * Return value: (transfer full) (nullable): A newly-created pixbuf * * Since: 2.26 **/ @@ -1807,16 +1818,16 @@ gdk_pixbuf_new_from_resource (const gchar *resource_path, } /** - * gdk_pixbuf_new_from_resource_at_scale: + * gdk_pixbuf_new_from_resource_at_scale: (constructor) * @resource_path: the path of the resource file * @width: The width the image should have or -1 to not constrain the width * @height: The height the image should have or -1 to not constrain the height - * @preserve_aspect_ratio: %TRUE to preserve the image's aspect ratio + * @preserve_aspect_ratio: `TRUE` to preserve the image's aspect ratio * @error: Return location for an error * * Creates a new pixbuf by loading an image from an resource. * - * The file format is detected automatically. If %NULL is returned, then + * The file format is detected automatically. If `NULL` is returned, then * @error will be set. * * The image will be scaled to fit in the requested size, optionally @@ -1828,10 +1839,7 @@ gdk_pixbuf_new_from_resource (const gchar *resource_path, * * The stream is not closed. * - * Return value: A newly-created pixbuf, or %NULL if any of several error - * conditions occurred: the file could not be opened, the image format is - * not supported, there was not enough memory to allocate the image buffer, - * the stream contained invalid data, or the operation was cancelled. + * Return value: (transfer full) (nullable): A newly-created pixbuf * * Since: 2.26 */ @@ -1856,9 +1864,9 @@ gdk_pixbuf_new_from_resource_at_scale (const char *resource_path, /** * gdk_pixbuf_new_from_stream_async: - * @stream: a #GInputStream from which to load the pixbuf - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: a #GAsyncReadyCallback to call when the pixbuf is loaded + * @stream: a `GInputStream` from which to load the pixbuf + * @cancellable: (allow-none): optional `GCancellable` object, `NULL` to ignore + * @callback: a `GAsyncReadyCallback` to call when the pixbuf is loaded * @user_data: the data to pass to the callback function * * Creates a new pixbuf by asynchronously loading an image from an input stream. @@ -1867,7 +1875,8 @@ gdk_pixbuf_new_from_resource_at_scale (const char *resource_path, * version of this function. * * When the operation is finished, @callback will be called in the main thread. - * You can then call gdk_pixbuf_new_from_stream_finish() to get the result of the operation. + * You can then call gdk_pixbuf_new_from_stream_finish() to get the result of + * the operation. * * Since: 2.24 **/ @@ -1897,14 +1906,13 @@ gdk_pixbuf_new_from_stream_async (GInputStream *stream, /** * gdk_pixbuf_new_from_stream_finish: - * @async_result: a #GAsyncResult - * @error: a #GError, or %NULL + * @async_result: a `GAsyncResult` + * @error: a `GError`, or `NULL` * * Finishes an asynchronous pixbuf creation operation started with * gdk_pixbuf_new_from_stream_async(). * - * Return value: a #GdkPixbuf or %NULL on error. Free the returned - * object with g_object_unref(). + * Return value: (transfer full) (nullable): the newly created pixbuf * * Since: 2.24 **/ @@ -1949,17 +1957,13 @@ info_cb (GdkPixbufLoader *loader, /** * gdk_pixbuf_get_file_info: * @filename: (type filename): The name of the file to identify. - * @width: (optional) (out): Return location for the width of the - * image, or %NULL - * @height: (optional) (out): Return location for the height of the - * image, or %NULL + * @width: (optional) (out): Return location for the width of the image + * @height: (optional) (out): Return location for the height of the image * * Parses an image file far enough to determine its format and size. * - * Returns: (nullable) (transfer none): A #GdkPixbufFormat describing - * the image format of the file or %NULL if the image format wasn't - * recognized. The return value is owned by #GdkPixbuf and should - * not be freed. + * Returns: (nullable) (transfer none): A `GdkPixbufFormat` describing + * the image format of the file * * Since: 2.4 **/ @@ -2051,8 +2055,8 @@ get_file_info_thread (GTask *task, /** * gdk_pixbuf_get_file_info_async: * @filename: (type filename): The name of the file to identify - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: a #GAsyncReadyCallback to call when the file info is available + * @cancellable: (allow-none): optional `GCancellable` object, `NULL` to ignore + * @callback: a `GAsyncReadyCallback` to call when the file info is available * @user_data: the data to pass to the callback function * * Asynchronously parses an image file far enough to determine its @@ -2093,18 +2097,16 @@ gdk_pixbuf_get_file_info_async (const gchar *filename, /** * gdk_pixbuf_get_file_info_finish: - * @async_result: a #GAsyncResult - * @width: (out): Return location for the width of the image, or %NULL - * @height: (out): Return location for the height of the image, or %NULL - * @error: a #GError, or %NULL + * @async_result: a `GAsyncResult` + * @width: (out): Return location for the width of the image, or `NULL` + * @height: (out): Return location for the height of the image, or `NULL` + * @error: a `GError`, or `NULL` * * Finishes an asynchronous pixbuf parsing operation started with * gdk_pixbuf_get_file_info_async(). * - * Returns: (transfer none): A #GdkPixbufFormat describing the image - * format of the file or %NULL if the image format wasn't - * recognized. The return value is owned by GdkPixbuf and should - * not be freed. + * Returns: (transfer none) (nullable): A `GdkPixbufFormat` describing the + * image format of the file * * Since: 2.32 **/ @@ -2140,10 +2142,12 @@ gdk_pixbuf_get_file_info_finish (GAsyncResult *async_result, * gdk_pixbuf_new_from_xpm_data: * @data: (array zero-terminated=1): Pointer to inline XPM data. * - * Creates a new pixbuf by parsing XPM data in memory. This data is commonly - * the result of including an XPM file into a program's C source. + * Creates a new pixbuf by parsing XPM data in memory. + * + * This data is commonly the result of including an XPM file into a + * program's C source. * - * Return value: A newly-created pixbuf with a reference count of 1. + * Return value: A newly-created pixbuf **/ GdkPixbuf * gdk_pixbuf_new_from_xpm_data (const char **data) @@ -2404,18 +2408,18 @@ gdk_pixbuf_real_save_to_callback (GdkPixbuf *pixbuf, /** * gdk_pixbuf_save: - * @pixbuf: a #GdkPixbuf. + * @pixbuf: a `GdkPixbuf`. * @filename: (type filename): name of file to save. * @type: name of file format. - * @error: (allow-none): return location for error, or %NULL - * @...: list of key-value save options, followed by %NULL + * @error: (nullable): return location for error + * @...: list of key-value save options, followed by `NULL` * * Saves pixbuf to a file in format @type. By default, "jpeg", "png", "ico" * and "bmp" are possible file formats to save in, but more formats may be * installed. The list of all writable formats can be determined in the * following way: * - * |[ + * ```c * void add_if_writable (GdkPixbufFormat *data, GSList **list) * { * if (gdk_pixbuf_format_is_writable (data)) @@ -2426,55 +2430,63 @@ gdk_pixbuf_real_save_to_callback (GdkPixbuf *pixbuf, * GSList *writable_formats = NULL; * g_slist_foreach (formats, add_if_writable, &writable_formats); * g_slist_free (formats); - * ]| + * ``` * - * If @error is set, %FALSE will be returned. Possible errors include - * those in the #GDK_PIXBUF_ERROR domain and those in the #G_FILE_ERROR domain. + * If `error` is set, `FALSE` will be returned. Possible errors include + * those in the `GDK_PIXBUF_ERROR` domain and those in the `G_FILE_ERROR` + * domain. * - * The variable argument list should be %NULL-terminated; if not empty, + * The variable argument list should be `NULL`-terminated; if not empty, * it should contain pairs of strings that modify the save * parameters. For example: - * |[ + * + * ```c * gdk_pixbuf_save (pixbuf, handle, "jpeg", &error, "quality", "100", NULL); - * ]| + * ``` * - * Currently only few parameters exist. JPEG images can be saved with a - * "quality" parameter; its value should be in the range [0,100]. JPEG - * and PNG density can be set by setting the "x-dpi" and "y-dpi" parameters - * to the appropriate values in dots per inch. + * Currently only few parameters exist. + * + * JPEG images can be saved with a "quality" parameter; its value should be + * in the range `[0, 100]`. JPEG and PNG density can be set by setting the + * "x-dpi" and "y-dpi" parameters to the appropriate values in dots per inch. * * Text chunks can be attached to PNG images by specifying parameters of * the form "tEXt::key", where key is an ASCII string of length 1-79. * The values are UTF-8 encoded strings. The PNG compression level can * be specified using the "compression" parameter; it's value is in an - * integer in the range of [0,9]. + * integer in the range of `[0, 9]`. * * ICC color profiles can also be embedded into PNG, JPEG and TIFF images. * The "icc-profile" value should be the complete ICC profile encoded * into base64. * - * |[ - * gchar *contents; - * gchar *contents_encode; + * ```c + * char *contents; * gsize length; - * g_file_get_contents ("/home/hughsie/.color/icc/L225W.icm", &contents, &length, NULL); - * contents_encode = g_base64_encode ((const guchar *) contents, length); + * + * // icm_path is set elsewhere + * g_file_get_contents (icm_path, &contents, &length, NULL); + * + * char *contents_encode = g_base64_encode ((const guchar *) contents, length); + * * gdk_pixbuf_save (pixbuf, handle, "png", &error, "icc-profile", contents_encode, NULL); - * ]| + * ``` * - * TIFF images recognize: (1) a "bits-per-sample" option (integer) which - * can be either 1 for saving bi-level CCITTFAX4 images, or 8 for saving - * 8-bits per sample; (2) a "compression" option (integer) which can be - * 1 for no compression, 2 for Huffman, 5 for LZW, 7 for JPEG and 8 for - * DEFLATE (see the libtiff documentation and tiff.h for all supported - * codec values); (3) an "icc-profile" option (zero-terminated string) - * containing a base64 encoded ICC color profile. + * TIFF images recognize: + * + * 1. a "bits-per-sample" option (integer) which can be either 1 for saving + * bi-level CCITTFAX4 images, or 8 for saving 8-bits per sample + * 2. a "compression" option (integer) which can be 1 for no compression, + * 2 for Huffman, 5 for LZW, 7 for JPEG and 8 for DEFLATE (see the libtiff + * documentation and tiff.h for all supported codec values) + * 3. an "icc-profile" option (zero-terminated string) containing a base64 + * encoded ICC color profile. * * ICO images can be saved in depth 16, 24, or 32, by using the "depth" * parameter. When the ICO saver is given "x_hot" and "y_hot" parameters, * it produces a CUR instead of an ICO. * - * Return value: whether an error was set + * Return value: `TRUE` on success, and `FALSE` otherwise **/ gboolean gdk_pixbuf_save (GdkPixbuf *pixbuf, @@ -2508,16 +2520,20 @@ gdk_pixbuf_save (GdkPixbuf *pixbuf, /** * gdk_pixbuf_savev: - * @pixbuf: a #GdkPixbuf. + * @pixbuf: a `GdkPixbuf`. * @filename: (type filename): name of file to save. * @type: name of file format. - * @option_keys: (array zero-terminated=1): name of options to set, %NULL-terminated - * @option_values: (array zero-terminated=1): values for named options - * @error: (allow-none): return location for error, or %NULL + * @option_keys: (array zero-terminated=1) (element-type utf8) (nullable): name of options to set + * @option_values: (array zero-terminated=1) (element-type utf8) (nullable): values for named options + * @error: (allow-none): return location for error, or `NULL` + * + * Vector version of `gdk_pixbuf_save()`. + * + * Saves pixbuf to a file in `type`, which is currently "jpeg", "png", "tiff", "ico" or "bmp". * - * Saves pixbuf to a file in @type, which is currently "jpeg", "png", "tiff", "ico" or "bmp". - * If @error is set, %FALSE will be returned. - * See gdk_pixbuf_save () for more details. + * If @error is set, `FALSE` will be returned. + * + * See [method@GdkPixbuf.Pixbuf.save] for more details. * * Return value: whether an error was set **/ @@ -2589,12 +2605,12 @@ gdk_pixbuf_savev (GdkPixbuf *pixbuf, /** * gdk_pixbuf_savev_utf8: - * @pixbuf: a #GdkPixbuf. + * @pixbuf: a `GdkPixbuf`. * @filename: name of file to save. * @type: name of file format. - * @option_keys: (array zero-terminated=1): name of options to set, %NULL-terminated - * @option_values: (array zero-terminated=1): values for named options - * @error: (allow-none): return location for error, or %NULL + * @option_keys: (array zero-terminated=1) (element-type utf8) (nullable): name of options to set + * @option_values: (array zero-terminated=1) (element-type utf8) (nullable): values for named options + * @error: (allow-none): return location for error, or `NULL` * * Same as gdk_pixbuf_savev() * @@ -2616,22 +2632,25 @@ gdk_pixbuf_savev_utf8 (GdkPixbuf *pixbuf, /** * gdk_pixbuf_save_to_callback: - * @pixbuf: a #GdkPixbuf. + * @pixbuf: a `GdkPixbuf`. * @save_func: (scope call): a function that is called to save each block of data that * the save routine generates. * @user_data: user data to pass to the save function. * @type: name of file format. - * @error: (allow-none): return location for error, or %NULL + * @error: (allow-none): return location for error, or `NULL` * @...: list of key-value save options * - * Saves pixbuf in format @type by feeding the produced data to a - * callback. Can be used when you want to store the image to something - * other than a file, such as an in-memory buffer or a socket. - * If @error is set, %FALSE will be returned. Possible errors - * include those in the #GDK_PIXBUF_ERROR domain and whatever the save + * Saves pixbuf in format `type` by feeding the produced data to a + * callback. + * + * This function can be used when you want to store the image to something + * other than a file, such as an in-memory buffer or a socket. + * + * If @error is set, `FALSE` will be returned. Possible errors + * include those in the `GDK_PIXBUF_ERROR` domain and whatever the save * function generates. * - * See gdk_pixbuf_save() for more details. + * See [method@GdkPixbuf.Pixbuf.save] for more details. * * Return value: whether an error was set * @@ -2670,18 +2689,23 @@ gdk_pixbuf_save_to_callback (GdkPixbuf *pixbuf, /** * gdk_pixbuf_save_to_callbackv: - * @pixbuf: a #GdkPixbuf. + * @pixbuf: a `GdkPixbuf`. * @save_func: (scope call): a function that is called to save each block of data that * the save routine generates. * @user_data: (closure): user data to pass to the save function. * @type: name of file format. - * @option_keys: (array zero-terminated=1) (element-type utf8): name of options to set, %NULL-terminated - * @option_values: (array zero-terminated=1) (element-type utf8): values for named options - * @error: (allow-none): return location for error, or %NULL + * @option_keys: (array zero-terminated=1) (element-type utf8) (nullable): name of options to set + * @option_values: (array zero-terminated=1) (element-type utf8) (nullable): values for named options + * @error: (allow-none): return location for error, or `NULL` + * + * Vector version of `gdk_pixbuf_save_to_callback()`. * * Saves pixbuf to a callback in format @type, which is currently "jpeg", - * "png", "tiff", "ico" or "bmp". If @error is set, %FALSE will be returned. See - * gdk_pixbuf_save_to_callback () for more details. + * "png", "tiff", "ico" or "bmp". + * + * If @error is set, `FALSE` will be returned. + * + * See [method@GdkPixbuf.Pixbuf.save_to_callback] for more details. * * Return value: whether an error was set * @@ -2721,23 +2745,28 @@ gdk_pixbuf_save_to_callbackv (GdkPixbuf *pixbuf, /** * gdk_pixbuf_save_to_buffer: - * @pixbuf: a #GdkPixbuf. + * @pixbuf: a `GdkPixbuf`. * @buffer: (array length=buffer_size) (out) (element-type guint8): location to receive a pointer * to the new buffer. * @buffer_size: location to receive the size of the new buffer. * @type: name of file format. - * @error: (allow-none): return location for error, or %NULL + * @error: (allow-none): return location for error, or `NULL` * @...: list of key-value save options * - * Saves pixbuf to a new buffer in format @type, which is currently "jpeg", - * "png", "tiff", "ico" or "bmp". This is a convenience function that uses - * gdk_pixbuf_save_to_callback() to do the real work. Note that the buffer - * is not nul-terminated and may contain embedded nuls. - * If @error is set, %FALSE will be returned and @buffer will be set to - * %NULL. Possible errors include those in the #GDK_PIXBUF_ERROR + * Saves pixbuf to a new buffer in format `type`, which is currently "jpeg", + * "png", "tiff", "ico" or "bmp". + * + * This is a convenience function that uses `gdk_pixbuf_save_to_callback()` + * to do the real work. + * + * Note that the buffer is not `NUL`-terminated and may contain embedded `NUL` + * characters. + * + * If @error is set, `FALSE` will be returned and @buffer will be set to + * `NULL`. Possible errors include those in the `GDK_PIXBUF_ERROR` * domain. * - * See gdk_pixbuf_save() for more details. + * See `gdk_pixbuf_save()` for more details. * * Return value: whether an error was set * @@ -2809,18 +2838,21 @@ save_to_buffer_callback (const gchar *data, /** * gdk_pixbuf_save_to_bufferv: - * @pixbuf: a #GdkPixbuf. + * @pixbuf: a `GdkPixbuf`. * @buffer: (array length=buffer_size) (out) (element-type guint8): * location to receive a pointer to the new buffer. * @buffer_size: location to receive the size of the new buffer. * @type: name of file format. - * @option_keys: (array zero-terminated=1): name of options to set, %NULL-terminated - * @option_values: (array zero-terminated=1): values for named options - * @error: (allow-none): return location for error, or %NULL + * @option_keys: (array zero-terminated=1) (element-type utf8) (nullable): name of options to set + * @option_values: (array zero-terminated=1) (element-type utf8) (nullable): values for named options + * @error: (allow-none): return location for error, or `NULL` + * + * Vector version of `gdk_pixbuf_save_to_buffer()`. * * Saves pixbuf to a new buffer in format @type, which is currently "jpeg", - * "tiff", "png", "ico" or "bmp". See gdk_pixbuf_save_to_buffer() - * for more details. + * "tiff", "png", "ico" or "bmp". + * + * See [method@GdkPixbuf.Pixbuf.save_to_buffer] for more details. * * Return value: whether an error was set * @@ -2908,21 +2940,23 @@ save_to_stream (const gchar *buffer, /** * gdk_pixbuf_save_to_streamv: - * @pixbuf: a #GdkPixbuf - * @stream: a #GOutputStream to save the pixbuf to + * @pixbuf: a `GdkPixbuf` + * @stream: a `GOutputStream` to save the pixbuf to * @type: name of file format - * @option_keys: (array zero-terminated=1): name of options to set, %NULL-terminated - * @option_values: (array zero-terminated=1): values for named options - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @error: (allow-none): return location for error, or %NULL + * @option_keys: (array zero-terminated=1) (element-type utf8) (nullable): name of options to set + * @option_values: (array zero-terminated=1) (element-type utf8) (nullable): values for named options + * @cancellable: (nullable): optional `GCancellable` object, `NULL` to ignore + * @error: return location for error * - * Saves @pixbuf to an output stream. + * Saves `pixbuf` to an output stream. * * Supported file formats are currently "jpeg", "tiff", "png", "ico" or - * "bmp". See gdk_pixbuf_save_to_stream() for more details. + * "bmp". * - * Returns: %TRUE if the pixbuf was saved successfully, %FALSE if an - * error was set. + * See [method@GdkPixbuf.Pixbuf.save_to_stream] for more details. + * + * Returns: `TRUE` if the pixbuf was saved successfully, `FALSE` if an + * error was set. * * Since: 2.36 */ @@ -2948,27 +2982,27 @@ gdk_pixbuf_save_to_streamv (GdkPixbuf *pixbuf, /** * gdk_pixbuf_save_to_stream: - * @pixbuf: a #GdkPixbuf - * @stream: a #GOutputStream to save the pixbuf to + * @pixbuf: a `GdkPixbuf` + * @stream: a `GOutputStream` to save the pixbuf to * @type: name of file format - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @error: (allow-none): return location for error, or %NULL + * @cancellable: (allow-none): optional `GCancellable` object, `NULL` to ignore + * @error: (allow-none): return location for error, or `NULL` * @...: list of key-value save options * - * Saves @pixbuf to an output stream. + * Saves `pixbuf` to an output stream. * * Supported file formats are currently "jpeg", "tiff", "png", "ico" or - * "bmp". See gdk_pixbuf_save_to_buffer() for more details. + * "bmp". See `gdk_pixbuf_save_to_buffer()` for more details. * - * The @cancellable can be used to abort the operation from another - * thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED - * will be returned. Other possible errors are in the #GDK_PIXBUF_ERROR - * and %G_IO_ERROR domains. + * The `cancellable` can be used to abort the operation from another + * thread. If the operation was cancelled, the error `G_IO_ERROR_CANCELLED` + * will be returned. Other possible errors are in the `GDK_PIXBUF_ERROR` + * and `G_IO_ERROR` domains. * - * The stream is not closed. + * The stream is not closed at the end of this call. * - * Returns: %TRUE if the pixbuf was saved successfully, %FALSE if an - * error was set. + * Returns: `TRUE` if the pixbuf was saved successfully, `FALSE` if an + * error was set. * * Since: 2.14 */ @@ -3044,22 +3078,24 @@ save_to_stream_thread (GTask *task, /** * gdk_pixbuf_save_to_streamv_async: - * @pixbuf: a #GdkPixbuf - * @stream: a #GOutputStream to which to save the pixbuf + * @pixbuf: a `GdkPixbuf` + * @stream: a `GOutputStream` to which to save the pixbuf * @type: name of file format - * @option_keys: (array zero-terminated=1): name of options to set, %NULL-terminated - * @option_values: (array zero-terminated=1): values for named options - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: a #GAsyncReadyCallback to call when the pixbuf is saved + * @option_keys: (array zero-terminated=1) (element-type utf8) (nullable): name of options to set + * @option_values: (array zero-terminated=1) (element-type utf8) (nullable): values for named options + * @cancellable: (allow-none): optional `GCancellable` object, `NULL` to ignore + * @callback: a `GAsyncReadyCallback` to call when the pixbuf is saved * @user_data: the data to pass to the callback function * - * Saves @pixbuf to an output stream asynchronously. + * Saves `pixbuf` to an output stream asynchronously. * * For more details see gdk_pixbuf_save_to_streamv(), which is the synchronous * version of this function. * - * When the operation is finished, @callback will be called in the main thread. - * You can then call gdk_pixbuf_save_to_stream_finish() to get the result of the operation. + * When the operation is finished, `callback` will be called in the main thread. + * + * You can then call gdk_pixbuf_save_to_stream_finish() to get the result of + * the operation. * * Since: 2.36 **/ @@ -3100,21 +3136,23 @@ gdk_pixbuf_save_to_streamv_async (GdkPixbuf *pixbuf, /** * gdk_pixbuf_save_to_stream_async: - * @pixbuf: a #GdkPixbuf - * @stream: a #GOutputStream to which to save the pixbuf + * @pixbuf: a `GdkPixbuf` + * @stream: a `GOutputStream` to which to save the pixbuf * @type: name of file format - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: a #GAsyncReadyCallback to call when the pixbuf is saved + * @cancellable: (allow-none): optional `GCancellable` object, `NULL` to ignore + * @callback: a `GAsyncReadyCallback` to call when the pixbuf is saved * @user_data: the data to pass to the callback function * @...: list of key-value save options * - * Saves @pixbuf to an output stream asynchronously. + * Saves `pixbuf` to an output stream asynchronously. * * For more details see gdk_pixbuf_save_to_stream(), which is the synchronous * version of this function. * - * When the operation is finished, @callback will be called in the main thread. - * You can then call gdk_pixbuf_save_to_stream_finish() to get the result of the operation. + * When the operation is finished, `callback` will be called in the main thread. + * + * You can then call gdk_pixbuf_save_to_stream_finish() to get the result of + * the operation. * * Since: 2.24 **/ @@ -3153,13 +3191,13 @@ gdk_pixbuf_save_to_stream_async (GdkPixbuf *pixbuf, /** * gdk_pixbuf_save_to_stream_finish: - * @async_result: a #GAsyncResult - * @error: a #GError, or %NULL + * @async_result: a `GAsyncResult` + * @error: a `GError`, or `NULL` * * Finishes an asynchronous pixbuf save operation started with * gdk_pixbuf_save_to_stream_async(). * - * Return value: %TRUE if the pixbuf was saved successfully, %FALSE if an error was set. + * Return value: `TRUE` if the pixbuf was saved successfully, `FALSE` if an error was set. * * Since: 2.24 **/ @@ -3185,7 +3223,7 @@ gdk_pixbuf_save_to_stream_finish (GAsyncResult *async_result, /** * gdk_pixbuf_format_get_name: - * @format: a #GdkPixbufFormat + * @format: a `GdkPixbufFormat` * * Returns the name of the format. * @@ -3203,7 +3241,7 @@ gdk_pixbuf_format_get_name (GdkPixbufFormat *format) /** * gdk_pixbuf_format_get_description: - * @format: a #GdkPixbufFormat + * @format: a `GdkPixbufFormat` * * Returns a description of the format. * @@ -3229,12 +3267,11 @@ gdk_pixbuf_format_get_description (GdkPixbufFormat *format) /** * gdk_pixbuf_format_get_mime_types: - * @format: a #GdkPixbufFormat + * @format: a `GdkPixbufFormat` * * Returns the mime types supported by the format. * - * Return value: (transfer full): a %NULL-terminated array of mime types which must be freed with - * g_strfreev() when it is no longer needed. + * Return value: (transfer full) (array zero-terminated=1): an array of mime types * * Since: 2.2 */ @@ -3248,13 +3285,13 @@ gdk_pixbuf_format_get_mime_types (GdkPixbufFormat *format) /** * gdk_pixbuf_format_get_extensions: - * @format: a #GdkPixbufFormat + * @format: a `GdkPixbufFormat` * * Returns the filename extensions typically used for files in the * given format. * - * Return value: (transfer full): a %NULL-terminated array of filename extensions which must be - * freed with g_strfreev() when it is no longer needed. + * Return value: (transfer full) (array zero-terminated=1): an array of + * filename extensions * * Since: 2.2 */ @@ -3268,7 +3305,7 @@ gdk_pixbuf_format_get_extensions (GdkPixbufFormat *format) /** * gdk_pixbuf_format_is_writable: - * @format: a #GdkPixbufFormat + * @format: a `GdkPixbufFormat` * * Returns whether pixbufs can be saved in the given format. * @@ -3286,12 +3323,13 @@ gdk_pixbuf_format_is_writable (GdkPixbufFormat *format) /** * gdk_pixbuf_format_is_scalable: - * @format: a #GdkPixbufFormat + * @format: a `GdkPixbufFormat` * - * Returns whether this image format is scalable. If a file is in a - * scalable format, it is preferable to load it at the desired size, - * rather than loading it at the default size and scaling the - * resulting pixbuf to the desired size. + * Returns whether this image format is scalable. + * + * If a file is in a scalable format, it is preferable to load it at + * the desired size, rather than loading it at the default size and + * scaling the resulting pixbuf to the desired size. * * Return value: whether this image format is scalable. * @@ -3307,10 +3345,11 @@ gdk_pixbuf_format_is_scalable (GdkPixbufFormat *format) /** * gdk_pixbuf_format_is_disabled: - * @format: a #GdkPixbufFormat + * @format: a `GdkPixbufFormat` + * + * Returns whether this image format is disabled. * - * Returns whether this image format is disabled. See - * gdk_pixbuf_format_set_disabled(). + * See gdk_pixbuf_format_set_disabled(). * * Return value: whether this image format is disabled. * @@ -3326,13 +3365,16 @@ gdk_pixbuf_format_is_disabled (GdkPixbufFormat *format) /** * gdk_pixbuf_format_set_disabled: - * @format: a #GdkPixbufFormat - * @disabled: %TRUE to disable the format @format + * @format: a `GdkPixbufFormat` + * @disabled: `TRUE` to disable the format @format * - * Disables or enables an image format. If a format is disabled, - * gdk-pixbuf won't use the image loader for this format to load - * images. Applications can use this to avoid using image loaders - * with an inappropriate license, see gdk_pixbuf_format_get_license(). + * Disables or enables an image format. + * + * If a format is disabled, GdkPixbuf won't use the image loader for + * this format to load images. + * + * Applications can use this to avoid using image loaders with an + * inappropriate license, see gdk_pixbuf_format_get_license(). * * Since: 2.6 */ @@ -3347,14 +3389,14 @@ gdk_pixbuf_format_set_disabled (GdkPixbufFormat *format, /** * gdk_pixbuf_format_get_license: - * @format: a #GdkPixbufFormat + * @format: a pixbuf format * - * Returns information about the license of the image loader for the format. The - * returned string should be a shorthand for a wellknown license, e.g. "LGPL", - * "GPL", "QPL", "GPL/QPL", or "other" to indicate some other license. This - * string should be freed with g_free() when it's no longer needed. + * Returns information about the license of the image loader for the format. * - * Returns: a string describing the license of @format. + * The returned string should be a shorthand for a well known license, e.g. + * "LGPL", "GPL", "QPL", "GPL/QPL", or "other" to indicate some other license. + * + * Returns: (transfer full): a string describing the license of the pixbuf format * * Since: 2.6 */ @@ -3381,9 +3423,7 @@ _gdk_pixbuf_get_format (GdkPixbufModule *module) * by GdkPixbuf. * * Returns: (transfer container) (element-type GdkPixbufFormat): A list of - * #GdkPixbufFormats describing the supported image formats. The list should - * be freed when it is no longer needed, but the structures themselves are - * owned by #GdkPixbuf and should not be freed. + * support image formats. * * Since: 2.2 */ @@ -3404,11 +3444,11 @@ gdk_pixbuf_get_formats (void) /** * gdk_pixbuf_format_copy: - * @format: a #GdkPixbufFormat + * @format: a pixbuf format * - * Creates a copy of @format + * Creates a copy of `format`. * - * Return value: the newly allocated copy of a #GdkPixbufFormat. Use + * Return value: the newly allocated copy of a `GdkPixbufFormat`. Use * gdk_pixbuf_format_free() to free the resources when done * * Since: 2.22 @@ -3424,9 +3464,9 @@ gdk_pixbuf_format_copy (const GdkPixbufFormat *format) /** * gdk_pixbuf_format_free: - * @format: a #GdkPixbufFormat + * @format: a pixbuf format * - * Frees the resources allocated when copying a #GdkPixbufFormat + * Frees the resources allocated when copying a `GdkPixbufFormat` * using gdk_pixbuf_format_copy() * * Since: 2.22 @@ -3440,14 +3480,15 @@ gdk_pixbuf_format_free (GdkPixbufFormat *format) /** * gdk_pixbuf_format_is_save_option_supported: - * @format: a #GdkPixbufFormat + * @format: a pixbuf format * @option_key: the name of an option * - * Returns %TRUE if the save option specified by @option_key is supported when + * Returns `TRUE` if the save option specified by @option_key is supported when * saving a pixbuf using the module implementing @format. + * * See gdk_pixbuf_save() for more information about option keys. * - * Returns: %TRUE if the specified option is supported + * Returns: `TRUE` if the specified option is supported * * Since: 2.36 */ -- cgit v1.2.1