Constructors

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 PixbufError and
GFileError domains.

Any of several error conditions may occur: 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.

If an error occurs, the function will throw an exception that can
be caught using e.g. System.Glib.GError.catchGErrorJust and one of the
error codes in PixbufError or GFileError

Get an iterator for displaying an animation. The iterator
provides the frames that should be displayed at a given time. The
start time would normally come from gGetCurrentTime, and marks
the beginning of animation playback. After creating an iterator,
you should immediately display the pixbuf returned by
pixbufAnimationIterGetPixbuf. Then, you should install a
timeout (with timeoutAdd) or by some other mechanism ensure
that you'll update the image after
pixbufAnimationIterGetDelayTime 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 Nothing, the result of
gGetCurrentTime will be used automatically.

If you're using PixbufLoader, in addition to updating the image
after the delay time, you should also update it whenever you
receive the area_updated signal and
pixbufAnimationIterOnCurrentlyLoadingFrame 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.

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 Nothing.

As a shortcut, pass Nothing for the current time and
gGetCurrentTime 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 display, assuming the display had been rendered prior to
advancing; if True, you need to call animationIterGetPixbuf and
update the display with the new pixbuf.

Gets the number of milliseconds the current pixbuf should be
displayed, or -1 if the current pixbuf should be displayed
forever. timeoutAdd conveniently takes a timeout in
milliseconds, so you can use a timeout to schedule the next
update.

Used to determine how to respond to the area_updated signal on
PixbufLoader 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.

Gets the current pixbuf which should be displayed; the pixbuf will
be the same size as the animation itself
(pixbufAnimationGetWidth, pixbufAnimationGetHeight). This
pixbuf should be displayed for pixbufAnimationIterGetDelayTime
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 pixbufAnimationIterAdvance. Copy the pixbuf to
keep it (don't just add a reference), as it may get recycled as you
advance the iterator.