1 /* 2 * GooCanvas. Copyright (C) 2005 Damon Chaplin. 3 * Released under the GNU LGPL license. See COPYING for details. 4 * 5 * goocanvasitem.h - interface for canvas items & groups. 6 */ 7 #ifndef __GOO_CANVAS_ITEM_H__ 8 #define __GOO_CANVAS_ITEM_H__ 9 10 #include <gtk/gtk.h> 11 #include "goocanvasstyle.h" 12 13 G_BEGIN_DECLS 14 15 16 /** 17 * GooCanvasAnimateType: 18 * @GOO_CANVAS_ANIMATE_FREEZE: the item remains in the final position. 19 * @GOO_CANVAS_ANIMATE_RESET: the item is moved back to the initial position. 20 * @GOO_CANVAS_ANIMATE_RESTART: the animation is restarted from the initial 21 * position. 22 * @GOO_CANVAS_ANIMATE_BOUNCE: the animation bounces back and forth between the 23 * start and end positions. 24 * 25 * #GooCanvasAnimateType is used to specify what happens when the end of an 26 * animation is reached. 27 */ 28 typedef enum 29 { 30 GOO_CANVAS_ANIMATE_FREEZE, 31 GOO_CANVAS_ANIMATE_RESET, 32 GOO_CANVAS_ANIMATE_RESTART, 33 GOO_CANVAS_ANIMATE_BOUNCE 34 } GooCanvasAnimateType; 35 36 37 /** 38 * GooCanvasBounds: 39 * @x1: the left edge. 40 * @y1: the top edge. 41 * @x2: the right edge. 42 * @y2: the bottom edge. 43 * 44 * #GooCanvasBounds represents the bounding box of an item in the canvas. 45 */ 46 typedef struct _GooCanvasBounds GooCanvasBounds; 47 struct _GooCanvasBounds 48 { 49 gdouble x1, y1, x2, y2; 50 }; 51 52 GType goo_canvas_bounds_get_type (void) G_GNUC_CONST; 53 #define GOO_TYPE_CANVAS_BOUNDS (goo_canvas_bounds_get_type ()) 54 55 56 #define GOO_TYPE_CANVAS_ITEM (goo_canvas_item_get_type ()) 57 #define GOO_CANVAS_ITEM(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), GOO_TYPE_CANVAS_ITEM, GooCanvasItem)) 58 #define GOO_IS_CANVAS_ITEM(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GOO_TYPE_CANVAS_ITEM)) 59 #define GOO_CANVAS_ITEM_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), GOO_TYPE_CANVAS_ITEM, GooCanvasItemIface)) 60 61 62 /* Workaround for circular dependencies. Include this file first. */ 63 typedef struct _GooCanvas GooCanvas; 64 typedef struct _GooCanvasItemModel GooCanvasItemModel; 65 66 67 /** 68 * GooCanvasItem: 69 * 70 * #GooCanvasItem is a typedef used for objects that implement the 71 * #GooCanvasItem interface. 72 * 73 * (There is no actual #GooCanvasItem struct, since it is only an interface. 74 * But using '#GooCanvasItem' is more helpful than using '#GObject'.) 75 */ 76 typedef struct _GooCanvasItem GooCanvasItem; 77 78 79 /** 80 * GooCanvasItemIface: 81 * @get_canvas: returns the canvas the item is in. 82 * @set_canvas: sets the canvas the item is in. 83 * @get_n_children: returns the number of children of the item. 84 * @get_child: returns the child at the given index. 85 * @request_update: requests that an update is scheduled. 86 * @add_child: adds a child. 87 * @move_child: moves a child up or down the stacking order. 88 * @remove_child: removes a child. 89 * @get_child_property: gets a child property of a given child item, 90 * e.g. the "row" or "column" property of an item in a #GooCanvasTable. 91 * @set_child_property: sets a child property for a given child item. 92 * @get_transform_for_child: gets the transform used to lay out a given child. 93 * @get_parent: gets the item's parent. 94 * @set_parent: sets the item's parent. 95 * @get_bounds: gets the bounds of the item. 96 * @get_items_at: gets all the items at the given point. 97 * @update: updates the item, if needed. It recalculates the bounds of the item 98 * and requests redraws of parts of the canvas if necessary. 99 * @paint: renders the item to the given cairo context. 100 * @get_requested_area: returns the requested area of the item, in its parent's 101 * coordinate space. This is only used for items in layout containers such as 102 * #GooCanvasTable. 103 * @get_requested_height: returns the requested height of the item, 104 * given a particular allocated width, using the parent's coordinate space. 105 * Note that this method should only be used if the position of the item 106 * remains unchanged. If the position might change use 107 * get_requested_area_for_width() instead. 108 * @get_requested_area_for_width: returns the requested bounds of the item, 109 * given a particular allocated width, using the parent's coordinate space. 110 * @allocate_area: allocates the item's area, in its parent's coordinate space. 111 * The item must recalculate its bounds and request redraws of parts of the 112 * canvas if necessary. This is only used for items in layout containers such 113 * as #GooCanvasTable. 114 * @get_transform: gets the item's transformation matrix. 115 * @set_transform: sets the item's transformation matrix. 116 * @get_style: gets the item's style. 117 * @set_style: sets the item's style. 118 * @is_visible: returns %TRUE if the item is currently visible. 119 * @get_is_static: returns %TRUE if the item is static. 120 * @set_is_static: notifies the item whether it is static or not. 121 * @get_model: gets the model that the canvas item is viewing. 122 * @set_model: sets the model that the canvas item will view. 123 * @enter_notify_event: signal emitted when the mouse enters the item. 124 * @leave_notify_event: signal emitted when the mouse leaves the item. 125 * @motion_notify_event: signal emitted when the mouse moves within the item. 126 * @button_press_event: signal emitted when a mouse button is pressed within 127 * the item. 128 * @button_release_event: signal emitted when a mouse button is released. 129 * @focus_in_event: signal emitted when the item receices the keyboard focus. 130 * @focus_out_event: signal emitted when the item loses the keyboard focus. 131 * @key_press_event: signal emitted when a key is pressed. 132 * @key_release_event: signal emitted when a key is released. 133 * @grab_broken_event: signal emitted when a grab that the item has is lost. 134 * @child_notify: signal emitted when a child property is changed. 135 * @query_tooltip: signal emitted to query the tooltip of an item. 136 * @animation_finished: signal emitted when the item's animation has finished. 137 * @scroll_event: signal emitted when the mouse wheel is activated within 138 * the item. 139 * 140 * #GooCanvasItemIFace holds the virtual methods that make up the 141 * #GooCanvasItem interface. 142 * 143 * Simple canvas items only need to implement the get_parent(), set_parent(), 144 * get_bounds(), get_items_at(), update() and paint() methods (and also 145 * get_requested_area() and allocate_area() if they are going to be used 146 * inside a layout container like #GooCanvasTable). 147 * 148 * Items that support transforms should also implement get_transform() and 149 * set_transform(). Items that support styles should implement get_style() 150 * and set_style(). 151 * 152 * Container items must implement get_canvas(), set_canvas(), 153 * get_n_children(), get_child() and request_update(). Containers that support 154 * dynamic changes to their children should implement add_child(), 155 * move_child() and remove_child(). Layout containers like #GooCanvasTable 156 * may implement get_child_property(), set_child_property() and 157 * get_transform_for_child(). 158 */ 159 typedef struct _GooCanvasItemIface GooCanvasItemIface; 160 161 struct _GooCanvasItemIface 162 { 163 /*< private >*/ 164 GTypeInterface base_iface; 165 166 /*< public >*/ 167 /* Virtual methods that group items must implement. */ 168 GooCanvas* (* get_canvas) (GooCanvasItem *item); 169 void (* set_canvas) (GooCanvasItem *item, 170 GooCanvas *canvas); 171 gint (* get_n_children) (GooCanvasItem *item); 172 GooCanvasItem* (* get_child) (GooCanvasItem *item, 173 gint child_num); 174 void (* request_update) (GooCanvasItem *item); 175 176 /* Virtual methods that group items may implement. */ 177 void (* add_child) (GooCanvasItem *item, 178 GooCanvasItem *child, 179 gint position); 180 void (* move_child) (GooCanvasItem *item, 181 gint old_position, 182 gint new_position); 183 void (* remove_child) (GooCanvasItem *item, 184 gint child_num); 185 void (* get_child_property) (GooCanvasItem *item, 186 GooCanvasItem *child, 187 guint property_id, 188 GValue *value, 189 GParamSpec *pspec); 190 void (* set_child_property) (GooCanvasItem *item, 191 GooCanvasItem *child, 192 guint property_id, 193 const GValue *value, 194 GParamSpec *pspec); 195 gboolean (* get_transform_for_child) (GooCanvasItem *item, 196 GooCanvasItem *child, 197 cairo_matrix_t *transform); 198 199 /* Virtual methods that all canvas items must implement. */ 200 GooCanvasItem* (* get_parent) (GooCanvasItem *item); 201 void (* set_parent) (GooCanvasItem *item, 202 GooCanvasItem *parent); 203 void (* get_bounds) (GooCanvasItem *item, 204 GooCanvasBounds *bounds); 205 GList* (* get_items_at) (GooCanvasItem *item, 206 gdouble x, 207 gdouble y, 208 cairo_t *cr, 209 gboolean is_pointer_event, 210 gboolean parent_is_visible, 211 GList *found_items); 212 void (* update) (GooCanvasItem *item, 213 gboolean entire_tree, 214 cairo_t *cr, 215 GooCanvasBounds *bounds); 216 void (* paint) (GooCanvasItem *item, 217 cairo_t *cr, 218 const GooCanvasBounds *bounds, 219 gdouble scale); 220 221 gboolean (* get_requested_area) (GooCanvasItem *item, 222 cairo_t *cr, 223 GooCanvasBounds *requested_area); 224 void (* allocate_area) (GooCanvasItem *item, 225 cairo_t *cr, 226 const GooCanvasBounds *requested_area, 227 const GooCanvasBounds *allocated_area, 228 gdouble x_offset, 229 gdouble y_offset); 230 231 /* Virtual methods that canvas items may implement. */ 232 gboolean (* get_transform) (GooCanvasItem *item, 233 cairo_matrix_t *transform); 234 void (* set_transform) (GooCanvasItem *item, 235 const cairo_matrix_t *transform); 236 GooCanvasStyle* (* get_style) (GooCanvasItem *item); 237 void (* set_style) (GooCanvasItem *item, 238 GooCanvasStyle *style); 239 gboolean (* is_visible) (GooCanvasItem *item); 240 gdouble (* get_requested_height) (GooCanvasItem *item, 241 cairo_t *cr, 242 gdouble width); 243 244 /* Virtual methods that model/view items must implement. */ 245 GooCanvasItemModel* (* get_model) (GooCanvasItem *item); 246 void (* set_model) (GooCanvasItem *item, 247 GooCanvasItemModel *model); 248 249 250 /* Signals. */ 251 gboolean (* enter_notify_event) (GooCanvasItem *item, 252 GooCanvasItem *target, 253 GdkEventCrossing *event); 254 gboolean (* leave_notify_event) (GooCanvasItem *item, 255 GooCanvasItem *target, 256 GdkEventCrossing *event); 257 gboolean (* motion_notify_event) (GooCanvasItem *item, 258 GooCanvasItem *target, 259 GdkEventMotion *event); 260 gboolean (* button_press_event) (GooCanvasItem *item, 261 GooCanvasItem *target, 262 GdkEventButton *event); 263 gboolean (* button_release_event) (GooCanvasItem *item, 264 GooCanvasItem *target, 265 GdkEventButton *event); 266 gboolean (* focus_in_event) (GooCanvasItem *item, 267 GooCanvasItem *target, 268 GdkEventFocus *event); 269 gboolean (* focus_out_event) (GooCanvasItem *item, 270 GooCanvasItem *target, 271 GdkEventFocus *event); 272 gboolean (* key_press_event) (GooCanvasItem *item, 273 GooCanvasItem *target, 274 GdkEventKey *event); 275 gboolean (* key_release_event) (GooCanvasItem *item, 276 GooCanvasItem *target, 277 GdkEventKey *event); 278 gboolean (* grab_broken_event) (GooCanvasItem *item, 279 GooCanvasItem *target, 280 GdkEventGrabBroken *event); 281 void (* child_notify) (GooCanvasItem *item, 282 GParamSpec *pspec); 283 gboolean (* query_tooltip) (GooCanvasItem *item, 284 gdouble x, 285 gdouble y, 286 gboolean keyboard_tooltip, 287 GtkTooltip *tooltip); 288 289 gboolean (* get_is_static) (GooCanvasItem *item); 290 void (* set_is_static) (GooCanvasItem *item, 291 gboolean is_static); 292 293 void (* animation_finished) (GooCanvasItem *item, 294 gboolean stopped); 295 296 gboolean (* scroll_event) (GooCanvasItem *item, 297 GooCanvasItem *target, 298 GdkEventScroll *event); 299 300 gboolean (* get_requested_area_for_width)(GooCanvasItem *item, 301 cairo_t *cr, 302 gdouble width, 303 GooCanvasBounds *requested_area); 304 305 /*< private >*/ 306 307 /* Padding for future expansion */ 308 void (*_goo_canvas_reserved1) (void); 309 void (*_goo_canvas_reserved2) (void); 310 void (*_goo_canvas_reserved3) (void); 311 }; 312 313 314 GType goo_canvas_item_get_type (void) G_GNUC_CONST; 315 316 317 /* 318 * Group functions - these should only be called on container items. 319 */ 320 gint goo_canvas_item_get_n_children (GooCanvasItem *item); 321 GooCanvasItem* goo_canvas_item_get_child (GooCanvasItem *item, 322 gint child_num); 323 gint goo_canvas_item_find_child (GooCanvasItem *item, 324 GooCanvasItem *child); 325 void goo_canvas_item_add_child (GooCanvasItem *item, 326 GooCanvasItem *child, 327 gint position); 328 void goo_canvas_item_move_child (GooCanvasItem *item, 329 gint old_position, 330 gint new_position); 331 void goo_canvas_item_remove_child (GooCanvasItem *item, 332 gint child_num); 333 334 void goo_canvas_item_get_child_property (GooCanvasItem *item, 335 GooCanvasItem *child, 336 const gchar *property_name, 337 GValue *value); 338 void goo_canvas_item_set_child_property (GooCanvasItem *item, 339 GooCanvasItem *child, 340 const gchar *property_name, 341 const GValue *value); 342 void goo_canvas_item_get_child_properties (GooCanvasItem *item, 343 GooCanvasItem *child, 344 ...) G_GNUC_NULL_TERMINATED; 345 void goo_canvas_item_set_child_properties (GooCanvasItem *item, 346 GooCanvasItem *child, 347 ...) G_GNUC_NULL_TERMINATED; 348 void goo_canvas_item_get_child_properties_valist (GooCanvasItem *item, 349 GooCanvasItem *child, 350 va_list var_args); 351 void goo_canvas_item_set_child_properties_valist (GooCanvasItem *item, 352 GooCanvasItem *child, 353 va_list var_args); 354 355 gboolean goo_canvas_item_get_transform_for_child (GooCanvasItem *item, 356 GooCanvasItem *child, 357 cairo_matrix_t *transform); 358 359 360 /* 361 * Item functions - these are safe to call on all items. 362 */ 363 GooCanvas* goo_canvas_item_get_canvas (GooCanvasItem *item); 364 void goo_canvas_item_set_canvas (GooCanvasItem *item, 365 GooCanvas *canvas); 366 GooCanvasItem* goo_canvas_item_get_parent (GooCanvasItem *item); 367 void goo_canvas_item_set_parent (GooCanvasItem *item, 368 GooCanvasItem *parent); 369 void goo_canvas_item_remove (GooCanvasItem *item); 370 gboolean goo_canvas_item_is_container (GooCanvasItem *item); 371 372 void goo_canvas_item_raise (GooCanvasItem *item, 373 GooCanvasItem *above); 374 void goo_canvas_item_lower (GooCanvasItem *item, 375 GooCanvasItem *below); 376 377 gboolean goo_canvas_item_get_transform (GooCanvasItem *item, 378 cairo_matrix_t *transform); 379 void goo_canvas_item_set_transform (GooCanvasItem *item, 380 const cairo_matrix_t *transform); 381 gboolean goo_canvas_item_get_simple_transform (GooCanvasItem *item, 382 gdouble *x, 383 gdouble *y, 384 gdouble *scale, 385 gdouble *rotation); 386 void goo_canvas_item_set_simple_transform (GooCanvasItem *item, 387 gdouble x, 388 gdouble y, 389 gdouble scale, 390 gdouble rotation); 391 392 void goo_canvas_item_translate (GooCanvasItem *item, 393 gdouble tx, 394 gdouble ty); 395 void goo_canvas_item_scale (GooCanvasItem *item, 396 gdouble sx, 397 gdouble sy); 398 void goo_canvas_item_rotate (GooCanvasItem *item, 399 gdouble degrees, 400 gdouble cx, 401 gdouble cy); 402 void goo_canvas_item_skew_x (GooCanvasItem *item, 403 gdouble degrees, 404 gdouble cx, 405 gdouble cy); 406 void goo_canvas_item_skew_y (GooCanvasItem *item, 407 gdouble degrees, 408 gdouble cx, 409 gdouble cy); 410 411 GooCanvasStyle* goo_canvas_item_get_style (GooCanvasItem *item); 412 void goo_canvas_item_set_style (GooCanvasItem *item, 413 GooCanvasStyle *style); 414 415 void goo_canvas_item_animate (GooCanvasItem *item, 416 gdouble x, 417 gdouble y, 418 gdouble scale, 419 gdouble degrees, 420 gboolean absolute, 421 gint duration, 422 gint step_time, 423 GooCanvasAnimateType type); 424 void goo_canvas_item_stop_animation (GooCanvasItem *item); 425 426 427 428 void goo_canvas_item_get_bounds (GooCanvasItem *item, 429 GooCanvasBounds *bounds); 430 GList* goo_canvas_item_get_items_at (GooCanvasItem *item, 431 gdouble x, 432 gdouble y, 433 cairo_t *cr, 434 gboolean is_pointer_event, 435 gboolean parent_is_visible, 436 GList *found_items); 437 gboolean goo_canvas_item_is_visible (GooCanvasItem *item); 438 439 GooCanvasItemModel* goo_canvas_item_get_model (GooCanvasItem *item); 440 void goo_canvas_item_set_model (GooCanvasItem *item, 441 GooCanvasItemModel *model); 442 443 void goo_canvas_item_request_update (GooCanvasItem *item); 444 void goo_canvas_item_ensure_updated (GooCanvasItem *item); 445 void goo_canvas_item_update (GooCanvasItem *item, 446 gboolean entire_tree, 447 cairo_t *cr, 448 GooCanvasBounds *bounds); 449 void goo_canvas_item_paint (GooCanvasItem *item, 450 cairo_t *cr, 451 const GooCanvasBounds *bounds, 452 gdouble scale); 453 454 gboolean goo_canvas_item_get_requested_area (GooCanvasItem *item, 455 cairo_t *cr, 456 GooCanvasBounds *requested_area); 457 gboolean goo_canvas_item_get_requested_area_for_width (GooCanvasItem *item, 458 cairo_t *cr, 459 gdouble width, 460 GooCanvasBounds *requested_area); 461 gdouble goo_canvas_item_get_requested_height (GooCanvasItem *item, 462 cairo_t *cr, 463 gdouble width); 464 void goo_canvas_item_allocate_area (GooCanvasItem *item, 465 cairo_t *cr, 466 const GooCanvasBounds *requested_area, 467 const GooCanvasBounds *allocated_area, 468 gdouble x_offset, 469 gdouble y_offset); 470 471 gboolean goo_canvas_item_get_is_static (GooCanvasItem *item); 472 void goo_canvas_item_set_is_static (GooCanvasItem *item, 473 gboolean is_static); 474 475 476 /* 477 * Functions to support child properties when implementing new canvas items. 478 */ 479 void goo_canvas_item_class_install_child_property (GObjectClass *iclass, 480 guint property_id, 481 GParamSpec *pspec); 482 GParamSpec* goo_canvas_item_class_find_child_property (GObjectClass *iclass, 483 const gchar *property_name); 484 GParamSpec** goo_canvas_item_class_list_child_properties (GObjectClass *iclass, 485 guint *n_properties); 486 487 488 489 490 G_END_DECLS 491 492 #endif /* __GOO_CANVAS_ITEM_H__ */ 493