GocItem: GOffice Reference Manual

## GocItem GocItem — Base canvas item. |

## Functions

void | goc_item_bounds_changed ()
void | goc_item_copy ()
void | goc_item_destroy ()
double | goc_item_distance ()
void | goc_item_draw ()
gboolean | goc_item_draw_region ()
GocItem * | goc_item_duplicate ()
void | goc_item_get_bounds ()
cairo_operator_t | goc_item_get_operator ()
GocGroup * | goc_item_get_parent ()
GtkStyleContext * | goc_item_get_style_context ()
GdkWindow * | goc_item_get_window ()
void | goc_item_grab ()
void | goc_item_hide ()
void | goc_item_invalidate ()
gboolean | goc_item_is_visible ()
void | goc_item_lower ()
void | goc_item_lower_to_bottom ()
GocItem * | goc_item_new ()
void | goc_item_raise ()
void | goc_item_raise_to_top ()
void | goc_item_set ()
void | goc_item_set_operator ()
void | goc_item_set_transform ()
void | goc_item_set_visible ()
void | goc_item_show ()
void | goc_item_ungrab ()

## Types and Values

| GocItem
struct | GocItemClass

## Object Hierarchy

        GObject
        ╰── GocItem
            ├── GocStyledItem
            ├── GocComponent
            ├── GocGraph
            ├── GocGroup
            ├── GocImage
            ├── GocPixbuf
            ╰── GocWidget

## Description

GocItem is the virtual base object for canvas items.

## Functions

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

#### Parameters

item | GocItem |

### goc_item_copy ()

    void
    goc_item_copy (GocItem *dest,
                   GocItem *source);

Copies `source` properties to `dest` . The two items must be of the same type and their common class needs a `copy` member.

#### Parameters

source | GocItem |
dest | GocItem |

### goc_item_destroy ()

    void
    goc_item_destroy (GocItem *item);

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

#### Parameters

item | GocItem |

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

    GocItem *
    goc_item_duplicate (GocItem *item,
                        GocGroup *parent);

Creates a new GocItem identical to `item` inside the parent GocGroup if not NULL.

#### Parameters

item | GocItem |
parent | GocGroup |

#### Returns

The duplicated item or NULL if the duplication was not possible.

[transfer none]

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

#### Parameters

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

    cairo_operator_t
    goc_item_get_operator (GocItem *item);

[skip]

#### Parameters

item | GocItem |

#### Returns

the operator used when drawing the item.

### goc_item_get_parent ()

    GocGroup *
    goc_item_get_parent (GocItem *item);

#### Parameters

item | GocItem |

#### Returns

The item parent GocGroup.

[transfer none]

### goc_item_get_style_context ()

    GtkStyleContext *
    goc_item_get_style_context (const GocItem *item);

#### Parameters

item | GocItem |

#### Returns

The style context to use for the item.

[transfer none]

### goc_item_get_window ()

    GdkWindow *
    goc_item_get_window (GocItem *item);

#### Parameters

item | GocItem |

#### Returns

The GdkWindow associated with the item if any or NULL. Only GocWidget owns a GdkWindow.

[transfer none]

### goc_item_grab ()

    void
    goc_item_grab (GocItem *item);

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

#### Parameters

item | GocItem |

### goc_item_hide ()

    void
    goc_item_hide (GocItem *item);

Hides `item` .

#### Parameters

item | GocItem |

### goc_item_invalidate ()

    void
    goc_item_invalidate (GocItem *item);

Force a redraw of `item` bounding region.

#### Parameters

item | GocItem |

### goc_item_is_visible ()

    gboolean
    goc_item_is_visible (GocItem *item);

#### Parameters

item | GocItem |

#### Returns

`TRUE` if `item` is visible.

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

#### Parameters

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.

#### Parameters

item | GocItem |

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

#### Parameters

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.

[transfer none]

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

#### Parameters

item | GocItem |
n | the rank change |

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

#### Parameters

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.

#### Parameters

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

    void
    goc_item_set_operator (GocItem *item,
                           cairo_operator_t op);

Set the operator used when drawing the item.

[skip]

#### Parameters

item | GocItem |
op | cairo_operator_t |

### goc_item_set_transform ()

    void
    goc_item_set_transform (GocItem *item,
                            cairo_matrix_t *m);

Set the matrix used to transform the item.

[skip]

#### Parameters

item | GocItem |
m | cairo_matrix_t |

### goc_item_set_visible ()

    void
    goc_item_set_visible (GocItem *item,
                          gboolean visible);

Either hides or shows `item` as appropriate..

#### Parameters

item | GocItem |
visible | whether the item should be visible |

### goc_item_show ()

    void
    goc_item_show (GocItem *item);

Makes `item` visible.

#### Parameters

item | GocItem |

### goc_item_ungrab ()

    void
    goc_item_ungrab (GocItem *item);

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

#### Parameters

item | GocItem |

## Types and Values

### GocItem

    typedef struct _GocItem GocItem;

### struct GocItemClass

    struct GocItemClass {
    	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);
    	void			(*notify_scrolled) (GocItem *item);
    #ifdef GOFFICE_WITH_GTK
    	gboolean		(*key_pressed) (GocItem *item, GdkEventKey* ev);
    	gboolean		(*key_released) (GocItem *item, GdkEventKey* ev);
    	GdkWindow*		(*get_window) (GocItem *item);
    #endif
    	void		(*copy) (GocItem *source, GocItem *dest);
    };

The base class for all canvas items.

#### Members

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. |
`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. |
`key_pressed` () | callback for a key press event. |
`key_released` () | callback for a key release event. |
`get_window` () | returns the GdkWindow for the item if any. |
`copy` () | method for copying an item. |