Base class for all canvas items
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.
Derives from
<gtk-object>.This class defines the following properties:
parent
<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.
<gnome-canvas-item>) (dx double) (dy double)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.
<gnome-canvas-item>) (x1 double) (y2 double) (x2 double) (y2 double) (x3 double) (y3 double)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.
<gnome-canvas-item>) (x1 double) (y2 double) (x2 double) (y2 double) (x3 double) (y3 double)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.
<gnome-canvas-item>) (positions int)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.
<gnome-canvas-item>) (positions int)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.
<gnome-canvas-item>)Raises an item to the top of its parent's stack.
- item
- A canvas item.
<gnome-canvas-item>)Lowers an item to the bottom of its parent's stack.
- item
- A canvas item.
<gnome-canvas-item>)Shows a canvas item. If the item was already shown, then no action is taken.
- item
- A canvas item.
<gnome-canvas-item>)Hides a canvas item. If the item was already hidden, then no action is taken.
- item
- A canvas item.
<gnome-canvas-item>) (event_mask unsigned-int) (cursor <gdk-cursor>) (etime unsigned-int32) ⇒ (ret int)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.
<gnome-canvas-item>) (etime unsigned-int32)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.
<gnome-canvas-item>) ⇒ (x double) (y double)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).
<gnome-canvas-item>) ⇒ (x double) (y double)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).
<gnome-canvas-item>) (new_group <gnome-canvas-group>)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.
<gnome-canvas-item>)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.
<gnome-canvas-item>) ⇒ (x1 double) (y1 double) (x2 double) (y2 double)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).