Pileus Git - ~andy/gtk/blob - docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-loader.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GdkPixbufLoader
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Application-driven progressive image loading.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8   <para>
   9     #GdkPixbufLoader provides a way for applications to drive the
  10     process of loading an image, by letting them send the image data
  11     directly.  Applications can use this functionality instead of
  12     gdk_pixbuf_new_from_file() when they need to parse image data in
  13     small chunks.  For example, it should be used when reading an image
  14     from a (potentially) slow network connection, or when loading an
  15     extremely large file.
  16   </para>
  17   <para>
  18     To use #GdkPixbufLoader to load an image, just create a new one, and
  19     call gdk_pixbuf_loader_write() to send the data to it.  When done,
  20     gdk_pixbuf_loader_close() should be called to end the stream and
  21     finalize everything.  The loader will emit two important signals
  22     throughout the process.  The first, #"area_prepared", will be called
  23     as soon as the image has enough information to determine the size of
  24     the image to be used.  It will pass a @GdkPixbuf in.  If you want to
  25     use it, you can simply ref it.  In addition, no actual information
  26     will be passed in yet, so the pixbuf can be safely filled with any
  27     temporary graphics (or an initial color) as needed.  You can also
  28     call the gdk_pixbuf_loader_get_pixbuf() once this signal has been
  29     emitted and get the same pixbuf.
  30   </para>
  31   <para>
  32     The other signal, #"area_updated" gets called every
  33     time a region is updated.  This way you can update a partially
  34     completed image.  Note that you do not know anything about the
  35     completeness of an image from the area updated.  For example, in an
  36     interlaced image, you need to make several passes before the image
  37     is done loading.
  38   </para>
  39   <refsect2>
  40   <title>Loading an animation</title>
  41     <para>
  42       Loading an animation is a little more complex then loading an
  43       image.  In addition to the above signals, there is also a
  44       #"frame_done" signal, as well as an #"animation_done" signal.  The
  45       first lets the application know that it is dealing with an
  46       animation, instead of a static image.  It also passes a
  47       #GdkPixbufFrame in the signal.  As before, if you want to keep the
  48       frame, you need to ref it.  Once the first #"frame_done" signal
  49       has been emitted, you can call gdk_pixbuf_loader_get_animation()
  50       to get the #GdkPixbufAnimation struct.  Each subsequent frame goes
  51       through a similar lifecycle.  For example #"area_prepared" is
  52       re-emitted.  Then #"area_updated" is emitted as many times as
  53       necessary.  Finally, #"animation_done" is emitted as soon as all
  54       frames are done.
  55     </para>
  56   </refsect2>
  57
  58 <!-- ##### SECTION See_Also ##### -->
  59   <para>
  60     gdk_pixbuf_new_from_file()
  61   </para>
  62
  63 <!-- ##### MACRO GDK_PIXBUF_LOADER ##### -->
  64   <para>
  65     Casts a #GtkObject to a #GdkPixbufLoader.
  66   </para>
  67
  68 @obj: A GTK+ object.
  69
  70
  71 <!-- ##### FUNCTION gdk_pixbuf_loader_new ##### -->
  72 <para>
  73
  74 </para>
  75
  76 @Returns:
  77
  78
  79 <!-- ##### FUNCTION gdk_pixbuf_loader_write ##### -->
  80 <para>
  81
  82 </para>
  83
  84 @loader:
  85 @buf:
  86 @count:
  87 @Returns:
  88
  89
  90 <!-- ##### FUNCTION gdk_pixbuf_loader_get_pixbuf ##### -->
  91 <para>
  92
  93 </para>
  94
  95 @loader:
  96 @Returns:
  97
  98
  99 <!-- ##### FUNCTION gdk_pixbuf_loader_get_animation ##### -->
 100 <para>
 101
 102 </para>
 103
 104 @loader:
 105 @Returns:
 106
 107
 108 <!-- ##### FUNCTION gdk_pixbuf_loader_close ##### -->
 109 <para>
 110
 111 </para>
 112
 113 @loader:
 114
 115
 116 <!-- ##### SIGNAL GdkPixbufLoader::area-updated ##### -->
 117   <para>
 118     This signal is emitted when a significant area of the image being
 119     loaded has been updated.  Normally it means that a complete
 120     scanline has been read in, but it could be a different area as
 121     well.  Applications can use this signal to know when to repaint
 122     areas of an image that is being loaded.
 123   </para>
 124
 125 @gdkpixbufloader: the object which received the signal.
 126 @arg1:
 127 @arg2:
 128 @arg3:
 129 @arg4:
 130 <!-- # Unused Parameters # -->
 131 @loader: Loader which emitted the signal.
 132 @x: X offset of upper-left corner of the updated area.
 133 @y: Y offset of upper-left corner of the updated area.
 134 @width: Width of updated area.
 135 @height: Height of updated area.
 136
 137 <!-- ##### SIGNAL GdkPixbufLoader::area-prepared ##### -->
 138   <para>
 139     This signal is emitted when the pixbuf loader has been fed the
 140     initial amount of data that is required to figure out the size and
 141     format of the image that it will create.  After this signal is
 142     emitted, applications can call gdk_pixbuf_loader_get_pixbuf() to
 143     fetch the partially-loaded pixbuf.
 144   </para>
 145
 146 @gdkpixbufloader: the object which received the signal.
 147 <!-- # Unused Parameters # -->
 148 @loader: Loader which emitted the signal.
 149
 150 <!-- ##### SIGNAL GdkPixbufLoader::frame-done ##### -->
 151 <para>
 152
 153 </para>
 154
 155 @gdkpixbufloader: the object which received the signal.
 156
 157 <!-- ##### SIGNAL GdkPixbufLoader::animation-done ##### -->
 158 <para>
 159
 160 </para>
 161
 162 @gdkpixbufloader: the object which received the signal.
 163
 164 <!-- ##### SIGNAL GdkPixbufLoader::closed ##### -->
 165   <para>
 166     This signal is emitted when gdk_pixbuf_loader_close() is called.
 167     It can be used by different parts of an application to receive
 168     notification when an image loader is closed by the code that
 169     drives it.
 170   </para>
 171
 172 @gdkpixbufloader: the object which received the signal.
 173 <!-- # Unused Parameters # -->
 174 @loader: Loader which emitted the signal.
 175
 176 <!--
 177 Local variables:
 178 mode: sgml
 179 sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
 180 End:
 181 -->
 182