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