![]() |
![]() |
![]() |
GooCanvas Reference Manual | ![]() |
---|---|---|---|---|
#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);
GObject +----GInitiallyUnowned +----GtkObject +----GtkWidget +----GtkContainer +----GooCanvasView
"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
"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
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; }
typedef struct _GooCanvasView GooCanvasView;
The GooCanvasView struct contains private data only.
GtkWidget* goo_canvas_view_new (void);
Creates a new GooCanvasView widget.
Returns : | a new GooCanvasView widget. |
GooCanvasModel* goo_canvas_view_get_model (GooCanvasView *view);
Gets the model being displayed in the canvas.
view : |
a GooCanvasView. |
Returns : | the GooCanvasModel being displayed. |
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. |
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 .
|
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. |
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. |
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. |
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.
|
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.
|
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.
|
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. |
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 .
|
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. |
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. |
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. |
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. |
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.
|
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. |
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. |
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.
|
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. |
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. |
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. |
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. |
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. |
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. |
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
scale
" property"scale" gdouble : Read / Write
The number of pixels to use for each device unit.
Allowed values: >= 0
Default value: 1
x1
" property"x1" gdouble : Read / Write
The x coordinate of the left edge of the canvas bounds, in device units.
Default value: 0
x2
" property"x2" gdouble : Read / Write
The x coordinate of the right edge of the canvas bounds, in device units.
Default value: 1000
y1
" property"y1" gdouble : Read / Write
The y coordinate of the top edge of the canvas bounds, in device units.
Default value: 0
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. |
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. |