GdkPixbufLoader
<!-- ##### SECTION Short_Description ##### -->
-
+Application-driven progressive image loading.
<!-- ##### SECTION Long_Description ##### -->
-<para>
+ <para>
+ #GdkPixbufLoader provides a way for applications to drive the
+ 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() 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.
+ </para>
+
+ <para>
+ 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 three important
+ signals throughout the process. The first, "<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. 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
+ gdk_pixbuf_loader_get_pixbuf() later and get the same pixbuf.
+ </para>
+
+ <para>
+ 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
+ about the completeness of an image from the area updated. For
+ example, in an interlaced image, you need to make several passes
+ before the image is done loading.
+ </para>
+
+ <refsect2>
+ <title>Loading an animation</title>
+
+ <para>
+ 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 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_animation_new_from_file()
+ </para>
+
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### SECTION Image ##### -->
+
+<!-- ##### STRUCT GdkPixbufLoader ##### -->
+<para>
+The <structname>GdkPixbufLoader</structname> struct contains only private
+fields.
</para>
-<!-- ##### SECTION See_Also ##### -->
+<!-- ##### 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:
+
-<!-- ##### MACRO GDK_PIXBUF_LOADER ##### -->
+<!-- ##### FUNCTION gdk_pixbuf_loader_new_with_type ##### -->
<para>
</para>
-@obj:
+@image_type:
+@error:
+@Returns:
-<!-- ##### FUNCTION gdk_pixbuf_loader_new ##### -->
+<!-- ##### FUNCTION gdk_pixbuf_loader_new_with_mime_type ##### -->
<para>
</para>
+@mime_type:
+@error:
@Returns:
-<!-- ##### FUNCTION gdk_pixbuf_loader_write ##### -->
+<!-- ##### FUNCTION gdk_pixbuf_loader_get_format ##### -->
<para>
</para>
@loader:
-@buf:
-@count:
@Returns:
-<!-- ##### FUNCTION gdk_pixbuf_loader_get_pixbuf ##### -->
+<!-- ##### 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 ##### -->
+<!-- ##### FUNCTION gdk_pixbuf_loader_get_pixbuf ##### -->
<para>
</para>
-@gdkpixbufloader: the object which received the signal.
-@arg1:
-@arg2:
-@arg3:
-@arg4:
+@loader:
+@Returns:
-<!-- ##### SIGNAL GdkPixbufLoader::area-prepared ##### -->
+
+<!-- ##### FUNCTION gdk_pixbuf_loader_get_animation ##### -->
<para>
</para>
-@gdkpixbufloader: the object which received the signal.
+@loader:
+@Returns:
+
-<!-- ##### SIGNAL GdkPixbufLoader::closed ##### -->
+<!-- ##### FUNCTION gdk_pixbuf_loader_close ##### -->
<para>
</para>
-@gdkpixbufloader: the object which received the signal.
+@loader:
+@error:
+@Returns:
+
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
+End:
+-->
+
projects / ~andy / gtk / blobdiff