[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