<para>
#GdkPixbufLoader provides a way for applications to drive the
process of loading an image, by letting them send the image data
- directly. Applications can use this functionality instead of
- gdk_pixbuf_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.
+ 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 two important signals
- throughout the process. The first, #"area_prepared", 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 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.
+ 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 other signal, #"area_updated" 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.
+ 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>
+ <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
- #"frame_done" signal, as well as an #"animation_done" 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 #"frame_done" 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 #"area_prepared" is
- re-emitted. Then #"area_updated" is emitted as many times as
- necessary. Finally, #"animation_done" is emitted as soon as all
- frames are done.
- </para>
+ 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>
-<!-- ##### MACRO GDK_PIXBUF_LOADER ##### -->
+@gdkpixbufloader:
+@arg1:
+@arg2:
+@arg3:
+@arg4:
+
+<!-- ##### SIGNAL GdkPixbufLoader::closed ##### -->
<para>
- Casts a #GtkObject to a #GdkPixbufLoader.
</para>
-@obj: A GTK+ object.
+@gdkpixbufloader:
+<!-- ##### SIGNAL GdkPixbufLoader::size-prepared ##### -->
+ <para>
+ </para>
+
+@gdkpixbufloader:
+@arg1:
+@arg2:
<!-- ##### FUNCTION gdk_pixbuf_loader_new ##### -->
<para>
</para>
+@void:
@Returns:
-<!-- ##### FUNCTION gdk_pixbuf_loader_write ##### -->
+<!-- ##### FUNCTION gdk_pixbuf_loader_new_with_type ##### -->
<para>
</para>
-@loader:
-@buf:
-@count:
+@image_type:
+@error:
@Returns:
-<!-- ##### FUNCTION gdk_pixbuf_loader_get_pixbuf ##### -->
+<!-- ##### FUNCTION gdk_pixbuf_loader_new_with_mime_type ##### -->
<para>
</para>
-@loader:
+@mime_type:
+@error:
@Returns:
-<!-- ##### FUNCTION gdk_pixbuf_loader_get_animation ##### -->
+<!-- ##### FUNCTION gdk_pixbuf_loader_get_format ##### -->
<para>
</para>
@Returns:
-<!-- ##### FUNCTION gdk_pixbuf_loader_close ##### -->
+<!-- ##### FUNCTION gdk_pixbuf_loader_write ##### -->
<para>
</para>
@loader:
+@buf:
+@count:
+@error:
+@Returns:
-<!-- ##### 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_set_size ##### -->
+<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:
+@width:
+@height:
-@gdkpixbufloader: the object which received the signal.
-<!-- # Unused Parameters # -->
-@loader: Loader which emitted the signal.
-<!-- ##### SIGNAL GdkPixbufLoader::frame-done ##### -->
+<!-- ##### FUNCTION gdk_pixbuf_loader_get_pixbuf ##### -->
<para>
</para>
-@gdkpixbufloader: the object which received the signal.
+@loader:
+@Returns:
-<!-- ##### SIGNAL GdkPixbufLoader::animation-done ##### -->
+
+<!-- ##### FUNCTION gdk_pixbuf_loader_get_animation ##### -->
<para>
</para>
-@gdkpixbufloader: the object which received the signal.
+@loader:
+@Returns:
-<!-- ##### 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>
-@gdkpixbufloader: the object which received the signal.
-<!-- # Unused Parameters # -->
-@loader: Loader which emitted the signal.
+<!-- ##### FUNCTION gdk_pixbuf_loader_close ##### -->
+<para>
+
+</para>
+
+@loader:
+@error:
+@Returns:
<!--
Local variables:
End:
-->
+