Canvas Items and Events

The standard Gnome canvas items have only one signal, "event", which is emitted for all types of event. The canvas widget preprocesses all GDK events that it receives, and forwards some of them to canvas items. It also sythesizes certain events. Remember that X sends events only to X windows (GdkWindows), and canvas items do not have an associated GdkWindow. Thus the canvas widget must act as intermediary. Here are some of the actions it takes:

• Coordinates are automatically converted to canvas world coordinates. For example, if a canvas item receives an event of type GDK_BUTTON_PRESS, the x and y fields of the event will be in world coordinates. (The raw event was received on the canvas's GdkWindow and thus had window coordinates.)

• Enter/leave events are synthesized for canvas items as the mouse pointer moves across the canvas.

• Events are propagated up the canvas item hierarchy, until some item's "event" signal handler returns TRUE. This works just as it does with GtkWidget; events are first sent to the bottommost or leaf canvas item, and eventually make it up to the root item.

• Only user-generated events are sent to canvas items; many events you might expect to receive on a GdkWindow, such as expose and configure events, are not forwarded to canvas items.

The canvas does this work behind the scenes, so item events work intuitively and much like normal GDK events.

A canvas item event callback looks like this:

static gint
item_event_callback(GnomeCanvasItem* item, 
                    GdkEvent* event, 
                    gpointer data)
{
  switch (event->type) {
    case GDK_BUTTON_PRESS:
      break;

    case GDK_MOTION_NOTIFY:
      break;

    case GDK_BUTTON_RELEASE:
      break;

    default:
      break;
  }

  /* Returning FALSE propagates the event to parent items;
   * returning TRUE ends event propagation. 
   */
  return FALSE;
}

      

Of course, a real callback would probably examine the contents of the event and take some action in response to some of them.