GocItem

## GocItem GocItem — Base canvas item. |

## Synopsis

                        GocItem;
                        GocItemClass;
    GocItem *           goc_item_new                        (GocGroup *parent,
                                                             GType type,
                                                             const gchar *first_arg_name,
                                                             ...);
    void                goc_item_destroy                    (GocItem *item);
    void                goc_item_set                        (GocItem *item,
                                                             const gchar *first_arg_name,
                                                             ...);
    double              goc_item_distance                   (GocItem *item,
                                                             double x,
                                                             double y,
                                                             GocItem **near_item);
    void                goc_item_draw                       (GocItem const *item,
                                                             cairo_t *cr);
    gboolean            goc_item_draw_region                (GocItem const *item,
                                                             cairo_t *cr,
                                                             double x0,
                                                             double y0,
                                                             double x1,
                                                             double y1);
    void                goc_item_invalidate                 (GocItem *item);
    void                goc_item_show                       (GocItem *item);
    void                goc_item_hide                       (GocItem *item);
    gboolean            goc_item_is_visible                 (GocItem *item);
    void                goc_item_get_bounds                 (GocItem const *item,
                                                             double *x0,
                                                             double *y0,
                                                             double *x1,
                                                             double *y1);
    void                goc_item_bounds_changed             (GocItem *item);
    void                goc_item_grab                       (GocItem *item);
    void                goc_item_ungrab                     (GocItem *item);
    void                goc_item_raise                      (GocItem *item,
                                                             int n);
    void                goc_item_lower                      (GocItem *item,
                                                             int n);
    void                goc_item_lower_to_bottom            (GocItem *item);
    void                goc_item_raise_to_top               (GocItem *item);

## Object Hierarchy

      GObject
       +----GocItem
             +----GocStyledItem
             +----GocGraph
             +----GocGroup
             +----GocPixbuf
             +----GocWidget

## Properties

      "canvas"                   GocCanvas*            : Read
      "parent"                   GocGroup*             : Read

## Description

GocItem is the virtual base object for canvas items.

## Details

### GocItem

    typedef struct _GocItem GocItem;

GocItem contains the following fields:

double x0; | The lowest horizontal bound of the item.
double y0; | The lowest vertical bound of the item.
double x1; | The highest horizontal bound of the item.
double y1; | The highest vertical bound of the item.

The various fields should not be accessed directly except from children objects which must update `x0`, `y0`, `x1`, and `y1` from their update_bounds method. All other fields are read-only and not documented.

### GocItemClass

    typedef struct {
    	GObjectClass	 base;

    	double			(*distance) (GocItem *item,
    					     double x, double y, GocItem **near_item);
    	void			(*draw) (GocItem const *item, cairo_t *cr);
    	gboolean		(*draw_region) (GocItem const *item, cairo_t *cr,
    						double x0, double y0, double x1, double y1);
    	void			(*update_bounds) (GocItem *item);
    	/* events related functions */
    	gboolean		(*button_pressed) (GocItem *item, int button, double x, double y);
    	gboolean		(*button2_pressed) (GocItem *item, int button, double x, double y);
    	gboolean		(*button_released) (GocItem *item, int button, double x, double y);
    	gboolean		(*motion) (GocItem *item, double x, double y);
    	gboolean		(*enter_notify) (GocItem *item, double x, double y);
    	gboolean		(*leave_notify) (GocItem *item, double x, double y);
    	void			(*realize) (GocItem *item);
    	void			(*unrealize) (GocItem *item);
    	gboolean		(*key_pressed) (GocItem *item, GdkEventKey* ev);
    	gboolean		(*key_released) (GocItem *item, GdkEventKey* ev);
    	void			(*notify_scrolled) (GocItem *item);
    } GocItemClass;

The base class for all canvas items.

GObjectClass `base`; | the parent class
`distance` () | returns the distance between the item and the point defined by `x` and `y`. When the distance is larger than a few pixels, the result is not relevant, so an approximate value or even G_MAXDOUBLE might be returned.
`draw` () | draws the item to the cairo context.
`draw_region` () | draws the item in the region defined by `x0`, `y0`, `x1` and `y1`. Should return TRUE when successfull. If FALSE is returned, `draw` will be called. There is no need to implement both methods for an item. Large items should implement `draw_region`.
`update_bounds` () | updates the bounds stored in GocItem as fields x0, y0, x1,and y1.
`button_pressed` () | callback for a button press event.
`button2_pressed` () | callback for a double click event.
`button_released` () | callback for a button release event.
`motion` () | callback for a motion event.
`enter_notify` () | callback for an enter notify event.
`leave_notify` () | callback for a leave notify event.
`realize` () | callback for a realizes event.
`unrealize` () | callback for an unrealize event.
`key_pressed` () | callback for a key press event.
`key_released` () | callback for a key release event.
`notify_scrolled` () | callback for a notify scrolled event. This is useful to reposition children of the GtkLayout parent of the canvas to their new position.

### goc_item_new ()

    GocItem *           goc_item_new                        (GocGroup *parent,
                                                             GType type,
                                                             const gchar *first_arg_name,
                                                             ...);

Creates a new item of type `type` in group `group`. Properties can be set just the same way they are in g_object_new.

`parent` : | parent GocGroup for the new item
`type` : | GType of the new item
`first_arg_name` : | property name or `NULL`
`...` : | value for the first property, followed optionally by more name/value pairs, followed by `NULL`
Returns : | the newly created GocItem.

### goc_item_destroy ()

    void                goc_item_destroy                    (GocItem *item);

Destroys `item`, removes it from its parent group and updates the canvas accordingly.

`item` : | GocItem

### goc_item_set ()

    void                goc_item_set                        (GocItem *item,
                                                             const gchar *first_arg_name,
                                                             ...);

Set properties and updates the canvas. Using g_object_set instead would set the properties, but not update the canvas.

`item` : | GocItem
`first_arg_name` : | property name or `NULL`
`...` : | value for the first property, followed optionally by more name/value pairs, followed by `NULL`

### goc_item_distance ()

    double              goc_item_distance                   (GocItem *item,
                                                             double x,
                                                             double y,
                                                             GocItem **near_item);

Evaluates the distance between the point with canvas coordinates `x`,`y` and the nearest point of `item`. `near_item` is set with either `item` or its appropriate child.

`item` : | GocItem
`x` : | horizontal position
`y` : | vertical position
`near_item` : | where to store the nearest item
Returns : | the evaluated distance.

### goc_item_draw ()

    void                goc_item_draw                       (GocItem const *item,
                                                             cairo_t *cr);

Renders `item` using `cr`. There is no need to call this function directly. Invalidating the item is the way to go.

`item` : | GocItem
`cr` : | cairo_t

### goc_item_draw_region ()

    gboolean            goc_item_draw_region                (GocItem const *item,
                                                             cairo_t *cr,
                                                             double x0,
                                                             double y0,
                                                             double x1,
                                                             double y1);

Renders `item` using `cr`, limiting all drawings to the region limited by `x0`, `y0`, `x1`, and `y1`. If this function returns `FALSE`, goc_item_draw should be called. There is no need to call this function directly. Invalidating the item is the way to go.

`item` : | GocItem
`cr` : | cairo_t
`x0` : | the lowest horizontal bound of the region to draw
`y0` : | the lowest vertical bound of the region to draw
`x1` : | the highest horizontal bound of the region to draw
`y1` : | the highest vertical bound of the region to draw
Returns : | `TRUE` if successful.

### goc_item_invalidate ()

    void                goc_item_invalidate                 (GocItem *item);

Force a redraw of `item` bounding region.

`item` : | GocItem

### goc_item_show ()

    void                goc_item_show                       (GocItem *item);

Makes `item` visible.

`item` : | GocItem

### goc_item_hide ()

    void                goc_item_hide                       (GocItem *item);

Hides `item`.

`item` : | GocItem

### goc_item_is_visible ()

    gboolean            goc_item_is_visible                 (GocItem *item);

`item` : | GocItem
Returns : | `TRUE` if `item` is visible.

### goc_item_get_bounds ()

    void                goc_item_get_bounds                 (GocItem const *item,
                                                             double *x0,
                                                             double *y0,
                                                             double *x1,
                                                             double *y1);

Retrieves the bounds of `item` in canvas coordinates.

`item` : | GocItem
`x0` : | where to store the lowest horizontal bound
`y0` : | where to store the lowest vertical bound
`x1` : | where to store the highest horizontal bound
`y1` : | where to store the highest vertical bound

### goc_item_bounds_changed ()

    void                goc_item_bounds_changed             (GocItem *item);

This function needs to be called each time the bounds of `item` change. It is normally called from inside the implementation of items derived classes.

`item` : | GocItem

### goc_item_grab ()

    void                goc_item_grab                       (GocItem *item);

Grabs the item. This function will fail if another item is grabbed.

`item` : | GocItem

### goc_item_ungrab ()

    void                goc_item_ungrab                     (GocItem *item);

Ungrabs the item. This function will fail if `item` is not grabbed.

`item` : | GocItem

### goc_item_raise ()

    void                goc_item_raise                      (GocItem *item,
                                                             int n);

Raises `item` by `n` steps inside its parent GocGroup (or less if the list is too short) in the item list so that it is displayed nearer the top of the items stack.

`item` : | GocItem
`n` : | the rank change

### goc_item_lower ()

    void                goc_item_lower                      (GocItem *item,
                                                             int n);

Lowers `item` by `n` steps inside its parent GocGroup (or less if the list is too short) in the item list so that it is displayed more deeply in the items stack.

`item` : | GocItem
`n` : | the rank change

### goc_item_lower_to_bottom ()

    void                goc_item_lower_to_bottom            (GocItem *item);

Lowers `item` to bottom inside its parent GocGroup so that it will be at least partly hidden by any overlapping item.

`item` : | GocItem

### goc_item_raise_to_top ()

    void                goc_item_raise_to_top               (GocItem *item);

Raises `item` to front so that it becomes the toplevel item inside its parent GocGroup.

`item` : | GocItem

## Property Details

### The `"canvas"` property

      "canvas"                   GocCanvas*            : Read

The canvas object on which the item resides.

### The `"parent"` property

      "parent"                   GocGroup*             : Read

The group in which the item resides.