|
|
|
GooCanvas Reference Manual | |
|---|---|---|---|---|
GooCanvas;
GooCanvasClass;
GtkWidget* goo_canvas_new (void);
GooCanvasItem* goo_canvas_get_root_item (GooCanvas *canvas);
void goo_canvas_set_root_item (GooCanvas *canvas,
GooCanvasItem *item);
GooCanvasItemModel* goo_canvas_get_root_item_model (GooCanvas *canvas);
void goo_canvas_set_root_item_model (GooCanvas *canvas,
GooCanvasItemModel *model);
void goo_canvas_get_bounds (GooCanvas *canvas,
gdouble *left,
gdouble *top,
gdouble *right,
gdouble *bottom);
void goo_canvas_set_bounds (GooCanvas *canvas,
gdouble left,
gdouble top,
gdouble right,
gdouble bottom);
gdouble goo_canvas_get_scale (GooCanvas *canvas);
void goo_canvas_set_scale (GooCanvas *canvas,
gdouble scale);
GooCanvasItem* goo_canvas_get_item (GooCanvas *canvas,
GooCanvasItemModel *model);
GooCanvasItem* goo_canvas_get_item_at (GooCanvas *canvas,
gdouble x,
gdouble y,
gboolean is_pointer_event);
void goo_canvas_scroll_to (GooCanvas *canvas,
gdouble left,
gdouble top);
void goo_canvas_render (GooCanvas *canvas,
cairo_t *cr,
GooCanvasBounds *bounds,
gdouble scale);
void goo_canvas_convert_to_pixels (GooCanvas *canvas,
gdouble *x,
gdouble *y);
void goo_canvas_convert_from_pixels (GooCanvas *canvas,
gdouble *x,
gdouble *y);
void goo_canvas_convert_to_item_space (GooCanvas *canvas,
GooCanvasItem *item,
gdouble *x,
gdouble *y);
void goo_canvas_convert_from_item_space (GooCanvas *canvas,
GooCanvasItem *item,
gdouble *x,
gdouble *y);
GdkGrabStatus goo_canvas_pointer_grab (GooCanvas *canvas,
GooCanvasItem *item,
GdkEventMask event_mask,
GdkCursor *cursor,
guint32 time);
void goo_canvas_pointer_ungrab (GooCanvas *canvas,
GooCanvasItem *item,
guint32 time);
void goo_canvas_grab_focus (GooCanvas *canvas,
GooCanvasItem *item);
GdkGrabStatus goo_canvas_keyboard_grab (GooCanvas *canvas,
GooCanvasItem *item,
gboolean owner_events,
guint32 time);
void goo_canvas_keyboard_ungrab (GooCanvas *canvas,
GooCanvasItem *item,
guint32 time);
GooCanvasItem* goo_canvas_create_item (GooCanvas *canvas,
GooCanvasItemModel *model);
void goo_canvas_unregister_item (GooCanvas *canvas,
GooCanvasItemModel *model);
void goo_canvas_register_widget_item (GooCanvas *canvas,
GooCanvasWidget *witem);
void goo_canvas_unregister_widget_item (GooCanvas *canvas,
GooCanvasWidget *witem);
void goo_canvas_update (GooCanvas *canvas);
void goo_canvas_request_update (GooCanvas *canvas);
void goo_canvas_request_redraw (GooCanvas *canvas,
GooCanvasBounds *bounds);
gdouble goo_canvas_get_default_line_width (GooCanvas *canvas);
GObject +----GInitiallyUnowned +----GtkObject +----GtkWidget +----GtkContainer +----GooCanvas
"anchor" GtkAnchorType : Read / Write "resolution-x" gdouble : Read / Write "resolution-y" gdouble : Read / Write "scale" gdouble : Read / Write "units" GtkUnit : Read / Write "x1" gdouble : Read / Write "x2" gdouble : Read / Write "y1" gdouble : Read / Write "y2" gdouble : Read / Write
GooCanvas is the main widget containing a number of canvas items.
Here is a simple example:
#include <goocanvas.h>
static gboolean on_rect_button_press (GooCanvasItem *view,
GooCanvasItem *target,
GdkEventButton *event,
gpointer data);
int
main (int argc, char *argv[])
{
GtkWidget *window, *scrolled_win, *canvas;
GooCanvasItem *root, *rect_item, *text_item;
/* Initialize GTK+. */
gtk_set_locale ();
gtk_init (&argc, &argv);
/* Create the window and widgets. */
window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
gtk_window_set_default_size (GTK_WINDOW (window), 640, 600);
gtk_widget_show (window);
g_signal_connect (window, "delete_event", (GtkSignalFunc) on_delete_event,
NULL);
scrolled_win = gtk_scrolled_window_new (NULL, NULL);
gtk_scrolled_window_set_shadow_type (GTK_SCROLLED_WINDOW (scrolled_win),
GTK_SHADOW_IN);
gtk_widget_show (scrolled_win);
gtk_container_add (GTK_CONTAINER (window), scrolled_win);
canvas = goo_canvas_new ();
gtk_widget_set_size_request (canvas, 600, 450);
goo_canvas_set_bounds (GOO_CANVAS (canvas), 0, 0, 1000, 1000);
gtk_widget_show (canvas);
gtk_container_add (GTK_CONTAINER (scrolled_win), canvas);
root = goo_canvas_get_root_item (GOO_CANVAS (canvas));
/* Add a few simple items. */
rect_item = goo_canvas_rect_new (root, 100, 100, 400, 400,
"line-width", 10.0,
"radius-x", 20.0,
"radius-y", 10.0,
"stroke-color", "yellow",
"fill-color", "red",
NULL);
text_item = goo_canvas_text_new (root, "Hello World", 300, 300, -1,
GTK_ANCHOR_CENTER,
"font", "Sans 24",
NULL);
goo_canvas_item_rotate (text_item, 45, 300, 300);
/* Connect a signal handler for the rectangle item. */
g_signal_connect (rect_item, "button_press_event",
(GtkSignalFunc) on_rect_button_press, NULL);
/* Pass control to the GTK+ main event loop. */
gtk_main ();
return 0;
}
/* This handles button presses in item views. We simply output a message to
the console. */
static gboolean
on_rect_button_press (GooCanvasItem *item,
GooCanvasItem *target,
GdkEventButton *event,
gpointer data)
{
g_print ("rect item received button press event\n");
return TRUE;
}
typedef struct {
GooCanvasItem* (* create_item) (GooCanvas *canvas,
GooCanvasItemModel *model);
/* Signals. */
void (* item_created) (GooCanvas *canvas,
GooCanvasItem *item,
GooCanvasItemModel *model);
} GooCanvasClass;
The GooCanvasClass struct contains one virtual method that subclasses may override.
create_item () |
a virtual method that subclasses may override to create custom canvas items for item models. |
item_created () |
signal emitted when a new canvas item has been created. Applications can connect to this to setup signal handlers for the new item. |
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. |
GooCanvasItem* goo_canvas_get_root_item (GooCanvas *canvas);
Gets the root item of the canvas, usually a GooCanvasGroup.
void goo_canvas_set_root_item (GooCanvas *canvas, GooCanvasItem *item);
Sets the root item of the canvas. Any existing canvas items are removed.
canvas : |
a GooCanvas. |
item : |
the root canvas item. |
GooCanvasItemModel* goo_canvas_get_root_item_model (GooCanvas *canvas);
Gets the root item model of the canvas.
void goo_canvas_set_root_item_model (GooCanvas *canvas, GooCanvasItemModel *model);
Sets the root item model of the canvas.
A hierarchy of canvas items will be created, corresponding to the hierarchy of items in the model. Any current canvas items will be removed.
canvas : |
a GooCanvas. |
model : |
a GooCanvasItemModel. |
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 GooCanvas:units property can be used to change the units to points, inches or millimeters.
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 GooCanvas:units property can be used to change the units to points, inches or millimeters.
canvas : |
a GooCanvas. |
left : |
the left edge. |
top : |
the top edge. |
right : |
the right edge. |
bottom : |
the bottom edge. |
gdouble goo_canvas_get_scale (GooCanvas *canvas);
Gets the current scale of the canvas.
The scale specifies the magnification factor of the canvas, e.g. if an item has a width of 2 pixels and the scale is set to 3, it will be displayed with a width of 2 x 3 = 6 pixels.
canvas : |
a GooCanvas. |
| Returns : | the current scale setting. |
void goo_canvas_set_scale (GooCanvas *canvas, gdouble scale);
Sets the scale of the canvas.
The scale specifies the magnification factor of the canvas, e.g. if an item has a width of 2 pixels and the scale is set to 3, it will be displayed with a width of 2 x 3 = 6 pixels.
canvas : |
a GooCanvas. |
scale : |
the new scale setting. |
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.
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 GooCanvas::item-created signal to hook up their signal handlers.
canvas : |
a GooCanvas. |
model : |
a GooCanvasItemModel. |
| Returns : | the canvas item corresponding to the given GooCanvasItemModel,
or NULL if no canvas item has been created for it yet.
|
GooCanvasItem* goo_canvas_get_item_at (GooCanvas *canvas, gdouble x, gdouble y, gboolean is_pointer_event);
Gets the item at the given point.
void goo_canvas_scroll_to (GooCanvas *canvas, gdouble left, gdouble top);
Scrolls the canvas, placing the given point as close to the top-left of the view as possible.
canvas : |
a GooCanvas. |
left : |
the x coordinate to scroll to. |
top : |
the y coordinate to scroll to. |
void goo_canvas_render (GooCanvas *canvas, cairo_t *cr, GooCanvasBounds *bounds, gdouble scale);
Renders all or part of a canvas to the given cairo context.
canvas : |
a GooCanvas. |
cr : |
a cairo context. |
bounds : |
the area to render, or NULL to render the entire canvas.
|
scale : |
the scale to compare with each item's visibility
threshold to see if they should be rendered. This only affects items that
have their visibility set to GOO_CANVAS_ITEM_VISIBLE_ABOVE_THRESHOLD.
|
void goo_canvas_convert_to_pixels (GooCanvas *canvas, gdouble *x, gdouble *y);
Converts a coordinate from the canvas coordinate space to pixels.
The canvas coordinate space is specified in the call to
goo_canvas_set_bounds().
The pixel coordinate space specifies pixels from the top-left of the entire
canvas window, according to the current scale setting.
See goo_canvas_set_scale().
canvas : |
a GooCanvas. |
x : |
a pointer to the x coordinate to convert. |
y : |
a pointer to the y coordinate to convert. |
void goo_canvas_convert_from_pixels (GooCanvas *canvas, gdouble *x, gdouble *y);
Converts a coordinate from pixels to the canvas coordinate space.
The pixel coordinate space specifies pixels from the top-left of the entire
canvas window, according to the current scale setting.
See goo_canvas_set_scale().
The canvas coordinate space is specified in the call to
goo_canvas_set_bounds().
canvas : |
a GooCanvas. |
x : |
a pointer to the x coordinate to convert. |
y : |
a pointer to the y coordinate to convert. |
void goo_canvas_convert_to_item_space (GooCanvas *canvas, GooCanvasItem *item, gdouble *x, gdouble *y);
Converts a coordinate from the canvas coordinate space to the given item's coordinate space, applying all transformation matrices including the item's own transformation matrix, if it has one.
canvas : |
a GooCanvas. |
item : |
a GooCanvasItem. |
x : |
a pointer to the x coordinate to convert. |
y : |
a pointer to the y coordinate to convert. |
void goo_canvas_convert_from_item_space (GooCanvas *canvas, GooCanvasItem *item, gdouble *x, gdouble *y);
Converts a coordinate from the given item's coordinate space to the canvas coordinate space, applying all transformation matrices including the item's own transformation matrix, if it has one.
canvas : |
a GooCanvas. |
item : |
a GooCanvasItem. |
x : |
a pointer to the x coordinate to convert. |
y : |
a pointer to the y coordinate to convert. |
GdkGrabStatus goo_canvas_pointer_grab (GooCanvas *canvas, GooCanvasItem *item, GdkEventMask event_mask, GdkCursor *cursor, guint32 time);
Attempts to grab the pointer for the given item.
canvas : |
a GooCanvas. |
item : |
the item to grab the pointer for. |
event_mask : |
the events to receive during the grab. |
cursor : |
the cursor to display during the grab, or NULL. |
time : |
the time of the event that lead to the pointer grab. This should come from the relevant GdkEvent. |
| Returns : | GDK_GRAB_SUCCESS if the grab succeeded.
|
void goo_canvas_pointer_ungrab (GooCanvas *canvas, GooCanvasItem *item, guint32 time);
Ungrabs the pointer, if the given item has the pointer grab.
void goo_canvas_grab_focus (GooCanvas *canvas, GooCanvasItem *item);
Grabs the keyboard focus for the given item.
canvas : |
a GooCanvas. |
item : |
the item to grab the focus. |
GdkGrabStatus goo_canvas_keyboard_grab (GooCanvas *canvas, GooCanvasItem *item, gboolean owner_events, guint32 time);
Attempts to grab the keyboard for the given item.
canvas : |
a GooCanvas. |
item : |
the item to grab the keyboard for. |
owner_events : |
TRUE if keyboard events for this application will be
reported normally, or FALSE if all keyboard events will be reported with
respect to the grab item.
|
time : |
the time of the event that lead to the keyboard grab. This should come from the relevant GdkEvent. |
| Returns : | GDK_GRAB_SUCCESS if the grab succeeded.
|
void goo_canvas_keyboard_ungrab (GooCanvas *canvas, GooCanvasItem *item, guint32 time);
Ungrabs the keyboard, if the given item has the keyboard grab.
GooCanvasItem* goo_canvas_create_item (GooCanvas *canvas, GooCanvasItemModel *model);
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 GooCanvas::item-created signal after creating the view, so application code can connect signal handlers to the new view if desired.
canvas : |
a GooCanvas. |
model : |
the item model to create a canvas item for. |
| Returns : | a new canvas item. |
void goo_canvas_unregister_item (GooCanvas *canvas, GooCanvasItemModel *model);
This function should be called in the finalize method of GooCanvasItem objects, to remove the canvas item from the GooCanvas's hash table.
canvas : |
a GooCanvas. |
model : |
the item model whose canvas item is being finalized. |
void goo_canvas_register_widget_item (GooCanvas *canvas, GooCanvasWidget *witem);
Registers a widget item with the canvas, so that the canvas can do the necessary actions to move and resize the widget as needed.
This function should only be used by GooCanvasWidget and subclass implementations.
canvas : |
a GooCanvas. |
witem : |
a GooCanvasWidget item. |
void goo_canvas_unregister_widget_item (GooCanvas *canvas, GooCanvasWidget *witem);
Unregisters a widget item from the canvas, when the item is no longer in the canvas.
This function should only be used by GooCanvasWidget and subclass implementations.
canvas : |
a GooCanvas. |
witem : |
a GooCanvasWidget item. |
void goo_canvas_update (GooCanvas *canvas);
Updates any items that need updating.
This is only intended to be used by subclasses of GooCanvas or GooCanvasItem implementations.
If the bounds of items change, they will request a redraw of the old and new bounds so the display is updated correctly.
canvas : |
a GooCanvas. |
void goo_canvas_request_update (GooCanvas *canvas);
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.
canvas : |
a GooCanvas. |
void goo_canvas_request_redraw (GooCanvas *canvas, GooCanvasBounds *bounds);
Requests that the given bounds be redrawn.
canvas : |
a GooCanvas. |
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
resolution-x" property"resolution-x" gdouble : Read / Write
The horizontal resolution of the display, in dots per inch.
Allowed values: >= 0
Default value: 96
resolution-y" property"resolution-y" gdouble : Read / Write
The vertical resolution of the display, in dots per inch.
Allowed values: >= 0
Default value: 96
scale" property"scale" gdouble : Read / Write
The magnification factor of the canvas.
Allowed values: >= 0
Default value: 1
units" property"units" GtkUnit : Read / Write
The units to use for the canvas.
Default value: GTK_UNIT_PIXEL
x1" property"x1" gdouble : Read / Write
The x coordinate of the left edge of the canvas bounds, in canvas units.
Default value: 0
x2" property"x2" gdouble : Read / Write
The x coordinate of the right edge of the canvas bounds, in canvas units.
Default value: 1000
y1" property"y1" gdouble : Read / Write
The y coordinate of the top edge of the canvas bounds, in canvas units.
Default value: 0
y2" property"y2" gdouble : Read / Write
The y coordinate of the bottom edge of the canvas bounds, in canvas units.
Default value: 1000
void user_function (GooCanvas *canvas, GooCanvasItem *item, GooCanvasItemModel *model, gpointer user_data) : Run Last
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.
canvas : |
the canvas. |
item : |
the new item. |
model : |
the item's model. |
user_data : |
user data set when the signal handler was connected. |
void user_function (GooCanvas *canvas, 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.
canvas : |
the canvas. |
hadjustment : |
the horizontal adjustment. |
vadjustment : |
the vertical adjustment. |
user_data : |
user data set when the signal handler was connected. |