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 <!-- ##### STRUCT GdkPixbufLoader ##### -->
  76 <para>
  77 The <structname>GdkPixbufLoader</structname> struct contains only private
  78 fields.
  79 </para>
  80
  81
  82 <!-- ##### SIGNAL GdkPixbufLoader::area-prepared ##### -->
  83   <para>
  84   </para>
  85
  86 @gdkpixbufloader:
  87
  88 <!-- ##### SIGNAL GdkPixbufLoader::area-updated ##### -->
  89   <para>
  90   </para>
  91
  92 @gdkpixbufloader:
  93 @arg1:
  94 @arg2:
  95 @arg3:
  96 @arg4:
  97
  98 <!-- ##### SIGNAL GdkPixbufLoader::closed ##### -->
  99   <para>
 100   </para>
 101
 102 @gdkpixbufloader:
 103
 104 <!-- ##### SIGNAL GdkPixbufLoader::size-prepared ##### -->
 105   <para>
 106   </para>
 107
 108 @gdkpixbufloader:
 109 @arg1:
 110 @arg2:
 111
 112 <!-- ##### FUNCTION gdk_pixbuf_loader_new ##### -->
 113 <para>
 114
 115 </para>
 116
 117 @Returns:
 118
 119
 120 <!-- ##### FUNCTION gdk_pixbuf_loader_new_with_type ##### -->
 121 <para>
 122
 123 </para>
 124
 125 @image_type:
 126 @error:
 127 @Returns:
 128
 129
 130 <!-- ##### FUNCTION gdk_pixbuf_loader_new_with_mime_type ##### -->
 131 <para>
 132
 133 </para>
 134
 135 @mime_type:
 136 @error:
 137 @Returns:
 138
 139
 140 <!-- ##### FUNCTION gdk_pixbuf_loader_get_format ##### -->
 141 <para>
 142
 143 </para>
 144
 145 @loader:
 146 @Returns:
 147
 148
 149 <!-- ##### FUNCTION gdk_pixbuf_loader_write ##### -->
 150 <para>
 151
 152 </para>
 153
 154 @loader:
 155 @buf:
 156 @count:
 157 @error:
 158 @Returns:
 159
 160
 161 <!-- ##### FUNCTION gdk_pixbuf_loader_set_size ##### -->
 162 <para>
 163
 164 </para>
 165
 166 @loader:
 167 @width:
 168 @height:
 169
 170
 171 <!-- ##### FUNCTION gdk_pixbuf_loader_get_pixbuf ##### -->
 172 <para>
 173
 174 </para>
 175
 176 @loader:
 177 @Returns:
 178
 179
 180 <!-- ##### FUNCTION gdk_pixbuf_loader_get_animation ##### -->
 181 <para>
 182
 183 </para>
 184
 185 @loader:
 186 @Returns:
 187
 188
 189 <!-- ##### FUNCTION gdk_pixbuf_loader_close ##### -->
 190 <para>
 191
 192 </para>
 193
 194 @loader:
 195 @error:
 196 @Returns:
 197
 198 <!--
 199 Local variables:
 200 mode: sgml
 201 sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
 202 End:
 203 -->
 204
 205