Next: , Previous: GnomeCanvasGroup, Up: Top


6 GnomeCanvasItem

Base class for all canvas items

6.1 Overview

This is the base class for all canvas items. Canvas items are the drawing elements of a <gnome-canvas>. Example items include lines, ellipses, polygons, images, text, curves and even arbitrary GTK+ widgets.

Canvas items use the GObject property system to query and set parameters. Properties are inherited so, for example, a <gnome-canvas-polygon> has a "fill-color" property that is inherited from its parent class object <gnome-canvas-shape>. So be sure to check the parent classes of <gnome-canvas-item> objects when looking for item properties. More information on GObject properties can be found in the glib library GObject API reference documentation.

To create a new canvas item call gnome-canvas-item-new which takes a parent <gnome-canvas-group>, GType of the item to create, and a NULL terminated list of name/value GObject properties to set for the new item.

To change an existing canvas item's properties call gnome-canvas-item-set, or g-object-set can also be used.

There are several functions to change the drawing stacking order of an item. Call gnome-canvas-item-raise to raise an item a specified number of positions or gnome-canvas-item-lower to lower it. To raise an item to the top call gnome-canvas-item-raise-to-top. The gnome-canvas-item-lower-to-bottom function will put it at the bottom.

To show an item call gnome-canvas-item-show. Note that canvas item's are shown by default and so do not need to be explicitly shown after creation (contrary to GTK+ widget behavior). Call gnome-canvas-item-hide to hide an item.

To move an item relative to its current position (item coordinates) call gnome-canvas-item-move or gnome-canvas-item-affine-relative for more complex transforms. gnome-canvas-item-affine-absolute can be used to set an item's transform to specific values (not offsets).

To convert between world and item coordinate systems call gnome-canvas-item-w2i, and to convert in the other direction call gnome-canvas-item-i2w. To get the transform for converting from item to world coordinates use gnome-canvas-item-i2w-affine or for converting item to canvas coordinates, gnome-canvas-item-i2c-affine.

Handling user input for interactive items is accomplished through a few functions and the "event" signal. To grab the mouse cursor call gnome-canvas-item-grab, it can be ungrabbed with gnome-canvas-item-ungrab (see gdk-pointer-grab of the GTK+ library for details). To grab keyboard focus call gnome-canvas-item-grab-focus. Received events will be signaled via the "event" signal.

Some other useful functions include a reparenting routine, gnome-canvas-item-reparent, and a function to query the bounding box of an item (a minumum rectangular area containing all parts of the item), gnome-canvas-item-get-bounds.

6.2 Usage

— Class: <gnome-canvas-item>

Derives from <gtk-object>.

This class defines the following properties:

parent
— Signal on <gnome-canvas-item>: event (arg0 <gdk-event>) ⇒ <gboolean>

Signals mouse button clicks, motion, enter/leave, and key press events on canvas items. Use this signal to create user interactive items. The "x") and converted to canvas world coordinates.

— Function: gnome-canvas-item-move (self <gnome-canvas-item>) (dx double) (dy double)
— Method: move

Moves a canvas item by creating an affine transformation matrix for translation by using the specified values. This happens in item local coordinate system, so if you have nontrivial transform, it most probably does not do, what you want.

item
A canvas item.
dx
Horizontal offset.
dy
Vertical offset.
— Function: gnome-canvas-item-affine-relative (self <gnome-canvas-item>) (x1 double) (y2 double) (x2 double) (y2 double) (x3 double) (y3 double)
— Method: affine-relative

Combines the specified affine transformation matrix with the item's current transformation. NULL affine is not allowed.

item
A canvas item.
affine
An affine transformation matrix.
— Function: gnome-canvas-item-affine-absolute (self <gnome-canvas-item>) (x1 double) (y2 double) (x2 double) (y2 double) (x3 double) (y3 double)
— Method: affine-absolute

Makes the item's affine transformation matrix be equal to the specified matrix. NULL affine is treated as identity.

item
A canvas item.
affine
An affine transformation matrix.
— Function: gnome-canvas-item-raise (self <gnome-canvas-item>) (positions int)
— Method: raise

Raises the item in its parent's stack by the specified number of positions. If the number of positions is greater than the distance to the top of the stack, then the item is put at the top.

item
A canvas item.
positions
Number of steps to raise the item.
— Function: gnome-canvas-item-lower (self <gnome-canvas-item>) (positions int)
— Method: lower

Lowers the item in its parent's stack by the specified number of positions. If the number of positions is greater than the distance to the bottom of the stack, then the item is put at the bottom.

item
A canvas item.
positions
Number of steps to lower the item.
— Function: gnome-canvas-item-raise-to-top (self <gnome-canvas-item>)
— Method: raise-to-top

Raises an item to the top of its parent's stack.

item
A canvas item.
— Function: gnome-canvas-item-lower-to-bottom (self <gnome-canvas-item>)
— Method: lower-to-bottom

Lowers an item to the bottom of its parent's stack.

item
A canvas item.
— Function: gnome-canvas-item-show (self <gnome-canvas-item>)
— Method: show

Shows a canvas item. If the item was already shown, then no action is taken.

item
A canvas item.
— Function: gnome-canvas-item-hide (self <gnome-canvas-item>)
— Method: hide

Hides a canvas item. If the item was already hidden, then no action is taken.

item
A canvas item.
— Function: gnome-canvas-item-grab (self <gnome-canvas-item>) (event_mask unsigned-int) (cursor <gdk-cursor>) (etime unsigned-int32) ⇒  (ret int)
— Method: grab

Specifies that all events that match the specified event mask should be sent to the specified item, and also grabs the mouse by calling gdk-pointer-grab. The event mask is also used when grabbing the pointer. If cursor is not NULL, then that cursor is used while the grab is active. The etime parameter is the timestamp required for grabbing the mouse.

Return value: If an item was already grabbed, it returns ‘GDK_GRAB_ALREADY_GRABBED’. If the specified item was hidden by calling gnome-canvas-item-hide, then it

item
A canvas item.
event-mask
Mask of events that will be sent to this item.
cursor
If non-NULL, the cursor that will be used while the grab is active.
etime
The timestamp required for grabbing the mouse, or GDK_CURRENT_TIME.
ret
GDK_GRAB_NOT_VIEWABLE’. Else, it returns the result of calling gdk-pointer-grab.
— Function: gnome-canvas-item-ungrab (self <gnome-canvas-item>) (etime unsigned-int32)
— Method: ungrab

Ungrabs the item, which must have been grabbed in the canvas, and ungrabs the mouse.

item
A canvas item that holds a grab.
etime
The timestamp for ungrabbing the mouse.
— Function: gnome-canvas-item-w2i (self <gnome-canvas-item>) ⇒  (double) (double)
— Method: w2i

Converts a coordinate pair from world coordinates to item-relative coordinates.

item
A canvas item.
x
X coordinate to convert (input/output value).
y
Y coordinate to convert (input/output value).
— Function: gnome-canvas-item-i2w (self <gnome-canvas-item>) ⇒  (double) (double)
— Method: i2w

Converts a coordinate pair from item-relative coordinates to world coordinates.

item
A canvas item.
x
X coordinate to convert (input/output value).
y
Y coordinate to convert (input/output value).
— Function: gnome-canvas-item-reparent (self <gnome-canvas-item>) (new_group <gnome-canvas-group>)
— Method: reparent

Changes the parent of the specified item to be the new group. The item keeps its group-relative coordinates as for its old parent, so the item may change its absolute position within the canvas.

item
A canvas item.
new-group
A canvas group.
— Function: gnome-canvas-item-grab-focus (self <gnome-canvas-item>)
— Method: grab-focus

Makes the specified item take the keyboard focus, so all keyboard events will be sent to it. If the canvas widget itself did not have the focus, it grabs it as well.

item
A canvas item.
— Function: gnome-canvas-item-get-bounds (self <gnome-canvas-item>) ⇒  (x1 double) (y1 double) (x2 double) (y2 double)
— Method: get-bounds

Queries the bounding box of a canvas item. The bounds are returned in the coordinate system of the item's parent.

item
A canvas item.
x1
Leftmost edge of the bounding box (return value).
y1
Upper edge of the bounding box (return value).
x2
Rightmost edge of the bounding box (return value).
y2
Lower edge of the bounding box (return value).
— Function: gnome-canvas-item-request-update (self <gnome-canvas-item>)
— Method: request-update

To be used only by item implementations. Requests that the canvas queue an update for the specified item.

item
A canvas item.