GNOME Documentation Library

Creating a Simple Subclass of GooCanvasItemSimple

For items that consist of a simple graphic element such as a line, rectangle or circle, it is possible to create a subclass of GooCanvasItemSimple and override just one method, simple_create_path(). (This method is used for the GooCanvasEllipse and GooCanvasPath items.)

The simple_create_path() method should create a path using the given cairo context. The path will be drawn using the stroke, fill and other painting properties from GooCanvasItemSimple.

This example shows the simple_create_path() method for a simple rectangular item, MyItem:

  static void
  my_item_simple_create_path (GooCanvasItemSimple *simple,
                              cairo_t             *cr)
  {
    MyItem *item = (MyItem*) simple;

    cairo_rectangle (cr, item->x, item->y, item->width, item->height);
  }
	

Whenever the item is changed in some way it should call goo_canvas_item_simple_changed(), passing a boolean value indicating whether the item's bounds need to be recalculated or if it only needs to be repainted. The GooCanvasItemSimple code will take care of updating the item and repainting the appropriate parts of the canvas.

Creating a Regular Subclass of GooCanvasItemSimple

Most items will need more than a simple line or rectangle, so they will need to create a subclass of GooCanvasItemSimple and override three methods, simple_update(), simple_paint() and simple_is_item_at().

The simple_update() method should compute the bounds of the item, in the item's coordinate space, and place them in the bounds member of GooCanvasItemSimple. Note that the cairo context passed to this function may have transformations applied to it, so cairo_identity_matrix() should be called before using it.

The simple_paint() method should paint the item using the given cairo context. To use the stroke and fill properties from GooCanvasItemSimple to paint parts of the item call goo_canvas_style_set_stroke_options() and goo_canvas_style_set_fill_options() before calling cairo_stroke() and cairo_fill(). (The item's style can be found in GOO_CANVAS_ITEM_SIMPLE (item)->simple_data->style).

The simple_is_item_at() method should return TRUE if the given coordinate (in the item's coordinate space) is inside the item. (The is_pointer_event argument can be ignored for most purposes since the GooCanvasItemSimple code will take care of it.)

This example code shows the simple_update(), simple_paint() and simple_is_item_at() methods for a rectangular item (the complete item's source code can be found in the GooCanvas demo directory, in demo-item.h and demo-item.c):

  static void
  goo_demo_item_update  (GooCanvasItemSimple *simple,
                         cairo_t             *cr)
  {
    GooDemoItem *demo_item = (GooDemoItem*) simple;
  
    /* Compute the new bounds. */
    simple->bounds.x1 = demo_item->x;
    simple->bounds.y1 = demo_item->y;
    simple->bounds.x2 = demo_item->x + demo_item->width;
    simple->bounds.y2 = demo_item->y + demo_item->height;
  }
  
  
  static void
  goo_demo_item_paint (GooCanvasItemSimple   *simple,
                       cairo_t               *cr,
                       const GooCanvasBounds *bounds)
  {
    GooDemoItem *demo_item = (GooDemoItem*) simple;
  
    cairo_move_to (cr, demo_item->x, demo_item->y);
    cairo_line_to (cr, demo_item->x, demo_item->y + demo_item->height);
    cairo_line_to (cr, demo_item->x + demo_item->width,
                   demo_item->y + demo_item->height);
    cairo_line_to (cr, demo_item->x + demo_item->width, demo_item->y);
    cairo_close_path (cr);
    goo_canvas_style_set_fill_options (simple->simple_data->style, cr);
    cairo_fill (cr);
  }
  
  
  static gboolean
  goo_demo_item_is_item_at (GooCanvasItemSimple *simple,
                            gdouble              x,
                            gdouble              y,
                            cairo_t             *cr,
                            gboolean             is_pointer_event)
  {
    GooDemoItem *demo_item = (GooDemoItem*) simple;
  
    if (x < demo_item->x || (x > demo_item->x + demo_item->width)
        || y < demo_item->y || (y > demo_item->y + demo_item->height))
      return FALSE;
  
    return TRUE;
  }
	

As with the simple GooCanvasItemSimple subclass, the item should call goo_canvas_item_simple_changed() whenever it is changed, to ensure that the item's bounds are recomputed and it is repainted if necessary.

Implementing the GooCanvasItem Interface

The most complicated way to create new canvas items is to implement the GooCanvasItem interface directly. This should not be needed in most cases, but may be desired if the developer wants to avoid the memory and processor overheads associated with the GooCanvasItemSimple class, or if the developer wants to turn an existing application object into a canvas item.

At a minimum the canvas item must implement these 6 methods:

The canvas item must also implement the "parent", "title", "description", "visibility", "visibility-threshold", "transform" and "pointer-events" properties. (The last 4 properties can simply be ignored if the application doesn't intend to use them.)

If the canvas item will be used within a container that does item layout, such as GooCanvasTable, it must implement the first two methods here at least:

If the canvas item supports a transformation matrix it must implement:

If the canvas item supports a GooCanvasStyle setting, it must implement:

Since GooCanvasItemSimple implements most of the above methods and properties its source code is a good place to look for help.

Creating Item Models

As with creating canvas items, to create item models it is possible to subclass GooCanvasItemModelSimple or to implement the GooCanvasItemModel interface directly.

Subclassing GooCanvasItemModelSimple is very easy, since only one method from the GooCanvasItemModel interface must be implemented - create_item(). This should return a new canvas item for viewing the item model in a canvas. (It may be called multiple times if multiple canvases are viewing the same canvas model.)

The GooCanvasItemModelSimple subclass should emit the "changed" signal whenever it has changed, with a boolean flag indicating if the bounds need to be recomputed. The canvas items will connect to this signal and request an update or a redraw as appropriate.

To implement the GooCanvasItemModel interface directly, the class must implement the get_parent(), set_parent() and create_item() methods. It may also implement get_transform(), set_transform(), get_style() and set_style() methods if desired.

The class must also implement the "parent", "title", "description", "can-focus", "visibility", "visibility-threshold", "transform" and "pointer-events" properties. (The last 4 properties can simply be ignored if the application doesn't intend to use them.)