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() when they need to parse image data in
+ 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 two important
+ and finalize everything. The loader will emit three important
signals throughout the process. The first, "<link
- linkend="GdkPixbufLoader-area-prepared">area_prepared</link>",
+ linkend="GdkPixbufLoader-size-prepared">size_prepared</link>",
will be called as soon as the image has enough information to
- determine the size of the image to be used. It will pass a
- @GdkPixbuf in. If you want to use it, you can simply ref it. In
- addition, no actual information will be passed in yet, so the
+ 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.
+ </para>
+
+ <para>The second signal, "<link
+ linkend="GdkPixbufLoader-area-prepared">area_prepared</link>",
+ will be called 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.
+ In addition, no actual information will be passed in yet, so the
pixbuf can be safely filled with any temporary graphics (or an
- initial color) as needed. You can also call the
- gdk_pixbuf_loader_get_pixbuf() once this signal has been emitted
- and get the same pixbuf.
+ initial color) as needed. You can also call
+ gdk_pixbuf_loader_get_pixbuf() later and get the same pixbuf.
</para>
<para>
- The other signal, "<link
+ The last signal, "<link
linkend="GdkPixbufLoader-area-updated">area_updated</link>" gets
called every time a region is updated. This way you can update a
partially completed image. Note that you do not know anything
<title>Loading an animation</title>
<para>
- Loading an animation is a little more complex then loading an
- image. In addition to the above signals, there is also a "<link
- linkend="GdkPixbufLoader-frame-done">frame_done</link>" signal,
- as well as an "<link
- linkend="GdkPixbufLoader-animation-done">animation_done</link>"
- signal. The first lets the application know that it is dealing
- with an animation, instead of a static image. It also passes a
- #GdkPixbufFrame in the signal. As before, if you want to keep
- the frame, you need to ref it. Once the first "<link
- linkend="GdkPixbufLoader-frame-done">frame_done</link>" signal
+ Loading an animation is almost as easy as loading an
+ image. Once the first "<link
+ linkend="GdkPixbufLoader-area-prepared">area_prepared</link>" signal
has been emitted, you can call gdk_pixbuf_loader_get_animation()
- to get the #GdkPixbufAnimation struct. Each subsequent frame
- goes through a similar lifecycle. For example "<link
- linkend="GdkPixbufLoader-area-prepared">area_prepared</link>" is
- re-emitted. Then "<link
- linkend="GdkPixbufLoader-area-updated">area_updated</link>" is
- emitted as many times as necessary. Finally, "<link
- linkend="GdkPixbufLoader-animation-done">animation_done</link>"
- is emitted as soon as all frames are done.
+ to get the #GdkPixbufAnimation struct and gdk_pixbuf_animation_get_iter()
+ to get an #GdkPixbufAnimationIter for displaying it.
</para>
</refsect2>
<!-- ##### SECTION See_Also ##### -->
<para>
- gdk_pixbuf_new_from_file()
+ gdk_pixbuf_new_from_file(), gdk_pixbuf_animation_new_from_file()
+ </para>
+
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### SECTION Image ##### -->
+
+
+<!-- ##### STRUCT GdkPixbufLoader ##### -->
+<para>
+The <structname>GdkPixbufLoader</structname> struct contains only private
+fields.
+</para>
+
+
+<!-- ##### SIGNAL GdkPixbufLoader::area-prepared ##### -->
+ <para>
+ </para>
+
+@gdkpixbufloader:
+
+<!-- ##### SIGNAL GdkPixbufLoader::area-updated ##### -->
+ <para>
</para>
+@gdkpixbufloader:
+@arg1:
+@arg2:
+@arg3:
+@arg4:
+
+<!-- ##### SIGNAL GdkPixbufLoader::closed ##### -->
+ <para>
+ </para>
+
+@gdkpixbufloader:
+
+<!-- ##### SIGNAL GdkPixbufLoader::size-prepared ##### -->
+ <para>
+ </para>
+
+@gdkpixbufloader:
+@arg1:
+@arg2:
+
<!-- ##### FUNCTION gdk_pixbuf_loader_new ##### -->
<para>
</para>
+@void:
@Returns:
@Returns:
-<!-- ##### FUNCTION gdk_pixbuf_loader_write ##### -->
+<!-- ##### FUNCTION gdk_pixbuf_loader_new_with_mime_type ##### -->
<para>
</para>
-@loader:
-@buf:
-@count:
+@mime_type:
@error:
@Returns:
-<!-- ##### FUNCTION gdk_pixbuf_loader_get_pixbuf ##### -->
+<!-- ##### FUNCTION gdk_pixbuf_loader_get_format ##### -->
<para>
</para>
@Returns:
-<!-- ##### FUNCTION gdk_pixbuf_loader_get_animation ##### -->
+<!-- ##### FUNCTION gdk_pixbuf_loader_write ##### -->
<para>
</para>
@loader:
+@buf:
+@count:
+@error:
@Returns:
-<!-- ##### FUNCTION gdk_pixbuf_loader_close ##### -->
+<!-- ##### FUNCTION gdk_pixbuf_loader_set_size ##### -->
<para>
</para>
@loader:
+@width:
+@height:
-<!-- ##### SIGNAL GdkPixbufLoader::area-updated ##### -->
- <para>
- 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
- areas of an image that is being loaded.
- </para>
+<!-- ##### FUNCTION gdk_pixbuf_loader_get_pixbuf ##### -->
+<para>
-@gdkpixbufloader: the object which received the signal.
-@arg1:
-@arg2:
-@arg3:
-@arg4:
-<!-- # Unused Parameters # -->
-@loader: Loader which emitted the signal.
-@x: X offset of upper-left corner of the updated area.
-@y: Y offset of upper-left corner of the updated area.
-@width: Width of updated area.
-@height: Height of updated area.
+</para>
-<!-- ##### SIGNAL GdkPixbufLoader::area-prepared ##### -->
- <para>
- This signal is emitted when the pixbuf loader has been fed the
- initial amount of data that is required to figure out the size and
- format of the image that it will create. After this signal is
- emitted, applications can call gdk_pixbuf_loader_get_pixbuf() to
- fetch the partially-loaded pixbuf.
- </para>
+@loader:
+@Returns:
-@gdkpixbufloader: the object which received the signal.
-<!-- # Unused Parameters # -->
-@loader: Loader which emitted the signal.
-<!-- ##### SIGNAL GdkPixbufLoader::frame-done ##### -->
- <para>
- This signal is emitted when a frame is done loading. It will be
- emitted for each frame in an animation data stream.
- </para>
+<!-- ##### FUNCTION gdk_pixbuf_loader_get_animation ##### -->
+<para>
-@gdkpixbufloader: the object which received the signal.
-@arg1:
-<!-- # Unused Parameters # -->
-@loader: Loader which emitted the signal.
-@frame: Frame which just completed loading.
+</para>
-<!-- ##### SIGNAL GdkPixbufLoader::animation-done ##### -->
- <para>
- This signal is emitted when an animation is done loading.
- </para>
+@loader:
+@Returns:
-@gdkpixbufloader: the object which received the signal.
-<!-- # Unused Parameters # -->
-@loader: Loader which emitted the signal.
-<!-- ##### SIGNAL GdkPixbufLoader::closed ##### -->
- <para>
- 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.
- </para>
+<!-- ##### FUNCTION gdk_pixbuf_loader_close ##### -->
+<para>
+
+</para>
-@gdkpixbufloader: the object which received the signal.
-<!-- # Unused Parameters # -->
-@loader: Loader which emitted the signal.
+@loader:
+@error:
+@Returns:
<!--
Local variables:
End:
-->
+