The
gdk-pixbuf
Library
gdkpixbufloader.html
<<< Previous Page
index.html
Home
r27.html
Up
gdk-pixbuf-gdk-pixbuf-xlib-init.html
Next Page >>>
GnomeCanvasPixbuf
Name
GnomeCanvasPixbuf -- Canvas item to display GdkPixbuf images.
Synopsis
#include <gdk-pixbuf/gdk-pixbuf.h>
#define
gnomecanvaspixbuf.html#GNOME-CANVAS-PIXBUF-CAPS
GNOME_CANVAS_PIXBUF
(obj)
Object Hierarchy
GtkObject
+----GnomeCanvasItem
+----GnomeCanvasPixbuf
Args
"
gnomecanvaspixbuf.html#GNOMECANVASPIXBUF--PIXBUF
pixbuf
"               gpointer             : Read / Write
"
gnomecanvaspixbuf.html#GNOMECANVASPIXBUF--WIDTH
width
"                gdouble              : Read / Write
"
gnomecanvaspixbuf.html#GNOMECANVASPIXBUF--WIDTH-SET
width-set
"            gboolean             : Read / Write
"
gnomecanvaspixbuf.html#GNOMECANVASPIXBUF--WIDTH-IN-PIXELS
width-in-pixels
"      gboolean             : Read / Write
"
gnomecanvaspixbuf.html#GNOMECANVASPIXBUF--HEIGHT
height
"               gdouble              : Read / Write
"
gnomecanvaspixbuf.html#GNOMECANVASPIXBUF--HEIGHT-SET
height-set
"           gboolean             : Read / Write
"
gnomecanvaspixbuf.html#GNOMECANVASPIXBUF--HEIGHT-IN-PIXELS
height-in-pixels
"     gboolean             : Read / Write
"
gnomecanvaspixbuf.html#GNOMECANVASPIXBUF--X
x
"                    gdouble              : Read / Write
"
gnomecanvaspixbuf.html#GNOMECANVASPIXBUF--X-IN-PIXELS
x-in-pixels
"          gboolean             : Read / Write
"
gnomecanvaspixbuf.html#GNOMECANVASPIXBUF--Y
y
"                    gdouble              : Read / Write
"
gnomecanvaspixbuf.html#GNOMECANVASPIXBUF--Y-IN-PIXELS
y-in-pixels
"          gboolean             : Read / Write
Description
This canvas item displays GdkPixbuf images.  It handles full
affine transformations in both GDK and antialiased modes, and also
supports the
http://www.w3.org
W3C
's
http://www.w3.org/Graphics/SVG/
SVG
-like scaling and
translation semantics for absolute pixel values.
GdkPixbuf structures may be shared among different pixbuf canvas
items; the pixbuf item uses GdkPixbuf's reference counting
functions for this.
Custom Scaling and Translation
In addition to the normal affine transformations supported by
canvas items, the
gnomecanvaspixbuf.html
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.
By default, the pixbuf canvas item will attain the size in units
of the GdkPixbuf it contains.  If a
gnomecanvaspixbuf.html
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.
To set custom width and height values, you must set the
gnomecanvaspixbuf.html#GNOMECANVASPIXBUF--WIDTH-SET
width_set
or
gnomecanvaspixbuf.html#GNOMECANVASPIXBUF--HEIGHT-SET
height_set
arguments to
TRUE
, and then set the
gnomecanvaspixbuf.html#GNOMECANVASPIXBUF--WIDTH
width
or
gnomecanvaspixbuf.html#GNOMECANVASPIXBUF--HEIGHT
height
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.
The custom translation offsets are controlled by the
gnomecanvaspixbuf.html#GNOMECANVASPIXBUF--X
x
and
gnomecanvaspixbuf.html#GNOMECANVASPIXBUF--Y
y
arguments.  The logical
upper-left vertex of the image will be translated by the
specified distance, aligned with the item's local coordinate
system.
Absolute Pixel Scaling and Translation
The
http://www.w3.org/Graphics/SVG/
Scalable Vector
Graphics
specification (SVG) of the
http://www.w3.org
World Wide Web Consortium
also
allows images to be translated and scaled by absolute pixel
values that are independent of an item's normal affine
transformation.
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
gnomecanvaspixbuf.html#GNOMECANVASPIXBUF--WIDTH-IN-PIXELS
width_in_pixels
,
gnomecanvaspixbuf.html#GNOMECANVASPIXBUF--HEIGHT-IN-PIXELS
height_in_pixels
,
gnomecanvaspixbuf.html#GNOMECANVASPIXBUF--X-IN-PIXELS
x_in_pixels
, and
gnomecanvaspixbuf.html#GNOMECANVASPIXBUF--Y-IN-PIXELS
y_in_pixels
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.
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
gnomecanvaspixbuf.html#GNOMECANVASPIXBUF--WIDTH-IN-PIXELS
width_in_pixels
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.
Likewise, consider a pixbuf item whose (
gnomecanvaspixbuf.html#GNOMECANVASPIXBUF--X
x
,
gnomecanvaspixbuf.html#GNOMECANVASPIXBUF--Y
y
) arguments are set to
(30, 40).  If the item is then modified by the same scaling
transformation of (0.5, 2.0) but the
gnomecanvaspixbuf.html#GNOMECANVASPIXBUF--Y-IN-PIXELS
y_in_pixels
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.
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.
Resource Management
When you set the GdkPixbuf structure that a
gnomecanvaspixbuf.html
GnomeCanvasPixbuf
item will use by setting the
gnomecanvaspixbuf.html#GNOMECANVASPIXBUF--PIXBUF
pixbuf
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.
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:
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);
After this happens, the reference count of the pixbuf structure
will be 1:  the
gdk-pixbuf-file-loading.html#GDK-PIXBUF-NEW-FROM-FILE
gdk_pixbuf_new_from_file
() function creates it
with a reference count of 1, then setting the
gnomecanvaspixbuf.html#GNOMECANVASPIXBUF--PIXBUF
pixbuf
argument of
the
gnomecanvaspixbuf.html
GnomeCanvasPixbuf
item increases it to 2, and then it is
decremented to 1 by the call to
gdk-pixbuf-refcounting.html#GDK-PIXBUF-UNREF
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.
Details
GNOME_CANVAS_PIXBUF()
#define     GNOME_CANVAS_PIXBUF(obj)
Casts a GtkOjbect to a
gnomecanvaspixbuf.html
GnomeCanvasPixbuf
.
obj
:
A GTK+ object.
Args
"
pixbuf
" (gpointer : Read / Write)
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.html
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.
"
width
" (gdouble : Read / Write)
Indicates the width the pixbuf will be scaled to.  This argument
will only be used if the
gnomecanvaspixbuf.html#GNOMECANVASPIXBUF--WIDTH-SET
width_set
argument
is
TRUE
.  If the
gnomecanvaspixbuf.html#GNOMECANVASPIXBUF--WIDTH-IN-PIXELS
width_in_pixels
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.
"
width-set
" (gboolean : Read / Write)
Determines whether the
gnomecanvaspixbuf.html#GNOMECANVASPIXBUF--WIDTH
width
argument is taken
into account when scaling the pixbuf item.  If this argument is
FALSE
, then the width value of the pixbuf will be used instead.
This argument is
FALSE
by default.
"
width-in-pixels
" (gboolean : Read / Write)
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
.
"
height
" (gdouble : Read / Write)
Indicates the height the pixbuf will be scaled to.  This argument
will only be used if the
gnomecanvaspixbuf.html#GNOMECANVASPIXBUF--HEIGHT-SET
height_set
argument
is
TRUE
.  Works in the same way as the
gnomecanvaspixbuf.html#GNOMECANVASPIXBUF--WIDTH
width
argument.
"
height-set
" (gboolean : Read / Write)
Determines whether the
gnomecanvaspixbuf.html#GNOMECANVASPIXBUF--HEIGHT
height
argument is
taken into account when scaling the pixbuf item.  Works in the
same way as the
gnomecanvaspixbuf.html#GNOMECANVASPIXBUF--WIDTH-SET
width_set
argument.
The default is
FALSE
.
"
height-in-pixels
" (gboolean : Read / Write)
Works in the same way as the
gnomecanvaspixbuf.html#GNOMECANVASPIXBUF--WIDTH-IN-PIXELS
width_in_pixels
argument.  The default is
FALSE
.
"
x
" (gdouble : Read / Write)
Indicates the horizontal translation offset of the pixbuf item's
image.  This offset may not actually appear horizontal, since it
will be affected by the item's affine transformation.  The default
is 0.0.
"
x-in-pixels
" (gboolean : Read / Write)
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.  The
default is
FALSE
.
"
y
" (gdouble : Read / Write)
Indicates the vertical translation offset of the pixbuf item's
image.  Works in the same way as the
gnomecanvaspixbuf.html#GNOMECANVASPIXBUF--X
x
argument.  The default is
0.0.
"
y-in-pixels
" (gboolean : Read / Write)
Works in the same way as the
gnomecanvaspixbuf.html#GNOMECANVASPIXBUF--X-IN-PIXELS
x_in_pixels
argument, but controls whether the
gnomecanvaspixbuf.html#GNOMECANVASPIXBUF--Y
y
translation offset is
scaled or not.  The default is
FALSE
.
See Also
GnomeCanvas, GdkPixbuf
gdkpixbufloader.html
<<< Previous Page
index.html
Home
r27.html
Up
gdk-pixbuf-gdk-pixbuf-xlib-init.html
Next Page >>>
GdkPixbufLoader
gdk-pixbuf
Xlib initialization
