diff options
Diffstat (limited to 'gdk-pixbuf/gdk-pixbuf-loader.c')
| -rw-r--r-- | gdk-pixbuf/gdk-pixbuf-loader.c | 251 |
1 files changed, 131 insertions, 120 deletions
diff --git a/gdk-pixbuf/gdk-pixbuf-loader.c b/gdk-pixbuf/gdk-pixbuf-loader.c index 81c5afb75..51202b6f1 100644 --- a/gdk-pixbuf/gdk-pixbuf-loader.c +++ b/gdk-pixbuf/gdk-pixbuf-loader.c @@ -32,52 +32,53 @@ #include "gdk-pixbuf-marshal.h" /** - * SECTION:gdk-pixbuf-loader - * @Short_description: Application-driven progressive image loading. - * @Title: GdkPixbufLoader - * @See_also: gdk_pixbuf_new_from_file(), gdk_pixbuf_animation_new_from_file() + * GdkPixbufLoader: + * + * Incremental image loader. * - * #GdkPixbufLoader provides a way for applications to drive the + * `GdkPixbufLoader` provides a way for applications to drive the * process of loading an image, by letting them send the image data * directly to the loader instead of having the loader read the data - * from a file. Applications can use this functionality instead of - * gdk_pixbuf_new_from_file() or gdk_pixbuf_animation_new_from_file() - * when they need to parse image data in - * small chunks. For example, it should be used when reading an - * image from a (potentially) slow network connection, or when - * loading an extremely large file. - * - * - * To use #GdkPixbufLoader to load an image, just create a new one, and - * call gdk_pixbuf_loader_write() to send the data to it. When done, - * gdk_pixbuf_loader_close() should be called to end the stream and - * finalize everything. The loader will emit three important signals - * throughout the process. The first, #GdkPixbufLoader::size-prepared, - * will be emitted as soon as the image has enough information to - * determine the size of the image to be used. If you want to scale - * the image while loading it, you can call gdk_pixbuf_loader_set_size() - * in response to this signal. - * - * - * The second signal, #GdkPixbufLoader::area-prepared, will be emitted as - * soon as the pixbuf of the desired has been allocated. You can obtain it - * by calling gdk_pixbuf_loader_get_pixbuf(). If you want to use it, simply - * ref it. You can also call gdk_pixbuf_loader_get_pixbuf() later and get - * the same pixbuf. - * - * The last signal, #GdkPixbufLoader::area-updated, gets emitted every time - * a region is updated. This way you can update a partially completed image. - * Note that you do not know anything about the completeness of an image - * from the updated area. For example, in an interlaced image, you need to - * make several passes before the image is done loading. + * from a file. Applications can use this functionality instead of + * `gdk_pixbuf_new_from_file()` or `gdk_pixbuf_animation_new_from_file()` + * when they need to parse image data in small chunks. For example, + * it should be used when reading an image from a (potentially) slow + * network connection, or when loading an extremely large file. + * + * To use `GdkPixbufLoader` to load an image, create a new instance, + * and call [method@GdkPixbuf.PixbufLoader.write] to send the data + * to it. When done, [method@GdkPixbuf.PixbufLoader.close] should be + * called to end the stream and finalize everything. + * + * The loader will emit three important signals throughout the process: + * + * - [signal@GdkPixbuf.PixbufLoader::size-prepared] will be emitted as + * soon as the image has enough information to determine the size of + * the image to be used. If you want to scale the image while loading + * it, you can call [method@GdkPixbuf.PixbufLoader.set_size] in + * response to this signal. + * - [signal@GdkPixbuf.PixbufLoader::area-prepared] will be emitted as + * soon as the pixbuf of the desired has been allocated. You can obtain + * the `GdkPixbuf` instance by calling [method@GdkPixbuf.PixbufLoader.get_pixbuf]. + * If you want to use it, simply acquire a reference to it. You can + * also call `gdk_pixbuf_loader_get_pixbuf()` later to get the same + * pixbuf. + * - [signal@GdkPixbuf.PixbufLoader::area-updated] will be emitted every + * time a region is updated. This way you can update a partially + * completed image. Note that you do not know anything about the + * completeness of an image from the updated area. For example, in an + * interlaced image you will need to make several passes before the + * image is done loading. * - * # Loading an animation + * ## Loading an animation * - * Loading an animation is almost as easy as loading an image. Once the first - * #GdkPixbufLoader::area-prepared signal has been emitted, you can call - * gdk_pixbuf_loader_get_animation() to get the #GdkPixbufAnimation struct - * and gdk_pixbuf_animation_get_iter() to get a #GdkPixbufAnimationIter for - * displaying it. + * Loading an animation is almost as easy as loading an image. Once the + * first [signal@GdkPixbuf.PixbufLoader::area-prepared] signal has been + * emitted, you can call [method@GdkPixbuf.PixbufLoader.get_animation] to + * get the [class@GdkPixbuf.PixbufAnimation] instance, and then call + * and [method@GdkPixbuf.PixbufAnimation.get_iter] to get a + * [class@GdkPixbuf.PixbufAnimationIter] to retrieve the pixbuf for the + * desired time stamp. */ @@ -133,9 +134,11 @@ gdk_pixbuf_loader_class_init (GdkPixbufLoaderClass *class) * * This signal is emitted when the pixbuf loader has been fed the * initial amount of data that is required to figure out the size - * of the image that it will create. Applications can call - * gdk_pixbuf_loader_set_size() in response to this signal to set - * the desired size to which the image should be scaled. + * of the image that it will create. + * + * Applications can call gdk_pixbuf_loader_set_size() in response + * to this signal to set the desired size to which the image + * should be scaled. */ pixbuf_loader_signals[SIZE_PREPARED] = g_signal_new ("size-prepared", @@ -153,9 +156,11 @@ gdk_pixbuf_loader_class_init (GdkPixbufLoaderClass *class) * @loader: the object which received the signal. * * This signal is emitted when the pixbuf loader has allocated the - * pixbuf in the desired size. After this signal is emitted, - * applications can call gdk_pixbuf_loader_get_pixbuf() to fetch - * the partially-loaded pixbuf. + * pixbuf in the desired size. + * + * After this signal is emitted, applications can call + * gdk_pixbuf_loader_get_pixbuf() to fetch the partially-loaded + * pixbuf. */ pixbuf_loader_signals[AREA_PREPARED] = g_signal_new ("area-prepared", @@ -175,9 +180,12 @@ gdk_pixbuf_loader_class_init (GdkPixbufLoaderClass *class) * @height: Height of updated area. * * This signal is emitted when a significant area of the image being - * loaded has been updated. Normally it means that a complete - * scanline has been read in, but it could be a different area as - * well. Applications can use this signal to know when to repaint + * loaded has been updated. + * + * Normally it means that a complete scanline has been read in, but + * it could be a different area as well. + * + * Applications can use this signal to know when to repaint * areas of an image that is being loaded. */ pixbuf_loader_signals[AREA_UPDATED] = @@ -198,6 +206,7 @@ gdk_pixbuf_loader_class_init (GdkPixbufLoaderClass *class) * @loader: the object which received the signal. * * This signal is emitted when gdk_pixbuf_loader_close() is called. + * * It can be used by different parts of an application to receive * notification when an image loader is closed by the code that * drives it. @@ -254,9 +263,10 @@ gdk_pixbuf_loader_finalize (GObject *object) * @width: The desired width of the image being loaded. * @height: The desired height of the image being loaded. * - * Causes the image to be scaled while it is loaded. The desired - * image size can be determined relative to the original size of - * the image by calling gdk_pixbuf_loader_set_size() from a + * Causes the image to be scaled while it is loaded. + * + * The desired image size can be determined relative to the original + * size of the image by calling gdk_pixbuf_loader_set_size() from a * signal handler for the ::size-prepared signal. * * Attempts to set the desired image size are ignored after the @@ -500,15 +510,10 @@ gdk_pixbuf_loader_eat_header_write (GdkPixbufLoader *loader, * @count: Length of the @buf buffer in bytes. * @error: return location for errors * - * This will cause a pixbuf loader to parse the next @count bytes of - * an image. It will return %TRUE if the data was loaded successfully, - * and %FALSE if an error occurred. In the latter case, the loader - * will be closed, and will not accept further writes. If %FALSE is - * returned, @error will be set to an error from the #GDK_PIXBUF_ERROR - * or #G_FILE_ERROR domains. + * Parses the next `count` bytes in the given image buffer. * - * Return value: %TRUE if the write was successful, or %FALSE if the loader - * cannot parse the buffer. + * Return value: `TRUE` if the write was successful, or + * `FALSE` if the loader cannot parse the buffer **/ gboolean gdk_pixbuf_loader_write (GdkPixbufLoader *loader, @@ -562,20 +567,13 @@ gdk_pixbuf_loader_write (GdkPixbufLoader *loader, /** * gdk_pixbuf_loader_write_bytes: * @loader: A pixbuf loader. - * @buffer: The image data as a #GBytes + * @buffer: The image data as a `GBytes` buffer. * @error: return location for errors * - * This will cause a pixbuf loader to parse a buffer inside a #GBytes - * for an image. It will return %TRUE if the data was loaded successfully, - * and %FALSE if an error occurred. In the latter case, the loader - * will be closed, and will not accept further writes. If %FALSE is - * returned, @error will be set to an error from the #GDK_PIXBUF_ERROR - * or #G_FILE_ERROR domains. - * - * See also: gdk_pixbuf_loader_write() + * Parses the next contents of the given image buffer. * - * Return value: %TRUE if the write was successful, or %FALSE if the loader - * cannot parse the buffer. + * Return value: `TRUE` if the write was successful, or `FALSE` if + * the loader cannot parse the buffer * * Since: 2.30 */ @@ -611,14 +609,16 @@ gdk_pixbuf_loader_new (void) /** * gdk_pixbuf_loader_new_with_type: * @image_type: name of the image format to be loaded with the image - * @error: (allow-none): return location for an allocated #GError, or %NULL to ignore errors + * @error: (allow-none): return location for an allocated #GError, or `NULL` to ignore errors * * Creates a new pixbuf loader object that always attempts to parse * image data as if it were an image of type @image_type, instead of - * identifying the type automatically. Useful if you want an error if - * the image isn't the expected type, for loading image formats - * that can't be reliably identified by looking at the data, or if - * the user manually forces a specific type. + * identifying the type automatically. + * + * This function is useful if you want an error if the image isn't the + * expected type; for loading image formats that can't be reliably + * identified by looking at the data; or if the user manually forces + * a specific type. * * The list of supported image formats depends on what image loaders * are installed, but typically "png", "jpeg", "gif", "tiff" and @@ -654,14 +654,16 @@ gdk_pixbuf_loader_new_with_type (const char *image_type, /** * gdk_pixbuf_loader_new_with_mime_type: * @mime_type: the mime type to be loaded - * @error: (allow-none): return location for an allocated #GError, or %NULL to ignore errors + * @error: (allow-none): return location for an allocated #GError, or `NULL` to ignore errors * * Creates a new pixbuf loader object that always attempts to parse - * image data as if it were an image of mime type @mime_type, instead of - * identifying the type automatically. Useful if you want an error if - * the image isn't the expected mime type, for loading image formats - * that can't be reliably identified by looking at the data, or if - * the user manually forces a specific mime type. + * image data as if it were an image of MIME type @mime_type, instead of + * identifying the type automatically. + * + * This function is useful if you want an error if the image isn't the + * expected MIME type; for loading image formats that can't be reliably + * identified by looking at the data; or if the user manually forces a + * specific MIME type. * * The list of supported mime types depends on what image loaders * are installed, but typically "image/png", "image/jpeg", "image/gif", @@ -671,6 +673,7 @@ gdk_pixbuf_loader_new_with_type (const char *image_type, * structs returned by gdk_pixbuf_get_formats(). * * Return value: A newly-created pixbuf loader. + * * Since: 2.4 **/ GdkPixbufLoader * @@ -736,19 +739,23 @@ _gdk_pixbuf_loader_new_with_filename (const char *filename) * @loader: A pixbuf loader. * * Queries the #GdkPixbuf that a pixbuf loader is currently creating. + * * In general it only makes sense to call this function after the - * "area-prepared" signal has been emitted by the loader; this means - * that enough data has been read to know the size of the image that - * will be allocated. If the loader has not received enough data via - * gdk_pixbuf_loader_write(), then this function returns %NULL. The - * returned pixbuf will be the same in all future calls to the loader, - * so simply calling g_object_ref() should be sufficient to continue - * using it. Additionally, if the loader is an animation, it will - * return the "static image" of the animation - * (see gdk_pixbuf_animation_get_static_image()). + * [signal@GdkPixbuf.PixbufLoader::area-prepared] signal has been + * emitted by the loader; this means that enough data has been read + * to know the size of the image that will be allocated. + * + * If the loader has not received enough data via gdk_pixbuf_loader_write(), + * then this function returns `NULL`. + * + * The returned pixbuf will be the same in all future calls to the loader, + * so if you want to keep using it, you should acquire a reference to it. + * + * Additionally, if the loader is an animation, it will return the "static + * image" of the animation (see gdk_pixbuf_animation_get_static_image()). * - * Return value: (transfer none): The #GdkPixbuf that the loader is creating, or %NULL if not - * enough data has been read to determine how to create the image buffer. + * Return value: (transfer none) (nullable): The pixbuf that the loader is + * creating **/ GdkPixbuf * gdk_pixbuf_loader_get_pixbuf (GdkPixbufLoader *loader) @@ -770,14 +777,17 @@ gdk_pixbuf_loader_get_pixbuf (GdkPixbufLoader *loader) * @loader: A pixbuf loader * * Queries the #GdkPixbufAnimation that a pixbuf loader is currently creating. - * In general it only makes sense to call this function after the "area-prepared" - * signal has been emitted by the loader. If the loader doesn't have enough - * bytes yet (hasn't emitted the "area-prepared" signal) this function will - * return %NULL. - * - * Return value: (transfer none): The #GdkPixbufAnimation that the loader is loading, or %NULL if - * not enough data has been read to determine the information. -**/ + * + * In general it only makes sense to call this function after the + * [signal@GdkPixbuf.PixbufLoader::area-prepared] signal has been emitted by + * the loader. + * + * If the loader doesn't have enough bytes yet, and hasn't emitted the `area-prepared` + * signal, this function will return `NULL`. + * + * Return value: (transfer none) (nullable): The animation that the loader is + * currently loading + */ GdkPixbufAnimation * gdk_pixbuf_loader_get_animation (GdkPixbufLoader *loader) { @@ -793,24 +803,27 @@ gdk_pixbuf_loader_get_animation (GdkPixbufLoader *loader) /** * gdk_pixbuf_loader_close: * @loader: A pixbuf loader. - * @error: (allow-none): return location for a #GError, or %NULL to ignore errors + * @error: (allow-none): return location for a #GError, or `NULL` to ignore errors * * Informs a pixbuf loader that no further writes with * gdk_pixbuf_loader_write() will occur, so that it can free its - * internal loading structures. Also, tries to parse any data that - * hasn't yet been parsed; if the remaining data is partial or - * corrupt, an error will be returned. If %FALSE is returned, @error - * will be set to an error from the #GDK_PIXBUF_ERROR or #G_FILE_ERROR - * domains. If you're just cancelling a load rather than expecting it - * to be finished, passing %NULL for @error to ignore it is - * reasonable. - * - * Remember that this does not unref the loader, so if you plan not to - * use it anymore, please g_object_unref() it. - * - * Returns: %TRUE if all image data written so far was successfully - passed out via the update_area signal - **/ + * internal loading structures. + * + * This function also tries to parse any data that hasn't yet been parsed; + * if the remaining data is partial or corrupt, an error will be returned. + * + * If `FALSE` is returned, `error` will be set to an error from the + * `GDK_PIXBUF_ERROR` or `G_FILE_ERROR` domains. + * + * If you're just cancelling a load rather than expecting it to be finished, + * passing `NULL` for `error` to ignore it is reasonable. + * + * Remember that this function does not release a reference on the loader, so + * you will need to explicitly release any reference you hold. + * + * Returns: `TRUE` if all image data written so far was successfully + * passed out via the update_area signal + */ gboolean gdk_pixbuf_loader_close (GdkPixbufLoader *loader, GError **error) @@ -882,9 +895,7 @@ gdk_pixbuf_loader_close (GdkPixbufLoader *loader, * Obtains the available information about the format of the * currently loading image file. * - * Returns: (nullable) (transfer none): A #GdkPixbufFormat or - * %NULL. The return value is owned by GdkPixbuf and should not be - * freed. + * Returns: (nullable) (transfer none): A #GdkPixbufFormat * * Since: 2.2 */ |