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.

Signals


"activated" void        user_function      (HippoCanvasItem *arg0,
                                            gpointer         user_data)      : Run last
"button-press-event"
            gboolean    user_function      (HippoCanvasItem *arg0,
                                            HippoEvent      *arg1,
                                            gpointer         user_data)      : Run last
"button-release-event"
            gboolean    user_function      (HippoCanvasItem *arg0,
                                            HippoEvent      *arg1,
                                            gpointer         user_data)      : Run last
"destroy"   void        user_function      (HippoCanvasItem *arg0,
                                            gpointer         user_data)      : Cleanup / No recursion / No hooks
"key-press-event"
            gboolean    user_function      (HippoCanvasItem *arg0,
                                            HippoEvent      *arg1,
                                            gpointer         user_data)      : Run last
"motion-notify-event"
            gboolean    user_function      (HippoCanvasItem *arg0,
                                            HippoEvent      *arg1,
                                            gpointer         user_data)      : Run last
"paint"     void        user_function      (HippoCanvasItem *arg0,
                                            gpointer         arg1,
                                            HippoRectangle  *arg2,
                                            gpointer         user_data)      : Run last
"paint-needed"
            void        user_function      (HippoCanvasItem *arg0,
                                            HippoRectangle  *arg1,
                                            gpointer         user_data)      : Run last
"request-changed"
            void        user_function      (HippoCanvasItem *arg0,
                                            gpointer         user_data)      : Run last
"tooltip-changed"
            void        user_function      (HippoCanvasItem *arg0,
                                            gpointer         user_data)      : Run last

Description

Details

HippoCanvasItem

typedef struct _HippoCanvasItem HippoCanvasItem;


HippoCanvasItemIface

typedef struct {
    GTypeInterface base_iface;

    void     (* sink)               (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);
} 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);
    
    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);
} 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 :

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.

(If you

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 "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.