mirror of
https://gitlab.gnome.org/GNOME/gtk.git
synced 2024-11-18 17:30:10 +00:00
e7b2454ce3
1999-12-08 Federico Mena Quintero <federico@redhat.com> * gdk-pixbuf/gdk-pixbuf-drawable.c: Fix includes. (gdk_pixbuf_get_from_drawable): Implemented the zillion sanity checks and API definition. The body needs filling in and it needs to do the Right Thing(tm) for pixmaps plus the given colormap and windows and their own colormaps. * gdk-pixbuf/gdk-pixbuf.h: Added prototype for gdk_pixbuf_get_from_drawable(). Killed gdk-pixbuf-drawable.h. * gdk-pixbuf/Makefile.am: Re-added the gdk-pixbuf-drawable sources. * doc/tmpl/from-drawables.sgml: Populated. * doc/gdk-pixbuf.sgml: Added the from-drawables section. * doc/Makefile.am (tmpl_sources): Added tmpl/from-drawables.sgml. * doc/gdk-pixbuf-sections.txt: Added a section for getting pixbufs from drawables.
329 lines
13 KiB
Plaintext
329 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-pixels">width_pixels</link>,
|
|
<link
|
|
linkend="GnomeCanvasPixbuf--height-pixels">height_pixels</link>,
|
|
<link linkend="GnomeCanvasPixbuf--x-pixels">x_pixels</link>, and
|
|
<link linkend="GnomeCanvasPixbuf--y-pixels">y_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-pixels">width_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-pixels">y_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-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
|
|
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_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_pixels ##### -->
|
|
<para>
|
|
Works in the same way as the <link
|
|
linkend="GnomeCanvasPixbuf--width-pixels">width_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_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_pixels ##### -->
|
|
<para>
|
|
Works in the same way as the <link
|
|
linkend="GnomeCanvasPixbuf--x-pixels">x_pixels</link> argument.
|
|
The default is %FALSE.
|
|
</para>
|
|
|
|
<!--
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
|
|
End:
|
|
-->
|
|
|