Other Methods

Events

The GnomeCanvasItem class has a slot in its vtable called event; this is the only GnomeCanvasItem class function associated with a signal. None of the stock canvas items implement a default handler for event, but of course your own canvas item could.

The return value of event works just like the GtkWidget "event" signal; if the last signal handler returns FALSE, the event is propagated to the item's parent item (by emitting the event signal on the parent), if TRUE propagation ends.

Point

The point method is used to determine which canvas item is located at a given point. The canvas uses this information to decide which item should receive events. A point method calculates the distance from some point to the canvas item. Canvas items must correctly report a distance of 0 if the point is on the canvas item, or they will not receive events; they must report non-zero if the point is not on the item, or they will receive too many events. The exact value returned is not nearly as important as the zero/non-zero distinction.

For convenience, the point method receives the same point pre-translated into both item and canvas pixel coordinates.

The point method also receives a pointer to a pointer to a GnomeCanvasItem; non-group canvas items should store a pointer to themselves in this space. Groups store the *actual_item received from the topmost child which returns 0 from its point method. If you think about it for a while, you will see the implication: the root canvas group's point method stores a pointer to the deepest child in the item tree at the point in question. The canvas sends events occurring at that point to this most-junior child. Note that the canvas item tree corresponds to the item stacking order (i.e. the root group is on the bottom), so events go to the topmost items, as you might expect. Remember that events are then propagated up the item tree hierarchy.

Here is the point method for GnomeCanvasRect:

static double
gnome_canvas_rect_point (GnomeCanvasItem *item, 
                         double x, double y, int cx, int cy, 
                         GnomeCanvasItem **actual_item)
{
  GnomeCanvasRE *re;
  double x1, y1, x2, y2;
  double hwidth;
  double dx, dy;
  double tmp;

  re = GNOME_CANVAS_RE (item);

  *actual_item = item;

  /* Find the bounds for the rectangle plus its outline width */

  x1 = re->x1;
  y1 = re->y1;
  x2 = re->x2;
  y2 = re->y2;

  if (re->outline_set) {
    if (re->width_pixels)
      hwidth = (re->width / item->canvas->pixels_per_unit) / 2.0;
    else
      hwidth = re->width / 2.0;

    x1 -= hwidth;
    y1 -= hwidth;
    x2 += hwidth;
    y2 += hwidth;
  } else
    hwidth = 0.0;

  /* Is point inside rectangle (which can be hollow if it has no fill set)? */

  if ((x >= x1) && (y >= y1) && (x <= x2) && (y <= y2)) {
    if (re->fill_set || !re->outline_set)
      return 0.0;

    dx = x - x1;
    tmp = x2 - x;
    if (tmp < dx)
      dx = tmp;

    dy = y - y1;
    tmp = y2 - y;
    if (tmp < dy)
      dy = tmp;

    if (dy < dx)
      dx = dy;

    dx -= 2.0 * hwidth;

    if (dx < 0.0)
      return 0.0;
    else
      return dx;
  }

  /* Point is outside rectangle */

  if (x < x1)
    dx = x1 - x;
  else if (x > x2)
    dx = x - x2;
  else
    dx = 0.0;

  if (y < y1)
    dy = y1 - y;
  else if (y > y2)
    dy = y - y2;
  else
    dy = 0.0;

  return sqrt (dx * dx + dy * dy);
}

      

It should be obvious how this function works; it is simple geometry. Again, notice the line:

  *actual_item = item;

      

If your item isn't receiving any events, make sure you included a similar statement.

Bounds

The bounds method computes the approximate bounding box of a canvas item. In Gnome 1.0, this method is only used in gnome_canvas_item_get_bounds(), a user-visible function to return the bounds of a canvas item. The canvas does not use it at all internally, and most likely you could get away without implementing it, though all the stock items do.

The function should return an item's bounding box in item coordinates; here is the GnomeCanvasRE version:

static void
gnome_canvas_re_bounds (GnomeCanvasItem *item, 
                        double *x1, double *y1, 
                        double *x2, double *y2)
{
  GnomeCanvasRE *re;
  double hwidth;

  re = GNOME_CANVAS_RE (item);

  if (re->width_pixels)
    hwidth = (re->width / item->canvas->pixels_per_unit) / 2.0;
  else
    hwidth = re->width / 2.0;

  *x1 = re->x1 - hwidth;
  *y1 = re->y1 - hwidth;
  *x2 = re->x2 + hwidth;
  *y2 = re->y2 + hwidth;
}
      

Realizing and Mapping

Canvas items are realized and mapped just as widgets are. These methods play the same role they do for widgets; realizing a canvas item allocates any GDK resources it plans to use, unrealizing it deallocates the same resources. Mapping a canvas item shows its GdkWindow, unmapping it hides the GdkWindow. Very few canvas items have a GdkWindow (GnomeCanvasWidget is the big exception), so most canvas items will not even implement map and unmap methods. GnomeCanvasRect does not. It does have realize and unrealize methods, however.

Here is its realize method:

static void
gnome_canvas_re_realize (GnomeCanvasItem *item)
{
  GnomeCanvasRE *re;

  re = GNOME_CANVAS_RE (item);

  if (re_parent_class->realize)
    (* re_parent_class->realize) (item);

  if (!item->canvas->aa) {
    re->fill_gc = gdk_gc_new (item->canvas->layout.bin_window);
    re->outline_gc = gdk_gc_new (item->canvas->layout.bin_window);
  }
}

      

And unrealize:

static void
gnome_canvas_re_unrealize (GnomeCanvasItem *item)
{
  GnomeCanvasRE *re;

  re = GNOME_CANVAS_RE (item);

  if (!item->canvas->aa) {
    gdk_gc_unref (re->fill_gc);
    gdk_gc_unref (re->outline_gc);
  }

  if (re_parent_class->unrealize)
    (* re_parent_class->unrealize) (item);
}
      

Note that your realize and unrealize methods are unlikely to have anything to do in antialiased mode, since there won't be any GDK resources to worry about.

GtkObject Methods

Of course, any canvas item subclass must implement the usual GtkObject methods, including destroy if the object allocates resources that need cleaning up, and a get_arg/set_arg pair if the object defines any arguments. The only canvas-item-specific concern is that you must schedule an update or redraw as needed if set_arg changes the properties of the canvas item. These functions are quite long due to the number of arguments, but not very interesting, so they are omitted here. See the full GnomeCanvasRect source code if you're curious.