Commit cfb02665 authored by Federico Mena Quintero's avatar Federico Mena Quintero Committed by Arturo Espinosa
Browse files

Populated.

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.
parent 23b50343
<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>
......@@ -86,8 +86,7 @@ Creating a pixbuf from image data that is already in memory.
</para>
@data:
@Returns:
<!--
@Returns: <!--
Local variables:
mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
......
......@@ -31,8 +31,7 @@ Loading a pixbuf from a file.
</para>
@filename:
@Returns:
<!--
@Returns: <!--
Local variables:
mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
......
......@@ -7,20 +7,23 @@ Application-driven image loading.
<!-- ##### 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>
<para>
gdk_pixbuf_new_from_file()
</para>
<!-- ##### MACRO GDK_PIXBUF_LOADER ##### -->
<para>
</para>
<para>
Casts a #GtkObject to a #GdkPixbufLoader.
</para>
@obj:
@obj: A GTK+ object.
<!-- ##### FUNCTION gdk_pixbuf_loader_new ##### -->
......@@ -60,29 +63,40 @@ Application-driven image loading.
<!-- ##### 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:
......@@ -90,3 +104,4 @@ mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
End:
-->
......@@ -98,8 +98,7 @@ the image data.
</para>
@pixbuf:
@Returns:
<!--
@Returns: <!--
Local variables:
mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
......
......@@ -160,6 +160,20 @@ Canvas item to display #GdkPixbuf images.
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
......@@ -179,18 +193,13 @@ Canvas item to display #GdkPixbuf images.
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 ##### -->
......@@ -210,13 +219,13 @@ Canvas item to display #GdkPixbuf images.
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 ##### -->
......@@ -237,15 +246,21 @@ Canvas item to display #GdkPixbuf images.
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
......@@ -263,18 +278,3 @@ Canvas item to display #GdkPixbuf images.
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:
-->
......@@ -33,8 +33,7 @@ Functions to perform reference counting on a #GdkPixbuf.
</para>
@pixbuf:
<!--
@pixbuf: <!--
Local variables:
mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
......
......@@ -96,8 +96,7 @@ In the future it will do full alpha compositing.
@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
......
......@@ -295,7 +295,7 @@ gdk_pixbuf_new_from_file (const char *filename)
/**
* 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.
......
......@@ -307,15 +307,16 @@ gdk_pixbuf_loader_eat_header_write (GdkPixbufLoader *loader, const gchar *buf, s
/**
* 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)
......@@ -354,14 +355,16 @@ 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)
......@@ -380,7 +383,8 @@ 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)
......
......@@ -307,15 +307,16 @@ gdk_pixbuf_loader_eat_header_write (GdkPixbufLoader *loader, const gchar *buf, s
/**
* 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)
......@@ -354,14 +355,16 @@ 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)
......@@ -380,7 +383,8 @@ 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)
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment