much longer long description added.

2000-01-07  Jonathan Blandford  <jrb@redhat.com>

	* doc/tmpl/gdk-pixbuf-loader.sgml: much longer long description
	added.

docs/reference/gdk-pixbuf/tmpl/animation.sgml

@@ -22,11 +22,11 @@ Animations as multi-frame structures.
   <para>
     Each animation frame can have several things happen to it when the
     next frame is displayed.  The #GdkPixbufFrameAction determines this.
-    If a frame as marked as @GDK_PIXBUF_FRAME_RETAIN, then the image
+    If a frame as marked as #GDK_PIXBUF_FRAME_RETAIN, then the image
     will remain displayed, and will be potentially occluded by the next
-    frame.  If it is marked as @GDK_PIXBUF_FRAME_DISPOSE, then the
+    frame.  If it is marked as #GDK_PIXBUF_FRAME_DISPOSE, then the
     animation is reverted to the setting before the frame was shown.  If
-    it is marked as @GDK_PIXBUF_FRAME_REVERT, then the animation is
+    it is marked as #GDK_PIXBUF_FRAME_REVERT, then the animation is
     reverted to the first image before continuing.
   </para>
 

docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-loader.sgml

@@ -2,17 +2,58 @@
 GdkPixbufLoader
 
 <!-- ##### SECTION Short_Description ##### -->
-Application-driven image loading.
+Application-driven progressive image loading.
 
 <!-- ##### SECTION Long_Description ##### -->
   <para>
     #GdkPixbufLoader provides a way for applications to drive the
-    process of loading an image.  Applications can use this
+    process of loading an image, by letting them send the image data
-    functionality instead of gdk_pixbuf_new_from_file() when they need
+    directly.  Applications can use this functionality instead of
-    to parse image data in small chunks, such as when reading it from
+    gdk_pixbuf_new_from_file() when they need to parse image data in
-    a network connection.
+    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.
+  </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.
+  </para>
+  <refsect2>
+  <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
+      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>  
+  </refsect2>
 <!-- ##### SECTION See_Also ##### -->
   <para>
     gdk_pixbuf_new_from_file()

gdk-pixbuf/ChangeLog

@@ -1,3 +1,8 @@
+2000-01-07  Jonathan Blandford  <jrb@redhat.com>
+
+	* doc/tmpl/gdk-pixbuf-loader.sgml: much longer long description
+	added. 
+
 2000-01-05  Owen Taylor  <otaylor@redhat.com>
 
 	* gdk-pixbuf/pixops/pixops.c (pixops_process): Fix computation of end of run indices.