<SIGNAL>
<NAME>GdkPixbufLoader::area-updated</NAME>
<RETURNS>void</RETURNS>
-GdkPixbufLoader *gdkpixbufloader
-gint arg1
-gint arg2
-gint arg3
-gint arg4
+GdkPixbufLoader *loader
+gint x
+gint y
+gint width
+gint height
</SIGNAL>
<SIGNAL>
<NAME>GdkPixbufLoader::area-prepared</NAME>
<RETURNS>void</RETURNS>
-GdkPixbufLoader *gdkpixbufloader
+GdkPixbufLoader *loader
</SIGNAL>
<SIGNAL>
<NAME>GdkPixbufLoader::closed</NAME>
<RETURNS>void</RETURNS>
-GdkPixbufLoader *gdkpixbufloader
+GdkPixbufLoader *loader
</SIGNAL>
</para>
@data:
-@Returns:
-<!--
+@Returns: <!--
Local variables:
mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
</para>
@filename:
-@Returns:
-<!--
+@Returns: <!--
Local variables:
mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
<!-- ##### SECTION Long_Description ##### -->
<para>
#GdkPIxbufLoader provides a way for applications to drive the
- process of loading an image.
+ process of loading an image. Applications can use this
+ functionality instead of gdk_pixbuf_new_from_file() when they need
+ to parse image data in small chunks, such as when reading it from
+ a network connection.
</para>
<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
+ gdk_pixbuf_new_from_file()
+ </para>
<!-- ##### MACRO GDK_PIXBUF_LOADER ##### -->
-<para>
-
-</para>
+ Casts a #GtkObject to a #GdkPixbufLoader.
+ </para>
-@obj:
+@obj: A GTK+ object.
<!-- ##### FUNCTION gdk_pixbuf_loader_new ##### -->
<!-- ##### SIGNAL GdkPixbufLoader::area-updated ##### -->
-<para>
-
-</para>
+ <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>
-@gdkpixbufloader: the object which received the signal.
-@arg1:
-@arg2:
-@arg3:
-@arg4:
+@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.
<!-- ##### SIGNAL GdkPixbufLoader::area-prepared ##### -->
-<para>
-
-</para>
+ <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>
-@gdkpixbufloader: the object which received the signal.
+@loader: Loader which emitted the signal.
<!-- ##### SIGNAL GdkPixbufLoader::closed ##### -->
-<para>
-
-</para>
+ <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.
+@loader: Loader which emitted the signal.
<!--
Local variables:
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
End:
-->
+
</para>
@pixbuf:
-@Returns:
-<!--
+@Returns: <!--
Local variables:
mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
this yourself if you intend to keep the pixbuf structure around.
</para>
+<!-- ##### ARG GnomeCanvasPixbuf:width ##### -->
+ <para>
+ Indicates the width the pixbuf will be scaled to. This argument
+ will only be used if the <link
+ linkend="GnomeCanvasPixbuf--width-set">width_set</link> argument
+ is %TRUE. If the <link
+ linkend="GnomeCanvasPixbuf--width-pixels">width_pixels</link>
+ argument is %FALSE, the width will be taken to be in canvas units,
+ and thus will be scaled along with the canvas item's affine
+ transformation. If width_pixels is %TRUE, the width will be taken
+ to be in pixels, and will visually remain a constant size even if
+ the item's affine transformation changes.
+ </para>
+
<!-- ##### ARG GnomeCanvasPixbuf:width_set ##### -->
<para>
Determines whether the <link
transformations. The default is %FALSE.
</para>
-<!-- ##### ARG GnomeCanvasPixbuf:width ##### -->
+<!-- ##### ARG GnomeCanvasPixbuf:height ##### -->
<para>
- Indicates the width the pixbuf will be scaled to. This argument
+ Indicates the height the pixbuf will be scaled to. This argument
will only be used if the <link
- linkend="GnomeCanvasPixbuf--width-set">width_set</link> argument
- is %TRUE. If the <link
- linkend="GnomeCanvasPixbuf--width-pixels">width_pixels</link>
- argument is %FALSE, the width will be taken to be in canvas units,
- and thus will be scaled along with the canvas item's affine
- transformation. If width_pixels is %TRUE, the width will be taken
- to be in pixels, and will visually remain a constant size even if
- the item's affine transformation changes.
+ linkend="GnomeCanvasPixbuf--height-set">height_set</link> argument
+ is %TRUE. Works in the same way as the <link
+ linkend="GnomeCanvasPixbuf--width">width</link> argument.
</para>
<!-- ##### ARG GnomeCanvasPixbuf:height_set ##### -->
argument. The default is %FALSE.
</para>
-<!-- ##### ARG GnomeCanvasPixbuf:height ##### -->
+<!-- ##### ARG GnomeCanvasPixbuf:x ##### -->
<para>
- Indicates the height the pixbuf will be scaled to. This argument
- will only be used if the <link
- linkend="GnomeCanvasPixbuf--height-set">height_set</link> argument
- is %TRUE. Works in the same way as the <link
- linkend="GnomeCanvasPixbuf--width">width</link> argument.
+ Indicates the horizontal translation offset of the pixbuf item's
+ image. This argument will only be used if the <link
+ linkend="GnomeCanvasPixbuf--x-set">x_set</link> argument is %TRUE.
+ This offset may not actually appear horizontal, since it will be
+ affected by the item's affine transformation.
</para>
<!-- ##### ARG GnomeCanvasPixbuf:x_set ##### -->
will change along with the item's affine transformation.
</para>
-<!-- ##### ARG GnomeCanvasPixbuf:x ##### -->
+<!-- ##### ARG GnomeCanvasPixbuf:y ##### -->
<para>
- Indicates the horizontal translation offset of the pixbuf item's
- image. This argument will only be used if the <link
- linkend="GnomeCanvasPixbuf--x-set">x_set</link> argument is %TRUE.
- This offset may not actually appear horizontal, since it will be
- affected by the item's affine transformation.
+ Indicates the vertical translation offset of the pixbuf item's
+ image. Works in the same way as the <link
+ linkend="GnomeCanvasPixbuf--x">x</link> argument.
</para>
+
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
+End:
+-->
+
<!-- ##### ARG GnomeCanvasPixbuf:y_set ##### -->
<para>
Determines whether the <link
The default is %FALSE.
</para>
-<!-- ##### ARG GnomeCanvasPixbuf:y ##### -->
- <para>
- Indicates the vertical translation offset of the pixbuf item's
- image. Works in the same way as the <link
- linkend="GnomeCanvasPixbuf--x">x</link> argument.
- </para>
-
-
-<!--
-Local variables:
-mode: sgml
-sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
-End:
--->
-
</para>
-@pixbuf:
-<!--
+@pixbuf: <!--
Local variables:
mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
@dest_y:
@width:
@height:
-@alpha_threshold:
-<!--
+@alpha_threshold: <!--
Local variables:
mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
+1999-11-10 Federico Mena Quintero <federico@redhat.com>
+
+ * doc/tmpl/gdk-pixbuf-loader.sgml: Populated.
+
+ * doc/gdk-pixbuf.signals: Put in the real names of signal
+ arguments.
+
+ * src/gdk-pixbuf-loader.c: Improved documentation comments.
+
1999-11-10 Jonathan Blandford <jrb@redhat.com>
* src/gdk-pixbuf-loader.c (gdk_pixbuf_loader_close): emit the
/**
* gdk_pixbuf_new_from_xpm_data:
- * @data:
+ * @data: Pointer to inline XPM data.
*
* Creates a new pixbuf by parsing XPM data in memory. This data is commonly
* the result of including an XPM file into a program's C source.
/**
* gdk_pixbuf_loader_write:
* @loader: A pixbuf loader.
- * @buf: The image data.
- * @count: The length of @buf in bytes.
+ * @buf: Pointer to image data.
+ * @count: Length of the @buf buffer in bytes.
*
- * This will load the next @size bytes of the image. It will return TRUE if the
- * data was loaded successfully, and FALSE if an error occurred. In this case,
- * the loader will be closed, and will not accept further writes.
+ * This will cause a pixbuf loader to parse the next @count bytes of an image.
+ * It will return TRUE if the data was loaded successfully, and FALSE if an
+ * error occurred. In the latter case, the loader will be closed, and will not
+ * accept further writes.
*
- * Return value: Returns TRUE if the write was successful -- FALSE if the loader
- * cannot parse the buf.
+ * Return value: #TRUE if the write was successful, or #FALSE if the loader
+ * cannot parse the buffer.
**/
gboolean
gdk_pixbuf_loader_write (GdkPixbufLoader *loader, const gchar *buf, size_t count)
* gdk_pixbuf_loader_get_pixbuf:
* @loader: A pixbuf loader.
*
- * Gets the GdkPixbuf that the loader is currently loading. If the loader
- * hasn't been enough data via gdk_pixbuf_loader_write, then NULL is returned.
- * Any application using this function should check for this value when it is
- * used. The pixbuf returned will be the same in all future calls to the
- * loader, so simply calling a gdk_pixbuf_ref() should be sufficient to continue
- * using it.
+ * Queries the GdkPixbuf that a pixbuf loader is currently creating. In general
+ * it only makes sense to call this function afer the "area_prepared" signal has
+ * been emitted by the loader; this means that enough data has been read to know
+ * the size of the image that will be allocated. If the loader has not received
+ * enough data via gdk_pixbuf_loader_write(), then this function returns NULL.
+ * The returned pixbuf will be the same in all future calls to the loader, so
+ * simply calling gdk_pixbuf_ref() should be sufficient to continue using it.
*
- * Return value: The GdkPixbuf that the loader is loading.
+ * Return value: The GdkPixbuf that the loader is creating, or NULL if not
+ * enough data has been read to determine how to create the image buffer.
**/
GdkPixbuf *
gdk_pixbuf_loader_get_pixbuf (GdkPixbufLoader *loader)
* gdk_pixbuf_loader_close:
* @loader: A pixbuf loader.
*
- * Tells the loader to stop accepting writes.
+ * Informs a pixbuf loader that no further writes with gdk_pixbuf_load_write()
+ * will occur, so that it can free its internal loading structures.
**/
void
gdk_pixbuf_loader_close (GdkPixbufLoader *loader)
/**
* gdk_pixbuf_loader_write:
* @loader: A pixbuf loader.
- * @buf: The image data.
- * @count: The length of @buf in bytes.
+ * @buf: Pointer to image data.
+ * @count: Length of the @buf buffer in bytes.
*
- * This will load the next @size bytes of the image. It will return TRUE if the
- * data was loaded successfully, and FALSE if an error occurred. In this case,
- * the loader will be closed, and will not accept further writes.
+ * This will cause a pixbuf loader to parse the next @count bytes of an image.
+ * It will return TRUE if the data was loaded successfully, and FALSE if an
+ * error occurred. In the latter case, the loader will be closed, and will not
+ * accept further writes.
*
- * Return value: Returns TRUE if the write was successful -- FALSE if the loader
- * cannot parse the buf.
+ * Return value: #TRUE if the write was successful, or #FALSE if the loader
+ * cannot parse the buffer.
**/
gboolean
gdk_pixbuf_loader_write (GdkPixbufLoader *loader, const gchar *buf, size_t count)
* gdk_pixbuf_loader_get_pixbuf:
* @loader: A pixbuf loader.
*
- * Gets the GdkPixbuf that the loader is currently loading. If the loader
- * hasn't been enough data via gdk_pixbuf_loader_write, then NULL is returned.
- * Any application using this function should check for this value when it is
- * used. The pixbuf returned will be the same in all future calls to the
- * loader, so simply calling a gdk_pixbuf_ref() should be sufficient to continue
- * using it.
+ * Queries the GdkPixbuf that a pixbuf loader is currently creating. In general
+ * it only makes sense to call this function afer the "area_prepared" signal has
+ * been emitted by the loader; this means that enough data has been read to know
+ * the size of the image that will be allocated. If the loader has not received
+ * enough data via gdk_pixbuf_loader_write(), then this function returns NULL.
+ * The returned pixbuf will be the same in all future calls to the loader, so
+ * simply calling gdk_pixbuf_ref() should be sufficient to continue using it.
*
- * Return value: The GdkPixbuf that the loader is loading.
+ * Return value: The GdkPixbuf that the loader is creating, or NULL if not
+ * enough data has been read to determine how to create the image buffer.
**/
GdkPixbuf *
gdk_pixbuf_loader_get_pixbuf (GdkPixbufLoader *loader)
* gdk_pixbuf_loader_close:
* @loader: A pixbuf loader.
*
- * Tells the loader to stop accepting writes.
+ * Informs a pixbuf loader that no further writes with gdk_pixbuf_load_write()
+ * will occur, so that it can free its internal loading structures.
**/
void
gdk_pixbuf_loader_close (GdkPixbufLoader *loader)
projects / ~andy / gtk / commitdiff