eel-canvas.c

/*
 * Copyright (C) 1997, 1998, 1999, 2000 Free Software Foundation
 * All rights reserved.
 *
 * This file is part of the Gnome Library.
 *
 * The Gnome Library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public License as
 * published by the Free Software Foundation; either version 2 of the
 * License, or (at your option) any later version.
 *
 * The Gnome Library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with the Gnome Library; see the file COPYING.LIB.  If not,
 * see <http://www.gnu.org/licenses/>.
 */
/*
 *  @NOTATION@
 */
/*
 * EelCanvas widget - Tk-like canvas widget for Gnome
 *
 * EelCanvas is basically a port of the Tk toolkit's most excellent canvas widget.  Tk is
 * copyrighted by the Regents of the University of California, Sun Microsystems, and other parties.
 *
 *
 * Authors: Federico Mena <federico@nuclecu.unam.mx>
 *          Raph Levien <raph@gimp.org>
 */

/*
 * TO-DO list for the canvas:
 *
 * - Allow to specify whether EelCanvasImage sizes are in units or pixels (scale or don't scale).
 *
 * - GC put functions for items.
 *
 * - Widget item (finish it).
 *
 * - GList *eel_canvas_gimme_all_items_contained_in_this_area (EelCanvas *canvas, Rectangle area);
 *
 * - Retrofit all the primitive items with microtile support.
 *
 * - Curve support for line item.
 *
 * - Arc item (Havoc has it; to be integrated in EelCanvasEllipse).
 *
 * - Sane font handling API.
 *
 * - Get_arg methods for items:
 *   - How to fetch the outline width and know whether it is in pixels or units?
 */

#include <config.h>

#include <math.h>
#include <string.h>
#include <stdio.h>
#include <gtk/gtk.h>
#include <glib/gi18n-lib.h>
#include <cairo-gobject.h>
#include "eel-canvas.h"

static void eel_canvas_request_update (EelCanvas *canvas);
static void group_add (EelCanvasGroup *group,
                       EelCanvasItem  *item);
static void group_remove (EelCanvasGroup *group,
                          EelCanvasItem  *item);
static void redraw_and_repick_if_mapped (EelCanvasItem *item);

/*** EelCanvasItem ***/

/* Some convenience stuff */
#define GCI_UPDATE_MASK (EEL_CANVAS_UPDATE_REQUESTED | EEL_CANVAS_UPDATE_DEEP)

enum
{
    ITEM_PROP_0,
    ITEM_PROP_VISIBLE
};

enum
{
    ITEM_DESTROY,
    ITEM_EVENT,
    ITEM_LAST_SIGNAL
};

static void eel_canvas_item_class_init (EelCanvasItemClass *klass);
static void eel_canvas_item_init (EelCanvasItem *item);
static int  emit_event (EelCanvas *canvas,
                        GdkEvent  *event);

static guint item_signals[ITEM_LAST_SIGNAL];

static GObjectClass *item_parent_class;

static gpointer accessible_item_parent_class;
static gpointer accessible_parent_class;


/**
 * eel_canvas_item_get_type:
 *
 * Registers the &EelCanvasItem class if necessary, and returns the type ID
 * associated to it.
 *
 * Return value:  The type ID of the &EelCanvasItem class.
 **/
GType
eel_canvas_item_get_type (void)
{
    static GType canvas_item_type = 0;

    if (!canvas_item_type)
    {
        static const GTypeInfo canvas_item_info =
        {
            sizeof (EelCanvasItemClass),
            (GBaseInitFunc) NULL,
            (GBaseFinalizeFunc) NULL,
            (GClassInitFunc) eel_canvas_item_class_init,
            NULL,                       /* class_finalize */
            NULL,                       /* class_data */
            sizeof (EelCanvasItem),
            0,                          /* n_preallocs */
            (GInstanceInitFunc) eel_canvas_item_init
        };

        canvas_item_type = g_type_register_static (G_TYPE_INITIALLY_UNOWNED,
                                                   "EelCanvasItem",
                                                   &canvas_item_info,
                                                   0);
    }

    return canvas_item_type;
}

/* Object initialization function for EelCanvasItem */
static void
eel_canvas_item_init (EelCanvasItem *item)
{
    item->flags |= EEL_CANVAS_ITEM_VISIBLE;
}

/* Performs post-creation operations on a canvas item (adding it to its parent
 * group, etc.)
 */
static void
item_post_create_setup (EelCanvasItem *item)
{
    group_add (EEL_CANVAS_GROUP (item->parent), item);

    redraw_and_repick_if_mapped (item);
}

/**
 * eel_canvas_item_new:
 * @parent: The parent group for the new item.
 * @type: The object type of the item.
 * @first_arg_name: A list of object argument name/value pairs, NULL-terminated,
 * used to configure the item.  For example, "fill_color", "black",
 * "width_units", 5.0, NULL.
 * @Varargs:
 *
 * Creates a new canvas item with @parent as its parent group.  The item is
 * created at the top of its parent's stack, and starts up as visible.  The item
 * is of the specified @type, for example, it can be
 * eel_canvas_rect_get_type().  The list of object arguments/value pairs is
 * used to configure the item.
 *
 * Return value: The newly-created item.
 **/
EelCanvasItem *
eel_canvas_item_new (EelCanvasGroup *parent,
                     GType           type,
                     const gchar    *first_arg_name,
                     ...)
{
    EelCanvasItem *item;
    va_list args;

    g_return_val_if_fail (EEL_IS_CANVAS_GROUP (parent), NULL);
    g_return_val_if_fail (g_type_is_a (type, eel_canvas_item_get_type ()), NULL);

    item = EEL_CANVAS_ITEM (g_object_new (type, NULL));

    item->parent = EEL_CANVAS_ITEM (parent);
    item->canvas = item->parent->canvas;

    va_start (args, first_arg_name);
    g_object_set_valist (G_OBJECT (item), first_arg_name, args);
    va_end (args);

    item_post_create_setup (item);

    return item;
}

/* Set_property handler for canvas items */
static void
eel_canvas_item_set_property (GObject      *gobject,
                              guint         param_id,
                              const GValue *value,
                              GParamSpec   *pspec)
{
    EelCanvasItem *item;

    g_return_if_fail (EEL_IS_CANVAS_ITEM (gobject));

    item = EEL_CANVAS_ITEM (gobject);

    switch (param_id)
    {
        case ITEM_PROP_VISIBLE:
        {
            if (g_value_get_boolean (value))
            {
                eel_canvas_item_show (item);
            }
            else
            {
                eel_canvas_item_hide (item);
            }
        }
        break;

        default:
        {
            G_OBJECT_WARN_INVALID_PROPERTY_ID (gobject, param_id, pspec);
        }
        break;
    }
}

/* Get_property handler for canvas items */
static void
eel_canvas_item_get_property (GObject    *gobject,
                              guint       param_id,
                              GValue     *value,
                              GParamSpec *pspec)
{
    EelCanvasItem *item;

    g_return_if_fail (EEL_IS_CANVAS_ITEM (gobject));

    item = EEL_CANVAS_ITEM (gobject);

    switch (param_id)
    {
        case ITEM_PROP_VISIBLE:
        {
            g_value_set_boolean (value, item->flags & EEL_CANVAS_ITEM_VISIBLE);
        }
        break;

        default:
        {
            G_OBJECT_WARN_INVALID_PROPERTY_ID (gobject, param_id, pspec);
        }
        break;
    }
}

static void
redraw_and_repick_if_mapped (EelCanvasItem *item)
{
    if (item->flags & EEL_CANVAS_ITEM_MAPPED)
    {
        eel_canvas_item_request_redraw (item);
        item->canvas->need_repick = TRUE;
    }
}

/* Dispose handler for canvas items */
static void
eel_canvas_item_dispose (GObject *object)
{
    EelCanvasItem *item;

    g_return_if_fail (EEL_IS_CANVAS_ITEM (object));

    item = EEL_CANVAS_ITEM (object);

    if (item->canvas)
    {
        eel_canvas_item_request_redraw (item);

        /* Make the canvas forget about us */

        if (item == item->canvas->current_item)
        {
            item->canvas->current_item = NULL;
            item->canvas->need_repick = TRUE;
        }

        if (item == item->canvas->new_current_item)
        {
            item->canvas->new_current_item = NULL;
            item->canvas->need_repick = TRUE;
        }

        eel_canvas_item_ungrab (item);

        if (item == item->canvas->focused_item)
        {
            item->canvas->focused_item = NULL;
        }

        /* Normal destroy stuff */

        if (item->flags & EEL_CANVAS_ITEM_MAPPED)
        {
            (*EEL_CANVAS_ITEM_GET_CLASS (item)->unmap)(item);
        }

        if (item->flags & EEL_CANVAS_ITEM_REALIZED)
        {
            (*EEL_CANVAS_ITEM_GET_CLASS (item)->unrealize)(item);
        }

        if (item->parent)
        {
            group_remove (EEL_CANVAS_GROUP (item->parent), item);
        }

        item->canvas = NULL;
    }

    g_object_set_data (object, "in-destruction", GINT_TO_POINTER (1));
    g_signal_emit (object, item_signals[ITEM_DESTROY], 0);

    g_object_set_data (object, "in-destruction", NULL);

    G_OBJECT_CLASS (item_parent_class)->dispose (object);
}

void
eel_canvas_item_destroy (EelCanvasItem *item)
{
    if (g_object_get_data (G_OBJECT (item), "in-destruction") == NULL)
    {
        g_object_run_dispose (G_OBJECT (item));
    }
}

/* Realize handler for canvas items */
static void
eel_canvas_item_realize (EelCanvasItem *item)
{
    if (item->parent && !(item->parent->flags & EEL_CANVAS_ITEM_REALIZED))
    {
        (*EEL_CANVAS_ITEM_GET_CLASS (item->parent)->realize)(item->parent);
    }

    if (item->parent == NULL && !gtk_widget_get_realized (GTK_WIDGET (item->canvas)))
    {
        gtk_widget_realize (GTK_WIDGET (item->canvas));
    }

    item->flags |= EEL_CANVAS_ITEM_REALIZED;

    eel_canvas_item_request_update (item);
}

/* Unrealize handler for canvas items */
static void
eel_canvas_item_unrealize (EelCanvasItem *item)
{
    if (item->flags & EEL_CANVAS_ITEM_MAPPED)
    {
        (*EEL_CANVAS_ITEM_GET_CLASS (item)->unmap)(item);
    }

    item->flags &= ~(EEL_CANVAS_ITEM_REALIZED);
}

/* Map handler for canvas items */
static void
eel_canvas_item_map (EelCanvasItem *item)
{
    item->flags |= EEL_CANVAS_ITEM_MAPPED;
}

/* Unmap handler for canvas items */
static void
eel_canvas_item_unmap (EelCanvasItem *item)
{
    item->flags &= ~(EEL_CANVAS_ITEM_MAPPED);
}

/* Update handler for canvas items */
static void
eel_canvas_item_update (EelCanvasItem *item,
                        double         i2w_dx,
                        double         i2w_dy,
                        int            flags)
{
    item->flags &= ~(EEL_CANVAS_ITEM_NEED_UPDATE);
    item->flags &= ~(EEL_CANVAS_ITEM_NEED_DEEP_UPDATE);
}

/*
 * This routine invokes the update method of the item
 * Please notice, that we take parent to canvas pixel matrix as argument
 * unlike virtual method ::update, whose argument is item 2 canvas pixel
 * matrix
 *
 * I will try to force somewhat meaningful naming for affines (Lauris)
 * General naming rule is FROM2TO, where FROM and TO are abbreviations
 * So p2cpx is Parent2CanvasPixel and i2cpx is Item2CanvasPixel
 * I hope that this helps to keep track of what really happens
 *
 */

static void
eel_canvas_item_invoke_update (EelCanvasItem *item,
                               double         i2w_dx,
                               double         i2w_dy,
                               int            flags)
{
    int child_flags;

    child_flags = flags;

    /* apply object flags to child flags */
    child_flags &= ~EEL_CANVAS_UPDATE_REQUESTED;

    if (item->flags & EEL_CANVAS_ITEM_NEED_UPDATE)
    {
        child_flags |= EEL_CANVAS_UPDATE_REQUESTED;
    }

    if (item->flags & EEL_CANVAS_ITEM_NEED_DEEP_UPDATE)
    {
        child_flags |= EEL_CANVAS_UPDATE_DEEP;
    }

    if (child_flags & GCI_UPDATE_MASK)
    {
        if (EEL_CANVAS_ITEM_GET_CLASS (item)->update)
        {
            EEL_CANVAS_ITEM_GET_CLASS (item)->update (item, i2w_dx, i2w_dy, child_flags);
        }
    }

    /* If this fail you probably forgot to chain up to
     * EelCanvasItem::update from a derived class */
    g_return_if_fail (!(item->flags & EEL_CANVAS_ITEM_NEED_UPDATE));
}

/*
 * This routine invokes the point method of the item.
 * The arguments x, y should be in the parent item local coordinates.
 */

static double
eel_canvas_item_invoke_point (EelCanvasItem  *item,
                              double          x,
                              double          y,
                              int             cx,
                              int             cy,
                              EelCanvasItem **actual_item)
{
    /* Calculate x & y in item local coordinates */

    if (EEL_CANVAS_ITEM_GET_CLASS (item)->point)
    {
        return EEL_CANVAS_ITEM_GET_CLASS (item)->point (item, x, y, cx, cy, actual_item);
    }

    return 1e18;
}

/**
 * eel_canvas_item_set:
 * @item: A canvas item.
 * @first_arg_name: The list of object argument name/value pairs used to configure the item.
 * @Varargs:
 *
 * Configures a canvas item.  The arguments in the item are set to the specified
 * values, and the item is repainted as appropriate.
 **/
void
eel_canvas_item_set (EelCanvasItem *item,
                     const gchar   *first_arg_name,
                     ...)
{
    va_list args;

    va_start (args, first_arg_name);
    g_object_set_valist (G_OBJECT (item), first_arg_name, args);
    va_end (args);

    item->canvas->need_repick = TRUE;
}

/**
 * eel_canvas_item_move:
 * @item: A canvas item.
 * @dx: Horizontal offset.
 * @dy: Vertical offset.
 *
 * Moves a canvas item by creating an affine transformation matrix for
 * translation by using the specified values. This happens in item
 * local coordinate system, so if you have nontrivial transform, it
 * most probably does not do, what you want.
 **/
void
eel_canvas_item_move (EelCanvasItem *item,
                      double         dx,
                      double         dy)
{
    g_return_if_fail (item != NULL);
    g_return_if_fail (EEL_IS_CANVAS_ITEM (item));

    if (!EEL_CANVAS_ITEM_GET_CLASS (item)->translate)
    {
        g_warning ("Item type %s does not implement translate method.\n",
                   g_type_name (G_OBJECT_TYPE (item)));
        return;
    }

    (*EEL_CANVAS_ITEM_GET_CLASS (item)->translate)(item, dx, dy);

    if (item->flags & EEL_CANVAS_ITEM_MAPPED)
    {
        item->canvas->need_repick = TRUE;
    }

    if (!(item->flags & EEL_CANVAS_ITEM_NEED_DEEP_UPDATE))
    {
        item->flags |= EEL_CANVAS_ITEM_NEED_DEEP_UPDATE;
        if (item->parent != NULL)
        {
            eel_canvas_item_request_update (item->parent);
        }
        else
        {
            eel_canvas_request_update (item->canvas);
        }
    }
}

static void
eel_canvas_queue_resize (EelCanvas *canvas)
{
    if (gtk_widget_is_drawable (GTK_WIDGET (canvas)))
    {
        gtk_widget_queue_resize (GTK_WIDGET (canvas));
    }
}

/* Convenience function to reorder items in a group's child list.  This puts the
 * specified link after the "before" link. Returns TRUE if the list was changed.
 */
static gboolean
put_item_after (GList *link,
                GList *before)
{
    EelCanvasGroup *parent;

    if (link == before)
    {
        return FALSE;
    }

    parent = EEL_CANVAS_GROUP (EEL_CANVAS_ITEM (link->data)->parent);

    if (before == NULL)
    {
        if (link == parent->item_list)
        {
            return FALSE;
        }

        link->prev->next = link->next;

        if (link->next)
        {
            link->next->prev = link->prev;
        }
        else
        {
            parent->item_list_end = link->prev;
        }

        link->prev = before;
        link->next = parent->item_list;
        link->next->prev = link;
        parent->item_list = link;
    }
    else
    {
        if ((link == parent->item_list_end) && (before == parent->item_list_end->prev))
        {
            return FALSE;
        }

        if (link->next)
        {
            link->next->prev = link->prev;
        }

        if (link->prev)
        {
            link->prev->next = link->next;
        }
        else
        {
            parent->item_list = link->next;
            parent->item_list->prev = NULL;
        }

        link->prev = before;
        link->next = before->next;

        link->prev->next = link;

        if (link->next)
        {
            link->next->prev = link;
        }
        else
        {
            parent->item_list_end = link;
        }
    }
    return TRUE;
}


/**
 * eel_canvas_item_raise:
 * @item: A canvas item.
 * @positions: Number of steps to raise the item.
 *
 * Raises the item in its parent's stack by the specified number of positions.
 * If the number of positions is greater than the distance to the top of the
 * stack, then the item is put at the top.
 **/
void
eel_canvas_item_raise (EelCanvasItem *item,
                       int            positions)
{
    GList *link, *before;
    EelCanvasGroup *parent;

    g_return_if_fail (EEL_IS_CANVAS_ITEM (item));
    g_return_if_fail (positions >= 0);

    if (!item->parent || positions == 0)
    {
        return;
    }

    parent = EEL_CANVAS_GROUP (item->parent);
    link = g_list_find (parent->item_list, item);
    g_assert (link != NULL);

    for (before = link; positions && before; positions--)
    {
        before = before->next;
    }

    if (!before)
    {
        before = parent->item_list_end;
    }

    if (put_item_after (link, before))
    {
        redraw_and_repick_if_mapped (item);
    }
}


/**
 * eel_canvas_item_lower:
 * @item: A canvas item.
 * @positions: Number of steps to lower the item.
 *
 * Lowers the item in its parent's stack by the specified number of positions.
 * If the number of positions is greater than the distance to the bottom of the
 * stack, then the item is put at the bottom.
 **/
void
eel_canvas_item_lower (EelCanvasItem *item,
                       int            positions)
{
    GList *link, *before;
    EelCanvasGroup *parent;

    g_return_if_fail (EEL_IS_CANVAS_ITEM (item));
    g_return_if_fail (positions >= 1);

    if (!item->parent)
    {
        return;
    }

    parent = EEL_CANVAS_GROUP (item->parent);
    link = g_list_find (parent->item_list, item);
    g_assert (link != NULL);

    if (link->prev)
    {
        for (before = link->prev; positions && before; positions--)
        {
            before = before->prev;
        }
    }
    else
    {
        before = NULL;
    }

    if (put_item_after (link, before))
    {
        redraw_and_repick_if_mapped (item);
    }
}


/**
 * eel_canvas_item_raise_to_top:
 * @item: A canvas item.
 *
 * Raises an item to the top of its parent's stack.
 **/
void
eel_canvas_item_raise_to_top (EelCanvasItem *item)
{
    GList *link;
    EelCanvasGroup *parent;

    g_return_if_fail (EEL_IS_CANVAS_ITEM (item));

    if (!item->parent)
    {
        return;
    }

    parent = EEL_CANVAS_GROUP (item->parent);
    link = g_list_find (parent->item_list, item);
    g_assert (link != NULL);

    if (put_item_after (link, parent->item_list_end))
    {
        redraw_and_repick_if_mapped (item);
    }
}


/**
 * eel_canvas_item_lower_to_bottom:
 * @item: A canvas item.
 *
 * Lowers an item to the bottom of its parent's stack.
 **/
void
eel_canvas_item_lower_to_bottom (EelCanvasItem *item)
{
    GList *link;
    EelCanvasGroup *parent;

    g_return_if_fail (EEL_IS_CANVAS_ITEM (item));

    if (!item->parent)
    {
        return;
    }

    parent = EEL_CANVAS_GROUP (item->parent);
    link = g_list_find (parent->item_list, item);
    g_assert (link != NULL);

    if (put_item_after (link, NULL))
    {
        redraw_and_repick_if_mapped (item);
    }
}

/**
 * eel_canvas_item_send_behind:
 * @item: A canvas item.
 * @behind_item: The canvas item to put item behind, or NULL
 *
 * Moves item to a in the position in the stacking order so that
 * it is placed immediately below behind_item, or at the top if
 * behind_item is NULL.
 **/
void
eel_canvas_item_send_behind (EelCanvasItem *item,
                             EelCanvasItem *behind_item)
{
    GList *item_list;
    int item_position, behind_position;

    g_return_if_fail (EEL_IS_CANVAS_ITEM (item));

    if (behind_item == NULL)
    {
        eel_canvas_item_raise_to_top (item);
        return;
    }

    g_return_if_fail (EEL_IS_CANVAS_ITEM (behind_item));
    g_return_if_fail (item->parent == behind_item->parent);

    item_list = EEL_CANVAS_GROUP (item->parent)->item_list;

    item_position = g_list_index (item_list, item);
    g_assert (item_position != -1);
    behind_position = g_list_index (item_list, behind_item);
    g_assert (behind_position != -1);
    g_assert (item_position != behind_position);

    if (item_position == behind_position - 1)
    {
        return;
    }

    if (item_position < behind_position)
    {
        eel_canvas_item_raise (item, (behind_position - 1) - item_position);
    }
    else
    {
        eel_canvas_item_lower (item, item_position - behind_position);
    }
}

/**
 * eel_canvas_item_show:
 * @item: A canvas item.
 *
 * Shows a canvas item.  If the item was already shown, then no action is taken.
 **/
void
eel_canvas_item_show (EelCanvasItem *item)
{
    g_return_if_fail (EEL_IS_CANVAS_ITEM (item));

    if (!(item->flags & EEL_CANVAS_ITEM_VISIBLE))
    {
        item->flags |= EEL_CANVAS_ITEM_VISIBLE;

        if (!(item->flags & EEL_CANVAS_ITEM_REALIZED))
        {
            (*EEL_CANVAS_ITEM_GET_CLASS (item)->realize)(item);
        }

        if (item->parent != NULL)
        {
            if (!(item->flags & EEL_CANVAS_ITEM_MAPPED) &&
                item->parent->flags & EEL_CANVAS_ITEM_MAPPED)
            {
                (*EEL_CANVAS_ITEM_GET_CLASS (item)->map)(item);
            }
        }
        else
        {
            if (!(item->flags & EEL_CANVAS_ITEM_MAPPED) &&
                gtk_widget_get_mapped (GTK_WIDGET (item->canvas)))
            {
                (*EEL_CANVAS_ITEM_GET_CLASS (item)->map)(item);
            }
        }

        redraw_and_repick_if_mapped (item);
        eel_canvas_queue_resize (item->canvas);
    }
}


/**
 * eel_canvas_item_hide:
 * @item: A canvas item.
 *
 * Hides a canvas item.  If the item was already hidden, then no action is
 * taken.
 **/
void
eel_canvas_item_hide (EelCanvasItem *item)
{
    g_return_if_fail (EEL_IS_CANVAS_ITEM (item));

    if (item->flags & EEL_CANVAS_ITEM_VISIBLE)
    {
        item->flags &= ~EEL_CANVAS_ITEM_VISIBLE;

        redraw_and_repick_if_mapped (item);

        if (item->flags & EEL_CANVAS_ITEM_MAPPED)
        {
            (*EEL_CANVAS_ITEM_GET_CLASS (item)->unmap)(item);
        }

        eel_canvas_queue_resize (item->canvas);

        /* No need to unrealize when we just want to hide */
    }
}


/*
 * Prepare the window for grabbing, i.e. show it.
 */
static void
seat_grab_prepare_window (GdkSeat   *seat,
                          GdkWindow *window,
                          gpointer   user_data)
{
    gdk_window_show (window);
}

/**
 * eel_canvas_item_grab:
 * @item: A canvas item.
 * @event_mask: Mask of events that will be sent to this item.
 * @cursor: If non-NULL, the cursor that will be used while the grab is active.
 * @event: The event, triggering the grab, if any.
 *
 * Specifies that all events that match the specified event mask should be sent
 * to the specified item, and also grabs the seat by calling gdk_seat_grab().
 * If @cursor is not NULL, then that cursor is used while the grab is active.
 *
 * Return value: If an item was already grabbed, it returns %GDK_GRAB_ALREADY_GRABBED. If
 * the specified item was hidden by calling eel_canvas_item_hide(), then it
 * returns %GDK_GRAB_NOT_VIEWABLE. Else, it returns the result of calling
 * gdk_seat_grab().
 **/
GdkGrabStatus
eel_canvas_item_grab (EelCanvasItem  *item,
                      GdkEventMask    event_mask,
                      GdkCursor      *cursor,
                      const GdkEvent *event)
{
    GdkGrabStatus retval;
    GdkDisplay *display;
    GdkSeat *seat;

    g_return_val_if_fail (EEL_IS_CANVAS_ITEM (item), GDK_GRAB_NOT_VIEWABLE);
    g_return_val_if_fail (gtk_widget_get_mapped (GTK_WIDGET (item->canvas)),
                          GDK_GRAB_NOT_VIEWABLE);

    if (item->canvas->grabbed_item)
    {
        return GDK_GRAB_ALREADY_GRABBED;
    }

    if (!(item->flags & EEL_CANVAS_ITEM_MAPPED))
    {
        return GDK_GRAB_NOT_VIEWABLE;
    }

    display = gtk_widget_get_display (GTK_WIDGET (item->canvas));
    seat = gdk_display_get_default_seat (display);

    retval = gdk_seat_grab (seat,
                            gtk_layout_get_bin_window (GTK_LAYOUT (item->canvas)),
                            GDK_SEAT_CAPABILITY_ALL_POINTING,
                            FALSE,
                            cursor,
                            event,
                            seat_grab_prepare_window,
                            NULL);

    if (retval != GDK_GRAB_SUCCESS)
    {
        return retval;
    }

    item->canvas->grabbed_item = item;
    item->canvas->grabbed_event_mask = event_mask;
    item->canvas->current_item = item;     /* So that events go to the grabbed item */

    return retval;
}


/**
 * eel_canvas_item_ungrab:
 * @item: A canvas item that holds a grab.
 *
 * Ungrabs the item, which must have been grabbed in the canvas, and ungrabs the
 * seat.
 **/
void
eel_canvas_item_ungrab (EelCanvasItem *item)
{
    GdkDisplay *display;
    GdkSeat *seat;

    g_return_if_fail (EEL_IS_CANVAS_ITEM (item));

    if (item->canvas->grabbed_item != item)
    {
        return;
    }

    display = gtk_widget_get_display (GTK_WIDGET (item->canvas));
    seat = gdk_display_get_default_seat (display);

    item->canvas->grabbed_item = NULL;
    gdk_seat_ungrab (seat);
}

/**
 * eel_canvas_item_i2w:
 * @item: A canvas item.
 * @x: X coordinate to convert (input/output value).
 * @y: Y coordinate to convert (input/output value).
 *
 * Converts a coordinate pair from item-relative coordinates to world
 * coordinates.
 **/
void
eel_canvas_item_i2w (EelCanvasItem *item,
                     double        *x,
                     double        *y)
{
    g_return_if_fail (EEL_IS_CANVAS_ITEM (item));
    g_return_if_fail (x != NULL);
    g_return_if_fail (y != NULL);

    item = item->parent;
    while (item)
    {
        if (EEL_IS_CANVAS_GROUP (item))
        {
            *x += EEL_CANVAS_GROUP (item)->xpos;
            *y += EEL_CANVAS_GROUP (item)->ypos;
        }

        item = item->parent;
    }
}

/* Returns whether the item is an inferior of or is equal to the parent. */
static int
is_descendant (EelCanvasItem *item,
               EelCanvasItem *parent)
{
    for (; item; item = item->parent)
    {
        if (item == parent)
        {
            return TRUE;
        }
    }

    return FALSE;
}

/**
 * eel_canvas_item_grab_focus:
 * @item: A canvas item.
 *
 * Makes the specified item take the keyboard focus, so all keyboard events will
 * be sent to it.  If the canvas widget itself did not have the focus, it grabs
 * it as well.
 **/
static void
eel_canvas_item_grab_focus (EelCanvasItem *item)
{
    EelCanvasItem *focused_item;
    GdkEvent ev;

    g_return_if_fail (EEL_IS_CANVAS_ITEM (item));
    g_return_if_fail (gtk_widget_get_can_focus (GTK_WIDGET (item->canvas)));

    focused_item = item->canvas->focused_item;

    if (focused_item)
    {
        ev.focus_change.type = GDK_FOCUS_CHANGE;
        ev.focus_change.window = gtk_layout_get_bin_window (GTK_LAYOUT (item->canvas));
        ev.focus_change.send_event = FALSE;
        ev.focus_change.in = FALSE;

        emit_event (item->canvas, &ev);
    }

    item->canvas->focused_item = item;
    gtk_widget_grab_focus (GTK_WIDGET (item->canvas));

    if (focused_item)
    {
        ev.focus_change.type = GDK_FOCUS_CHANGE;
        ev.focus_change.window = gtk_layout_get_bin_window (GTK_LAYOUT (item->canvas));
        ev.focus_change.send_event = FALSE;
        ev.focus_change.in = TRUE;

        emit_event (item->canvas, &ev);
    }
}


/**
 * eel_canvas_item_get_bounds:
 * @item: A canvas item.
 * @x1: Leftmost edge of the bounding box (return value).
 * @y1: Upper edge of the bounding box (return value).
 * @x2: Rightmost edge of the bounding box (return value).
 * @y2: Lower edge of the bounding box (return value).
 *
 * Queries the bounding box of a canvas item.  The bounds are returned in the
 * coordinate system of the item's parent.
 **/
void
eel_canvas_item_get_bounds (EelCanvasItem *item,
                            double        *x1,
                            double        *y1,
                            double        *x2,
                            double        *y2)
{
    double tx1, ty1, tx2, ty2;

    g_return_if_fail (EEL_IS_CANVAS_ITEM (item));

    tx1 = ty1 = tx2 = ty2 = 0.0;

    /* Get the item's bounds in its coordinate system */

    if (EEL_CANVAS_ITEM_GET_CLASS (item)->bounds)
    {
        (*EEL_CANVAS_ITEM_GET_CLASS (item)->bounds)(item, &tx1, &ty1, &tx2, &ty2);
    }

    /* Return the values */

    if (x1)
    {
        *x1 = tx1;
    }

    if (y1)
    {
        *y1 = ty1;
    }

    if (x2)
    {
        *x2 = tx2;
    }

    if (y2)
    {
        *y2 = ty2;
    }
}


/**
 * eel_canvas_item_request_update
 * @item: A canvas item.
 *
 * To be used only by item implementations.  Requests that the canvas queue an
 * update for the specified item.
 **/
void
eel_canvas_item_request_update (EelCanvasItem *item)
{
    if (NULL == item->canvas)
    {
        return;
    }

    g_return_if_fail (!item->canvas->doing_update);

    if (item->flags & EEL_CANVAS_ITEM_NEED_UPDATE)
    {
        return;
    }

    item->flags |= EEL_CANVAS_ITEM_NEED_UPDATE;

    if (item->parent != NULL)
    {
        /* Recurse up the tree */
        eel_canvas_item_request_update (item->parent);
    }
    else
    {
        /* Have reached the top of the tree, make sure the update call gets scheduled. */
        eel_canvas_request_update (item->canvas);
    }
}

/**
 * eel_canvas_item_request_update
 * @item: A canvas item.
 *
 * Convenience function that informs a canvas that the specified item needs
 * to be repainted. To be used by item implementations
 **/
void
eel_canvas_item_request_redraw (EelCanvasItem *item)
{
    if (item->flags & EEL_CANVAS_ITEM_MAPPED)
    {
        eel_canvas_request_redraw (item->canvas,
                                   item->x1, item->y1,
                                   item->x2 + 1, item->y2 + 1);
    }
}



/*** EelCanvasGroup ***/


enum
{
    GROUP_PROP_0,
    GROUP_PROP_X,
    GROUP_PROP_Y
};


static void eel_canvas_group_class_init (EelCanvasGroupClass *klass);
static void eel_canvas_group_init (EelCanvasGroup *group);
static void eel_canvas_group_set_property (GObject      *object,
                                           guint         param_id,
                                           const GValue *value,
                                           GParamSpec   *pspec);
static void eel_canvas_group_get_property (GObject    *object,
                                           guint       param_id,
                                           GValue     *value,
                                           GParamSpec *pspec);

static void eel_canvas_group_destroy (EelCanvasItem *object);

static void   eel_canvas_group_update (EelCanvasItem *item,
                                       double         i2w_dx,
                                       double         i2w_dy,
                                       int            flags);
static void   eel_canvas_group_unrealize (EelCanvasItem *item);
static void   eel_canvas_group_map (EelCanvasItem *item);
static void   eel_canvas_group_unmap (EelCanvasItem *item);
static void   eel_canvas_group_draw (EelCanvasItem  *item,
                                     cairo_t        *cr,
                                     cairo_region_t *region);
static double eel_canvas_group_point (EelCanvasItem  *item,
                                      double          x,
                                      double          y,
                                      int             cx,
                                      int             cy,
                                      EelCanvasItem **actual_item);
static void   eel_canvas_group_translate (EelCanvasItem *item,
                                          double         dx,
                                          double         dy);
static void   eel_canvas_group_bounds (EelCanvasItem *item,
                                       double        *x1,
                                       double        *y1,
                                       double        *x2,
                                       double        *y2);


static EelCanvasItemClass *group_parent_class;


/**
 * eel_canvas_group_get_type:
 *
 * Registers the &EelCanvasGroup class if necessary, and returns the type ID
 * associated to it.
 *
 * Return value:  The type ID of the &EelCanvasGroup class.
 **/
GType
eel_canvas_group_get_type (void)
{
    static GType group_type = 0;

    if (!group_type)
    {
        static const GTypeInfo group_info =
        {
            sizeof (EelCanvasGroupClass),
            (GBaseInitFunc) NULL,
            (GBaseFinalizeFunc) NULL,
            (GClassInitFunc) eel_canvas_group_class_init,
            NULL,                       /* class_finalize */
            NULL,                       /* class_data */
            sizeof (EelCanvasGroup),
            0,                          /* n_preallocs */
            (GInstanceInitFunc) eel_canvas_group_init
        };

        group_type = g_type_register_static (eel_canvas_item_get_type (),
                                             "EelCanvasGroup",
                                             &group_info,
                                             0);
    }

    return group_type;
}

/* Class initialization function for EelCanvasGroupClass */
static void
eel_canvas_group_class_init (EelCanvasGroupClass *klass)
{
    GObjectClass *gobject_class;
    EelCanvasItemClass *item_class;

    gobject_class = (GObjectClass *) klass;
    item_class = (EelCanvasItemClass *) klass;

    group_parent_class = g_type_class_peek_parent (klass);

    gobject_class->set_property = eel_canvas_group_set_property;
    gobject_class->get_property = eel_canvas_group_get_property;

    g_object_class_install_property
        (gobject_class, GROUP_PROP_X,
        g_param_spec_double ("x",
                             _("X"),
                             _("X"),
                             -G_MAXDOUBLE, G_MAXDOUBLE, 0.0,
                             G_PARAM_READWRITE));
    g_object_class_install_property
        (gobject_class, GROUP_PROP_Y,
        g_param_spec_double ("y",
                             _("Y"),
                             _("Y"),
                             -G_MAXDOUBLE, G_MAXDOUBLE, 0.0,
                             G_PARAM_READWRITE));

    item_class->destroy = eel_canvas_group_destroy;
    item_class->update = eel_canvas_group_update;
    item_class->unrealize = eel_canvas_group_unrealize;
    item_class->map = eel_canvas_group_map;
    item_class->unmap = eel_canvas_group_unmap;
    item_class->draw = eel_canvas_group_draw;
    item_class->point = eel_canvas_group_point;
    item_class->translate = eel_canvas_group_translate;
    item_class->bounds = eel_canvas_group_bounds;
}

/* Object initialization function for EelCanvasGroup */
static void
eel_canvas_group_init (EelCanvasGroup *group)
{
    group->xpos = 0.0;
    group->ypos = 0.0;
}

/* Set_property handler for canvas groups */
static void
eel_canvas_group_set_property (GObject      *gobject,
                               guint         param_id,
                               const GValue *value,
                               GParamSpec   *pspec)
{
    EelCanvasItem *item;
    EelCanvasGroup *group;
    double old;
    gboolean moved;

    g_return_if_fail (EEL_IS_CANVAS_GROUP (gobject));

    item = EEL_CANVAS_ITEM (gobject);
    group = EEL_CANVAS_GROUP (gobject);

    moved = FALSE;
    switch (param_id)
    {
        case GROUP_PROP_X:
        {
            old = group->xpos;
            group->xpos = g_value_get_double (value);
            if (old != group->xpos)
            {
                moved = TRUE;
            }
        }
        break;

        case GROUP_PROP_Y:
        {
            old = group->ypos;
            group->ypos = g_value_get_double (value);
            if (old != group->ypos)
            {
                moved = TRUE;
            }
        }
        break;

        default:
        {
            G_OBJECT_WARN_INVALID_PROPERTY_ID (gobject, param_id, pspec);
        }
        break;
    }

    if (moved)
    {
        item->flags |= EEL_CANVAS_ITEM_NEED_DEEP_UPDATE;
        if (item->parent != NULL)
        {
            eel_canvas_item_request_update (item->parent);
        }
        else
        {
            eel_canvas_request_update (item->canvas);
        }
    }
}

/* Get_property handler for canvas groups */
static void
eel_canvas_group_get_property (GObject    *gobject,
                               guint       param_id,
                               GValue     *value,
                               GParamSpec *pspec)
{
    EelCanvasGroup *group;

    g_return_if_fail (EEL_IS_CANVAS_GROUP (gobject));

    group = EEL_CANVAS_GROUP (gobject);

    switch (param_id)
    {
        case GROUP_PROP_X:
        {
            g_value_set_double (value, group->xpos);
        }
        break;

        case GROUP_PROP_Y:
        {
            g_value_set_double (value, group->ypos);
        }
        break;

        default:
        {
            G_OBJECT_WARN_INVALID_PROPERTY_ID (gobject, param_id, pspec);
        }
        break;
    }
}

/* Destroy handler for canvas groups */
static void
eel_canvas_group_destroy (EelCanvasItem *object)
{
    EelCanvasGroup *group;
    EelCanvasItem *child;
    GList *list;

    g_return_if_fail (EEL_IS_CANVAS_GROUP (object));

    group = EEL_CANVAS_GROUP (object);

    list = group->item_list;
    while (list)
    {
        child = list->data;
        list = list->next;

        eel_canvas_item_destroy (child);
    }