## GnomeCanvasItem

GnomeCanvasItem — Base class for all canvas items

## Synopsis

    #include <libgnomecanvas/libgnomecanvas.h>

                        GnomeCanvasItem;
                        GnomeCanvasItemClass;
    GnomeCanvasItem*    gnome_canvas_item_new               (GnomeCanvasGroup *parent,
                                                             GType type,
                                                             const gchar *first_arg_name,
                                                             ...);
    void                gnome_canvas_item_construct         (GnomeCanvasItem *item,
                                                             GnomeCanvasGroup *parent,
                                                             const gchar *first_arg_name,
                                                             va_list args);
    void                gnome_canvas_item_set               (GnomeCanvasItem *item,
                                                             const gchar *first_arg_name,
                                                             ...);
    void                gnome_canvas_item_set_valist        (GnomeCanvasItem *item,
                                                             const gchar *first_arg_name,
                                                             va_list args);
    void                gnome_canvas_item_move              (GnomeCanvasItem *item,
                                                             double dx,
                                                             double dy);
    void                gnome_canvas_item_affine_relative   (GnomeCanvasItem *item,
                                                             const double affine[6]);
    void                gnome_canvas_item_affine_absolute   (GnomeCanvasItem *item,
                                                             const double affine[6]);
    void                gnome_canvas_item_raise             (GnomeCanvasItem *item,
                                                             int positions);
    void                gnome_canvas_item_lower             (GnomeCanvasItem *item,
                                                             int positions);
    void                gnome_canvas_item_raise_to_top      (GnomeCanvasItem *item);
    void                gnome_canvas_item_lower_to_bottom   (GnomeCanvasItem *item);
    void                gnome_canvas_item_show              (GnomeCanvasItem *item);
    void                gnome_canvas_item_hide              (GnomeCanvasItem *item);
    int                 gnome_canvas_item_grab              (GnomeCanvasItem *item,
                                                             unsigned int event_mask,
                                                             GdkCursor *cursor,
                                                             guint32 etime);
    void                gnome_canvas_item_ungrab            (GnomeCanvasItem *item,
                                                             guint32 etime);
    void                gnome_canvas_item_w2i               (GnomeCanvasItem *item,
                                                             double *x,
                                                             double *y);
    void                gnome_canvas_item_i2w               (GnomeCanvasItem *item,
                                                             double *x,
                                                             double *y);
    void                gnome_canvas_item_i2w_affine        (GnomeCanvasItem *item,
                                                             double affine[6]);
    void                gnome_canvas_item_i2c_affine        (GnomeCanvasItem *item,
                                                             double affine[6]);
    void                gnome_canvas_item_reparent          (GnomeCanvasItem *item,
                                                             GnomeCanvasGroup *new_group);
    void                gnome_canvas_item_grab_focus        (GnomeCanvasItem *item);
    void                gnome_canvas_item_get_bounds        (GnomeCanvasItem *item,
                                                             double *x1,
                                                             double *y1,
                                                             double *x2,
                                                             double *y2);
    void                gnome_canvas_item_request_update    (GnomeCanvasItem *item);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkObject
                   +----GnomeCanvasItem
                         +----GnomeCanvasShape
                         +----GnomeCanvasGroup
                         +----GnomeCanvasLine
                         +----GnomeCanvasPixbuf
                         +----GnomeCanvasRichText
                         +----GnomeCanvasText
                         +----GnomeCanvasWidget

## Properties

      "parent"                   GnomeCanvasItem       : Read / Write

## Signals

      "event"                                          : Run Last

## Description

This is the base class for all canvas items. Canvas items are the drawing elements of a GnomeCanvas. 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 GnomeCanvasPolygon has a "fill-color" property that is inherited from its parent class object GnomeCanvasShape. So be sure to check the parent classes of GnomeCanvasItem 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 GnomeCanvasGroup, 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()`.

## Details

### GnomeCanvasItem

    typedef struct _GnomeCanvasItem GnomeCanvasItem;

This structure should not be accessed directly. Use the object's properties and functions for querying or changing its parameters.

### GnomeCanvasItemClass

    typedef struct {
    	GtkObjectClass parent_class;

    	/* Tell the item to update itself.  The flags are from the update flags
    	 * defined above.  The item should update its internal state from its
    	 * queued state, and recompute and request its repaint area.  The
    	 * affine, if used, is a pointer to a 6-element array of doubles.  The
    	 * update method also recomputes the bounding box of the item.
    	 */
    	void (* update) (GnomeCanvasItem *item, double *affine, ArtSVP *clip_path, int flags);

    	/* Realize an item -- create GCs, etc. */
    	void (* realize) (GnomeCanvasItem *item);

    	/* Unrealize an item */
    	void (* unrealize) (GnomeCanvasItem *item);

    	/* Map an item - normally only need by items with their own GdkWindows */
    	void (* map) (GnomeCanvasItem *item);

    	/* Unmap an item */
    	void (* unmap) (GnomeCanvasItem *item);

    	/* Return the microtile coverage of the item */
    	ArtUta *(* coverage) (GnomeCanvasItem *item);

    	/* Draw an item of this type.  (x, y) are the upper-left canvas pixel
    	 * coordinates of the drawable, a temporary pixmap, where things get
    	 * drawn.  (width, height) are the dimensions of the drawable.
    	 */
    	void (* draw) (GnomeCanvasItem *item, GdkDrawable *drawable,
    		       int x, int y, int width, int height);

    	/* Render the item over the buffer given.  The buf data structure
    	 * contains both a pointer to a packed 24-bit RGB array, and the
    	 * coordinates.  This method is only used for antialiased canvases.
    	 *
    	 * TODO: figure out where clip paths fit into the rendering framework.
    	 */
    	void (* render) (GnomeCanvasItem *item, GnomeCanvasBuf *buf);

    	/* Calculate the distance from an item to the specified point.  It also
             * returns a canvas item which is the item itself in the case of the
             * object being an actual leaf item, or a child in case of the object
             * being a canvas group.  (cx, cy) are the canvas pixel coordinates that
             * correspond to the item-relative coordinates (x, y).
    	 */
    	double (* point) (GnomeCanvasItem *item, double x, double y, int cx, int cy,
    			  GnomeCanvasItem **actual_item);

    	/* Fetch the item's bounding box (need not be exactly tight).  This
    	 * should be in item-relative coordinates.
    	 */
    	void (* bounds) (GnomeCanvasItem *item, double *x1, double *y1, double *x2, double *y2);

    	/* Signal: an event occurred for an item of this type.  The (x, y)
    	 * coordinates are in the canvas world coordinate system.
    	 */
    	gboolean (* event)                (GnomeCanvasItem *item, GdkEvent *event);

    	/* Reserved for future expansion */
    	gpointer spare_vmethods [4];
    } GnomeCanvasItemClass;

The internals of this class structure are of interest to those creating objects derived from GnomeCanvasItem.

GtkObjectClass `parent_class`; | Parent derived class.
`update` () | Update method called to tell the item to update itself.
`realize` () | Realize an item (create graphics contexts, etc).
`unrealize` () | Unrealize an item.
`map` () | Map an item - normally only needed by items with their own GdkWindows.
`unmap` () | Unmap an item.
`coverage` () | Return the microtile coverage of the item.
`draw` () | Draw an item of this type.
`render` () | Render the item for anti-aliased canvases.
`point` () | Calculate the distance from an item to a point.
`bounds` () | Fetch the item's bounding box (rectangular area it occupies).
`event` () | The class signal method for the "event" signal.
gpointer `spare_vmethods`[4]; | Reserved.

### gnome_canvas_item_new ()

    GnomeCanvasItem*    gnome_canvas_item_new               (GnomeCanvasGroup *parent,
                                                             GType type,
                                                             const gchar *first_arg_name,
                                                             ...);

Creates a new canvas item with `parent` as its parent group. The item is created at the top of its parent's stack, and starts up as visible. The item is of the specified `type`, for example, it can be `gnome_canvas_rect_get_type()`. The list of object arguments/value pairs is used to configure the item. If you need to pass construct time parameters, you should use `g_object_new()` to pass the parameters and `gnome_canvas_item_construct()` to set up the canvas item.

`parent` : | The parent group for the new item.
`type` : | The object type of the item.
`first_arg_name` : | A list of object argument name/value pairs, NULL-terminated, used to configure the item. For example, "fill_color", "black", "width_units", 5.0, NULL.
`...` : |
Returns : | The newly-created item.

### gnome_canvas_item_construct ()

    void                gnome_canvas_item_construct         (GnomeCanvasItem *item,
                                                             GnomeCanvasGroup *parent,
                                                             const gchar *first_arg_name,
                                                             va_list args);

Constructs a canvas item; meant for use only by item implementations.

`item` : | An unconstructed canvas item.
`parent` : | The parent group for the item.
`first_arg_name` : | The name of the first argument for configuring the item.
`args` : | The list of arguments used to configure the item.

### gnome_canvas_item_set ()

    void                gnome_canvas_item_set               (GnomeCanvasItem *item,
                                                             const gchar *first_arg_name,
                                                             ...);

Configures a canvas item. The arguments in the item are set to the specified values, and the item is repainted as appropriate.

`item` : | A canvas item.
`first_arg_name` : | The list of object argument name/value pairs used to configure the item.
`...` : |

### gnome_canvas_item_set_valist ()

    void                gnome_canvas_item_set_valist        (GnomeCanvasItem *item,
                                                             const gchar *first_arg_name,
                                                             va_list args);

Configures a canvas item. The arguments in the item are set to the specified values, and the item is repainted as appropriate.

`item` : | A canvas item.
`first_arg_name` : | The name of the first argument used to configure the item.
`args` : | The list of object argument name/value pairs used to configure the item.

### gnome_canvas_item_move ()

    void                gnome_canvas_item_move              (GnomeCanvasItem *item,
                                                             double dx,
                                                             double dy);

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_affine_relative ()

    void                gnome_canvas_item_affine_relative   (GnomeCanvasItem *item,
                                                             const double affine[6]);

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_affine_absolute ()

    void                gnome_canvas_item_affine_absolute   (GnomeCanvasItem *item,
                                                             const double affine[6]);

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_raise ()

    void                gnome_canvas_item_raise             (GnomeCanvasItem *item,
                                                             int positions);

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_lower ()

    void                gnome_canvas_item_lower             (GnomeCanvasItem *item,
                                                             int positions);

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_raise_to_top ()

    void                gnome_canvas_item_raise_to_top      (GnomeCanvasItem *item);

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

`item` : | A canvas item.

### gnome_canvas_item_lower_to_bottom ()

    void                gnome_canvas_item_lower_to_bottom   (GnomeCanvasItem *item);

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

`item` : | A canvas item.

### gnome_canvas_item_show ()

    void                gnome_canvas_item_show              (GnomeCanvasItem *item);

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

`item` : | A canvas item.

### gnome_canvas_item_hide ()

    void                gnome_canvas_item_hide              (GnomeCanvasItem *item);

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

`item` : | A canvas item.

### gnome_canvas_item_grab ()

    int                 gnome_canvas_item_grab              (GnomeCanvasItem *item,
                                                             unsigned int event_mask,
                                                             GdkCursor *cursor,
                                                             guint32 etime);

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.
Returns : | `GDK_GRAB_NOT_VIEWABLE`. Else, it returns the result of calling `gdk_pointer_grab()`.

### gnome_canvas_item_ungrab ()

    void                gnome_canvas_item_ungrab            (GnomeCanvasItem *item,
                                                             guint32 etime);

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_w2i ()

    void                gnome_canvas_item_w2i               (GnomeCanvasItem *item,
                                                             double *x,
                                                             double *y);

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_i2w ()

    void                gnome_canvas_item_i2w               (GnomeCanvasItem *item,
                                                             double *x,
                                                             double *y);

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_i2w_affine ()

    void                gnome_canvas_item_i2w_affine        (GnomeCanvasItem *item,
                                                             double affine[6]);

Gets the affine transform that converts from the item's coordinate system to world coordinates.

`item` : | A canvas item
`affine` : | An affine transformation matrix (return value).

### gnome_canvas_item_i2c_affine ()

    void                gnome_canvas_item_i2c_affine        (GnomeCanvasItem *item,
                                                             double affine[6]);

Gets the affine transform that converts from item-relative coordinates to canvas pixel coordinates.

`item` : | A canvas item.
`affine` : | An affine transformation matrix (return value).

### gnome_canvas_item_reparent ()

    void                gnome_canvas_item_reparent          (GnomeCanvasItem *item,
                                                             GnomeCanvasGroup *new_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_grab_focus ()

    void                gnome_canvas_item_grab_focus        (GnomeCanvasItem *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_get_bounds ()

    void                gnome_canvas_item_get_bounds        (GnomeCanvasItem *item,
                                                             double *x1,
                                                             double *y1,
                                                             double *x2,
                                                             double *y2);

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).

### gnome_canvas_item_request_update ()

    void                gnome_canvas_item_request_update    (GnomeCanvasItem *item);

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

`item` : | A canvas item.

## Property Details

### The "`parent`" property

      "parent"                   GnomeCanvasItem       : Read / Write

Parent GnomeCanvasGroup that contains the item.

## Signal Details

### The "event" signal

    gboolean            user_function                      (GnomeCanvasItem *canvasitem,
                                                            GdkEvent        *event,
                                                            gpointer         user_data)       : Run Last

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 `y` coordinates of the `event` structure have been converted to canvas world coordinates.

`canvasitem` : | the object which received the signal.
`event` : | A GdkEvent structure containing the event that occurred.
`user_data` : | user data set when the signal handler was connected.
Returns : | Signal handlers should return `TRUE` to stop signal emission or `FALSE` to allow other signal handlers to process this event.