summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorEmmanuele Bassi <ebassi@gnome.org>2021-03-21 13:17:20 +0000
committerEmmanuele Bassi <ebassi@gnome.org>2021-03-21 13:17:20 +0000
commitd2cb184255008e19ac5ae4ee01c6d0ae8aa4bd6c (patch)
tree1f9a370cd52e05fbd1f4c63927ac8e7945d9b94b
parent3b49374085cd00b391ab715c3299dbdd46588ae9 (diff)
downloadgdk-pixbuf-d2cb184255008e19ac5ae4ee01c6d0ae8aa4bd6c.tar.gz
docs: Update pixbuf-animation style
-rw-r--r--gdk-pixbuf/gdk-pixbuf-animation.c153
1 files changed, 83 insertions, 70 deletions
diff --git a/gdk-pixbuf/gdk-pixbuf-animation.c b/gdk-pixbuf/gdk-pixbuf-animation.c
index 9b7372e00..6f2c170b8 100644
--- a/gdk-pixbuf/gdk-pixbuf-animation.c
+++ b/gdk-pixbuf/gdk-pixbuf-animation.c
@@ -147,18 +147,19 @@ noop_updated_notify (GdkPixbuf *pixbuf,
/**
* gdk_pixbuf_animation_new_from_file:
* @filename: (type filename): Name of file to load, in the GLib file
- * name encoding
+ * name encoding
* @error: return location for error
*
- * Creates a new animation by loading it from a file. The file format is
- * detected automatically. If the file's format does not support multi-frame
- * images, then an animation with a single frame will be created. Possible errors
- * are in the #GDK_PIXBUF_ERROR and #G_FILE_ERROR domains.
+ * Creates a new animation by loading it from a file.
*
- * Return value: A newly-created animation with a reference count of 1, or %NULL
- * if any of several error conditions ocurred: 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 the file's format does not support multi-frame images, then an animation
+ * with a single frame will be created.
+ *
+ * Possible errors are in the `GDK_PIXBUF_ERROR` and `G_FILE_ERROR` domains.
+ *
+ * Return value: (transfer full) (nullable): A newly-created animation
*/
GdkPixbufAnimation *
gdk_pixbuf_animation_new_from_file (const gchar *filename,
@@ -329,7 +330,7 @@ fail_begin_load:
*
* Same as gdk_pixbuf_animation_new_from_file()
*
- * Return value: A newly-created animation with a reference count of 1, or %NULL
+ * Return value: A newly-created animation with a reference count of 1, or `NULL`
* if any of several error conditions ocurred: 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.
@@ -344,24 +345,24 @@ gdk_pixbuf_animation_new_from_file_utf8 (const gchar *filename,
/**
* gdk_pixbuf_animation_new_from_stream:
- * @stream: a #GInputStream to load the pixbuf from
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
+ * @stream: a `GInputStream` to load the pixbuf from
+ * @cancellable: (nullable): optional `GCancellable` object
* @error: Return location for an error
*
* Creates a new animation by loading it 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 animation
*
* Since: 2.28
*/
@@ -442,8 +443,8 @@ animation_new_from_stream_thread (GTask *task,
/**
* gdk_pixbuf_animation_new_from_stream_async:
* @stream: a #GInputStream from which to load the animation
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
- * @callback: a #GAsyncReadyCallback to call when the pixbuf is loaded
+ * @cancellable: (nullable): optional #GCancellable object
+ * @callback: a `GAsyncReadyCallback` to call when the pixbuf is loaded
* @user_data: the data to pass to the callback function
*
* Creates a new animation by asynchronously loading an image from an input stream.
@@ -451,7 +452,7 @@ animation_new_from_stream_thread (GTask *task,
* For more details see gdk_pixbuf_new_from_stream(), which is the synchronous
* version of this function.
*
- * When the operation is finished, @callback will be called in the main thread.
+ * When the operation is finished, `callback` will be called in the main thread.
* You can then call gdk_pixbuf_animation_new_from_stream_finish() to get the
* result of the operation.
*
@@ -478,13 +479,12 @@ gdk_pixbuf_animation_new_from_stream_async (GInputStream *stream,
/**
* gdk_pixbuf_animation_new_from_stream_finish:
* @async_result: a #GAsyncResult
- * @error: a #GError, or %NULL
+ * @error: a #GError, or `NULL`
*
* Finishes an asynchronous pixbuf animation creation operation started with
- * gdk_pixbuf_animation_new_from_stream_async().
+ * [func@GdkPixbuf.PixbufAnimation.new_from_stream_async].
*
- * Return value: a #GdkPixbufAnimation or %NULL on error. Free the returned
- * object with g_object_unref().
+ * Return value: (transfer full) (nullable): the newly created animation
*
* Since: 2.28
**/
@@ -508,13 +508,10 @@ gdk_pixbuf_animation_new_from_stream_finish (GAsyncResult *async_result,
*
* Creates a new pixbuf animation 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 animation, 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 animation
*
* Since: 2.28
*/
@@ -576,12 +573,14 @@ gdk_pixbuf_animation_unref (GdkPixbufAnimation *animation)
* gdk_pixbuf_animation_is_static_image:
* @animation: a #GdkPixbufAnimation
*
+ * Checks whether the animation is a static image.
+ *
* If you load a file with gdk_pixbuf_animation_new_from_file() and it
* turns out to be a plain, unanimated image, then this function will
- * return %TRUE. Use gdk_pixbuf_animation_get_static_image() to retrieve
+ * return `TRUE`. Use gdk_pixbuf_animation_get_static_image() to retrieve
* the image.
*
- * Return value: %TRUE if the "animation" was really just an image
+ * Return value: `TRUE` if the "animation" was really just an image
*/
gboolean
gdk_pixbuf_animation_is_static_image (GdkPixbufAnimation *animation)
@@ -595,12 +594,17 @@ gdk_pixbuf_animation_is_static_image (GdkPixbufAnimation *animation)
* gdk_pixbuf_animation_get_static_image:
* @animation: a #GdkPixbufAnimation
*
+ * Retrieves a static image for the animation.
+ *
* If an animation is really just a plain image (has only one frame),
- * this function returns that image. If the animation is an animation,
- * this function returns a reasonable thing to display as a static
- * unanimated image, which might be the first frame, or something more
- * sophisticated. If an animation hasn't loaded any frames yet, this
- * function will return %NULL.
+ * this function returns that image.
+ *
+ * If the animation is an animation, this function returns a reasonable
+ * image to use as a static unanimated image, which might be the first
+ * frame, or something more sophisticated depending on the file format.
+ *
+ * If an animation hasn't loaded any frames yet, this function will
+ * return `NULL`.
*
* Return value: (transfer none): unanimated image representing the animation
*/
@@ -662,9 +666,10 @@ gdk_pixbuf_animation_get_height (GdkPixbufAnimation *animation)
* @animation: a #GdkPixbufAnimation
* @start_time: (allow-none): time when the animation starts playing
*
- * Get an iterator for displaying an animation. The iterator provides
- * the frames that should be displayed at a given time. It should be
- * freed after use with g_object_unref().
+ * Get an iterator for displaying an animation.
+ *
+ * The iterator provides the frames that should be displayed at a
+ * given time.
*
* @start_time would normally come from g_get_current_time(), and marks
* the beginning of animation playback. After creating an iterator, you
@@ -676,7 +681,7 @@ gdk_pixbuf_animation_get_height (GdkPixbufAnimation *animation)
* the image is updated, you should reinstall the timeout with the new,
* possibly-changed delay time.
*
- * As a shortcut, if @start_time is %NULL, the result of
+ * As a shortcut, if @start_time is `NULL`, the result of
* g_get_current_time() will be used automatically.
*
* To update the image (i.e. possibly change the result of
@@ -687,14 +692,14 @@ gdk_pixbuf_animation_get_height (GdkPixbufAnimation *animation)
* after the delay time, you should also update it whenever you
* receive the area_updated signal and
* gdk_pixbuf_animation_iter_on_currently_loading_frame() returns
- * %TRUE. In this case, the frame currently being fed into the loader
+ * `TRUE`. In this case, the frame currently being fed into the loader
* has received new data, so needs to be refreshed. The delay time for
* a frame may also be modified after an area_updated signal, for
* example if the delay time for a frame is encoded in the data after
* the frame itself. So your timeout should be reinstalled after any
* area_updated signal.
*
- * A delay time of -1 is possible, indicating "infinite."
+ * A delay time of -1 is possible, indicating "infinite".
*
* Return value: (transfer full): an iterator to move over the animation
*/
@@ -732,9 +737,10 @@ gdk_pixbuf_animation_iter_init (GdkPixbufAnimationIter *iter)
* @iter: an animation iterator
*
* Gets the number of milliseconds the current pixbuf should be displayed,
- * or -1 if the current pixbuf should be displayed forever. g_timeout_add()
- * conveniently takes a timeout in milliseconds, so you can use a timeout
- * to schedule the next update.
+ * or -1 if the current pixbuf should be displayed forever.
+ *
+ * The `g_timeout_add()` function conveniently takes a timeout in milliseconds,
+ * so you can use a timeout to schedule the next update.
*
* Note that some formats, like GIF, might clamp the timeout values in the
* image file to avoid updates that are just too quick. The minimum timeout
@@ -755,17 +761,21 @@ gdk_pixbuf_animation_iter_get_delay_time (GdkPixbufAnimationIter *iter)
* gdk_pixbuf_animation_iter_get_pixbuf:
* @iter: an animation iterator
*
- * Gets the current pixbuf which should be displayed; the pixbuf might not
- * be the same size as the animation itself
+ * Gets the current pixbuf which should be displayed.
+ *
+ * The pixbuf might not be the same size as the animation itself
* (gdk_pixbuf_animation_get_width(), gdk_pixbuf_animation_get_height()).
- * This pixbuf should be displayed for
- * gdk_pixbuf_animation_iter_get_delay_time() milliseconds. The caller
- * of this function does not own a reference to the returned pixbuf;
- * the returned pixbuf will become invalid when the iterator advances
- * to the next frame, which may happen anytime you call
- * gdk_pixbuf_animation_iter_advance(). Copy the pixbuf to keep it
- * (don't just add a reference), as it may get recycled as you advance
- * the iterator.
+ *
+ * This pixbuf should be displayed for gdk_pixbuf_animation_iter_get_delay_time()
+ * milliseconds.
+ *
+ * The caller of this function does not own a reference to the returned
+ * pixbuf; the returned pixbuf will become invalid when the iterator
+ * advances to the next frame, which may happen anytime you call
+ * gdk_pixbuf_animation_iter_advance().
+ *
+ * Copy the pixbuf to keep it (don't just add a reference), as it may get
+ * recycled as you advance the iterator.
*
* Return value: (transfer none): the pixbuf to be displayed
*/
@@ -783,12 +793,13 @@ gdk_pixbuf_animation_iter_get_pixbuf (GdkPixbufAnimationIter *iter)
* @iter: a #GdkPixbufAnimationIter
*
* Used to determine how to respond to the area_updated signal on
- * #GdkPixbufLoader when loading an animation. area_updated is emitted
- * for an area of the frame currently streaming in to the loader. So if
- * you're on the currently loading frame, you need to redraw the screen for
- * the updated area.
+ * #GdkPixbufLoader when loading an animation.
*
- * Return value: %TRUE if the frame we're on is partially loaded, or the last frame
+ * The `::area_updated` signal is emitted for an area of the frame currently
+ * streaming in to the loader. So if you're on the currently loading frame,
+ * you will need to redraw the screen for the updated area.
+ *
+ * Return value: `TRUE` if the frame we're on is partially loaded, or the last frame
*/
gboolean
gdk_pixbuf_animation_iter_on_currently_loading_frame (GdkPixbufAnimationIter *iter)
@@ -804,8 +815,10 @@ gdk_pixbuf_animation_iter_on_currently_loading_frame (GdkPixbufAnimationIter *it
* @iter: a #GdkPixbufAnimationIter
* @current_time: (allow-none): current time
*
- * Possibly advances an animation to a new frame. Chooses the frame based
- * on the start time passed to gdk_pixbuf_animation_get_iter().
+ * Possibly advances an animation to a new frame.
+ *
+ * Chooses the frame based on the start time passed to
+ * gdk_pixbuf_animation_get_iter().
*
* @current_time would normally come from g_get_current_time(), and
* must be greater than or equal to the time passed to
@@ -814,17 +827,17 @@ gdk_pixbuf_animation_iter_on_currently_loading_frame (GdkPixbufAnimationIter *it
* called. That is, you can't go backward in time; animations only
* play forward.
*
- * As a shortcut, pass %NULL for the current time and g_get_current_time()
+ * As a shortcut, pass `NULL` for the current time and g_get_current_time()
* will be invoked on your behalf. So you only need to explicitly pass
* @current_time if you're doing something odd like playing the animation
* at double speed.
*
- * If this function returns %FALSE, there's no need to update the animation
+ * If this function returns `FALSE`, there's no need to update the animation
* display, assuming the display had been rendered prior to advancing;
- * if %TRUE, you need to call gdk_pixbuf_animation_iter_get_pixbuf()
+ * if `TRUE`, you need to call gdk_pixbuf_animation_iter_get_pixbuf()
* and update the display with the new pixbuf.
*
- * Returns: %TRUE if the image may need updating
+ * Returns: `TRUE` if the image may need updating
*/
gboolean
gdk_pixbuf_animation_iter_advance (GdkPixbufAnimationIter *iter,