Most of the time you will be interested in canvas items
rather than the canvas itself. Canvas items are typically
very easy to use, compared to widgets; none of the
standard items have any unique signals, since they are
not interactive. (Since
GnomeCanvasItem is a subclass of GtkObject, however, you could
certainly have an item with signals if you wanted to.)
The GnomeCanvasItem base
class has a single signal,
"event", which is used to convey all types of
event. The "event" signal has
no default handler; canvas items do not respond to events
unless you connect handlers of your own. Figure 8 lists all the
useful functions for working with the GnomeCanvasItem base class.
To create a canvas item, you use the generic gnome_canvas_item_new() (or gnome_canvas_item_newv()). This function
accepts the group to place the item in, the GtkType of the GnomeCanvasItem subclass to create,
and finally a NULL-terminated list of arguments to set.
The argument list is purely for convenience, so you don't
have to call
gnome_canvas_item_set() immediately. gnome_canvas_item_new() creates a new
instance of the type with
gtk_type_new(), adds the item to its GnomeCanvasGroup, and schedules it to
be redrawn.
To destroy an item and remove it from the canvas, simply
call gtk_object_destroy(). You
can also use the standard reference counting mechanism
with canvas items.
You can set an item's affine using
gnome_canvas_item_affine_absolute(), or compose a
new affine with the item's existing affine using
gnome_canvas_item_affine_relative(). These functions
can be used to translate, scale, or rotate a canvas item
(however, scaling and rotation only work in antialiased
mode).
Items in a group are normally stacked in the order you
add them, with the most recently-added item "on top" and
the oldest item on the bottom. You can manipulate the
stacking order with
gnome_canvas_item_raise() and
gnome_canvas_item_lower(). These move an item up or
down by the given number of positions. It is safe to pass
in a too-large value for
positions; the item will be moved as far as
possible and no more. You can also request that an item
is moved to one extreme or the other, using gnome_canvas_item_raise_to_top() and gnome_canvas_item_lower_to_bottom.
Items can be shown and hidden; hidden items are not
rendered by the canvas and do not receive events. All
items are visible by default. The routines are gnome_canvas_item_show() and gnome_canvas_item_hide().
Reparenting a canvas item is straightforward; the only
rule is that the new group must be on the same canvas as
the old group.
gnome_canvas_item_grab_focus()
is analagous to
gtk_widget_grab_focus(); it sends all key events to
the item with the grab. It also sends focus change events
to the item (when the item gains or loses the focus).
Canvas items can grab and ungrab the mouse pointer just
as a GdkWindow can; the
arguments to
gnome_canvas_item_grab() are exactly analagous to
those of gdk_pointer_grab()
(see the chapter called GDK
Basics). While a canvas item has the pointer
grabbed, no other item receives events. Behind the
scenes, GnomeCanvas uses gdk_pointer_grab() to implement gnome_canvas_item_grab(), so an
item grabbing the mouse away from other items implies the
canvas grabbing the mouse away from other widgets.
The visual properties of canvas items are manipulated
almost entirely via object arguments. If you skipped the chapter called The GTK+
Object and Type System, go back and read the
section on object arguments now. Two functions are used
to set canvas item properties:
gnome_canvas_item_set() and
gnome_canvas_item_setv(). These are almost but not
quite equivalent to
gtk_object_set() and
gtk_object_setv()---they set object arguments in the
same way, but they also mark the canvas item to be
redrawn. So you should prefer them to the GtkObject variants. (This is
something of a design bug, and future canvas versions
will most likely allow you to use
gtk_object_set().)
gnome_canvas_item_request_update() marks the canvas
item as "dirty" and queues it to be redrawn. Internally,
the canvas uses a one-shot idle function to perform
redraws; that is, it waits until no more GTK+ events are
pending, then redraws itself a single time. It does this
by installing an idle function with
gtk_idle_add() and removing it after it runs once.
Thus
gnome_canvas_item_request_update() can be called
many times without creating an efficiency problem---it
pretty much does nothing at all if an update is already
pending.
