Gnome User Interface Library Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# GnomeCanvasItem

## Name

GnomeCanvasItem --

## Synopsis

    #include <gnome.h>

    struct      GnomeCanvasItem;
    GnomeCanvasItem* gnome_canvas_item_new      (GnomeCanvasGroup *parent,
                                                 GtkType type,
                                                 const gchar *first_arg_name,
                                                 ...);
    GnomeCanvasItem* gnome_canvas_item_newv     (GnomeCanvasGroup *parent,
                                                 GtkType type,
                                                 guint nargs,
                                                 GtkArg *args);
    void        gnome_canvas_item_construct     (GnomeCanvasItem *item,
                                                 GnomeCanvasGroup *parent,
                                                 const gchar *first_arg_name,
                                                 va_list args);
    void        gnome_canvas_item_constructv    (GnomeCanvasItem *item,
                                                 GnomeCanvasGroup *parent,
                                                 guint nargs,
                                                 GtkArg *args);
    void        gnome_canvas_item_set           (GnomeCanvasItem *item,
                                                 const gchar *first_arg_name,
                                                 ...);
    void        gnome_canvas_item_setv          (GnomeCanvasItem *item,
                                                 guint nargs,
                                                 GtkArg *args);
    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_scale         (GnomeCanvasItem *item,
                                                 double x,
                                                 double y,
                                                 double scale_x,
                                                 double scale_y);
    void        gnome_canvas_item_rotate        (GnomeCanvasItem *item,
                                                 double x,
                                                 double y,
                                                 double angle);
    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

      GtkObject
       +----GnomeCanvasItem

## Description

## Details

### struct GnomeCanvasItem

    struct GnomeCanvasItem;

### gnome_canvas_item_new ()

    GnomeCanvasItem* gnome_canvas_item_new      (GnomeCanvasGroup *parent,
                                                 GtkType 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.

`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_newv ()

    GnomeCanvasItem* gnome_canvas_item_newv     (GnomeCanvasGroup *parent,
                                                 GtkType type,
                                                 guint nargs,
                                                 GtkArg *args);

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 is used to configure the item.

`parent` : | The parent group for the new item.
`type` : | The object type of the item.
`nargs` : | The number of arguments used to configure the item.
`args` : | The list of arguments used to configure the item.
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_constructv ()

    void        gnome_canvas_item_constructv    (GnomeCanvasItem *item,
                                                 GnomeCanvasGroup *parent,
                                                 guint nargs,
                                                 GtkArg *args);

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

`item` : | An unconstructed canvas item.
`parent` : | The parent group for the item.
`nargs` : | The number of arguments used to configure 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_setv ()

    void        gnome_canvas_item_setv          (GnomeCanvasItem *item,
                                                 guint nargs,
                                                 GtkArg *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.
`nargs` : | The number of arguments used to configure the item.
`args` : | The arguments 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.
`var_args` : |

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

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

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

`item` : | A canvas item.
`affine` : | An affine transformation matrix.

### gnome_canvas_item_scale ()

    void        gnome_canvas_item_scale         (GnomeCanvasItem *item,
                                                 double x,
                                                 double y,
                                                 double scale_x,
                                                 double scale_y);

`item` : |
`x` : |
`y` : |
`scale_x` : |
`scale_y` : |

### gnome_canvas_item_rotate ()

    void        gnome_canvas_item_rotate        (GnomeCanvasItem *item,
                                                 double x,
                                                 double y,
                                                 double angle);

`item` : |
`x` : |
`y` : |
`angle` : |

### 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 `AlreadyGrabbed`. 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 : | `GrabNotViewable`. 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.

<<< Previous Page | Home | Up | Next Page >>>
GnomeCanvas | GnomeCanvasGroup