forked from AuroraMiddleware/gtk
a70843bab2
1999-12-13 Federico Mena Quintero <federico@redhat.com> * gdk-pixbuf/gnome-canvas-pixbuf.c (gnome_canvas_pixbuf_class_init): Renamed arguments to width_in_pixels, height_in_pixels, x_in_pixels, y_in_pixels, for consistency with the new canvas. (PixbufPrivate): Do the same renaming in the structure fields, for consistency. * doc/tmpl/gnome-canvas-pixbuf.sgml: Updated for new argument names.
331 lines
13 KiB
Plaintext
331 lines
13 KiB
Plaintext
<!-- ##### SECTION Title ##### -->
|
|
GnomeCanvasPixbuf
|
|
|
|
<!-- ##### SECTION Short_Description ##### -->
|
|
Canvas item to display #GdkPixbuf images.
|
|
|
|
<!-- ##### SECTION Long_Description ##### -->
|
|
<para>
|
|
This canvas item displays #GdkPixbuf images. It handles full
|
|
affine transformations in both GDK and antialiased modes, and also
|
|
supports the <ulink url="http://www.w3.org">W3C</ulink>'s <ulink
|
|
url="http://www.w3.org/Graphics/SVG/">SVG</ulink>-like scaling and
|
|
translation semantics for absolute pixel values.
|
|
</para>
|
|
|
|
<para>
|
|
#GdkPixbuf structures may be shared among different pixbuf canvas
|
|
items; the pixbuf item uses #GdkPixbuf's reference counting
|
|
functions for this.
|
|
</para>
|
|
|
|
<refsect2>
|
|
<title>Custom Scaling and Translation</title>
|
|
|
|
<para>
|
|
In addition to the normal affine transformations supported by
|
|
canvas items, the #GnomeCanvasPixbuf item supports independent
|
|
object arguments for scaling and translation. This is useful
|
|
for explicitly setting a size to which the pixbuf's image will
|
|
be scaled, and for specifying translation offsets that take
|
|
place in the item's local coordinate system.
|
|
</para>
|
|
|
|
<para>
|
|
By default, the pixbuf canvas item will attain the size in units
|
|
of the #GdkPixbuf it contains. If a #GnomeCanvasPixbuf is
|
|
configured to use a #GdkPixbuf that has a size of 300 by 200
|
|
pixels, then the pixbuf item will automatically obtain a size of
|
|
300 by 200 units in the item's local coordinate system. If the
|
|
item is transformed with a scaling transformation of (0.5, 2.0),
|
|
then the final image size will be of 150 by 400 pixels.
|
|
</para>
|
|
|
|
<para>
|
|
To set custom width and height values, you must set the <link
|
|
linkend="GnomeCanvasPixbuf--width-set">width_set</link> or <link
|
|
linkend="GnomeCanvasPixbuf--height-set">height_set</link>
|
|
arguments to %TRUE, and then set the <link
|
|
linkend="GnomeCanvasPixbuf--width">width</link> or <link
|
|
linkend="GnomeCanvasPixbuf--height">height</link> arguments to
|
|
the desired values. The former two arguments control whether
|
|
the latter two are used when computing the final image's size;
|
|
they are both %FALSE by default so that the pixbuf item will
|
|
attain a size in units equal to the size in pixels of the
|
|
#GdkPixbuf that the item contains.
|
|
</para>
|
|
|
|
<para>
|
|
The custom translation values are analogously controlled by the
|
|
<link linkend="GnomeCanvasPixbuf--x-set">x_set</link>, <link
|
|
linkend="GnomeCanvasPixbuf--y-set">y_set</link>, <link
|
|
linkend="GnomeCanvasPixbuf--x">x</link>, and <link
|
|
linkend="GnomeCanvasPixbuf--y">y</link> arguments. The former
|
|
two control whether the custom translation offsets are used and
|
|
they are %FALSE by default, and the latter two control the
|
|
offsets themselves. If a custom translation offset is not used,
|
|
it is taken to be 0.0 by default. Otherwise, the logical
|
|
upper-left vertex of the image will be translated by the
|
|
specified distance, aligned with the item's local coordinate
|
|
system.
|
|
</para>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Absolute Pixel Scaling and Translation</title>
|
|
|
|
<para>
|
|
The <ulink url="http://www.w3.org/Graphics/SVG/">Scalable Vector
|
|
Graphics</ulink> specification (SVG) of the <ulink
|
|
url="http://www.w3.org">World Wide Web Consortium</ulink> also
|
|
allows images to be translated and scaled by absolute pixel
|
|
values that are independent of an item's normal affine
|
|
transformation.
|
|
</para>
|
|
|
|
<para>
|
|
Normally, the pixbuf item's translation and scaling arguments
|
|
are interpreted in units, so they will be modified by the item's
|
|
affine transformation. The <link
|
|
linkend="GnomeCanvasPixbuf--width-in-pixels">width_in_pixels</link>,
|
|
<link
|
|
linkend="GnomeCanvasPixbuf--height-in-pixels">height_in_pixels</link>,
|
|
<link
|
|
linkend="GnomeCanvasPixbuf--x-in-pixels">x_in_pixels</link>, and
|
|
<link
|
|
linkend="GnomeCanvasPixbuf--y-in-pixels">y_in_pixels</link>
|
|
object arguments can be used to modify this behavior. If one of
|
|
these arguments is %TRUE, then the corresponding scaling or
|
|
translation value will not be affected lengthwise by the pixbuf
|
|
item's affine transformation.
|
|
</para>
|
|
|
|
<para>
|
|
For example, consider a pixbuf item whose size is (300, 200).
|
|
If the item is modified with a scaling transformation of (0.5,
|
|
2.0) but the <link
|
|
linkend="GnomeCanvasPixbuf--width-in-pixels">width_in_pixels</link>
|
|
is set to %TRUE, then the item will appear to be (300, 400)
|
|
pixels in size. This means that in this case the item's affine
|
|
transformation only applies to the height value, while the width
|
|
value is kept in absolute pixels.
|
|
</para>
|
|
|
|
<para>
|
|
Likewise, consider a pixbuf item whose (<link
|
|
linkend="GnomeCanvasPixbuf--x">x</link>, <link
|
|
linkend="GnomeCanvasPixbuf--y">y</link>) arguments are set to
|
|
(30, 40)<footnote>
|
|
<para>
|
|
This of course assumes that the <link
|
|
linkend="GnomeCanvasPixbuf--x-set">x_set</link> and <link
|
|
linkend="GnomeCanvasPixbuf--y-set">y_set</link> arguments
|
|
are set to %TRUE for the translation offsets to take effect.
|
|
</para>
|
|
</footnote>. If the item is then modified by the same scaling
|
|
transformation of (0.5, 2.0) but the <link
|
|
linkend="GnomeCanvasPixbuf--y-in-pixels">y_in_pixels</link>
|
|
argument is set to %TRUE, then the image's upper-left corner
|
|
will appear to be at position (15, 40). In this case, the
|
|
affine transformation is applied only to the x offset, while the
|
|
y offset is kept in absolute pixels.
|
|
</para>
|
|
|
|
<para>
|
|
In short, these arguments control whether a particular dimension
|
|
of a pixbuf item is scaled or not in the normal way by the
|
|
item's affine transformation.
|
|
</para>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Resource Management</title>
|
|
|
|
<para>
|
|
When you set the #GdkPixbuf structure that a #GnomeCanvasPixbuf
|
|
item will use by setting the <link
|
|
linkend="GnomeCanvasPixbuf--pixbuf">pixbuf</link> argument, a
|
|
reference count will be added to that #GdkPixbuf structure.
|
|
When the pixbuf item no longer needs the #GdkPixbuf structure,
|
|
such as when the item is destroyed or when a new pixbuf
|
|
structure is passed to it, then the old #GdkPixbuf structure
|
|
will be automatically unreferenced.
|
|
</para>
|
|
|
|
<para>
|
|
This means that if an application just needs to load a pixbuf
|
|
image and set it into a pixbuf canvas item, it can do the
|
|
following to ‘forget’ about the pixbuf structure:
|
|
|
|
<programlisting>
|
|
GdkPixbuf *pixbuf;
|
|
GnomeCanvasItem *item;
|
|
|
|
pixbuf = gdk_pixbuf_new_from_file ("foo.png");
|
|
g_assert (pixbuf != NULL);
|
|
|
|
item = gnome_canvas_item_new (gnome_canvas_root (my_canvas),
|
|
gnome_canvas_pixbuf_get_type (),
|
|
"pixbuf", pixbuf,
|
|
NULL);
|
|
gdk_pixbuf_unref (pixbuf);
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
After this happens, the reference count of the pixbuf structure
|
|
will be 1: the gdk_pixbuf_new_from_file() function creates it
|
|
with a reference count of 1, then setting the <link
|
|
linkend="GnomeCanvasPixbuf--pixbuf">pixbuf</link> argument of
|
|
the #GnomeCanvasPixbuf item increases it to 2, and then it is
|
|
decremented to 1 by the call to gdk_pixbuf_unref(). When the
|
|
canvas item is destroyed, it will automatically unreference the
|
|
pixbuf structure again, causing its reference count to drop to
|
|
zero and thus be freed.
|
|
</para>
|
|
</refsect2>
|
|
|
|
<!-- ##### SECTION See_Also ##### -->
|
|
<para>
|
|
#GnomeCanvas, #GdkPixbuf
|
|
</para>
|
|
|
|
<!-- ##### MACRO GNOME_CANVAS_PIXBUF ##### -->
|
|
<para>
|
|
Casts a #GtkOjbect to a #GnomeCanvasPixbuf.
|
|
</para>
|
|
|
|
@obj: A GTK+ object.
|
|
|
|
|
|
<!-- ##### ARG GnomeCanvasPixbuf:pixbuf ##### -->
|
|
<para>
|
|
Contains a pointer to a #GdkPixbuf structure that will be used by
|
|
the pixbuf canvas item as an image source. When a pixbuf is set
|
|
its reference count is incremented; if the pixbuf item kept a
|
|
pointer to another #GdkPixbuf structure, the reference count of
|
|
this structure will be decremented. Also, the GdkPixbuf's
|
|
reference count will automatically be decremented when the
|
|
#GnomeCanvasPixbuf item is destroyed. When a pixbuf is queried, a
|
|
reference count will not be added to the return value; you must do
|
|
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-in-pixels">width_in_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_in_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
|
|
linkend="GnomeCanvasPixbuf--width">width</link> argument is taken
|
|
into account when scaling the pixbuf item. If this argument is
|
|
%FALSE, then the width value of the pixbuf's #ArtPixBuf will be
|
|
used instead. This argument is %FALSE by default.
|
|
</para>
|
|
|
|
<!-- ##### ARG GnomeCanvasPixbuf:width_in_pixels ##### -->
|
|
<para>
|
|
If this argument is %TRUE, then the width of the pixbuf will be
|
|
considered to be in pixels, that is, it will not be visually
|
|
scaled even if the item's affine transformation changes. If this
|
|
is %FALSE, then the width of the pixbuf will be considered to be
|
|
in canvas units, and so will be scaled normally by affine
|
|
transformations. The default is %FALSE.
|
|
</para>
|
|
|
|
<!-- ##### ARG GnomeCanvasPixbuf:height ##### -->
|
|
<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.
|
|
</para>
|
|
|
|
<!-- ##### ARG GnomeCanvasPixbuf:height_set ##### -->
|
|
<para>
|
|
Determines whether the <link
|
|
linkend="GnomeCanvasPixbuf--height">height</link> argument is
|
|
taken into account when scaling the pixbuf item. Works in the
|
|
same way as the <link
|
|
linkend="GnomeCanvasPixbuf--width-set">width_set</link> argument.
|
|
The default is %FALSE.
|
|
</para>
|
|
|
|
<!-- ##### ARG GnomeCanvasPixbuf:height_in_pixels ##### -->
|
|
<para>
|
|
Works in the same way as the <link
|
|
linkend="GnomeCanvasPixbuf--width-in-pixels">width_in_pixels</link>
|
|
argument. The default is %FALSE.
|
|
</para>
|
|
|
|
<!-- ##### ARG GnomeCanvasPixbuf:x ##### -->
|
|
<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.
|
|
</para>
|
|
|
|
<!-- ##### ARG GnomeCanvasPixbuf:x_set ##### -->
|
|
<para>
|
|
Determines whether the <link
|
|
linkend="GnomeCanvasPixbuf--x">x</link> argument is used to
|
|
translate the pixbuf from its logical origin in item-relative
|
|
coordinates.
|
|
</para>
|
|
|
|
<!-- ##### ARG GnomeCanvasPixbuf:x_in_pixels ##### -->
|
|
<para>
|
|
If this argument is %TRUE, the pixbuf's translation with respect
|
|
to its logical origin in item-relative coordinates will be in
|
|
pixels, that is, the visible offset will not change even if the
|
|
item's affine transformation changes. If it is %FALSE, the
|
|
pixbuf's translation will be taken to be in canvas units, and thus
|
|
will change along with the item's affine transformation.
|
|
</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>
|
|
|
|
<!-- ##### ARG GnomeCanvasPixbuf:y_set ##### -->
|
|
<para>
|
|
Determines whether the <link
|
|
linkend="GnomeCanvasPixbuf--y">y</link> argument is used to
|
|
translate the pixbuf from its logical origin in item-relative
|
|
coordinates. Works in the same way as the <link
|
|
linkend="GnomeCanvasPixbuf--x-set">x_set</link> argument. The
|
|
default is %FALSE.
|
|
</para>
|
|
|
|
<!-- ##### ARG GnomeCanvasPixbuf:y_in_pixels ##### -->
|
|
<para>
|
|
Works in the same way as the <link
|
|
linkend="GnomeCanvasPixbuf--x-in-pixels">x_in_pixels</link>
|
|
argument. The default is %FALSE.
|
|
</para>
|
|
|
|
<!--
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
|
|
End:
|
|
-->
|
|
|