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 to the loader instead of having the loader read the data
  12     from a file.  Applications can use this functionality instead of
  13     gdk_pixbuf_new_from_file() or gdk_pixbuf_animation_new_from_file()
  14     when they need to parse image data in
  15     small chunks.  For example, it should be used when reading an
  16     image from a (potentially) slow network connection, or when
  17     loading an extremely large file.
  18   </para>
  19
  20   <para>
  21     To use #GdkPixbufLoader to load an image, just create a new one,
  22     and call gdk_pixbuf_loader_write() to send the data to it.  When
  23     done, gdk_pixbuf_loader_close() should be called to end the stream
  24     and finalize everything.  The loader will emit three important
  25     signals throughout the process.  The first, "<link
  26     linkend="GdkPixbufLoader-size-prepared">size_prepared</link>",
  27     will be called as soon as the image has enough information to
  28     determine the size of the image to be used. If you want to scale
  29     the image while loading it, you can call gdk_pixbuf_loader_set_size()
  30     in response to this signal.
  31     </para>
  32
  33     <para>The second signal, "<link
  34     linkend="GdkPixbufLoader-area-prepared">area_prepared</link>",
  35     will be called as soon as the pixbuf of the desired has been
  36     allocated.  You can obtain it by calling gdk_pixbuf_loader_get_pixbuf().
  37     If you want to use it, simply ref it.
  38     In addition, no actual information will be passed in yet, so the
  39     pixbuf can be safely filled with any temporary graphics (or an
  40     initial color) as needed.  You can also call
  41     gdk_pixbuf_loader_get_pixbuf() later and get the same pixbuf.
  42   </para>
  43
  44   <para>
  45     The last signal, "<link
  46     linkend="GdkPixbufLoader-area-updated">area_updated</link>" gets
  47     called every time a region is updated.  This way you can update a
  48     partially completed image.  Note that you do not know anything
  49     about the completeness of an image from the area updated.  For
  50     example, in an interlaced image, you need to make several passes
  51     before the image is done loading.
  52   </para>
  53
  54   <refsect2>
  55     <title>Loading an animation</title>
  56
  57     <para>
  58       Loading an animation is almost as easy as loading an
  59       image.  Once the first "<link
  60       linkend="GdkPixbufLoader-area-prepared">area_prepared</link>" signal
  61       has been emitted, you can call gdk_pixbuf_loader_get_animation()
  62       to get the #GdkPixbufAnimation struct and gdk_pixbuf_animation_get_iter()
  63       to get an #GdkPixbufAnimationIter for displaying it.
  64     </para>
  65   </refsect2>
  66
  67 <!-- ##### SECTION See_Also ##### -->
  68   <para>
  69     gdk_pixbuf_new_from_file(), gdk_pixbuf_animation_new_from_file()
  70   </para>
  71
  72 <!-- ##### SECTION Stability_Level ##### -->
  73
  74
  75 <!-- ##### SECTION Image ##### -->
  76
  77
  78 <!-- ##### STRUCT GdkPixbufLoader ##### -->
  79 <para>
  80 The <structname>GdkPixbufLoader</structname> struct contains only private
  81 fields.
  82 </para>
  83
  84
  85 <!-- ##### SIGNAL GdkPixbufLoader::area-prepared ##### -->
  86   <para>
  87   </para>
  88
  89 @gdkpixbufloader:
  90
  91 <!-- ##### SIGNAL GdkPixbufLoader::area-updated ##### -->
  92   <para>
  93   </para>
  94
  95 @gdkpixbufloader:
  96 @arg1:
  97 @arg2:
  98 @arg3:
  99 @arg4:
 100
 101 <!-- ##### SIGNAL GdkPixbufLoader::closed ##### -->
 102   <para>
 103   </para>
 104
 105 @gdkpixbufloader:
 106
 107 <!-- ##### SIGNAL GdkPixbufLoader::size-prepared ##### -->
 108   <para>
 109   </para>
 110
 111 @gdkpixbufloader:
 112 @arg1:
 113 @arg2:
 114
 115 <!-- ##### FUNCTION gdk_pixbuf_loader_new ##### -->
 116 <para>
 117
 118 </para>
 119
 120 @void:
 121 @Returns:
 122
 123
 124 <!-- ##### FUNCTION gdk_pixbuf_loader_new_with_type ##### -->
 125 <para>
 126
 127 </para>
 128
 129 @image_type:
 130 @error:
 131 @Returns:
 132
 133
 134 <!-- ##### FUNCTION gdk_pixbuf_loader_new_with_mime_type ##### -->
 135 <para>
 136
 137 </para>
 138
 139 @mime_type:
 140 @error:
 141 @Returns:
 142
 143
 144 <!-- ##### FUNCTION gdk_pixbuf_loader_get_format ##### -->
 145 <para>
 146
 147 </para>
 148
 149 @loader:
 150 @Returns:
 151
 152
 153 <!-- ##### FUNCTION gdk_pixbuf_loader_write ##### -->
 154 <para>
 155
 156 </para>
 157
 158 @loader:
 159 @buf:
 160 @count:
 161 @error:
 162 @Returns:
 163
 164
 165 <!-- ##### FUNCTION gdk_pixbuf_loader_set_size ##### -->
 166 <para>
 167
 168 </para>
 169
 170 @loader:
 171 @width:
 172 @height:
 173
 174
 175 <!-- ##### FUNCTION gdk_pixbuf_loader_get_pixbuf ##### -->
 176 <para>
 177
 178 </para>
 179
 180 @loader:
 181 @Returns:
 182
 183
 184 <!-- ##### FUNCTION gdk_pixbuf_loader_get_animation ##### -->
 185 <para>
 186
 187 </para>
 188
 189 @loader:
 190 @Returns:
 191
 192
 193 <!-- ##### FUNCTION gdk_pixbuf_loader_close ##### -->
 194 <para>
 195
 196 </para>
 197
 198 @loader:
 199 @error:
 200 @Returns:
 201
 202 <!--
 203 Local variables:
 204 mode: sgml
 205 sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
 206 End:
 207 -->
 208
 209