:right-sidebar: True PixbufAnimation =================================================================== .. currentmodule:: gi.repository.GdkPixbuf .. class:: PixbufAnimation(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.Object` Subclasses: :class:`~gi.repository.GdkPixbuf.PixbufNonAnim`, :class:`~gi.repository.GdkPixbuf.PixbufSimpleAnim` An opaque object representing an animation. The GdkPixBuf library provides a simple mechanism to load and represent animations. An animation is conceptually a series of frames to be displayed over time. The animation may not be represented as a series of frames internally; for example, it may be stored as a sprite and instructions for moving the sprite around a background. To display an animation you don't need to understand its representation, however; you just ask ``GdkPixbuf`` what should be displayed at a given point in time. Constructors ------------ .. rst-class:: interim-class .. class:: PixbufAnimation :no-index: .. classmethod:: new_from_file(filename: str) -> ~gi.repository.GdkPixbuf.PixbufAnimation | None 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. :param filename: Name of file to load, in the GLib file name encoding .. classmethod:: new_from_resource(resource_path: str) -> ~gi.repository.GdkPixbuf.PixbufAnimation | None Creates a new pixbuf animation by loading an image from an resource. The file format is detected automatically. If ``NULL`` is returned, then ``error`` will be set. .. versionadded:: 2.28 :param resource_path: the path of the resource file .. classmethod:: new_from_stream(stream: ~gi.repository.Gio.InputStream, cancellable: ~gi.repository.Gio.Cancellable | None = None) -> ~gi.repository.GdkPixbuf.PixbufAnimation | None 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 stream is not closed. .. versionadded:: 2.28 :param stream: a ``GInputStream`` to load the pixbuf from :param cancellable: optional ``GCancellable`` object .. classmethod:: new_from_stream_finish(async_result: ~gi.repository.Gio.AsyncResult) -> ~gi.repository.GdkPixbuf.PixbufAnimation | None Finishes an asynchronous pixbuf animation creation operation started with :obj:`~gi.repository.GdkPixbuf.PixbufAnimation.new_from_stream_async`\. .. versionadded:: 2.28 :param async_result: a :obj:`~gi.repository.Gio.AsyncResult` Methods ------- .. rst-class:: interim-class .. class:: PixbufAnimation :no-index: .. method:: do_get_iter(self, start_time: ~gi.repository.GLib.TimeVal | None = None) -> ~gi.repository.GdkPixbuf.PixbufAnimationIter :param start_time: .. method:: do_get_size(self, width: int, height: int) -> None :param width: :param height: .. method:: do_get_static_image(self) -> ~gi.repository.GdkPixbuf.Pixbuf .. method:: do_is_static_image(self) -> bool .. method:: get_height() -> int Queries the height of the bounding box of a pixbuf animation. .. method:: get_iter(start_time: ~gi.repository.GLib.TimeVal | None = None) -> ~gi.repository.GdkPixbuf.PixbufAnimationIter 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 :func:`~gi.repository.GLib.get_current_time`, and marks the beginning of animation playback. After creating an iterator, you should immediately display the pixbuf returned by :func:`~gi.repository.GdkPixbuf.PixbufAnimationIter.get_pixbuf`. Then, you should install a timeout (with :func:`~gi.repository.GLib.timeout_add`) or by some other mechanism ensure that you'll update the image after :func:`~gi.repository.GdkPixbuf.PixbufAnimationIter.get_delay_time` milliseconds. Each time 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 :func:`~gi.repository.GLib.get_current_time` will be used automatically. To update the image (i.e. possibly change the result of :func:`~gi.repository.GdkPixbuf.PixbufAnimationIter.get_pixbuf` to a new frame of the animation), call :func:`~gi.repository.GdkPixbuf.PixbufAnimationIter.advance`. If you're using :obj:`~gi.repository.GdkPixbuf.PixbufLoader`\, in addition to updating the image after the delay time, you should also update it whenever you receive the area_updated signal and :func:`~gi.repository.GdkPixbuf.PixbufAnimationIter.on_currently_loading_frame` returns ``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". :param start_time: time when the animation starts playing .. method:: get_static_image() -> ~gi.repository.GdkPixbuf.Pixbuf 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 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``\. .. method:: get_width() -> int Queries the width of the bounding box of a pixbuf animation. .. method:: is_static_image() -> bool Checks whether the animation is a static image. If you load a file with :func:`~gi.repository.GdkPixbuf.PixbufAnimation.new_from_file` and it turns out to be a plain, unanimated image, then this function will return ``TRUE``\. Use :func:`~gi.repository.GdkPixbuf.PixbufAnimation.get_static_image` to retrieve the image. .. classmethod:: new_from_stream_async(cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None Creates a new animation by asynchronously loading an image from an input stream. For more details see :func:`~gi.repository.GdkPixbuf.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. You can then call :func:`~gi.repository.GdkPixbuf.PixbufAnimation.new_from_stream_finish` to get the result of the operation. .. versionadded:: 2.28 :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` object :param callback: a ``GAsyncReadyCallback`` to call when the pixbuf is loaded :param user_data: the data to pass to the callback function Virtual Methods --------------- .. rst-class:: interim-class .. class:: PixbufAnimation :no-index: .. method:: do_get_iter(start_time: ~gi.repository.GLib.TimeVal | None = None) -> ~gi.repository.GdkPixbuf.PixbufAnimationIter 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 :func:`~gi.repository.GLib.get_current_time`, and marks the beginning of animation playback. After creating an iterator, you should immediately display the pixbuf returned by :func:`~gi.repository.GdkPixbuf.PixbufAnimationIter.get_pixbuf`. Then, you should install a timeout (with :func:`~gi.repository.GLib.timeout_add`) or by some other mechanism ensure that you'll update the image after :func:`~gi.repository.GdkPixbuf.PixbufAnimationIter.get_delay_time` milliseconds. Each time 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 :func:`~gi.repository.GLib.get_current_time` will be used automatically. To update the image (i.e. possibly change the result of :func:`~gi.repository.GdkPixbuf.PixbufAnimationIter.get_pixbuf` to a new frame of the animation), call :func:`~gi.repository.GdkPixbuf.PixbufAnimationIter.advance`. If you're using :obj:`~gi.repository.GdkPixbuf.PixbufLoader`\, in addition to updating the image after the delay time, you should also update it whenever you receive the area_updated signal and :func:`~gi.repository.GdkPixbuf.PixbufAnimationIter.on_currently_loading_frame` returns ``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". :param start_time: time when the animation starts playing .. method:: do_get_size(width: int, height: int) -> None The type of the None singleton. :param width: :param height: .. method:: do_get_static_image() -> ~gi.repository.GdkPixbuf.Pixbuf 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 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``\. .. method:: do_is_static_image() -> bool Checks whether the animation is a static image. If you load a file with :func:`~gi.repository.GdkPixbuf.PixbufAnimation.new_from_file` and it turns out to be a plain, unanimated image, then this function will return ``TRUE``\. Use :func:`~gi.repository.GdkPixbuf.PixbufAnimation.get_static_image` to retrieve the image. Fields ------ .. rst-class:: interim-class .. class:: PixbufAnimation :no-index: .. attribute:: parent_instance