GooCanvas: GooCanvas Reference Manual

## GooCanvas GooCanvas — the main canvas widget. |

## Functions

GtkWidget * | goo_canvas_new ()
GooCanvasItem * | goo_canvas_get_root_item ()
void | goo_canvas_set_root_item ()
GooCanvasItemModel * | goo_canvas_get_root_item_model ()
void | goo_canvas_set_root_item_model ()
GooCanvasItem * | goo_canvas_get_static_root_item ()
void | goo_canvas_set_static_root_item ()
GooCanvasItemModel * | goo_canvas_get_static_root_item_model ()
void | goo_canvas_set_static_root_item_model ()
void | goo_canvas_get_bounds ()
void | goo_canvas_set_bounds ()
gdouble | goo_canvas_get_scale ()
void | goo_canvas_set_scale ()
GooCanvasItem * | goo_canvas_get_item ()
GooCanvasItem * | goo_canvas_get_item_at ()
GList * | goo_canvas_get_items_at ()
GList * | goo_canvas_get_items_in_area ()
void | goo_canvas_scroll_to ()
void | goo_canvas_render ()
void | goo_canvas_convert_to_pixels ()
void | goo_canvas_convert_from_pixels ()
void | goo_canvas_convert_to_item_space ()
void | goo_canvas_convert_from_item_space ()
void | goo_canvas_convert_bounds_to_item_space ()
void | goo_canvas_convert_units_to_pixels ()
void | goo_canvas_convert_units_from_pixels ()
GdkGrabStatus | goo_canvas_pointer_grab ()
void | goo_canvas_pointer_ungrab ()
void | goo_canvas_grab_focus ()
GdkGrabStatus | goo_canvas_keyboard_grab ()
void | goo_canvas_keyboard_ungrab ()
cairo_t * | goo_canvas_create_cairo_context ()
GooCanvasItem * | goo_canvas_create_item ()
void | goo_canvas_unregister_item ()
void | goo_canvas_register_widget_item ()
void | goo_canvas_unregister_widget_item ()
void | goo_canvas_update ()
void | goo_canvas_request_update ()
void | goo_canvas_request_redraw ()
void | goo_canvas_request_item_redraw ()
gdouble | goo_canvas_get_default_line_width ()

## Properties

GooCanvasAnchorType | anchor | Read / Write
gboolean | automatic-bounds | Read / Write
char * | background-color | Write
GdkRGBA * | background-color-gdk-rgba | Write
guint | background-color-rgb | Write
gboolean | bounds-from-origin | Read / Write
double | bounds-padding | Read / Write
gboolean | clear-background | Read / Write
gboolean | integer-layout | Read / Write
gboolean | redraw-when-scrolled | Read / Write
double | resolution-x | Read / Write
double | resolution-y | Read / Write
double | scale | Read / Write
double | scale-x | Read / Write
double | scale-y | Read / Write
GtkUnit | units | Read / Write
double | x1 | Read / Write
double | x2 | Read / Write
double | y1 | Read / Write
double | y2 | Read / Write

## Signals

void | item-created | Run Last

## Types and Values

| GooCanvas
struct | GooCanvasClass

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkWidget
                ╰── GtkContainer
                    ╰── GooCanvas

## Implemented Interfaces

GooCanvas implements AtkImplementorIface, GtkBuildable and GtkScrollable.

## 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
    #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_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", G_CALLBACK (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,
                                       GOO_CANVAS_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",
                        G_CALLBACK (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;
    }

A GooCanvas widget is usually placed inside a GtkScrolledWindow widget and can be scrolled with the scrollbar or with the scroll wheel on a mouse. To disable mouse wheel scrolling, do this:

    1
    g_signal_connect (canvas, "scroll-event", G_CALLBACK (gtk_true), NULL);

## Functions

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

#### Parameters

canvas | a GooCanvas. |

#### Returns

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

[transfer none]

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

#### Parameters

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.

#### Parameters

canvas | a GooCanvas. |

#### Returns

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

[transfer none]

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

#### Parameters

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.

#### Parameters

canvas | a GooCanvas. |

#### Returns

the static root item, or `NULL`.

[transfer none]

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

#### Parameters

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.

#### Parameters

canvas | a GooCanvas. |

#### Returns

the static root item model, or `NULL`.

[transfer none]

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

#### Parameters

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.

#### Parameters

canvas | a GooCanvas. |
left | a pointer to a gdouble to return the left edge, or `NULL`. | [out][allow-none]
top | a pointer to a gdouble to return the top edge, or `NULL`. | [out][allow-none]
right | a pointer to a gdouble to return the right edge, or `NULL`. | [out][allow-none]
bottom | a pointer to a gdouble to return the bottom edge, or `NULL`. | [out][allow-none]

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

[transfer none]

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

#### Parameters

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.

[transfer none]

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

#### Parameters

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()`.

[element-type GooCanvas.CanvasItem][transfer container]

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

#### Parameters

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()`.

[element-type GooCanvas.CanvasItem][transfer container]

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

#### Parameters

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.

This example code could be used in a GtkPrintOperation “draw-page” callback to print each page in a multi-page document (assuming the pages appear one after the other vertically in the canvas). Note the call to `cairo_translate()` to translate the output to the correct position on the printed page.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    GooCanvasBounds bounds;
    bounds.x1 = 0;
    bounds.x2 = A4_PAGE_WIDTH;
    bounds.y1 = A4_PAGE_HEIGHT * page_num;
    bounds.y2 = A4_PAGE_HEIGHT * (page_num + 1);

    cr = gtk_print_context_get_cairo_context (print_context);
    cairo_translate (cr, 0, -A4_PAGE_HEIGHT * page_num);
    goo_canvas_render (GOO_CANVAS (canvas), cr, &bounds, 0.0);

#### Parameters

canvas | a GooCanvas. |
cr | a cairo context. |
bounds | the area to render, or `NULL` to render the entire canvas. | [allow-none]
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()`.

#### Parameters

canvas | a GooCanvas. |
x | a pointer to the x coordinate to convert. | [inout]
y | a pointer to the y coordinate to convert. | [inout]

### 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()`.

#### Parameters

canvas | a GooCanvas. |
x | a pointer to the x coordinate to convert. | [inout]
y | a pointer to the y coordinate to convert. | [inout]

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

#### Parameters

canvas | a GooCanvas. |
item | a GooCanvasItem. |
x | a pointer to the x coordinate to convert. | [inout]
y | a pointer to the y coordinate to convert. | [inout]

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

#### Parameters

canvas | a GooCanvas. |
item | a GooCanvasItem. |
x | a pointer to the x coordinate to convert. | [inout]
y | a pointer to the y coordinate to convert. | [inout]

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

#### Parameters

canvas | a GooCanvas. |
item | a GooCanvasItem. |
bounds | the bounds in canvas coordinate space, to be converted. |

### goo_canvas_convert_units_to_pixels ()

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

Converts a coordinate from the canvas's units to pixels, ignoring scaling and ignoring the coordinate space specified in the call to `goo_canvas_set_bounds()`.

#### Parameters

canvas | a GooCanvas. |
x | a pointer to the x coordinate to convert. | [inout]
y | a pointer to the y coordinate to convert. | [inout]

Since: 2.0.1

### goo_canvas_convert_units_from_pixels ()

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

Converts a coordinate from pixels to the canvas's units, ignoring scaling and ignoring the coordinate space specified in the call to `goo_canvas_set_bounds()`.

#### Parameters

canvas | a GooCanvas. |
x | a pointer to the x coordinate to convert. | [inout]
y | a pointer to the y coordinate to convert. | [inout]

Since: 2.0.1

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

#### Parameters

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. | [nullable]
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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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,
                                guint32 time);

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

#### Parameters

canvas | a GooCanvas. |
item | the item that has the keyboard grab. |
time | the time of the event that lead to the keyboard ungrab. This should come from the relevant GdkEvent. |

### goo_canvas_create_cairo_context ()

    cairo_t *
    goo_canvas_create_cairo_context (GooCanvas *canvas);

Creates a cairo context, initialized with the default canvas settings. Note that this context should not be used for drawing. It should only be used for calculating bounds of items.

#### Parameters

canvas | a GooCanvas. |

#### Returns

a new cairo context. It should be freed with `cairo_destroy()`.

### goo_canvas_create_item ()

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

This function is only intended to be used when implementing new canvas items, typically container items such as GooCanvasGroup.

It creates a new canvas item for the given item model, and recursively creates items for any children.

It uses the `create_item()` virtual method if it has been set. Subclasses of GooCanvas can define this method if they want to use custom views for items.

It emits the “item-created” signal after creating the view, so application code can connect signal handlers to the new view if desired.

#### Parameters

canvas | a GooCanvas. |
model | the item model to create a canvas item for. |

#### Returns

a new canvas item.

[transfer full]

### goo_canvas_unregister_item ()

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

This function is only intended to be used when implementing new canvas items.

It should be called in the finalize method of GooCanvasItem objects, to remove the canvas item from the GooCanvas's hash table.

#### Parameters

canvas | a GooCanvas. |
model | the item model whose canvas item is being finalized. |

### goo_canvas_register_widget_item ()

    void
    goo_canvas_register_widget_item (GooCanvas *canvas,
                                     GooCanvasWidget *witem);

This function should only be used by GooCanvasWidget and subclass implementations.

It registers a widget item with the canvas, so that the canvas can do the necessary actions to move and resize the widget as needed.

#### Parameters

canvas | a GooCanvas. |
witem | a GooCanvasWidget item. |

### goo_canvas_unregister_widget_item ()

    void
    goo_canvas_unregister_widget_item (GooCanvas *canvas,
                                       GooCanvasWidget *witem);

This function should only be used by GooCanvasWidget and subclass implementations.

It unregisters a widget item from the canvas, when the item is no longer in the canvas.

#### Parameters

canvas | a GooCanvas. |
witem | a GooCanvasWidget item. |

### goo_canvas_update ()

    void
    goo_canvas_update (GooCanvas *canvas);

This function is only intended to be used by subclasses of GooCanvas or GooCanvasItem implementations.

It updates any items that need updating.

If the bounds of items change, they will request a redraw of the old and new bounds so the display is updated correctly.

#### Parameters

canvas | a GooCanvas. |

### goo_canvas_request_update ()

    void
    goo_canvas_request_update (GooCanvas *canvas);

This function is only intended to be used by subclasses of GooCanvas or GooCanvasItem implementations.

It schedules an update of the GooCanvas. This will be performed in the idle loop, after all pending events have been handled, but before the canvas has been repainted.

#### Parameters

canvas | a GooCanvas. |

### goo_canvas_request_redraw ()

    void
    goo_canvas_request_redraw (GooCanvas *canvas,
                               const GooCanvasBounds *bounds);

This function is only intended to be used by subclasses of GooCanvas or GooCanvasItem implementations.

Requests that the given bounds be redrawn. The bounds must be in the canvas coordinate space.

#### Parameters

canvas | a GooCanvas. |
bounds | the bounds to redraw, in device space. |

### goo_canvas_request_item_redraw ()

    void
    goo_canvas_request_item_redraw (GooCanvas *canvas,
                                    const GooCanvasBounds *bounds,
                                    gboolean is_static);

This function is only intended to be used by subclasses of GooCanvas or GooCanvasItem implementations.

Requests that the given bounds be redrawn. If `is_static` is `TRUE` the bounds are assumed to be in the static item coordinate space, otherwise they are assumed to be in the canvas coordinate space.

If `is_static` is `FALSE` this function behaves the same as `goo_canvas_request_redraw()`.

#### Parameters

canvas | a GooCanvas. |
bounds | the bounds of the item to redraw. |
is_static | if the item is static. |

### goo_canvas_get_default_line_width ()

    gdouble
    goo_canvas_get_default_line_width (GooCanvas *canvas);

Gets the default line width, which depends on the current units setting.

#### Parameters

canvas | a GooCanvas. |

#### Returns

the default line width of the canvas.

## Types and Values

### GooCanvas

    typedef struct _GooCanvas GooCanvas;

The GooCanvas struct contains private data only.

### struct GooCanvasClass

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

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

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

#### Members

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

## Property Details

### The `“anchor”` property

      “anchor”                   GooCanvasAnchorType

Where to place the canvas when it is smaller than the widget's allocated area.

Owner: GooCanvas

Flags: Read / Write

Default value: GOO_CANVAS_ANCHOR_NORTH_WEST

### The `“automatic-bounds”` property

      “automatic-bounds”         gboolean

If the bounds are automatically calculated based on the bounds of all the items in the canvas.

Owner: GooCanvas

Flags: Read / Write

Default value: FALSE

### The `“background-color”` property

      “background-color”         char *

The color to use for the canvas background.

Owner: GooCanvas

Flags: Write

Default value: NULL

### The `“background-color-gdk-rgba”` property

      “background-color-gdk-rgba” GdkRGBA *

The color to use for the canvas background, specified as a GdkRGBA.

Owner: GooCanvas

Flags: Write

Since: 2.0.1

### The `“background-color-rgb”` property

      “background-color-rgb”     guint

The color to use for the canvas background, specified as a 24-bit integer value, 0xRRGGBB.

Owner: GooCanvas

Flags: Write

Default value: 0

### The `“bounds-from-origin”` property

      “bounds-from-origin”       gboolean

If the automatic bounds are calculated from the origin.

Owner: GooCanvas

Flags: Read / Write

Default value: TRUE

### The `“bounds-padding”` property

      “bounds-padding”           double

The padding added to the automatic bounds.

Owner: GooCanvas

Flags: Read / Write

Allowed values: >= 0

Default value: 0

### The `“clear-background”` property

      “clear-background”         gboolean

If the background is cleared before the canvas is painted.

Owner: GooCanvas

Flags: Read / Write

Default value: TRUE

### The `“integer-layout”` property

      “integer-layout”           gboolean

If all item layout is done to the nearest integer.

Owner: GooCanvas

Flags: Read / Write

Default value: FALSE

### The `“redraw-when-scrolled”` property

      “redraw-when-scrolled”     gboolean

If the canvas is completely redrawn when scrolled, to reduce the flicker of static items. Note that since GTK+ 3.0 the canvas is always redrawn when scrolled, so this option has no effect.

Owner: GooCanvas

Flags: Read / Write

Default value: FALSE

### The `“resolution-x”` property

      “resolution-x”             double

The horizontal resolution of the display, in dots per inch.

Owner: GooCanvas

Flags: Read / Write

Allowed values: >= 0

Default value: 96

### The `“resolution-y”` property

      “resolution-y”             double

The vertical resolution of the display, in dots per inch.

Owner: GooCanvas

Flags: Read / Write

Allowed values: >= 0

Default value: 96

### The `“scale”` property

      “scale”                    double

The magnification factor of the canvas.

Owner: GooCanvas

Flags: Read / Write

Allowed values: >= 0

Default value: 1

### The `“scale-x”` property

      “scale-x”                  double

The horizontal magnification factor of the canvas.

Owner: GooCanvas

Flags: Read / Write

Allowed values: >= 0

Default value: 1

### The `“scale-y”` property

      “scale-y”                  double

The vertical magnification factor of the canvas.

Owner: GooCanvas

Flags: Read / Write

Allowed values: >= 0

Default value: 1

### The `“units”` property

      “units”                    GtkUnit

The units to use for the canvas.

Owner: GooCanvas

Flags: Read / Write

Default value: GTK_UNIT_NONE

### The `“x1”` property

      “x1”                       double

The x coordinate of the left edge of the canvas bounds, in canvas units.

Owner: GooCanvas

Flags: Read / Write

Default value: 0

### The `“x2”` property

      “x2”                       double

The x coordinate of the right edge of the canvas bounds, in canvas units.

Owner: GooCanvas

Flags: Read / Write

Default value: 1000

### The `“y1”` property

      “y1”                       double

The y coordinate of the top edge of the canvas bounds, in canvas units.

Owner: GooCanvas

Flags: Read / Write

Default value: 0

### The `“y2”` property

      “y2”                       double

The y coordinate of the bottom edge of the canvas bounds, in canvas units.

Owner: GooCanvas

Flags: Read / Write

Default value: 1000

## Signal Details

### The `“item-created”` signal

    void
    user_function (GooCanvas          *canvas,
                   GooCanvasItem      *item,
                   GooCanvasItemModel *model,
                   gpointer            user_data)

This is emitted when a new canvas item is created, in model/view mode.

Applications can set up signal handlers for the new items here.

#### Parameters

canvas | the canvas. |
item | the new item. |
model | the item's model. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last