GooCanvas Reference Manual: GooCanvasItemSimple

## GooCanvasItemSimple GooCanvasItemSimple — the base class for the standard canvas items. |

## Synopsis

    struct              GooCanvasItemSimple;
    struct              GooCanvasItemSimpleData;
    struct              GooCanvasItemSimpleClass;

    void                goo_canvas_item_simple_check_style  (GooCanvasItemSimple *item);
    gdouble             goo_canvas_item_simple_get_line_width
                                                            (GooCanvasItemSimple *item);
    void                goo_canvas_item_simple_get_path_bounds
                                                            (GooCanvasItemSimple *item,
                                                             cairo_t *cr,
                                                             GooCanvasBounds *bounds);
    void                goo_canvas_item_simple_user_bounds_to_device
                                                            (GooCanvasItemSimple *item,
                                                             cairo_t *cr,
                                                             GooCanvasBounds *bounds);
    void                goo_canvas_item_simple_user_bounds_to_parent
                                                            (GooCanvasItemSimple *item,
                                                             cairo_t *cr,
                                                             GooCanvasBounds *bounds);
    gboolean            goo_canvas_item_simple_check_in_path
                                                            (GooCanvasItemSimple *item,
                                                             gdouble x,
                                                             gdouble y,
                                                             cairo_t *cr,
                                                             GooCanvasPointerEvents pointer_events);
    void                goo_canvas_item_simple_paint_path   (GooCanvasItemSimple *item,
                                                             cairo_t *cr);
    void                goo_canvas_item_simple_changed      (GooCanvasItemSimple *item,
                                                             gboolean recompute_bounds);
    void                goo_canvas_item_simple_set_model    (GooCanvasItemSimple *item,
                                                             GooCanvasItemModel *model);

## Object Hierarchy

      GObject
       +----GooCanvasItemSimple
             +----GooCanvasWidget
             +----GooCanvasRect
             +----GooCanvasGroup
             +----GooCanvasPath
             +----GooCanvasEllipse
             +----GooCanvasText
             +----GooCanvasPolyline
             +----GooCanvasImage
             +----GooCanvasGrid

## Implemented Interfaces

GooCanvasItemSimple implements GooCanvasItem.

## Properties

      "antialias"                GooCairoAntialias     : Read / Write
      "clip-fill-rule"           GooCairoFillRule      : Read / Write
      "clip-path"                gchar*                : Write
      "fill-color"               gchar*                : Write
      "fill-color-gdk-rgba"      GdkRGBA*              : Read / Write
      "fill-color-rgba"          guint                 : Read / Write
      "fill-pattern"             GooCairoPattern*      : Read / Write
      "fill-pixbuf"              GdkPixbuf*            : Write
      "fill-rule"                GooCairoFillRule      : Read / Write
      "font"                     gchar*                : Read / Write
      "font-desc"                PangoFontDescription*  : Read / Write
      "hint-metrics"             GooCairoHintMetrics   : Read / Write
      "line-cap"                 GooCairoLineCap       : Read / Write
      "line-dash"                GooCanvasLineDash*    : Read / Write
      "line-join"                GooCairoLineJoin      : Read / Write
      "line-join-miter-limit"    gdouble               : Read / Write
      "line-width"               gdouble               : Read / Write
      "operator"                 GooCairoOperator      : Read / Write
      "stroke-color"             gchar*                : Write
      "stroke-color-gdk-rgba"    GdkRGBA*              : Read / Write
      "stroke-color-rgba"        guint                 : Read / Write
      "stroke-pattern"           GooCairoPattern*      : Read / Write
      "stroke-pixbuf"            GdkPixbuf*            : Write

## Description

GooCanvasItemSimple is used as a base class for all of the standard canvas items. It can also be used as the base class for new custom canvas items.

It provides default implementations for many of the GooCanvasItem methods.

For very simple items, all that is needed is to implement the `create_path()` method. (GooCanvasEllipse, GooCanvasRect and GooCanvasPath do this.)

More complicated items need to implement the `update()`, `paint()` and `is_item_at()` methods instead. (GooCanvasImage, GooCanvasPolyline, GooCanvasText and GooCanvasWidget do this.) They may also need to override some of the other GooCanvasItem methods such as `set_canvas()`, `set_parent()` or `allocate_area()` if special code is needed. (GooCanvasWidget does this to make sure the GtkWidget is embedded in the GooCanvas widget correctly.)

## Details

### struct GooCanvasItemSimple

    struct GooCanvasItemSimple {
      GooCanvas *canvas;
      GooCanvasItem *parent;
      GooCanvasItemModelSimple *model;
      GooCanvasItemSimpleData *simple_data;
      GooCanvasBounds bounds;
      guint need_update			: 1;
      guint need_entire_subtree_update      : 1;
    };

The GooCanvasItemSimple struct contains the basic data needed to implement canvas items.

GooCanvas *`canvas`; | the canvas.
GooCanvasItem *`parent`; | the parent item.
GooCanvasItemModelSimple *`model`; | the item's model, if it has one.
GooCanvasItemSimpleData *`simple_data`; | data that is common to both the model and view classes. If the canvas item has a model, this will point to the model's GooCanvasItemSimpleData, otherwise the canvas item will have its own GooCanvasItemSimpleData.
GooCanvasBounds `bounds`; | the bounds of the item, in device space.
guint `need_update` : 1; | if the item needs to recompute its bounds and redraw.
guint `need_entire_subtree_update` : 1; | if all descendants need to be updated.

### struct GooCanvasItemSimpleData

    struct GooCanvasItemSimpleData {
      GooCanvasStyle *style;
      cairo_matrix_t *transform;
      GArray *clip_path_commands;
      gchar *tooltip;

      gdouble visibility_threshold;
      guint visibility			: 2;
      guint pointer_events			: 4;
      guint can_focus                       : 1;
      guint own_style                       : 1;
      guint clip_fill_rule			: 4;
      guint is_static			: 1;
    };

This is the data common to both the model and view classes.

GooCanvasStyle *`style`; | the style to draw with.
cairo_matrix_t *`transform`; | the transformation matrix of the item, or `NULL`.
GArray *`clip_path_commands`; | an array of GooCanvasPathCommand specifying the clip path of the item, or `NULL`.
gchar *`tooltip`; | the item's tooltip.
gdouble `visibility_threshold`; | the threshold scale setting at which to show the item (if the `visibility` setting is set to `VISIBLE_ABOVE_THRESHOLD`).
guint `visibility` : 2; | the GooCanvasItemVisibility setting specifying whether the item is visible, invisible, or visible above a given canvas scale setting.
guint `pointer_events` : 4; | the GooCanvasPointerEvents setting specifying the events the item should receive.
guint `can_focus` : 1; | if the item can take the keyboard focus.
guint `own_style` : 1; | if the item has its own style, rather than using its parent's.
guint `clip_fill_rule` : 4; | the cairo_fill_rule_t setting specifying the fill rule used for the clip path.
guint `is_static` : 1; | if the item is static.

### struct GooCanvasItemSimpleClass

    struct GooCanvasItemSimpleClass {
      void		 (* simple_create_path) (GooCanvasItemSimple   *simple,
    					 cairo_t               *cr);

      void           (* simple_update) (GooCanvasItemSimple   *simple,
    					 cairo_t               *cr);
      void           (* simple_paint) (GooCanvasItemSimple   *simple,
    					 cairo_t               *cr,
    					 const GooCanvasBounds *bounds);
      gboolean       (* simple_is_item_at)  (GooCanvasItemSimple   *simple,
    					 gdouble                x,
    					 gdouble                y,
    					 cairo_t               *cr,
    					 gboolean               is_pointer_event);
    };

The GooCanvasItemSimpleClass struct contains several methods that subclasses can override.

Simple items need only implement the `create_path()` method. More complex items must override the `update()`, `paint()` and `is_item_at()` methods instead.

`simple_create_path` () | simple subclasses that draw basic shapes and paths only need to override this one method. It creates the path for the item. All updating, painting and hit-testing is provided automatically by the GooCanvasItemSimple class. (This method is used by the builtin GooCanvasEllipse, GooCanvasRect and GooCanvasPath items.) More complicated subclasses must override `simple_update`, `simple_paint` and `simple_is_item_at` instead.
`simple_update` () | subclasses should override this to calculate their new bounds, in user space.
`simple_paint` () | subclasses should override this to paint their item.
`simple_is_item_at` () | subclasses should override this to do hit-testing.

### goo_canvas_item_simple_check_style ()

    void                goo_canvas_item_simple_check_style  (GooCanvasItemSimple *item);

This function is intended to be used by subclasses of GooCanvasItemSimple, typically in their `update()` or `get_requested_area()` methods.

It ensures that the item's style is setup correctly. If the item has its own GooCanvasStyle it makes sure the parent is set correctly. If it doesn't have its own style it uses the parent item's style.

`item` : | a GooCanvasItemSimple.

### goo_canvas_item_simple_get_line_width ()

    gdouble             goo_canvas_item_simple_get_line_width
                                                            (GooCanvasItemSimple *item);

Gets the item's line width.

`item` : | a GooCanvasItemSimple.
Returns : | the item's line width.

### goo_canvas_item_simple_get_path_bounds ()

    void                goo_canvas_item_simple_get_path_bounds
                                                            (GooCanvasItemSimple *item,
                                                             cairo_t *cr,
                                                             GooCanvasBounds *bounds);

This function is intended to be used by subclasses of GooCanvasItemSimple, typically in their `update()` or `get_requested_area()` methods.

It calculates the bounds of the current path, using the item's style settings, and stores the results in the given GooCanvasBounds struct.

The returned bounds contains the bounding box of the path in device space, converted to user space coordinates. To calculate the bounds completely in user space, use `cairo_identity_matrix()` to temporarily reset the current transformation matrix to the identity matrix.

`item` : | a GooCanvasItemSimple.
`cr` : | a cairo context.
`bounds` : | the GooCanvasBounds struct to store the resulting bounding box.

### goo_canvas_item_simple_user_bounds_to_device ()

    void                goo_canvas_item_simple_user_bounds_to_device
                                                            (GooCanvasItemSimple *item,
                                                             cairo_t *cr,
                                                             GooCanvasBounds *bounds);

This function is intended to be used by subclasses of GooCanvasItemSimple, typically in their `update()` or `get_requested_area()` methods.

It converts the item's bounds to a bounding box in the canvas (device) coordinate space.

`item` : | a GooCanvasItemSimple.
`cr` : | a cairo context.
`bounds` : | the bounds of the item, in the item's coordinate space.

### goo_canvas_item_simple_user_bounds_to_parent ()

    void                goo_canvas_item_simple_user_bounds_to_parent
                                                            (GooCanvasItemSimple *item,
                                                             cairo_t *cr,
                                                             GooCanvasBounds *bounds);

This function is intended to be used by subclasses of GooCanvasItemSimple, typically in their `get_requested_area()` method.

It converts the item's bounds to a bounding box in its parent's coordinate space. If the item has no transformation matrix set then no conversion is needed.

`item` : | a GooCanvasItemSimple.
`cr` : | a cairo context.
`bounds` : | the bounds of the item, in the item's coordinate space.

### goo_canvas_item_simple_check_in_path ()

    gboolean            goo_canvas_item_simple_check_in_path
                                                            (GooCanvasItemSimple *item,
                                                             gdouble x,
                                                             gdouble y,
                                                             cairo_t *cr,
                                                             GooCanvasPointerEvents pointer_events);

This function is intended to be used by subclasses of GooCanvasItemSimple.

It checks if the given point is in the current path, using the item's style settings.

`item` : | a GooCanvasItemSimple.
`x` : | the x coordinate of the point.
`y` : | the y coordinate of the point.
`cr` : | a cairo context.
`pointer_events` : | specifies which parts of the path to check.
Returns : | `TRUE` if the given point is in the current path.

### goo_canvas_item_simple_paint_path ()

    void                goo_canvas_item_simple_paint_path   (GooCanvasItemSimple *item,
                                                             cairo_t *cr);

This function is intended to be used by subclasses of GooCanvasItemSimple.

It paints the current path, using the item's style settings.

`item` : | a GooCanvasItemSimple.
`cr` : | a cairo context.

### goo_canvas_item_simple_changed ()

    void                goo_canvas_item_simple_changed      (GooCanvasItemSimple *item,
                                                             gboolean recompute_bounds);

This function is intended to be used by subclasses of GooCanvasItemSimple.

It is used as a callback for the "changed" signal of the item models. It requests an update or redraw of the item as appropriate.

`item` : | a GooCanvasItemSimple.
`recompute_bounds` : | if the item's bounds need to be recomputed.

### goo_canvas_item_simple_set_model ()

    void                goo_canvas_item_simple_set_model    (GooCanvasItemSimple *item,
                                                             GooCanvasItemModel *model);

This function should be called by subclasses of GooCanvasItemSimple in their `set_model()` method.

`item` : | a GooCanvasItemSimple.
`model` : | the model that `item` will view.

## Property Details

### The `"antialias"` property

      "antialias"                GooCairoAntialias     : Read / Write

The antialiasing mode to use.

Default value: CAIRO_ANTIALIAS_GRAY

### The `"clip-fill-rule"` property

      "clip-fill-rule"           GooCairoFillRule      : Read / Write

The fill rule used to determine which parts of the item are clipped.

Default value: CAIRO_FILL_RULE_WINDING

### The `"clip-path"` property

      "clip-path"                gchar*                : Write

The sequence of commands describing the clip path of the item, specified as a string using the same syntax as in the Scalable Vector Graphics (SVG) path element.

Default value: NULL

### The `"fill-color"` property

      "fill-color"               gchar*                : Write

The color to use to paint the interior of the item. To disable painting set the 'fill-pattern' property to NULL.

Default value: NULL

### The `"fill-color-gdk-rgba"` property

      "fill-color-gdk-rgba"      GdkRGBA*              : Read / Write

The color to use to paint the interior of the item, specified as a GdkRGBA. To disable painting set the 'fill-pattern' property to NULL.

Since 2.0.1

### The `"fill-color-rgba"` property

      "fill-color-rgba"          guint                 : Read / Write

The color to use to paint the interior of the item, specified as a 32-bit integer value. To disable painting set the 'fill-pattern' property to NULL.

Default value: 0

### The `"fill-pattern"` property

      "fill-pattern"             GooCairoPattern*      : Read / Write

The pattern to use to paint the interior of the item, or NULL to disable painting.

### The `"fill-pixbuf"` property

      "fill-pixbuf"              GdkPixbuf*            : Write

The pixbuf to use to paint the interior of the item. To disable painting set the 'fill-pattern' property to NULL.

### The `"fill-rule"` property

      "fill-rule"                GooCairoFillRule      : Read / Write

The fill rule used to determine which parts of the item are filled.

Default value: CAIRO_FILL_RULE_WINDING

### The `"font"` property

      "font"                     gchar*                : Read / Write

The base font to use for the text.

Default value: NULL

### The `"font-desc"` property

      "font-desc"                PangoFontDescription*  : Read / Write

The attributes specifying which font to use.

### The `"hint-metrics"` property

      "hint-metrics"             GooCairoHintMetrics   : Read / Write

The hinting to be used for font metrics.

Default value: CAIRO_HINT_METRICS_OFF

### The `"line-cap"` property

      "line-cap"                 GooCairoLineCap       : Read / Write

The line cap style to use.

Default value: CAIRO_LINE_CAP_BUTT

### The `"line-dash"` property

      "line-dash"                GooCanvasLineDash*    : Read / Write

The dash pattern to use.

### The `"line-join"` property

      "line-join"                GooCairoLineJoin      : Read / Write

The line join style to use.

Default value: CAIRO_LINE_JOIN_MITER

### The `"line-join-miter-limit"` property

      "line-join-miter-limit"    gdouble               : Read / Write

The smallest angle to use with miter joins, in degrees. Bevel joins will be used below this limit.

Allowed values: >= 0

Default value: 10

### The `"line-width"` property

      "line-width"               gdouble               : Read / Write

The line width to use for the item's perimeter.

Allowed values: >= 0

Default value: 2

### The `"operator"` property

      "operator"                 GooCairoOperator      : Read / Write

The compositing operator to use.

Default value: CAIRO_OPERATOR_OVER

### The `"stroke-color"` property

      "stroke-color"             gchar*                : Write

The color to use for the item's perimeter. To disable painting set the 'stroke-pattern' property to NULL.

Default value: NULL

### The `"stroke-color-gdk-rgba"` property

      "stroke-color-gdk-rgba"    GdkRGBA*              : Read / Write

The color to use for the item's perimeter, specified as a GdkRGBA. To disable painting set the 'stroke-pattern' property to NULL.

Since 2.0.1

### The `"stroke-color-rgba"` property

      "stroke-color-rgba"        guint                 : Read / Write

The color to use for the item's perimeter, specified as a 32-bit integer value. To disable painting set the 'stroke-pattern' property to NULL.

Default value: 0

### The `"stroke-pattern"` property

      "stroke-pattern"           GooCairoPattern*      : Read / Write

The pattern to use to paint the perimeter of the item, or NULL disable painting.

### The `"stroke-pixbuf"` property

      "stroke-pixbuf"            GdkPixbuf*            : Write

The pixbuf to use to draw the item's perimeter. To disable painting set the 'stroke-pattern' property to NULL.