GooCanvas

GooCanvas — the main canvas widget.

Synopsis

                    GooCanvas;
                    GooCanvasClass;

GtkWidget*          goo_canvas_new                      (void);

GooCanvasItem*      goo_canvas_get_root_item            (GooCanvas *canvas);
void                goo_canvas_set_root_item            (GooCanvas *canvas,
                                                         GooCanvasItem *item);
GooCanvasItemModel* goo_canvas_get_root_item_model      (GooCanvas *canvas);
void                goo_canvas_set_root_item_model      (GooCanvas *canvas,
                                                         GooCanvasItemModel *model);

GooCanvasItem*      goo_canvas_get_static_root_item     (GooCanvas *canvas);
void                goo_canvas_set_static_root_item     (GooCanvas *canvas,
                                                         GooCanvasItem *item);
GooCanvasItemModel* goo_canvas_get_static_root_item_model
                                                        (GooCanvas *canvas);
void                goo_canvas_set_static_root_item_model
                                                        (GooCanvas *canvas,
                                                         GooCanvasItemModel *model);

void                goo_canvas_get_bounds               (GooCanvas *canvas,
                                                         gdouble *left,
                                                         gdouble *top,
                                                         gdouble *right,
                                                         gdouble *bottom);
void                goo_canvas_set_bounds               (GooCanvas *canvas,
                                                         gdouble left,
                                                         gdouble top,
                                                         gdouble right,
                                                         gdouble bottom);
gdouble             goo_canvas_get_scale                (GooCanvas *canvas);
void                goo_canvas_set_scale                (GooCanvas *canvas,
                                                         gdouble scale);

GooCanvasItem*      goo_canvas_get_item                 (GooCanvas *canvas,
                                                         GooCanvasItemModel *model);
GooCanvasItem*      goo_canvas_get_item_at              (GooCanvas *canvas,
                                                         gdouble x,
                                                         gdouble y,
                                                         gboolean is_pointer_event);
GList*              goo_canvas_get_items_at             (GooCanvas *canvas,
                                                         gdouble x,
                                                         gdouble y,
                                                         gboolean is_pointer_event);
GList*              goo_canvas_get_items_in_area        (GooCanvas *canvas,
                                                         const GooCanvasBounds *area,
                                                         gboolean inside_area,
                                                         gboolean allow_overlaps,
                                                         gboolean include_containers);

void                goo_canvas_scroll_to                (GooCanvas *canvas,
                                                         gdouble left,
                                                         gdouble top);
void                goo_canvas_render                   (GooCanvas *canvas,
                                                         cairo_t *cr,
                                                         const GooCanvasBounds *bounds,
                                                         gdouble scale);

void                goo_canvas_convert_to_pixels        (GooCanvas *canvas,
                                                         gdouble *x,
                                                         gdouble *y);
void                goo_canvas_convert_from_pixels      (GooCanvas *canvas,
                                                         gdouble *x,
                                                         gdouble *y);
void                goo_canvas_convert_to_item_space    (GooCanvas *canvas,
                                                         GooCanvasItem *item,
                                                         gdouble *x,
                                                         gdouble *y);
void                goo_canvas_convert_from_item_space  (GooCanvas *canvas,
                                                         GooCanvasItem *item,
                                                         gdouble *x,
                                                         gdouble *y);
void                goo_canvas_convert_bounds_to_item_space
                                                        (GooCanvas *canvas,
                                                         GooCanvasItem *item,
                                                         GooCanvasBounds *bounds);

GdkGrabStatus       goo_canvas_pointer_grab             (GooCanvas *canvas,
                                                         GooCanvasItem *item,
                                                         GdkEventMask event_mask,
                                                         GdkCursor *cursor,
                                                         guint32 time);
void                goo_canvas_pointer_ungrab           (GooCanvas *canvas,
                                                         GooCanvasItem *item,
                                                         guint32 time);

void                goo_canvas_grab_focus               (GooCanvas *canvas,
                                                         GooCanvasItem *item);
GdkGrabStatus       goo_canvas_keyboard_grab            (GooCanvas *canvas,
                                                         GooCanvasItem *item,
                                                         gboolean owner_events,
                                                         guint32 time);
void                goo_canvas_keyboard_ungrab          (GooCanvas *canvas,
                                                         GooCanvasItem *item,
                                                         guint32 time);

cairo_t*            goo_canvas_create_cairo_context     (GooCanvas *canvas);
GooCanvasItem*      goo_canvas_create_item              (GooCanvas *canvas,
                                                         GooCanvasItemModel *model);
void                goo_canvas_unregister_item          (GooCanvas *canvas,
                                                         GooCanvasItemModel *model);
void                goo_canvas_register_widget_item     (GooCanvas *canvas,
                                                         GooCanvasWidget *witem);
void                goo_canvas_unregister_widget_item   (GooCanvas *canvas,
                                                         GooCanvasWidget *witem);
void                goo_canvas_update                   (GooCanvas *canvas);
void                goo_canvas_request_update           (GooCanvas *canvas);
void                goo_canvas_request_redraw           (GooCanvas *canvas,
                                                         const GooCanvasBounds *bounds);
void                goo_canvas_request_item_redraw      (GooCanvas *canvas,
                                                         const GooCanvasBounds *bounds,
                                                         gboolean is_static);
gdouble             goo_canvas_get_default_line_width   (GooCanvas *canvas);

Object Hierarchy

  GObject
   +----GInitiallyUnowned
         +----GtkObject
               +----GtkWidget
                     +----GtkContainer
                           +----GooCanvas

Implemented Interfaces

GooCanvas implements AtkImplementorIface and GtkBuildable.

Properties

  "anchor"                   GtkAnchorType         : Read / Write
  "automatic-bounds"         gboolean              : Read / Write
  "background-color"         gchar*                : Write
  "background-color-rgb"     guint                 : Write
  "bounds-from-origin"       gboolean              : Read / Write
  "bounds-padding"           gdouble               : Read / Write
  "clear-background"         gboolean              : Read / Write
  "integer-layout"           gboolean              : Read / Write
  "redraw-when-scrolled"     gboolean              : Read / Write
  "resolution-x"             gdouble               : Read / Write
  "resolution-y"             gdouble               : Read / Write
  "scale"                    gdouble               : Read / Write
  "scale-x"                  gdouble               : Read / Write
  "scale-y"                  gdouble               : Read / Write
  "units"                    GtkUnit               : Read / Write
  "x1"                       gdouble               : Read / Write
  "x2"                       gdouble               : Read / Write
  "y1"                       gdouble               : Read / Write
  "y2"                       gdouble               : Read / Write

Signals

  "item-created"                                   : Run Last
  "set-scroll-adjustments"                         : Run Last / Action

Description

GooCanvas is the main widget containing a number of canvas items.

Here is a simple example: 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
 
#include <goocanvas.h>

static gboolean on_rect_button_press (GooCanvasItem  *view,
                                      GooCanvasItem  *target,
                                      GdkEventButton *event,
                                      gpointer        data);

int
main (int argc, char *argv[])
{
  GtkWidget *window, *scrolled_win, *canvas;
  GooCanvasItem *root, *rect_item, *text_item;

  /* Initialize GTK+. */
  gtk_set_locale ();
  gtk_init (&argc, &argv);

  /* Create the window and widgets. */
  window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
  gtk_window_set_default_size (GTK_WINDOW (window), 640, 600);
  gtk_widget_show (window);
  g_signal_connect (window, "delete_event", (GtkSignalFunc) on_delete_event,
                    NULL);

  scrolled_win = gtk_scrolled_window_new (NULL, NULL);
  gtk_scrolled_window_set_shadow_type (GTK_SCROLLED_WINDOW (scrolled_win),
                                       GTK_SHADOW_IN);
  gtk_widget_show (scrolled_win);
  gtk_container_add (GTK_CONTAINER (window), scrolled_win);

  canvas = goo_canvas_new ();
  gtk_widget_set_size_request (canvas, 600, 450);
  goo_canvas_set_bounds (GOO_CANVAS (canvas), 0, 0, 1000, 1000);
  gtk_widget_show (canvas);
  gtk_container_add (GTK_CONTAINER (scrolled_win), canvas);

  root = goo_canvas_get_root_item (GOO_CANVAS (canvas));

  /* Add a few simple items. */
  rect_item = goo_canvas_rect_new (root, 100, 100, 400, 400,
                                   "line-width", 10.0,
                                   "radius-x", 20.0,
                                   "radius-y", 10.0,
                                   "stroke-color", "yellow",
                                   "fill-color", "red",
                                   NULL);

  text_item = goo_canvas_text_new (root, "Hello World", 300, 300, -1,
                                   GTK_ANCHOR_CENTER,
                                   "font", "Sans 24",
                                   NULL);
  goo_canvas_item_rotate (text_item, 45, 300, 300);

  /* Connect a signal handler for the rectangle item. */
  g_signal_connect (rect_item, "button_press_event",
                    (GtkSignalFunc) on_rect_button_press, NULL);

  /* Pass control to the GTK+ main event loop. */
  gtk_main ();

  return 0;
}


/* This handles button presses in item views. We simply output a message to
   the console. */
static gboolean
on_rect_button_press (GooCanvasItem  *item,
                      GooCanvasItem  *target,
                      GdkEventButton *event,
                      gpointer        data)
{
  g_print ("rect item received button press event\n");
  return TRUE;
}

Details

GooCanvas

typedef struct _GooCanvas GooCanvas;

The GooCanvas struct contains private data only.

GooCanvasClass

typedef struct {
  GooCanvasItem* (* create_item)	    (GooCanvas          *canvas,
					     GooCanvasItemModel *model);

  /* Signals. */
  void           (* item_created)	    (GooCanvas          *canvas,
					     GooCanvasItem      *item,
					     GooCanvasItemModel *model);
} GooCanvasClass;

The GooCanvasClass struct contains one virtual method that subclasses may override.

create_item ()

 a virtual method that subclasses may override to create custom canvas items for item models.

item_created ()

 signal emitted when a new canvas item has been created. Applications can connect to this to setup signal handlers for the new item.

goo_canvas_new ()

GtkWidget*          goo_canvas_new                      (void);

Creates a new GooCanvas widget.

A GooCanvasGroup is created automatically as the root item of the canvas, though this can be overriden with goo_canvas_set_root_item() or goo_canvas_set_root_item_model().

Returns :

 a new GooCanvas widget.

goo_canvas_get_root_item ()

GooCanvasItem*      goo_canvas_get_root_item            (GooCanvas *canvas);

Gets the root item of the canvas, usually a GooCanvasGroup.

canvas :

 a GooCanvas.

Returns :

 the root item, or NULL if there is no root item.

goo_canvas_set_root_item ()

void                goo_canvas_set_root_item            (GooCanvas *canvas,
                                                         GooCanvasItem *item);

Sets the root item of the canvas. Any existing canvas items are removed.

canvas :

 a GooCanvas.

item :

 the root canvas item.

goo_canvas_get_root_item_model ()

GooCanvasItemModel* goo_canvas_get_root_item_model      (GooCanvas *canvas);

Gets the root item model of the canvas.

canvas :

 a GooCanvas.

Returns :

 the root item model, or NULL if there is no root item model.

goo_canvas_set_root_item_model ()

void                goo_canvas_set_root_item_model      (GooCanvas *canvas,
                                                         GooCanvasItemModel *model);

Sets the root item model of the canvas.

A hierarchy of canvas items will be created, corresponding to the hierarchy of items in the model. Any current canvas items will be removed.

canvas :

 a GooCanvas.

model :

 a GooCanvasItemModel.

goo_canvas_get_static_root_item ()

GooCanvasItem*      goo_canvas_get_static_root_item     (GooCanvas *canvas);

Gets the static root item of the canvas.

Static items are exactly the same as ordinary canvas items, except that they do not move or change size when the canvas is scrolled or the scale changes.

Static items are added to the static root item in exactly the same way that ordinary items are added to the root item.

canvas :

 a GooCanvas.

Returns :

 the static root item, or NULL.

goo_canvas_set_static_root_item ()

void                goo_canvas_set_static_root_item     (GooCanvas *canvas,
                                                         GooCanvasItem *item);

Sets the static root item. Any existing static items are removed.

Static items are exactly the same as ordinary canvas items, except that they do not move or change size when the canvas is scrolled or the scale changes.

Static items are added to the static root item in exactly the same way that ordinary items are added to the root item.

canvas :

 a GooCanvas.

item :

 the static root item.

goo_canvas_get_static_root_item_model ()

GooCanvasItemModel* goo_canvas_get_static_root_item_model
                                                        (GooCanvas *canvas);

Gets the static root item model of the canvas.

Static item models are exactly the same as ordinary item models, except that the corresponding items do not move or change size when the canvas is scrolled or the scale changes.

Static items models are added to the static root item model in exactly the same way that ordinary item models are added to the root item model.

canvas :

 a GooCanvas.

Returns :

 the static root item model, or NULL.

goo_canvas_set_static_root_item_model ()

void                goo_canvas_set_static_root_item_model
                                                        (GooCanvas *canvas,
                                                         GooCanvasItemModel *model);

Sets the static root item model. Any existing static item models are removed.

Static item models are exactly the same as ordinary item models, except that the corresponding items do not move or change size when the canvas is scrolled or the scale changes.

Static items models are added to the static root item model in exactly the same way that ordinary item models are added to the root item model.

canvas :

 a GooCanvas.

model :

 the static root item model.

goo_canvas_get_bounds ()

void                goo_canvas_get_bounds               (GooCanvas *canvas,
                                                         gdouble *left,
                                                         gdouble *top,
                                                         gdouble *right,
                                                         gdouble *bottom);

Gets the bounds of the canvas, in canvas units.

By default, canvas units are pixels, though the "units" property can be used to change the units to points, inches or millimeters.

canvas :

 a GooCanvas.

left :

 a pointer to a gdouble to return the left edge, or NULL.

top :

 a pointer to a gdouble to return the top edge, or NULL.

right :

 a pointer to a gdouble to return the right edge, or NULL.

bottom :

 a pointer to a gdouble to return the bottom edge, or NULL.

goo_canvas_set_bounds ()

void                goo_canvas_set_bounds               (GooCanvas *canvas,
                                                         gdouble left,
                                                         gdouble top,
                                                         gdouble right,
                                                         gdouble bottom);

Sets the bounds of the GooCanvas, in canvas units.

By default, canvas units are pixels, though the "units" property can be used to change the units to points, inches or millimeters.

canvas :

 a GooCanvas.

left :

 the left edge.

top :

 the top edge.

right :

 the right edge.

bottom :

 the bottom edge.

goo_canvas_get_scale ()

gdouble             goo_canvas_get_scale                (GooCanvas *canvas);

Gets the current scale of the canvas.

The scale specifies the magnification factor of the canvas, e.g. if an item has a width of 2 pixels and the scale is set to 3, it will be displayed with a width of 2 x 3 = 6 pixels.

canvas :

 a GooCanvas.

Returns :

 the current scale setting.

goo_canvas_set_scale ()

void                goo_canvas_set_scale                (GooCanvas *canvas,
                                                         gdouble scale);

Sets the scale of the canvas.

The scale specifies the magnification factor of the canvas, e.g. if an item has a width of 2 pixels and the scale is set to 3, it will be displayed with a width of 2 x 3 = 6 pixels.

canvas :

 a GooCanvas.

scale :

 the new scale setting.

goo_canvas_get_item ()

GooCanvasItem*      goo_canvas_get_item                 (GooCanvas *canvas,
                                                         GooCanvasItemModel *model);

Gets the canvas item associated with the given GooCanvasItemModel. This is only useful when goo_canvas_set_root_item_model() has been used to set a model for the canvas.

For simple applications you can use goo_canvas_get_item() to set up signal handlers for your items, e.g. 

1
2
3
 
item = goo_canvas_get_item (GOO_CANVAS (canvas), my_item);
g_signal_connect (item, "button_press_event",
                  (GtkSignalFunc) on_my_item_button_press, NULL);

More complex applications may want to use the "item-created" signal to hook up their signal handlers.

canvas :

 a GooCanvas.

model :

 a GooCanvasItemModel.

Returns :

 the canvas item corresponding to the given GooCanvasItemModel, or NULL if no canvas item has been created for it yet.

goo_canvas_get_item_at ()

GooCanvasItem*      goo_canvas_get_item_at              (GooCanvas *canvas,
                                                         gdouble x,
                                                         gdouble y,
                                                         gboolean is_pointer_event);

Gets the item at the given point.

canvas :

 a GooCanvas.

x :

 the x coordinate of the point.

y :

 the y coordinate of the point

is_pointer_event :

 TRUE if the "pointer-events" property of items should be used to determine which parts of the item are tested.

Returns :

 the item found at the given point, or NULL if no item was found.

goo_canvas_get_items_at ()

GList*              goo_canvas_get_items_at             (GooCanvas *canvas,
                                                         gdouble x,
                                                         gdouble y,
                                                         gboolean is_pointer_event);

Gets all items at the given point.

canvas :

 a GooCanvas.

x :

 the x coordinate of the point.

y :

 the y coordinate of the point

is_pointer_event :

 TRUE if the "pointer-events" property of items should be used to determine which parts of the item are tested.

Returns :

 a list of items found at the given point, with the top item at the start of the list, or NULL if no items were found. The list must be freed with g_list_free().

goo_canvas_get_items_in_area ()

GList*              goo_canvas_get_items_in_area        (GooCanvas *canvas,
                                                         const GooCanvasBounds *area,
                                                         gboolean inside_area,
                                                         gboolean allow_overlaps,
                                                         gboolean include_containers);

Gets a list of items inside or outside a given area.

canvas :

 a GooCanvas.

area :

 the area to compare with each item's bounds.

inside_area :

 TRUE if items inside area should be returned, or FALSE if items outside area should be returned.

allow_overlaps :

 TRUE if items which are partly inside and partly outside should be returned.

include_containers :

 TRUE if containers should be checked as well as normal items.

Returns :

 a list of items in the given area, or NULL if no items are found. The list should be freed with g_list_free().

goo_canvas_scroll_to ()

void                goo_canvas_scroll_to                (GooCanvas *canvas,
                                                         gdouble left,
                                                         gdouble top);

Scrolls the canvas, placing the given point as close to the top-left of the view as possible.

canvas :

 a GooCanvas.

left :

 the x coordinate to scroll to.

top :

 the y coordinate to scroll to.

goo_canvas_render ()

void                goo_canvas_render                   (GooCanvas *canvas,
                                                         cairo_t *cr,
                                                         const GooCanvasBounds *bounds,
                                                         gdouble scale);

Renders all or part of a canvas to the given cairo context.

canvas :

 a GooCanvas.

cr :

 a cairo context.

bounds :

 the area to render, or NULL to render the entire canvas.

scale :

 the scale to compare with each item's visibility threshold to see if they should be rendered. This only affects items that have their visibility set to GOO_CANVAS_ITEM_VISIBLE_ABOVE_THRESHOLD.

goo_canvas_convert_to_pixels ()

void                goo_canvas_convert_to_pixels        (GooCanvas *canvas,
                                                         gdouble *x,
                                                         gdouble *y);

Converts a coordinate from the canvas coordinate space to pixels.

The canvas coordinate space is specified in the call to goo_canvas_set_bounds().

The pixel coordinate space specifies pixels from the top-left of the entire canvas window, according to the current scale setting. See goo_canvas_set_scale().

canvas :

 a GooCanvas.

x :

 a pointer to the x coordinate to convert.

y :

 a pointer to the y coordinate to convert.

goo_canvas_convert_from_pixels ()

void                goo_canvas_convert_from_pixels      (GooCanvas *canvas,
                                                         gdouble *x,
                                                         gdouble *y);

Converts a coordinate from pixels to the canvas coordinate space.

The pixel coordinate space specifies pixels from the top-left of the entire canvas window, according to the current scale setting. See goo_canvas_set_scale().

The canvas coordinate space is specified in the call to goo_canvas_set_bounds().

canvas :

 a GooCanvas.

x :

 a pointer to the x coordinate to convert.

y :

 a pointer to the y coordinate to convert.

goo_canvas_convert_to_item_space ()

void                goo_canvas_convert_to_item_space    (GooCanvas *canvas,
                                                         GooCanvasItem *item,
                                                         gdouble *x,
                                                         gdouble *y);

Converts a coordinate from the canvas coordinate space to the given item's coordinate space, applying all transformation matrices including the item's own transformation matrix, if it has one.

canvas :

 a GooCanvas.

item :

 a GooCanvasItem.

x :

 a pointer to the x coordinate to convert.

y :

 a pointer to the y coordinate to convert.

goo_canvas_convert_from_item_space ()

void                goo_canvas_convert_from_item_space  (GooCanvas *canvas,
                                                         GooCanvasItem *item,
                                                         gdouble *x,
                                                         gdouble *y);

Converts a coordinate from the given item's coordinate space to the canvas coordinate space, applying all transformation matrices including the item's own transformation matrix, if it has one.

canvas :

 a GooCanvas.

item :

 a GooCanvasItem.

x :

 a pointer to the x coordinate to convert.

y :

 a pointer to the y coordinate to convert.

goo_canvas_convert_bounds_to_item_space ()

void                goo_canvas_convert_bounds_to_item_space
                                                        (GooCanvas *canvas,
                                                         GooCanvasItem *item,
                                                         GooCanvasBounds *bounds);

Converts the given bounds in the canvas coordinate space to a bounding box in item space. This is useful in the item paint() methods to convert the bounds to be painted to the item's coordinate space.

canvas :

 a GooCanvas.

item :

 a GooCanvasItem.

bounds :

 the bounds in canvas coordinate space, to be converted.

goo_canvas_pointer_grab ()

GdkGrabStatus       goo_canvas_pointer_grab             (GooCanvas *canvas,
                                                         GooCanvasItem *item,
                                                         GdkEventMask event_mask,
                                                         GdkCursor *cursor,
                                                         guint32 time);

Attempts to grab the pointer for the given item.

canvas :

 a GooCanvas.

item :

 the item to grab the pointer for.

event_mask :

 the events to receive during the grab.

cursor :

 the cursor to display during the grab, or NULL.

time :

 the time of the event that lead to the pointer grab. This should come from the relevant GdkEvent.

Returns :

 GDK_GRAB_SUCCESS if the grab succeeded.

goo_canvas_pointer_ungrab ()

void                goo_canvas_pointer_ungrab           (GooCanvas *canvas,
                                                         GooCanvasItem *item,
                                                         guint32 time);

Ungrabs the pointer, if the given item has the pointer grab.

canvas :

 a GooCanvas.

item :

 the item that has the grab.

time :

 the time of the event that lead to the pointer ungrab. This should come from the relevant GdkEvent.

goo_canvas_grab_focus ()

void                goo_canvas_grab_focus               (GooCanvas *canvas,
                                                         GooCanvasItem *item);

Grabs the keyboard focus for the given item.

canvas :

 a GooCanvas.

item :

 the item to grab the focus.

goo_canvas_keyboard_grab ()

GdkGrabStatus       goo_canvas_keyboard_grab            (GooCanvas *canvas,
                                                         GooCanvasItem *item,
                                                         gboolean owner_events,
                                                         guint32 time);

Attempts to grab the keyboard for the given item.

canvas :

 a GooCanvas.

item :

 the item to grab the keyboard for.

owner_events :

 TRUE if keyboard events for this application will be reported normally, or FALSE if all keyboard events will be reported with respect to the grab item.

time :

 the time of the event that lead to the keyboard grab. This should come from the relevant GdkEvent.

Returns :

 GDK_GRAB_SUCCESS if the grab succeeded.

goo_canvas_keyboard_ungrab ()

void                goo_canvas_keyboard_ungrab          (GooCanvas *canvas,
                                                         GooCanvasItem *item,