## HippoCanvasItem

HippoCanvasItem

## Synopsis

    #include <hippo/hippo-canvas-item.h>

                        HippoCanvasItem;
                        HippoCanvasItemIface;
    enum                HippoCanvasPointer;
    enum                HippoItemAlignment;
                        HippoCanvasItemIface;
    void                hippo_canvas_item_sink              (HippoCanvasItem *canvas_item);
    void                hippo_canvas_item_destroy           (HippoCanvasItem *canvas_item);
    void                hippo_canvas_item_set_context       (HippoCanvasItem *canvas_item,
                                                             HippoCanvasContext *context);
    void                hippo_canvas_item_set_parent        (HippoCanvasItem *canvas_item,
                                                             HippoCanvasContainer *container);
    HippoCanvasContainer* hippo_canvas_item_get_parent      (HippoCanvasItem *canvas_item);
    void                hippo_canvas_item_get_width_request (HippoCanvasItem *canvas_item,
                                                             int *min_width_p,
                                                             int *natural_width_p);
    void                hippo_canvas_item_get_height_request
                                                            (HippoCanvasItem *canvas_item,
                                                             int for_width,
                                                             int *min_height_p,
                                                             int *natural_height_p);
    void                hippo_canvas_item_allocate          (HippoCanvasItem *canvas_item,
                                                             int width,
                                                             int height,
                                                             gboolean origin_changed);
    void                hippo_canvas_item_get_allocation    (HippoCanvasItem *canvas_item,
                                                             int *width_p,
                                                             int *height_p);
    gboolean            hippo_canvas_item_get_needs_request (HippoCanvasItem *canvas_item);
    char*               hippo_canvas_item_get_tooltip       (HippoCanvasItem *canvas_item,
                                                             int x,
                                                             int y,
                                                             HippoRectangle *for_area);
    HippoCanvasPointer  hippo_canvas_item_get_pointer       (HippoCanvasItem *canvas_item,
                                                             int x,
                                                             int y);
    gboolean            hippo_canvas_item_get_visible       (HippoCanvasItem *canvas_item);
    void                hippo_canvas_item_set_visible       (HippoCanvasItem *canvas_item,
                                                             gboolean visible);
    void                hippo_canvas_item_emit_destroy      (HippoCanvasItem *canvas_item);
    gboolean            hippo_canvas_item_emit_button_press_event
                                                            (HippoCanvasItem *canvas_item,
                                                             int x,
                                                             int y,
                                                             int button,
                                                             int x11_x_root,
                                                             int x11_y_root,
                                                             guint32 x11_time,
                                                             int count);
    gboolean            hippo_canvas_item_emit_button_release_event
                                                            (HippoCanvasItem *canvas_item,
                                                             int x,
                                                             int y,
                                                             int button,
                                                             int x11_x_root,
                                                             int x11_y_root,
                                                             guint32 x11_time);
    gboolean            hippo_canvas_item_emit_motion_notify_event
                                                            (HippoCanvasItem *canvas_item,
                                                             int x,
                                                             int y,
                                                             HippoMotionDetail detail);
    gboolean            hippo_canvas_item_emit_key_press_event
                                                            (HippoCanvasItem *canvas_item,
                                                             HippoKey key,
                                                             gunichar character,
                                                             guint modifiers);
    void                hippo_canvas_item_emit_activated    (HippoCanvasItem *canvas_item);
    void                hippo_canvas_item_emit_paint_needed (HippoCanvasItem *canvas_item,
                                                             int x,
                                                             int y,
                                                             int width,
                                                             int height);
    void                hippo_canvas_item_emit_tooltip_changed
                                                            (HippoCanvasItem *canvas_item);
    void                hippo_canvas_item_emit_request_changed
                                                            (HippoCanvasItem *canvas_item);
    gboolean            hippo_canvas_item_process_event     (HippoCanvasItem *canvas_item,
                                                             HippoEvent *event,
                                                             int allocation_x,
                                                             int allocation_y);
    void                hippo_canvas_item_process_paint     (HippoCanvasItem *canvas_item,
                                                             cairo_t *cr,
                                                             HippoRectangle *damaged_box,
                                                             int allocation_x,
                                                             int allocation_y);

## Object Hierarchy

      GInterface
       +----HippoCanvasItem

## Known Implementations

HippoCanvasItem is implemented by HippoCanvasGradient, HippoCanvasLink, HippoCanvasImage, HippoCanvasBox, HippoCanvasText and HippoCanvasImageButton.

## Properties

      "classes"                  gchar*                : Read / Write
      "id"                       gchar*                : Read / Write

## Signals

      "activated"                                      : Run Last
      "button-press-event"                             : Run Last
      "button-release-event"                           : Run Last
      "destroy"                                        : Cleanup / No Recursion / No Hooks
      "key-press-event"                                : Run Last
      "motion-notify-event"                            : Run Last
      "paint"                                          : Run Last
      "paint-needed"                                   : Run Last
      "request-changed"                                : Run Last
      "scroll-event"                                   : Run Last
      "tooltip-changed"                                : Run Last

## Description

## Details

### HippoCanvasItem

    typedef struct _HippoCanvasItem HippoCanvasItem;

### HippoCanvasItemIface

    typedef struct {
        GTypeInterface base_iface;

        void                   (* sink)                 (HippoCanvasItem *canvas_item);
        HippoCanvasContext*    (* get_context)          (HippoCanvasItem *canvas_item);
        void                   (* set_context)          (HippoCanvasItem      *canvas_item,
                                                         HippoCanvasContext   *context);
        void                   (* set_parent)           (HippoCanvasItem      *canvas_item,
                                                         HippoCanvasContainer *container);
        HippoCanvasContainer*  (* get_parent)           (HippoCanvasItem *canvas_item);
        void                   (* paint)                (HippoCanvasItem *canvas_item,
                                                         cairo_t         *cr,
                                                         HippoRectangle  *damaged_box);
        void                   (* get_width_request)    (HippoCanvasItem *canvas_item,
                                                         int             *min_width_p,
                                                         int             *natural_width_p);
        void                   (* get_height_request)   (HippoCanvasItem *canvas_item,
                                                         int              for_width,
                                                         int             *min_height_p,
                                                         int             *natural_height_p);

        /* The origin changed flag indicates that the position of the item with respect to the
         * canvas root changed. The item must then call allocate on it's children passing
         * TRUE for origin_changed as well. */
        void                   (* allocate)             (HippoCanvasItem *canvas_item,
                                                         int              width,
                                                         int              height,
                                                         gboolean         origin_changed);
        void                   (* get_allocation)       (HippoCanvasItem *canvas_item,
                                                         int             *width_p,
                                                         int             *height_p);
        gboolean               (* button_press_event)   (HippoCanvasItem *canvas_item,
                                                         HippoEvent      *event);
        gboolean               (* button_release_event) (HippoCanvasItem *canvas_item,
                                                         HippoEvent      *event);
        gboolean               (* motion_notify_event)  (HippoCanvasItem *canvas_item,
                                                         HippoEvent      *event);
        gboolean               (* key_press_event)      (HippoCanvasItem *canvas_item,
                                                         HippoEvent      *event);
        void                   (* activated)            (HippoCanvasItem *canvas_item);
        void                   (* request_changed)      (HippoCanvasItem *canvas_item);
        void                   (* paint_needed)         (HippoCanvasItem *canvas_item,
                                                         const HippoRectangle *damage_box);
        gboolean               (* get_needs_request)    (HippoCanvasItem *canvas_item);
        char*                  (* get_tooltip)          (HippoCanvasItem *canvas_item,
                                                         int              x,
                                                         int              y,
                                                         HippoRectangle  *for_area);
        void                   (* tooltip_changed)      (HippoCanvasItem *canvas_item);
        HippoCanvasPointer     (* get_pointer)          (HippoCanvasItem *canvas_item,
                                                         int              x,
                                                         int              y);
        gboolean               (* scroll_event)         (HippoCanvasItem *canvas_item,
                                                         HippoEvent      *event);
    } HippoCanvasItemIface;

### enum HippoCanvasPointer

    typedef enum {
        HIPPO_CANVAS_POINTER_UNSET,
        HIPPO_CANVAS_POINTER_DEFAULT,
        HIPPO_CANVAS_POINTER_HAND
    } HippoCanvasPointer;

### enum HippoItemAlignment

    typedef enum {
        HIPPO_ALIGNMENT_FILL,
        HIPPO_ALIGNMENT_START, /* left or top */
        HIPPO_ALIGNMENT_CENTER,
        HIPPO_ALIGNMENT_END    /* right or bottom */
    } HippoItemAlignment;

### HippoCanvasItemIface

    typedef struct {
        GTypeInterface base_iface;

        void                   (* sink)                 (HippoCanvasItem *canvas_item);
        HippoCanvasContext*    (* get_context)          (HippoCanvasItem *canvas_item);
        void                   (* set_context)          (HippoCanvasItem      *canvas_item,
                                                         HippoCanvasContext   *context);
        void                   (* set_parent)           (HippoCanvasItem      *canvas_item,
                                                         HippoCanvasContainer *container);
        HippoCanvasContainer*  (* get_parent)           (HippoCanvasItem *canvas_item);
        void                   (* paint)                (HippoCanvasItem *canvas_item,
                                                         cairo_t         *cr,
                                                         HippoRectangle  *damaged_box);
        void                   (* get_width_request)    (HippoCanvasItem *canvas_item,
                                                         int             *min_width_p,
                                                         int             *natural_width_p);
        void                   (* get_height_request)   (HippoCanvasItem *canvas_item,
                                                         int              for_width,
                                                         int             *min_height_p,
                                                         int             *natural_height_p);

        /* The origin changed flag indicates that the position of the item with respect to the
         * canvas root changed. The item must then call allocate on it's children passing
         * TRUE for origin_changed as well. */
        void                   (* allocate)             (HippoCanvasItem *canvas_item,
                                                         int              width,
                                                         int              height,
                                                         gboolean         origin_changed);
        void                   (* get_allocation)       (HippoCanvasItem *canvas_item,
                                                         int             *width_p,
                                                         int             *height_p);
        gboolean               (* button_press_event)   (HippoCanvasItem *canvas_item,
                                                         HippoEvent      *event);
        gboolean               (* button_release_event) (HippoCanvasItem *canvas_item,
                                                         HippoEvent      *event);
        gboolean               (* motion_notify_event)  (HippoCanvasItem *canvas_item,
                                                         HippoEvent      *event);
        gboolean               (* key_press_event)      (HippoCanvasItem *canvas_item,
                                                         HippoEvent      *event);
        void                   (* activated)            (HippoCanvasItem *canvas_item);
        void                   (* request_changed)      (HippoCanvasItem *canvas_item);
        void                   (* paint_needed)         (HippoCanvasItem *canvas_item,
                                                         const HippoRectangle *damage_box);
        gboolean               (* get_needs_request)    (HippoCanvasItem *canvas_item);
        char*                  (* get_tooltip)          (HippoCanvasItem *canvas_item,
                                                         int              x,
                                                         int              y,
                                                         HippoRectangle  *for_area);
        void                   (* tooltip_changed)      (HippoCanvasItem *canvas_item);
        HippoCanvasPointer     (* get_pointer)          (HippoCanvasItem *canvas_item,
                                                         int              x,
                                                         int              y);
        gboolean               (* scroll_event)         (HippoCanvasItem *canvas_item,
                                                         HippoEvent      *event);
    } HippoCanvasItemIface;

### hippo_canvas_item_sink ()

    void                hippo_canvas_item_sink              (HippoCanvasItem *canvas_item);

`canvas_item` : |

### hippo_canvas_item_destroy ()

    void                hippo_canvas_item_destroy           (HippoCanvasItem *canvas_item);

Explicitly requests that the item be destroyed. This will cause item to drop all references it holds to other objects, and also result in the ::destroy signal being emitted. In response to the ::destroy signal, any other objects that are holding on to references to the item should drop the references they hold. In particular, the item will be removed from its parent container.

Note that this function doesn't directly cause the memory for the object to be freed; the object will be freed only if the above actions cause all references to it to be dropped.

`canvas_item` : |

### hippo_canvas_item_set_context ()

    void                hippo_canvas_item_set_context       (HippoCanvasItem *canvas_item,
                                                             HippoCanvasContext *context);

`canvas_item` : |
`context` : |

### hippo_canvas_item_set_parent ()

    void                hippo_canvas_item_set_parent        (HippoCanvasItem *canvas_item,
                                                             HippoCanvasContainer *container);

`canvas_item` : |
`container` : |

### hippo_canvas_item_get_parent ()

    HippoCanvasContainer* hippo_canvas_item_get_parent      (HippoCanvasItem *canvas_item);

`canvas_item` : |
Returns : |

### hippo_canvas_item_get_width_request ()

    void                hippo_canvas_item_get_width_request (HippoCanvasItem *canvas_item,
                                                             int *min_width_p,
                                                             int *natural_width_p);

`canvas_item` : |
`min_width_p` : |
`natural_width_p` : |

### hippo_canvas_item_get_height_request ()

    void                hippo_canvas_item_get_height_request
                                                            (HippoCanvasItem *canvas_item,
                                                             int for_width,
                                                             int *min_height_p,
                                                             int *natural_height_p);

`canvas_item` : |
`for_width` : |
`min_height_p` : |
`natural_height_p` : |

### hippo_canvas_item_allocate ()

    void                hippo_canvas_item_allocate          (HippoCanvasItem *canvas_item,
                                                             int width,
                                                             int height,
                                                             gboolean origin_changed);

`canvas_item` : |
`width` : |
`height` : |
`origin_changed` : |

### hippo_canvas_item_get_allocation ()

    void                hippo_canvas_item_get_allocation    (HippoCanvasItem *canvas_item,
                                                             int *width_p,
                                                             int *height_p);

`canvas_item` : |
`width_p` : |
`height_p` : |

### hippo_canvas_item_get_needs_request ()

    gboolean            hippo_canvas_item_get_needs_request (HippoCanvasItem *canvas_item);

`canvas_item` : |
Returns : |

### hippo_canvas_item_get_tooltip ()

    char*               hippo_canvas_item_get_tooltip       (HippoCanvasItem *canvas_item,
                                                             int x,
                                                             int y,
                                                             HippoRectangle *for_area);

`canvas_item` : |
`x` : |
`y` : |
`for_area` : |
Returns : |

### hippo_canvas_item_get_pointer ()

    HippoCanvasPointer  hippo_canvas_item_get_pointer       (HippoCanvasItem *canvas_item,
                                                             int x,
                                                             int y);

`canvas_item` : |
`x` : |
`y` : |
Returns : |

### hippo_canvas_item_get_visible ()

    gboolean            hippo_canvas_item_get_visible       (HippoCanvasItem *canvas_item);

`canvas_item` : |
Returns : |

### hippo_canvas_item_set_visible ()

    void                hippo_canvas_item_set_visible       (HippoCanvasItem *canvas_item,
                                                             gboolean visible);

`canvas_item` : |
`visible` : |

### hippo_canvas_item_emit_destroy ()

    void                hippo_canvas_item_emit_destroy      (HippoCanvasItem *canvas_item);

Emit the ::destroy signal on canvas_item. Note that this doesn't actually destroy the item (see `hippo_canvas_item()`) for that. This function should be called at the end of your implementation of `dispose()` before chaining up if you are implementing HippoCanvasItem directly. If you derive from an implementation of HippoCanvasItem like HippoCanvasBox, you need not and should not call this function.

`canvas_item` : | the canvas item

### hippo_canvas_item_emit_button_press_event ()

    gboolean            hippo_canvas_item_emit_button_press_event
                                                            (HippoCanvasItem *canvas_item,
                                                             int x,
                                                             int y,
                                                             int button,
                                                             int x11_x_root,
                                                             int x11_y_root,
                                                             guint32 x11_time,
                                                             int count);

`canvas_item` : |
`x` : |
`y` : |
`button` : |
`x11_x_root` : |
`x11_y_root` : |
`x11_time` : |
`count` : |
Returns : |

### hippo_canvas_item_emit_button_release_event ()

    gboolean            hippo_canvas_item_emit_button_release_event
                                                            (HippoCanvasItem *canvas_item,
                                                             int x,
                                                             int y,
                                                             int button,
                                                             int x11_x_root,
                                                             int x11_y_root,
                                                             guint32 x11_time);

`canvas_item` : |
`x` : |
`y` : |
`button` : |
`x11_x_root` : |
`x11_y_root` : |
`x11_time` : |
Returns : |

### hippo_canvas_item_emit_motion_notify_event ()

    gboolean            hippo_canvas_item_emit_motion_notify_event
                                                            (HippoCanvasItem *canvas_item,
                                                             int x,
                                                             int y,
                                                             HippoMotionDetail detail);

`canvas_item` : |
`x` : |
`y` : |
`detail` : |
Returns : |

### hippo_canvas_item_emit_key_press_event ()

    gboolean            hippo_canvas_item_emit_key_press_event
                                                            (HippoCanvasItem *canvas_item,
                                                             HippoKey key,
                                                             gunichar character,
                                                             guint modifiers);

`canvas_item` : |
`key` : |
`character` : |
`modifiers` : |
Returns : |

### hippo_canvas_item_emit_activated ()

    void                hippo_canvas_item_emit_activated    (HippoCanvasItem *canvas_item);

`canvas_item` : |

### hippo_canvas_item_emit_paint_needed ()

    void                hippo_canvas_item_emit_paint_needed (HippoCanvasItem *canvas_item,
                                                             int x,
                                                             int y,
                                                             int width,
                                                             int height);

`canvas_item` : |
`x` : |
`y` : |
`width` : |
`height` : |

### hippo_canvas_item_emit_tooltip_changed ()

    void                hippo_canvas_item_emit_tooltip_changed
                                                            (HippoCanvasItem *canvas_item);

`canvas_item` : |

### hippo_canvas_item_emit_request_changed ()

    void                hippo_canvas_item_emit_request_changed
                                                            (HippoCanvasItem *canvas_item);

`canvas_item` : |

### hippo_canvas_item_process_event ()

    gboolean            hippo_canvas_item_process_event     (HippoCanvasItem *canvas_item,
                                                             HippoEvent *event,
                                                             int allocation_x,
                                                             int allocation_y);

`canvas_item` : |
`event` : |
`allocation_x` : |
`allocation_y` : |
Returns : |

### hippo_canvas_item_process_paint ()

    void                hippo_canvas_item_process_paint     (HippoCanvasItem *canvas_item,
                                                             cairo_t *cr,
                                                             HippoRectangle *damaged_box,
                                                             int allocation_x,
                                                             int allocation_y);

`canvas_item` : |
`cr` : |
`damaged_box` : |
`allocation_x` : |
`allocation_y` : |

## Property Details

### The `"classes"` property

      "classes"                  gchar*                : Read / Write

Class names for the element; this is used when matching a CSS rule selector against the element tree. Multiple classes can be specified, specified by spaces. (This property is called 'classes' and not 'class' to avoid problems with language bindings.)

Default value: NULL

### The `"id"` property

      "id"                       gchar*                : Read / Write

The ID of the element; this is used when matching a CSS rule selector against the element tree.

Default value: NULL

## Signal Details

### The `"activated"` signal

    void                user_function                      (HippoCanvasItem *arg0,
                                                            gpointer         user_data)      : Run Last

Signal emitted when the canvas item is "activated" (e.g. if a button is clicked or an url is clicked).

`user_data` : | user data set when the signal handler was connected.

### The `"button-press-event"` signal

    gboolean            user_function                      (HippoCanvasItem *arg0,
                                                            HippoEvent      *arg1,
                                                            gpointer         user_data)      : Run Last

Signal emitted when a mouse button is pressed down on the canvas item.

`user_data` : | user data set when the signal handler was connected.

### The `"button-release-event"` signal

    gboolean            user_function                      (HippoCanvasItem *arg0,
                                                            HippoEvent      *arg1,
                                                            gpointer         user_data)      : Run Last

Signal emitted when a mouse button is released on the canvas item.

`user_data` : | user data set when the signal handler was connected.

### The `"destroy"` signal

    void                user_function                      (HippoCanvasItem *arg0,
                                                            gpointer         user_data)      : Cleanup / No Recursion / No Hooks

This canvas item has explicitely been destroyed. All references it holds to other objects will be dropped, and all signal handlers removed.

`user_data` : | user data set when the signal handler was connected.

### The `"key-press-event"` signal

    gboolean            user_function                      (HippoCanvasItem *arg0,
                                                            HippoEvent      *arg1,
                                                            gpointer         user_data)      : Run Last

Signal emitted when a key is pressed while the canvas item is focused.

`user_data` : | user data set when the signal handler was connected.

### The `"motion-notify-event"` signal

    gboolean            user_function                      (HippoCanvasItem *arg0,
                                                            HippoEvent      *arg1,
                                                            gpointer         user_data)      : Run Last

Signal emitted when the mouse pointer enters, leaves, or moves within a canvas item. Note that unlike GtkWidget, there are not separate events for enter and leave.

`user_data` : | user data set when the signal handler was connected.

### The `"paint"` signal

    void                user_function                      (HippoCanvasItem *arg0,
                                                            gpointer         arg1,
                                                            HippoRectangle  *arg2,
                                                            gpointer         user_data)      : Run Last

All drawing of a canvas item happens in the handlers for this signal. The rectangle is the bounding box of the damage region. Most concrete items derive from HippoCanvasBox, whose default paint handler invokes a series of more fine-grained paint handlers to paint the background, content, etc.; usually you should override one of those fine-grained handlers rather than this all-encompassing paint.

`user_data` : | user data set when the signal handler was connected.

### The `"paint-needed"` signal

    void                user_function                      (HippoCanvasItem *arg0,
                                                            HippoRectangle  *arg1,
                                                            gpointer         user_data)      : Run Last

Signal emitted when a canvas item needs to be repainted. The rectangle is the bounding box of the areas that need repainting.

`user_data` : | user data set when the signal handler was connected.

### The `"request-changed"` signal

    void                user_function                      (HippoCanvasItem *arg0,
                                                            gpointer         user_data)      : Run Last

Signal emitted when the natural or minimum size of the canvas item may have changed. The parent canvas or parent canvas item will normally need to recompute its layout in response.

`user_data` : | user data set when the signal handler was connected.

### The `"scroll-event"` signal

    gboolean            user_function                      (HippoCanvasItem *arg0,
                                                            HippoEvent      *arg1,
                                                            gpointer         user_data)      : Run Last

Signal emitted when the mouse wheel or other mechanism requests scrolling.

`user_data` : | user data set when the signal handler was connected.

### The `"tooltip-changed"` signal

    void                user_function                      (HippoCanvasItem *arg0,
                                                            gpointer         user_data)      : Run Last

Signal emitted when the canvas item's tooltip changes. The code displaying the tooltip may need this signal in order to update in response to changes.

`user_data` : | user data set when the signal handler was connected.