gtk.gdk.PixbufAnimation
Prev | The gtk.gdk Class Reference | Next

## gtk.gdk.PixbufAnimation

gtk.gdk.PixbufAnimation — an object holding an animation

## Synopsis

    class gtk.gdk.PixbufAnimation(gobject.GObject):
        gtk.gdk.PixbufAnimation(filename)
        def get_width()
        def get_height()
        def is_static_image()
        def get_static_image()
        def get_iter(start_time=0.0)

## Ancestry

    +-- gobject.GObject
      +-- gtk.gdk.PixbufAnimation

## Description

A `gtk.gdk.PixbufAnimation` is an object that holds an animation. An animation is conceptually a series of frames to be displayed over time. Each frame is the same size. 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, you just ask a `gtk.gdk.PixbufAnimationIter` for the next frame that should be displayed at a given point in time.

## Constructor

        gtk.gdk.PixbufAnimation(filename)

`filename` : | the name of the file to load.
Returns : | a new `gtk.gdk.PixbufAnimation` object.

Creates a new `gtk.gdk.PixbufAnimation` 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.

This constructor raises the GError exception 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.

## Methods

### gtk.gdk.PixbufAnimation.get_width

        def get_width()

Returns : | the width of the bounding box of the animation.

The `get_width`() method returns the width of the bounding box of a pixbuf animation.

### gtk.gdk.PixbufAnimation.get_height

        def get_height()

Returns : | the height of the bounding box of the animation.

The `get_height`() method returns the height of the bounding box of a pixbuf animation.

### gtk.gdk.PixbufAnimation.is_static_image

        def is_static_image()

Returns : | `TRUE` if the "animation" was really just an image

The `is_static_image`() method returns TRUE if you load a file containing a plain, unanimated image. Use the `get_static_image`() method to retrieve the image.

### gtk.gdk.PixbufAnimation.get_static_image

        def get_static_image()

Returns : | the unanimated image representing the animation

The `get_static_image`() method returns a `gtk.gdk.Pixbuf` that represents a static image of the animation. If the animation is really just a plain image (has only one frame), this method returns that image. If the animation is an animation, this method 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 method will return `None`.

### gtk.gdk.PixbufAnimation.get_iter

        def get_iter(start_time=0.0)

`start_time` : | the time when the animation starts playing
Returns : | a `gtk.gdk.PixbufAnimationIter` object

The `get_iter`() method returns a `gtk.gdk.PixbufAnimationIter` that is used to access the frames of the animation. The iterator provides the frames that should be displayed at specific times. `start_time` is the start time specified as a float as output from the Python time.time() function. `start_time` marks the beginning of the animation playback. After creating an iterator, you should immediately display the pixbuf returned by the `gtk.gdk.PixbufAnimationIter.get_pixbuf`() method. Then, you should install a timeout (with the `gobject.timeout_add`()() function) or by some other mechanism ensure that you'll update the image after the number of milliseconds specified by the `gtk.gdk.PixbufAnimationIter.get_delay_time`() method. 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 0.0 (the default), the current time will be used.

To update the image (i.e. possibly change the result of the `gtk.gdk.PixbufAnimationIter.get_pixbuf`() method to a new frame of the animation), call the `gtk.gdk.PixbufAnimationIter.advance`() method.

If you're using a `gtk.gdk.PixbufLoader`, in addition to updating the image after the delay time, you should also update it whenever you receive the "area_updated" signal and the `gtk.gdk.PixbufAnimationIter.on_currently_loading_frame`() method 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."

Prev | Up | Next
gtk.gdk.Pixbuf | Home | gtk.gdk.PixbufAnimationIter