/* * GooCanvas. Copyright (C) 2005 Damon Chaplin. * Released under the GNU LGPL license. See COPYING for details. * * goocanvasitem.h - interface for canvas items & groups. */ #ifndef __GOO_CANVAS_ITEM_H__ #define __GOO_CANVAS_ITEM_H__ #include #include "goocanvasstyle.h" G_BEGIN_DECLS /** * GooCanvasAnimateType * @GOO_CANVAS_ANIMATE_FREEZE: the item remains in the final position. * @GOO_CANVAS_ANIMATE_RESET: the item is moved back to the initial position. * @GOO_CANVAS_ANIMATE_RESTART: the animation is restarted from the initial * position. * @GOO_CANVAS_ANIMATE_BOUNCE: the animation bounces back and forth between the * start and end positions. * * #GooCanvasAnimateType is used to specify what happens when the end of an * animation is reached. */ typedef enum { GOO_CANVAS_ANIMATE_FREEZE, GOO_CANVAS_ANIMATE_RESET, GOO_CANVAS_ANIMATE_RESTART, GOO_CANVAS_ANIMATE_BOUNCE } GooCanvasAnimateType; /** * GooCanvasBounds * @x1: the left edge. * @y1: the top edge. * @x2: the right edge. * @y2: the bottom edge. * * #GooCanvasBounds represents the bounding box of an item in the canvas. */ typedef struct _GooCanvasBounds GooCanvasBounds; struct _GooCanvasBounds { gdouble x1, y1, x2, y2; }; GType goo_canvas_bounds_get_type (void) G_GNUC_CONST; #define GOO_TYPE_CANVAS_BOUNDS (goo_canvas_bounds_get_type ()) #define GOO_TYPE_CANVAS_ITEM (goo_canvas_item_get_type ()) #define GOO_CANVAS_ITEM(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), GOO_TYPE_CANVAS_ITEM, GooCanvasItem)) #define GOO_IS_CANVAS_ITEM(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GOO_TYPE_CANVAS_ITEM)) #define GOO_CANVAS_ITEM_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), GOO_TYPE_CANVAS_ITEM, GooCanvasItemIface)) /* Workaround for circular dependencies. Include this file first. */ typedef struct _GooCanvas GooCanvas; typedef struct _GooCanvasItemModel GooCanvasItemModel; /** * GooCanvasItem * * #GooCanvasItem is a typedef used for objects that implement the * #GooCanvasItem interface. * * (There is no actual #GooCanvasItem struct, since it is only an interface. * But using '#GooCanvasItem' is more helpful than using '#GObject'.) */ typedef struct _GooCanvasItem GooCanvasItem; /** * GooCanvasItemIface * @get_canvas: returns the canvas the item is in. * @set_canvas: sets the canvas the item is in. * @get_n_children: returns the number of children of the item. * @get_child: returns the child at the given index. * @request_update: requests that an update is scheduled. * @add_child: adds a child. * @move_child: moves a child up or down the stacking order. * @remove_child: removes a child. * @get_child_property: gets a child property of a given child item, * e.g. the "row" or "column" property of an item in a #GooCanvasTable. * @set_child_property: sets a child property for a given child item. * @get_transform_for_child: gets the transform used to lay out a given child. * @get_parent: gets the item's parent. * @set_parent: sets the item's parent. * @get_bounds: gets the bounds of the item. * @get_items_at: gets all the items at the given point. * @update: updates the item, if needed. It recalculates the bounds of the item * and requests redraws of parts of the canvas if necessary. * @paint: renders the item to the given cairo context. * @get_requested_area: returns the requested area of the item, in its parent's * coordinate space. This is only used for items in layout containers such as * #GooCanvasTable. * @allocate_area: allocates the item's area, in its parent's coordinate space. * The item must recalculate its bounds and request redraws of parts of the * canvas if necessary. This is only used for items in layout containers such * as #GooCanvasTable. * @get_transform: gets the item's transformation matrix. * @set_transform: sets the item's transformation matrix. * @get_style: gets the item's style. * @set_style: sets the item's style. * @is_visible: returns %TRUE if the item is currently visible. * @get_is_static: returns %TRUE if the item is static. * @set_is_static: notifies the item whether it is static or not. * @get_requested_height: returns the requested height of the item, * given a particular allocated width, using the parent's coordinate space. * @get_model: gets the model that the canvas item is viewing. * @set_model: sets the model that the canvas item will view. * @enter_notify_event: signal emitted when the mouse enters the item. * @leave_notify_event: signal emitted when the mouse leaves the item. * @motion_notify_event: signal emitted when the mouse moves within the item. * @button_press_event: signal emitted when a mouse button is pressed within * the item. * @button_release_event: signal emitted when a mouse button is released. * @focus_in_event: signal emitted when the item receices the keyboard focus. * @focus_out_event: signal emitted when the item loses the keyboard focus. * @key_press_event: signal emitted when a key is pressed. * @key_release_event: signal emitted when a key is released. * @grab_broken_event: signal emitted when a grab that the item has is lost. * @child_notify: signal emitted when a child property is changed. * @query_tooltip: signal emitted to query the tooltip of an item. * @animation_finished: signal emitted when the item's animation has finished. * @scroll_event: signal emitted when the mouse wheel is activated within * the item. * * #GooCanvasItemIFace holds the virtual methods that make up the * #GooCanvasItem interface. * * Simple canvas items only need to implement the get_parent(), set_parent(), * get_bounds(), get_items_at(), update() and paint() methods (and also * get_requested_area() and allocate_area() if they are going to be used * inside a layout container like #GooCanvasTable). * * Items that support transforms should also implement get_transform() and * set_transform(). Items that support styles should implement get_style() * and set_style(). * * Container items must implement get_canvas(), set_canvas(), * get_n_children(), get_child() and request_update(). Containers that support * dynamic changes to their children should implement add_child(), * move_child() and remove_child(). Layout containers like #GooCanvasTable * may implement get_child_property(), set_child_property() and * get_transform_for_child(). */ typedef struct _GooCanvasItemIface GooCanvasItemIface; struct _GooCanvasItemIface { /*< private >*/ GTypeInterface base_iface; /*< public >*/ /* Virtual methods that group items must implement. */ GooCanvas* (* get_canvas) (GooCanvasItem *item); void (* set_canvas) (GooCanvasItem *item, GooCanvas *canvas); gint (* get_n_children) (GooCanvasItem *item); GooCanvasItem* (* get_child) (GooCanvasItem *item, gint child_num); void (* request_update) (GooCanvasItem *item); /* Virtual methods that group items may implement. */ void (* add_child) (GooCanvasItem *item, GooCanvasItem *child, gint position); void (* move_child) (GooCanvasItem *item, gint old_position, gint new_position); void (* remove_child) (GooCanvasItem *item, gint child_num); void (* get_child_property) (GooCanvasItem *item, GooCanvasItem *child, guint property_id, GValue *value, GParamSpec *pspec); void (* set_child_property) (GooCanvasItem *item, GooCanvasItem *child, guint property_id, const GValue *value, GParamSpec *pspec); gboolean (* get_transform_for_child) (GooCanvasItem *item, GooCanvasItem *child, cairo_matrix_t *transform); /* Virtual methods that all canvas items must implement. */ GooCanvasItem* (* get_parent) (GooCanvasItem *item); void (* set_parent) (GooCanvasItem *item, GooCanvasItem *parent); void (* get_bounds) (GooCanvasItem *item, GooCanvasBounds *bounds); GList* (* get_items_at) (GooCanvasItem *item, gdouble x, gdouble y, cairo_t *cr, gboolean is_pointer_event, gboolean parent_is_visible, GList *found_items); void (* update) (GooCanvasItem *item, gboolean entire_tree, cairo_t *cr, GooCanvasBounds *bounds); void (* paint) (GooCanvasItem *item, cairo_t *cr, const GooCanvasBounds *bounds, gdouble scale); gboolean (* get_requested_area) (GooCanvasItem *item, cairo_t *cr, GooCanvasBounds *requested_area); void (* allocate_area) (GooCanvasItem *item, cairo_t *cr, const GooCanvasBounds *requested_area, const GooCanvasBounds *allocated_area, gdouble x_offset, gdouble y_offset); /* Virtual methods that canvas items may implement. */ gboolean (* get_transform) (GooCanvasItem *item, cairo_matrix_t *transform); void (* set_transform) (GooCanvasItem *item, const cairo_matrix_t *transform); GooCanvasStyle* (* get_style) (GooCanvasItem *item); void (* set_style) (GooCanvasItem *item, GooCanvasStyle *style); gboolean (* is_visible) (GooCanvasItem *item); gdouble (* get_requested_height) (GooCanvasItem *item, cairo_t *cr, gdouble width); /* Virtual methods that model/view items must implement. */ GooCanvasItemModel* (* get_model) (GooCanvasItem *item); void (* set_model) (GooCanvasItem *item, GooCanvasItemModel *model); /* Signals. */ gboolean (* enter_notify_event) (GooCanvasItem *item, GooCanvasItem *target, GdkEventCrossing *event); gboolean (* leave_notify_event) (GooCanvasItem *item, GooCanvasItem *target, GdkEventCrossing *event); gboolean (* motion_notify_event) (GooCanvasItem *item, GooCanvasItem *target, GdkEventMotion *event); gboolean (* button_press_event) (GooCanvasItem *item, GooCanvasItem *target, GdkEventButton *event); gboolean (* button_release_event) (GooCanvasItem *item, GooCanvasItem *target, GdkEventButton *event); gboolean (* focus_in_event) (GooCanvasItem *item, GooCanvasItem *target, GdkEventFocus *event); gboolean (* focus_out_event) (GooCanvasItem *item, GooCanvasItem *target, GdkEventFocus *event); gboolean (* key_press_event) (GooCanvasItem *item, GooCanvasItem *target, GdkEventKey *event); gboolean (* key_release_event) (GooCanvasItem *item, GooCanvasItem *target, GdkEventKey *event); gboolean (* grab_broken_event) (GooCanvasItem *item, GooCanvasItem *target, GdkEventGrabBroken *event); void (* child_notify) (GooCanvasItem *item, GParamSpec *pspec); gboolean (* query_tooltip) (GooCanvasItem *item, gdouble x, gdouble y, gboolean keyboard_tooltip, GtkTooltip *tooltip); gboolean (* get_is_static) (GooCanvasItem *item); void (* set_is_static) (GooCanvasItem *item, gboolean is_static); void (* animation_finished) (GooCanvasItem *item, gboolean stopped); gboolean (* scroll_event) (GooCanvasItem *item, GooCanvasItem *target, GdkEventScroll *event); /*< private >*/ /* Padding for future expansion */ void (*_goo_canvas_reserved1) (void); void (*_goo_canvas_reserved2) (void); void (*_goo_canvas_reserved3) (void); void (*_goo_canvas_reserved4) (void); }; GType goo_canvas_item_get_type (void) G_GNUC_CONST; /* * Group functions - these should only be called on container items. */ gint goo_canvas_item_get_n_children (GooCanvasItem *item); GooCanvasItem* goo_canvas_item_get_child (GooCanvasItem *item, gint child_num); gint goo_canvas_item_find_child (GooCanvasItem *item, GooCanvasItem *child); void goo_canvas_item_add_child (GooCanvasItem *item, GooCanvasItem *child, gint position); void goo_canvas_item_move_child (GooCanvasItem *item, gint old_position, gint new_position); void goo_canvas_item_remove_child (GooCanvasItem *item, gint child_num); void goo_canvas_item_get_child_property (GooCanvasItem *item, GooCanvasItem *child, const gchar *property_name, GValue *value); void goo_canvas_item_set_child_property (GooCanvasItem *item, GooCanvasItem *child, const gchar *property_name, const GValue *value); void goo_canvas_item_get_child_properties (GooCanvasItem *item, GooCanvasItem *child, ...) G_GNUC_NULL_TERMINATED; void goo_canvas_item_set_child_properties (GooCanvasItem *item, GooCanvasItem *child, ...) G_GNUC_NULL_TERMINATED; void goo_canvas_item_get_child_properties_valist (GooCanvasItem *item, GooCanvasItem *child, va_list var_args); void goo_canvas_item_set_child_properties_valist (GooCanvasItem *item, GooCanvasItem *child, va_list var_args); gboolean goo_canvas_item_get_transform_for_child (GooCanvasItem *item, GooCanvasItem *child, cairo_matrix_t *transform); /* * Item functions - these are safe to call on all items. */ GooCanvas* goo_canvas_item_get_canvas (GooCanvasItem *item); void goo_canvas_item_set_canvas (GooCanvasItem *item, GooCanvas *canvas); GooCanvasItem* goo_canvas_item_get_parent (GooCanvasItem *item); void goo_canvas_item_set_parent (GooCanvasItem *item, GooCanvasItem *parent); void goo_canvas_item_remove (GooCanvasItem *item); gboolean goo_canvas_item_is_container (GooCanvasItem *item); void goo_canvas_item_raise (GooCanvasItem *item, GooCanvasItem *above); void goo_canvas_item_lower (GooCanvasItem *item, GooCanvasItem *below); gboolean goo_canvas_item_get_transform (GooCanvasItem *item, cairo_matrix_t *transform); void goo_canvas_item_set_transform (GooCanvasItem *item, const cairo_matrix_t *transform); gboolean goo_canvas_item_get_simple_transform (GooCanvasItem *item, gdouble *x, gdouble *y, gdouble *scale, gdouble *rotation); void goo_canvas_item_set_simple_transform (GooCanvasItem *item, gdouble x, gdouble y, gdouble scale, gdouble rotation); void goo_canvas_item_translate (GooCanvasItem *item, gdouble tx, gdouble ty); void goo_canvas_item_scale (GooCanvasItem *item, gdouble sx, gdouble sy); void goo_canvas_item_rotate (GooCanvasItem *item, gdouble degrees, gdouble cx, gdouble cy); void goo_canvas_item_skew_x (GooCanvasItem *item, gdouble degrees, gdouble cx, gdouble cy); void goo_canvas_item_skew_y (GooCanvasItem *item, gdouble degrees, gdouble cx, gdouble cy); GooCanvasStyle* goo_canvas_item_get_style (GooCanvasItem *item); void goo_canvas_item_set_style (GooCanvasItem *item, GooCanvasStyle *style); void goo_canvas_item_animate (GooCanvasItem *item, gdouble x, gdouble y, gdouble scale, gdouble degrees, gboolean absolute, gint duration, gint step_time, GooCanvasAnimateType type); void goo_canvas_item_stop_animation (GooCanvasItem *item); void goo_canvas_item_get_bounds (GooCanvasItem *item, GooCanvasBounds *bounds); GList* goo_canvas_item_get_items_at (GooCanvasItem *item, gdouble x, gdouble y, cairo_t *cr, gboolean is_pointer_event, gboolean parent_is_visible, GList *found_items); gboolean goo_canvas_item_is_visible (GooCanvasItem *item); GooCanvasItemModel* goo_canvas_item_get_model (GooCanvasItem *item); void goo_canvas_item_set_model (GooCanvasItem *item, GooCanvasItemModel *model); void goo_canvas_item_request_update (GooCanvasItem *item); void goo_canvas_item_ensure_updated (GooCanvasItem *item); void goo_canvas_item_update (GooCanvasItem *item, gboolean entire_tree, cairo_t *cr, GooCanvasBounds *bounds); void goo_canvas_item_paint (GooCanvasItem *item, cairo_t *cr, const GooCanvasBounds *bounds, gdouble scale); gboolean goo_canvas_item_get_requested_area (GooCanvasItem *item, cairo_t *cr, GooCanvasBounds *requested_area); gdouble goo_canvas_item_get_requested_height (GooCanvasItem *item, cairo_t *cr, gdouble width); void goo_canvas_item_allocate_area (GooCanvasItem *item, cairo_t *cr, const GooCanvasBounds *requested_area, const GooCanvasBounds *allocated_area, gdouble x_offset, gdouble y_offset); gboolean goo_canvas_item_get_is_static (GooCanvasItem *item); void goo_canvas_item_set_is_static (GooCanvasItem *item, gboolean is_static); /* * Functions to support child properties when implementing new canvas items. */ void goo_canvas_item_class_install_child_property (GObjectClass *iclass, guint property_id, GParamSpec *pspec); GParamSpec* goo_canvas_item_class_find_child_property (GObjectClass *iclass, const gchar *property_name); GParamSpec** goo_canvas_item_class_list_child_properties (GObjectClass *iclass, guint *n_properties); G_END_DECLS #endif /* __GOO_CANVAS_ITEM_H__ */