GooCanvasView

GooCanvasView — the main canvas widget.

Synopsis


#include <goocanvas.h>


            GooCanvasView;
GtkWidget*  goo_canvas_view_new             (void);
GooCanvasModel* goo_canvas_view_get_model   (GooCanvasView *view);
void        goo_canvas_view_set_model       (GooCanvasView *view,
                                             GooCanvasModel *model);
void        goo_canvas_view_get_bounds      (GooCanvasView *view,
                                             gdouble *left,
                                             gdouble *top,
                                             gdouble *right,
                                             gdouble *bottom);
void        goo_canvas_view_set_bounds      (GooCanvasView *view,
                                             gdouble left,
                                             gdouble top,
                                             gdouble right,
                                             gdouble bottom);
gdouble     goo_canvas_view_get_scale       (GooCanvasView *view);
void        goo_canvas_view_set_scale       (GooCanvasView *view,
                                             gdouble pixels_per_unit);

GooCanvasItemView* goo_canvas_view_get_root_view
                                            (GooCanvasView *view);
GooCanvasItemView* goo_canvas_view_get_item_view
                                            (GooCanvasView *view,
                                             GooCanvasItem *item);
GooCanvasItemView* goo_canvas_view_get_item_view_at
                                            (GooCanvasView *view,
                                             gdouble x,
                                             gdouble y,
                                             gboolean is_pointer_event);

void        goo_canvas_view_scroll_to       (GooCanvasView *view,
                                             gdouble left,
                                             gdouble top);
void        goo_canvas_view_render          (GooCanvasView *view,
                                             cairo_t *cr,
                                             GooCanvasBounds *bounds,
                                             gdouble scale);

void        goo_canvas_view_convert_to_pixels
                                            (GooCanvasView *canvas_view,
                                             gdouble *x,
                                             gdouble *y);
void        goo_canvas_view_convert_from_pixels
                                            (GooCanvasView *canvas_view,
                                             gdouble *x,
                                             gdouble *y);
void        goo_canvas_view_convert_to_item_space
                                            (GooCanvasView *canvas_view,
                                             GooCanvasItemView *item_view,
                                             gdouble *x,
                                             gdouble *y);
void        goo_canvas_view_convert_from_item_space
                                            (GooCanvasView *canvas_view,
                                             GooCanvasItemView *item_view,
                                             gdouble *x,
                                             gdouble *y);

GdkGrabStatus goo_canvas_view_pointer_grab  (GooCanvasView *canvas_view,
                                             GooCanvasItemView *item_view,
                                             GdkEventMask event_mask,
                                             GdkCursor *cursor,
                                             guint32 time);
void        goo_canvas_view_pointer_ungrab  (GooCanvasView *canvas_view,
                                             GooCanvasItemView *item_view,
                                             guint32 time);

void        goo_canvas_view_grab_focus      (GooCanvasView *canvas_view,
                                             GooCanvasItemView *item_view);
GdkGrabStatus goo_canvas_view_keyboard_grab (GooCanvasView *canvas_view,
                                             GooCanvasItemView *item_view,
                                             gboolean owner_events,
                                             guint32 time);
void        goo_canvas_view_keyboard_ungrab (GooCanvasView *canvas_view,
                                             GooCanvasItemView *item_view,
                                             guint32 time);

GooCanvasItemView* goo_canvas_view_create_item_view
                                            (GooCanvasView *view,
                                             GooCanvasItem *item,
                                             GooCanvasItemView *parent_view);
void        goo_canvas_view_unregister_item_view
                                            (GooCanvasView *view,
                                             GooCanvasItem *item);
void        goo_canvas_view_request_update  (GooCanvasView *view);
void        goo_canvas_view_update          (GooCanvasView *view);
void        goo_canvas_view_request_redraw  (GooCanvasView *view,
                                             GooCanvasBounds *bounds);

Object Hierarchy


  GObject
   +----GInitiallyUnowned
         +----GtkObject
               +----GtkWidget
                     +----GtkContainer
                           +----GooCanvasView

Implemented Interfaces

GooCanvasView implements AtkImplementorIface.

Properties


  "anchor"               GtkAnchorType         : Read / Write
  "model"                GooCanvasModel        : Read / Write
  "scale"                gdouble               : Read / Write
  "x1"                   gdouble               : Read / Write
  "x2"                   gdouble               : Read / Write
  "y1"                   gdouble               : Read / Write
  "y2"                   gdouble               : Read / Write

Signals


"item-view-created"
            void        user_function      (GooCanvasView     *view,
                                            GooCanvasItemView *item_view,
                                            GooCanvasItem     *item,
                                            gpointer           user_data)      : Run last
"set-scroll-adjustments"
            void        user_function      (GooCanvasView *view,
                                            GtkAdjustment *hadjustment,
                                            GtkAdjustment *vadjustment,
                                            gpointer       user_data)        : Run last / Action

Description

GooCanvasView is the main widget containing the view of the canvas model.

Here is a simple example:

 #include <goocanvas.h>
 
 static gboolean on_rect_button_press (GooCanvasItemView *view,
                                       GooCanvasItemView *target,
                                       GdkEventButton    *event,
                                       gpointer           data);
 
 int
 main (int argc, char *argv[])
 {
   GtkWidget *window, *scrolled_win, *canvas;
   GooCanvasModelSimple *canvas_model;
   GooCanvasItemView *item_view;
   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);
 
   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_view_new ();
   gtk_widget_set_size_request (canvas, 600, 450);
   goo_canvas_view_set_bounds (GOO_CANVAS_VIEW (canvas), 0, 0, 1000, 1000);
   gtk_widget_show (canvas);
   gtk_container_add (GTK_CONTAINER (scrolled_win), canvas);
 
   /* Create the canvas model */
   canvas_model = goo_canvas_model_simple_new ();
 
   root = goo_canvas_model_get_root_item (GOO_CANVAS_MODEL (canvas_model));
 
   /* 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);
 
   /* Set the model of the canvas view. This will create item views for all the
      items in the model. */
   goo_canvas_view_set_model (GOO_CANVAS_VIEW (canvas),
                              GOO_CANVAS_MODEL (canvas_model));
   g_object_unref (canvas_model);
 
   /* Connect a signal handler for the item view of the rectangle item. */
   item_view = goo_canvas_view_get_item_view (GOO_CANVAS_VIEW (canvas),
                                              rect_item);
   g_signal_connect (item_view, "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 (GooCanvasItemView *view,
                       GooCanvasItemView *target,
                       GdkEventButton *event,
                       gpointer data)
 {
   g_print ("rect item received button press event\n");
   return TRUE;
 }
 

Details

GooCanvasView

typedef struct _GooCanvasView GooCanvasView;

The GooCanvasView struct contains private data only.


goo_canvas_view_new ()

GtkWidget*  goo_canvas_view_new             (void);

Creates a new GooCanvasView widget.

Returns : a new GooCanvasView widget.

goo_canvas_view_get_model ()

GooCanvasModel* goo_canvas_view_get_model   (GooCanvasView *view);

Gets the model being displayed in the canvas.

view : a GooCanvasView.
Returns : the GooCanvasModel being displayed.

goo_canvas_view_set_model ()

void        goo_canvas_view_set_model       (GooCanvasView *view,
                                             GooCanvasModel *model);

Sets the model to be displayed in the GooCanvasView.

A hierarchy of item views will be created, corresponding to the hierarchy of items in the model.

view : a GooCanvasView.
model : a GooCanvasModel.

goo_canvas_view_get_bounds ()

void        goo_canvas_view_get_bounds      (GooCanvasView *view,
                                             gdouble *left,
                                             gdouble *top,
                                             gdouble *right,
                                             gdouble *bottom);

Gets the bounds of the canvas.

view : a GooCanvasView.
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_view_set_bounds ()

void        goo_canvas_view_set_bounds      (GooCanvasView *view,
                                             gdouble left,
                                             gdouble top,
                                             gdouble right,
                                             gdouble bottom);

Sets the bounds of the GooCanvasView, in device units.

By default, device units are the same as pixels, though goo_canvas_view_set_scale() can be used to specify a different scale.

view : a GooCanvasView.
left : the left edge.
top : the top edge.
right : the right edge.
bottom : the bottom edge.

goo_canvas_view_get_scale ()

gdouble     goo_canvas_view_get_scale       (GooCanvasView *view);

Gets the current scale of the canvas, i.e. the number of pixels to use for each device unit.

view : a GooCanvasView.
Returns : the current scale setting.

goo_canvas_view_set_scale ()

void        goo_canvas_view_set_scale       (GooCanvasView *view,
                                             gdouble pixels_per_unit);

Sets the current scale of the canvas, i.e. the number of pixels to use for each device unit.

view : a GooCanvasView.
pixels_per_unit : the new scale setting.

goo_canvas_view_get_root_view ()

GooCanvasItemView* goo_canvas_view_get_root_view
                                            (GooCanvasView *view);

Gets the root item view.

view : a GooCanvasView.
Returns : the root item view, or NULL of no canvas model is set.

goo_canvas_view_get_item_view ()

GooCanvasItemView* goo_canvas_view_get_item_view
                                            (GooCanvasView *view,
                                             GooCanvasItem *item);

Gets the view for the given GooCanvasItem.

For simple applications you can use this function to set up signal handlers for your item views, e.g.

   item_view = goo_canvas_view_get_item_view (GOO_CANVAS_VIEW (canvas),
                                              my_item);
   g_signal_connect (item_view, "button_press_event",
                     (GtkSignalFunc) on_my_item_view_button_press, NULL);

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

view : a GooCanvasView.
item : a GooCanvasItem.
Returns : the view for the given GooCanvasItem, or NULL if no view has been created for it yet.

goo_canvas_view_get_item_view_at ()

GooCanvasItemView* goo_canvas_view_get_item_view_at
                                            (GooCanvasView *view,
                                             gdouble x,
                                             gdouble y,
                                             gboolean is_pointer_event);

Gets the item view at the given point.

view : a GooCanvasView.
x : the x coordinate of the point.
y : the y coordinate of the point
is_pointer_event : TRUE if the "pointer-events" properties of items should be used to determine which parts of the item are tested.
Returns : the item view found at the given point, or NULL if no item view was found.

goo_canvas_view_scroll_to ()

void        goo_canvas_view_scroll_to       (GooCanvasView *view,
                                             gdouble left,
                                             gdouble top);

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

view : a GooCanvasView.
left : the x coordinate to scroll to.
top : the y coordinate to scroll to.

goo_canvas_view_render ()

void        goo_canvas_view_render          (GooCanvasView *view,
                                             cairo_t *cr,
                                             GooCanvasBounds *bounds,
                                             gdouble scale);

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

view : a GooCanvasView.
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_view_convert_to_pixels ()

void        goo_canvas_view_convert_to_pixels
                                            (GooCanvasView *canvas_view,
                                             gdouble *x,
                                             gdouble *y);

Converts a coordinate from the canvas view coordinate space to pixels.

The canvas view coordinate space is specified in the call to goo_canvas_view_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_view_set_scale().

canvas_view : a GooCanvasView.
x : a pointer to the x coordinate to convert.
y : a pointer to the y coordinate to convert.

goo_canvas_view_convert_from_pixels ()

void        goo_canvas_view_convert_from_pixels
                                            (GooCanvasView *canvas_view,
                                             gdouble *x,
                                             gdouble *y);

Converts a coordinate from pixels to the canvas view 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_view_set_scale().

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

canvas_view : a GooCanvasView.
x : a pointer to the x coordinate to convert.
y : a pointer to the y coordinate to convert.

goo_canvas_view_convert_to_item_space ()

void        goo_canvas_view_convert_to_item_space
                                            (GooCanvasView *canvas_view,
                                             GooCanvasItemView *item_view,
                                             gdouble *x,
                                             gdouble *y);

Converts a coordinate from the canvas view 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_view : a GooCanvasView.
item_view : a GooCanvasItemView.
x : a pointer to the x coordinate to convert.
y : a pointer to the y coordinate to convert.

goo_canvas_view_convert_from_item_space ()

void        goo_canvas_view_convert_from_item_space
                                            (GooCanvasView *canvas_view,
                                             GooCanvasItemView *item_view,
                                             gdouble *x,
                                             gdouble *y);

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

canvas_view : a GooCanvasView.
item_view : a GooCanvasItemView.
x : a pointer to the x coordinate to convert.
y : a pointer to the y coordinate to convert.

goo_canvas_view_pointer_grab ()

GdkGrabStatus goo_canvas_view_pointer_grab  (GooCanvasView *canvas_view,
                                             GooCanvasItemView *item_view,
                                             GdkEventMask event_mask,
                                             GdkCursor *cursor,
                                             guint32 time);

Attempts to grab the pointer for the given item view.

canvas_view : a GooCanvasView.
item_view : the item view 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_view_pointer_ungrab ()

void        goo_canvas_view_pointer_ungrab  (GooCanvasView *canvas_view,
                                             GooCanvasItemView *item_view,
                                             guint32 time);

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

canvas_view : a GooCanvasView.
item_view : the item view 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_view_grab_focus ()

void        goo_canvas_view_grab_focus      (GooCanvasView *canvas_view,
                                             GooCanvasItemView *item_view);

Grabs the keyboard focus for the given item.

canvas_view : a GooCanvasView.
item_view : the item view to grab the focus.

goo_canvas_view_keyboard_grab ()

GdkGrabStatus goo_canvas_view_keyboard_grab (GooCanvasView *canvas_view,
                                             GooCanvasItemView *item_view,
                                             gboolean owner_events,
                                             guint32 time);

Attempts to grab the keyboard for the given item view.

canvas_view : a GooCanvasView.
item_view : the item view 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 view.
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_view_keyboard_ungrab ()

void        goo_canvas_view_keyboard_ungrab (GooCanvasView *canvas_view,
                                             GooCanvasItemView *item_view,
                                             guint32 time);

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

canvas_view : a GooCanvasView.
item_view : the item view 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_view_create_item_view ()

GooCanvasItemView* goo_canvas_view_create_item_view
                                            (GooCanvasView *view,
                                             GooCanvasItem *item,
                                             GooCanvasItemView *parent_view);

Creates a new item view for the given item.

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

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

view : a GooCanvasView.
item : the item to create a view for.
parent_view : the parent view of the new item.
Returns : a new item view.

goo_canvas_view_unregister_item_view ()

void        goo_canvas_view_unregister_item_view
                                            (GooCanvasView *view,
                                             GooCanvasItem *item);

This function should be called in the finalize method of GooCanvasItemView objects, to remove the item view from the GooCanvasView's hash table.

view : a GooCanvasView.
item : the item whose view is being finalized.

goo_canvas_view_request_update ()

void        goo_canvas_view_request_update  (GooCanvasView *view);

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

view : a GooCanvasView.

goo_canvas_view_update ()

void        goo_canvas_view_update          (GooCanvasView *view);

Updates any item views that need updating.

This is only intended to be used by subclasses of GooCanvasView or GooCanvasItemView implementations.

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

view : a GooCanvasView.

goo_canvas_view_request_redraw ()

void        goo_canvas_view_request_redraw  (GooCanvasView *view,
                                             GooCanvasBounds *bounds);

Requests that the given bounds be redrawn.

view : a GooCanvasView.
bounds : the bounds to redraw.

Property Details

The "anchor" property

  "anchor"               GtkAnchorType         : Read / Write

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

Default value: GTK_ANCHOR_NORTH_WEST


The "model" property

  "model"                GooCanvasModel        : Read / Write

The model for the canvas view.


The "scale" property

  "scale"                gdouble               : Read / Write

The number of pixels to use for each device unit.

Allowed values: >= 0

Default value: 1


The "x1" property

  "x1"                   gdouble               : Read / Write

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

Default value: 0


The "x2" property

  "x2"                   gdouble               : Read / Write

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

Default value: 1000


The "y1" property

  "y1"                   gdouble               : Read / Write

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

Default value: 0


The "y2" property

  "y2"                   gdouble               : Read / Write

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

Default value: 1000

Signal Details

The "item-view-created" signal

void        user_function                  (GooCanvasView     *view,
                                            GooCanvasItemView *item_view,
                                            GooCanvasItem     *item,
                                            gpointer           user_data)      : Run last

This is emitted when a new item view is created.

Applications can set up signal handlers for the new item views here.

view : the canvas view.
item_view : the new item view.
item : the canvas item.
user_data : user data set when the signal handler was connected.

The "set-scroll-adjustments" signal

void        user_function                  (GooCanvasView *view,
                                            GtkAdjustment *hadjustment,
                                            GtkAdjustment *vadjustment,
                                            gpointer       user_data)        : Run last / Action

This is used when the GooCanvas is placed inside a GtkScrolledWindow, to connect up the adjustments so scrolling works properly.

It isn't useful for applications.

view : the canvas view.
hadjustment : the horizontal adjustment.
vadjustment : the vertical adjustment.
user_data : user data set when the signal handler was connected.