[cairo-commit] goocanvas/src goocanvasitem.c, 1.3,
1.4 goocanvasview.c, 1.8, 1.9 goocanvasview.h, 1.5, 1.6
Damon Chaplin
commit at pdx.freedesktop.org
Fri Apr 14 11:52:29 PDT 2006
Committed by: damon
Update of /cvs/cairo/goocanvas/src
In directory kemper:/tmp/cvs-serv25242/src
Modified Files:
goocanvasitem.c goocanvasview.c goocanvasview.h
Log Message:
2006-04-14 Damon Chaplin <damon at gnome.org>
* src/goocanvasview.c: documented GooCanvasView, though it needs an
overview and demo code.
Index: goocanvasitem.c
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvasitem.c,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -d -r1.3 -r1.4
--- goocanvasitem.c 14 Apr 2006 16:59:04 -0000 1.3
+++ goocanvasitem.c 14 Apr 2006 18:52:28 -0000 1.4
@@ -10,7 +10,7 @@
* @Title: GooCanvasItem
* @Short_Description: the interface for canvas items.
*
- * GooCanvasItem defines the interface that canvas items must implement,
+ * #GooCanvasItem defines the interface that canvas items must implement,
* and contains methods for operating on canvas items.
*/
#include <config.h>
Index: goocanvasview.c
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvasview.c,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -d -r1.8 -r1.9
--- goocanvasview.c 8 Apr 2006 13:14:17 -0000 1.8
+++ goocanvasview.c 14 Apr 2006 18:52:28 -0000 1.9
@@ -4,6 +4,14 @@
*
* goocanvasview.c - the main canvas widget.
*/
+
+/**
+ * SECTION:goocanvasview
+ * @Title: GooCanvasView
+ * @Short_Description: the main #GooCanvas widget.
+ *
+ * #GooCanvasView is the main widget containing the view of the canvas.
+ */
#include <config.h>
#include <gtk/gtk.h>
#include "goocanvasview.h"
@@ -89,6 +97,16 @@
klass->set_scroll_adjustments = goo_canvas_view_set_adjustments;
+ /**
+ * GooCanvasView::set-scroll-adjustments
+ * @hadjustment: the horizontal adjustment.
+ * @vadjustment: the vertical adjustment.
+ *
+ * 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.
+ */
widget_class->set_scroll_adjustments_signal =
g_signal_new ("set_scroll_adjustments",
G_OBJECT_CLASS_TYPE (gobject_class),
@@ -101,6 +119,16 @@
GTK_TYPE_ADJUSTMENT);
/* Signals. */
+
+ /**
+ * GooCanvasView::item-view-created
+ * @view: the new item view.
+ * @item: the canvas item.
+ *
+ * This is emitted when a new item view is created.
+ *
+ * Applications can set up signal handlers for the new item views here.
+ */
canvas_view_signals[ITEM_VIEW_CREATED] =
g_signal_new ("item-view-created",
G_TYPE_FROM_CLASS (gobject_class),
@@ -124,6 +152,13 @@
}
+/**
+ * goo_canvas_view_new:
+ *
+ * Creates a new #GooCanvasView widget.
+ *
+ * Returns: a new #GooCanvasView widget.
+ **/
GtkWidget*
goo_canvas_view_new (void)
{
@@ -156,6 +191,16 @@
}
+/**
+ * goo_canvas_view_set_model:
+ * @view: a #GooCanvasView.
+ * @model: a #GooCanvasModel.
+ *
+ * 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.
+ **/
void
goo_canvas_view_set_model (GooCanvasView *view,
GooCanvasModel *model)
@@ -651,6 +696,19 @@
}
+/**
+ * goo_canvas_view_set_bounds:
+ * @view: a #GooCanvasView.
+ * @left: the left edge.
+ * @top: the top edge.
+ * @right: the right edge.
+ * @bottom: the bottom edge.
+ *
+ * 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.
+ **/
void
goo_canvas_view_set_bounds (GooCanvasView *view,
gdouble left,
@@ -669,11 +727,12 @@
/**
* goo_canvas_view_scroll_to:
- * @view:
- * @left:
- * @top:
- *
+ * @view: a #GooCanvasView.
+ * @left: the x coordinate to scroll to.
+ * @top: the y coordinate to scroll to.
*
+ * Scrolls the canvas, placing the given point as close to the top-left of
+ * the view as possible.
**/
void
goo_canvas_view_scroll_to (GooCanvasView *view,
@@ -701,9 +760,17 @@
}
+/**
+ * goo_canvas_view_set_scale:
+ * @view: a #GooCanvasView.
+ * @pixels_per_unit: the new scale setting.
+ *
+ * Sets the current scale of the canvas, i.e. the number of pixels to use
+ * for each device unit.
+ **/
void
goo_canvas_view_set_scale (GooCanvasView *view,
- gdouble scale)
+ gdouble pixels_per_unit)
{
gdouble x, y;
@@ -725,7 +792,7 @@
view->freeze_count++;
- view->scale = scale;
+ view->scale = pixels_per_unit;
reconfigure_canvas (view, FALSE);
/* Convert from the center point to the new desired top-left posision. */
@@ -751,6 +818,18 @@
}
+/**
+ * goo_canvas_view_set_anchor:
+ * @view: a #GooCanvasView.
+ * @anchor: the new anchor setting.
+ *
+ * Sets the anchor position of the canvas. This is the position that the
+ * canvas is placed in if it is smaller than the #GooCanvasView area.
+ *
+ * For example, if the anchor is set to %GTK_ANCHOR_CENTER, then the canvas
+ * will be displayed in the center of the #GooCanvasView widget when it is
+ * very small.
+ **/
void
goo_canvas_view_set_anchor (GooCanvasView *view,
GtkAnchorType anchor)
@@ -760,6 +839,23 @@
}
+/**
+ * goo_canvas_view_create_item_view:
+ * @view: a #GooCanvasView.
+ * @item: the item to create a view for.
+ * @parent_view: the parent view of the new item.
+ *
+ * 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.
+ *
+ * Returns: a new item view.
+ **/
GooCanvasItemView*
goo_canvas_view_create_item_view (GooCanvasView *view,
GooCanvasItem *item,
@@ -803,6 +899,15 @@
}
+/**
+ * goo_canvas_view_update:
+ * @view: a #GooCanvasView.
+ *
+ * Updates any item views that need updating.
+ *
+ * If the bounds of items change, they will request a redraw of the old and
+ * new bounds.
+ **/
void
goo_canvas_view_update (GooCanvasView *view)
{
@@ -830,6 +935,14 @@
}
+/**
+ * goo_canvas_view_request_update:
+ * @view: a #GooCanvasView.
+ *
+ * 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.
+ **/
void
goo_canvas_view_request_update (GooCanvasView *view)
{
@@ -847,6 +960,13 @@
}
+/**
+ * goo_canvas_view_request_redraw:
+ * @view: a #GooCanvasView.
+ * @bounds: the bounds to redraw.
+ *
+ * Requests that the given bounds be redrawn.
+ **/
void
goo_canvas_view_request_redraw (GooCanvasView *view,
GooCanvasBounds *bounds)
@@ -944,7 +1064,7 @@
* goo_canvas_view_render:
* @view: a #GooCanvasView.
* @cr: a cairo context.
- * @bounds: the area to render, or NULL to render the entire canvas.
+ * @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.
@@ -1456,6 +1576,13 @@
}
+/**
+ * goo_canvas_view_grab_focus:
+ * @canvas_view: a #GooCanvasView.
+ * @item_view: the item view to grab the focus.
+ *
+ * Grabs the keyboard focus for the given item.
+ **/
void
goo_canvas_view_grab_focus (GooCanvasView *canvas_view,
GooCanvasItemView *item_view)
@@ -1498,15 +1625,16 @@
/**
* goo_canvas_view_pointer_grab:
- * @canvas_view:
- * @item_view:
- * @event_mask:
- * @cursor:
- * @time:
- *
+ * @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.
*
+ * Attempts to grab the pointer for the given item view.
*
- * Returns:
+ * Returns: %GDK_GRAB_SUCCESS if the grab succeeded.
**/
GdkGrabStatus
goo_canvas_view_pointer_grab (GooCanvasView *canvas_view,
@@ -1548,11 +1676,12 @@
/**
* goo_canvas_view_pointer_ungrab:
- * @canvas_view:
- * @item_view:
- * @time:
- *
+ * @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.
*
+ * Ungrabs the pointer, if the given item view has the pointer grab.
**/
void
goo_canvas_view_pointer_ungrab (GooCanvasView *canvas_view,
@@ -1589,14 +1718,17 @@
/**
* goo_canvas_view_keyboard_grab:
- * @canvas_view:
- * @item_view:
- * @owner_events:
- * @time:
- *
+ * @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.
*
+ * Attempts to grab the keyboard for the given item view.
*
- * Returns:
+ * Returns: %GDK_GRAB_SUCCESS if the grab succeeded.
**/
GdkGrabStatus
goo_canvas_view_keyboard_grab (GooCanvasView *canvas_view,
@@ -1635,11 +1767,12 @@
/**
* goo_canvas_view_keyboard_ungrab:
- * @canvas_view:
- * @item_view:
- * @time:
- *
+ * @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.
*
+ * Ungrabs the keyboard, if the given item view has the keyboard grab.
**/
void
goo_canvas_view_keyboard_ungrab (GooCanvasView *canvas_view,
@@ -1667,7 +1800,7 @@
*/
/**
- * goo_canvas_view_device_to_pixel:
+ * goo_canvas_view_convert_to_pixels:
* @canvas_view: a #GooCanvasView.
* @x: a pointer to the x coordinate to convert.
* @y: a pointer to the y coordinate to convert.
Index: goocanvasview.h
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvasview.h,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -d -r1.5 -r1.6
--- goocanvasview.h 8 Apr 2006 13:14:17 -0000 1.5
+++ goocanvasview.h 14 Apr 2006 18:52:28 -0000 1.6
@@ -23,6 +23,11 @@
typedef struct _GooCanvasViewClass GooCanvasViewClass;
+/**
+ * GooCanvasView
+ *
+ * The #GooCanvasView-struct struct contains private data only.
+ */
struct _GooCanvasView
{
GtkContainer container;
More information about the cairo-commit
mailing list