[cairo-commit] goocanvas/src goocanvas.c, 1.2, 1.3 goocanvasellipse.c, 1.7, 1.8 goocanvasgroup.c, 1.16, 1.17 goocanvasimage.c, 1.10, 1.11 goocanvaspath.c, 1.8, 1.9 goocanvaspolyline.c, 1.9, 1.10 goocanvasrect.c, 1.7, 1.8 goocanvastable.c, 1.3, 1.4 goocanvastext.c, 1.9, 1.10 goocanvaswidget.c, 1.2, 1.3

Damon Chaplin commit at pdx.freedesktop.org
Fri Feb 2 13:54:05 PST 2007


Committed by: damon

Update of /cvs/cairo/goocanvas/src
In directory kemper:/tmp/cvs-serv26001/src

Modified Files:
	goocanvas.c goocanvasellipse.c goocanvasgroup.c 
	goocanvasimage.c goocanvaspath.c goocanvaspolyline.c 
	goocanvasrect.c goocanvastable.c goocanvastext.c 
	goocanvaswidget.c 
Log Message:
2007-02-02  Damon Chaplin  <damon at gnome.org>

	* */*: updated docs for all canvas items & models.



Index: goocanvas.c
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvas.c,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- goocanvas.c	1 Feb 2007 01:19:05 -0000	1.2
+++ goocanvas.c	2 Feb 2007 21:54:00 -0000	1.3
@@ -1591,7 +1591,7 @@
  * Subclasses of #GooCanvas 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
+ * It emits the "item-created" signal after creating the view, so
  * application code can connect signal handlers to the new view if desired.
  * 
  * Returns: a new canvas item.

Index: goocanvasellipse.c
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvasellipse.c,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -d -r1.7 -r1.8
--- goocanvasellipse.c	29 Nov 2006 18:40:53 -0000	1.7
+++ goocanvasellipse.c	2 Feb 2007 21:54:00 -0000	1.8
@@ -23,10 +23,6 @@
  *
  * To get or set the properties of an existing #GooCanvasEllipse, use
  * g_object_get() and g_object_set().
- *
- * To respond to events such as mouse clicks on the ellipse you must connect
- * to the signal handlers of the corresponding #GooCanvasEllipse objects.
- * (See goo_canvas_get_item_view() and #GooCanvas::item-view-created.)
  */
 #include <config.h>
 #include <math.h>
@@ -341,8 +337,28 @@
 }
 
 
-/*
- * GooCanvasEllipseModel.
+/**
+ * SECTION:goocanvasellipsemodel
+ * @Title: GooCanvasEllipseModel
+ * @Short_Description: a model for ellipse items.
+ *
+ * GooCanvasEllipseModel represents a model for ellipse items.
+ *
+ * It is a subclass of #GooCanvasItemModelSimple and so inherits all of the
+ * style properties such as "stroke-color", "fill-color" and "line-width".
+ *
+ * It also implements the #GooCanvasItemModel interface, so you can use the
+ * #GooCanvasItemModel functions such as goo_canvas_item_model_raise() and
+ * goo_canvas_item_model_rotate().
+ *
+ * To create a #GooCanvasEllipseModel use goo_canvas_ellipse_model_new().
+ *
+ * To get or set the properties of an existing #GooCanvasEllipseModel, use
+ * g_object_get() and g_object_set().
+ *
+ * To respond to events such as mouse clicks on the ellipse you must connect
+ * to the signal handlers of the corresponding #GooCanvasEllipse objects.
+ * (See goo_canvas_get_item() and #GooCanvas::item-created.)
  */
 
 static void item_model_interface_init (GooCanvasItemModelIface *iface);
@@ -383,6 +399,35 @@
 }
 
 
+/**
+ * goo_canvas_ellipse_model_new:
+ * @parent: the parent model, or %NULL. If a parent is specified, it will
+ *  assume ownership of the item, and the item will automatically be freed when
+ *  it is removed from the parent. Otherwise call g_object_unref() to free it.
+ * @center_x: the x coordinate of the center of the ellipse.
+ * @center_y: the y coordinate of the center of the ellipse.
+ * @radius_x: the horizontal radius of the ellipse.
+ * @radius_y: the vertical radius of the ellipse.
+ * @...: optional pairs of property names and values, and a terminating %NULL.
+ * 
+ * Creates a new ellipse model.
+ *
+ * <!--PARAMETERS-->
+ *
+ * Here's an example showing how to create an ellipse centered at (100.0,
+ * 100.0), with a horizontal radius of 50.0 and a vertical radius of 30.0.
+ * It is drawn with a red outline with a width of 5.0 and filled with blue:
+ *
+ * <informalexample><programlisting>
+ *  GooCanvasItemModel *ellipse = goo_canvas_ellipse_model_new (mygroup, 100.0, 100.0, 50.0, 30.0,
+ *                                                              "stroke-color", "red",
+ *                                                              "line-width", 5.0,
+ *                                                              "fill-color", "blue",
+ *                                                              NULL);
+ * </programlisting></informalexample>
+ * 
+ * Returns: a new ellipse model.
+ **/
 GooCanvasItemModel*
 goo_canvas_ellipse_model_new (GooCanvasItemModel *parent,
 			      gdouble             center_x,

Index: goocanvasgroup.c
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvasgroup.c,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -d -r1.16 -r1.17
--- goocanvasgroup.c	1 Feb 2007 01:19:05 -0000	1.16
+++ goocanvasgroup.c	2 Feb 2007 21:54:00 -0000	1.17
@@ -10,12 +10,18 @@
  * @Title: GooCanvasGroup
  * @Short_Description: a group of items.
  *
- * #GooCanvasGroup represents a group of items. Groups can be nested to any
- * depth, to create a hierarchy of items. Items are ordered within each group,
- * with later items being displayed above earlier items.
+ * #GooCanvasGroup represents a group of items. Groups can be nested to
+ * any depth, to create a hierarchy of items. Items are ordered within each
+ * group, with later items being displayed above earlier items.
  *
- * #GooCanvasGroup implements the #GooCanvasItem interface, so you can use the
- * #GooCanvasItem functions such as goo_canvas_item_raise() and
+ * #GooCanvasGroup is a subclass of #GooCanvasItemSimple and so
+ * inherits all of the style properties such as "stroke-color", "fill-color"
+ * and "line-width". Setting a style property on a #GooCanvasGroup will affect
+ * all children of the #GooCanvasGroup (unless the children override the
+ * property setting).
+ *
+ * #GooCanvasGroup implements the #GooCanvasItem interface, so you can use
+ * the #GooCanvasItem functions such as goo_canvas_item_raise() and
  * goo_canvas_item_rotate(), and the properties such as "visibility" and
  * "pointer-events".
  *
@@ -23,10 +29,6 @@
  *
  * To get or set the properties of an existing #GooCanvasGroup, use
  * g_object_get() and g_object_set().
- *
- * To respond to events such as mouse clicks on the group you must connect
- * to the signal handlers of the corresponding #GooCanvasGroupView objects.
- * (See goo_canvas_get_item_view() and #GooCanvas::item-created.)
  */
 #include <config.h>
 #include <glib/gi18n-lib.h>
@@ -508,16 +510,22 @@
 /**
  * SECTION:goocanvasgroupmodel
  * @Title: GooCanvasGroupModel
- * @Short_Description: model for a group of items.
+ * @Short_Description: a model for a group of items.
  *
- * #GooCanvasGroupModel represents a group of items. Groups can be nested to any
- * depth, to create a hierarchy of items. Items are ordered within each group,
- * with later items being displayed above earlier items.
+ * #GooCanvasGroupModel represents a group of items. Groups can be nested to
+ * any depth, to create a hierarchy of items. Items are ordered within each
+ * group, with later items being displayed above earlier items.
  *
- * #GooCanvasGroupModel implements the #GooCanvasItem interface, so you can use the
- * #GooCanvasItem functions such as goo_canvas_item_raise() and
- * goo_canvas_item_rotate(), and the properties such as "visibility" and
- * "pointer-events".
+ * #GooCanvasGroupModel is a subclass of #GooCanvasItemModelSimple and so
+ * inherits all of the style properties such as "stroke-color", "fill-color"
+ * and "line-width". Setting a style property on a #GooCanvasGroupModel will
+ * affect all children of the #GooCanvasGroupModel (unless the children
+ * override the property setting).
+ *
+ * #GooCanvasGroupModel implements the #GooCanvasItemModel interface, so you
+ * can use the #GooCanvasItemModel functions such as
+ * goo_canvas_item_model_raise() and goo_canvas_item_model_rotate(), and the
+ * properties such as "visibility" and "pointer-events".
  *
  * To create a #GooCanvasGroupModel use goo_canvas_group_model_new().
  *
@@ -525,8 +533,8 @@
  * g_object_get() and g_object_set().
  *
  * To respond to events such as mouse clicks on the group you must connect
- * to the signal handlers of the corresponding #GooCanvasGroupModelView objects.
- * (See goo_canvas_view_get_item_view() and #GooCanvasView::item-view-created.)
+ * to the signal handlers of the corresponding #GooCanvasGroup objects.
+ * (See goo_canvas_get_item() and #GooCanvas::item-created.)
  */
 static void item_model_interface_init (GooCanvasItemModelIface *iface);
 static void goo_canvas_group_model_finalize     (GObject            *object);
@@ -555,14 +563,14 @@
 
 /**
  * goo_canvas_group_model_new:
- * @parent: the parent item, or %NULL. If a parent is specified, it will assume
- *  ownership of the item, and the item will automatically be freed when it is
- *  removed from the parent. Otherwise call g_object_unref() to free it.
+ * @parent: the parent model, or %NULL. If a parent is specified, it will
+ *  assume ownership of the item, and the item will automatically be freed when
+ *  it is removed from the parent. Otherwise call g_object_unref() to free it.
  * @...: optional pairs of property names and values, and a terminating %NULL.
  * 
  * Creates a new group item.
  * 
- * Return value: a new group item.
+ * Return value: a new group model.
  **/
 GooCanvasItemModel*
 goo_canvas_group_model_new (GooCanvasItemModel *parent,

Index: goocanvasimage.c
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvasimage.c,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -d -r1.10 -r1.11
--- goocanvasimage.c	1 Feb 2007 01:19:05 -0000	1.10
+++ goocanvasimage.c	2 Feb 2007 21:54:00 -0000	1.11
@@ -23,10 +23,6 @@
  *
  * To get or set the properties of an existing #GooCanvasImage, use
  * g_object_get() and g_object_set().
- *
- * To respond to events such as mouse clicks on the image you must connect
- * to the signal handlers of the corresponding #GooCanvasImageView objects.
- * (See goo_canvas_get_item_view() and #GooCanvasView::item-view-created.)
  */
 #include <config.h>
 #include <glib/gi18n-lib.h>
@@ -425,8 +421,28 @@
 
 
 
-/*
- * GooCanvasImageModel.
+/**
+ * SECTION:goocanvasimagemodel
+ * @Title: GooCanvasImageModel
+ * @Short_Description: a model for image items.
+ *
+ * GooCanvasImageModel represent a model for image items.
+ *
+ * It is a subclass of #GooCanvasItemModelSimple and so inherits all of the
+ * style properties such as "operator" and "pointer-events".
+ *
+ * It also implements the #GooCanvasItemModel interface, so you can use the
+ * #GooCanvasItemModel functions such as goo_canvas_item_model_raise() and
+ * goo_canvas_item_model_rotate().
+ *
+ * To create a #GooCanvasImageModel use goo_canvas_image_model_new().
+ *
+ * To get or set the properties of an existing #GooCanvasImageModel, use
+ * g_object_get() and g_object_set().
+ *
+ * To respond to events such as mouse clicks on the image you must connect
+ * to the signal handlers of the corresponding #GooCanvasImage objects.
+ * (See goo_canvas_get_item() and #GooCanvas::item-created.)
  */
 
 static void item_model_interface_init (GooCanvasItemModelIface *iface);
@@ -467,6 +483,30 @@
 }
 
 
+/**
+ * goo_canvas_image_model_new:
+ * @parent: the parent model, or %NULL. If a parent is specified, it will
+ *  assume ownership of the item, and the item will automatically be freed when
+ *  it is removed from the parent. Otherwise call g_object_unref() to free it.
+ * @pixbuf: the #GdkPixbuf containing the image data, or %NULL.
+ * @x: the x coordinate of the image.
+ * @y: the y coordinate of the image.
+ * @...: optional pairs of property names and values, and a terminating %NULL.
+ * 
+ * Creates a new image model.
+ * 
+ * <!--PARAMETERS-->
+ *
+ * Here's an example showing how to create an image at (100.0, 100.0), using
+ * the given pixbuf at its natural width and height:
+ *
+ * <informalexample><programlisting>
+ *  GooCanvasItemModel *image = goo_canvas_image_model_new (mygroup, pixbuf, 100.0, 100.0,
+ *                                                          NULL);
+ * </programlisting></informalexample>
+ *
+ * Returns: a new image model.
+ **/
 GooCanvasItemModel*
 goo_canvas_image_model_new (GooCanvasItemModel *parent,
 			    GdkPixbuf          *pixbuf,

Index: goocanvaspath.c
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvaspath.c,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -d -r1.8 -r1.9
--- goocanvaspath.c	29 Nov 2006 18:40:53 -0000	1.8
+++ goocanvaspath.c	2 Feb 2007 21:54:00 -0000	1.9
@@ -28,10 +28,6 @@
  *
  * To get or set the properties of an existing #GooCanvasPath, use
  * g_object_get() and g_object_set().
- *
- * To respond to events such as mouse clicks on the path you must connect
- * to the signal handlers of the corresponding #GooCanvasPathView objects.
- * (See goo_canvas_get_item_view() and #GooCanvasView::item-view-created.)
  */
 #include <config.h>
 #include <math.h>
@@ -940,8 +936,33 @@
 }
 
 
-/*
- * GooCanvasPathModel.
+/**
+ * SECTION:goocanvaspathmodel
+ * @Title: GooCanvasPathModel
+ * @Short_Description: a model for path items (a series of lines and curves).
+ *
+ * GooCanvasPathModel represents a model for path items, which are a series of
+ * one or more lines, bezier curves, or elliptical arcs.
+ *
+ * It is a subclass of #GooCanvasItemModelSimple and so inherits all of the
+ * style properties such as "stroke-color", "fill-color" and "line-width".
+ *
+ * It also implements the #GooCanvasItemModel interface, so you can use the
+ * #GooCanvasItemModel functions such as goo_canvas_item_model_raise() and
+ * goo_canvas_item_model_rotate().
+ *
+ * #GooCanvasPathModel uses the same path specification strings as the Scalable
+ * Vector Graphics (SVG) path element. For details see the
+ * <ulink url="http://www.w3.org/Graphics/SVG/">SVG specification</ulink>.
+ *
+ * To create a #GooCanvasPathModel use goo_canvas_path_model_new().
+ *
+ * To get or set the properties of an existing #GooCanvasPathModel, use
+ * g_object_get() and g_object_set().
+ *
+ * To respond to events such as mouse clicks on the path you must connect
+ * to the signal handlers of the corresponding #GooCanvasPath objects.
+ * (See goo_canvas_get_item() and #GooCanvas::item-created.)
  */
 
 static void item_model_interface_init (GooCanvasItemModelIface *iface);
@@ -982,6 +1003,53 @@
 }
 
 
+/**
+ * goo_canvas_path_model_new:
+ * @parent: the parent model, or %NULL. If a parent is specified, it will
+ *  assume ownership of the item, and the item will automatically be freed when
+ *  it is removed from the parent. Otherwise call g_object_unref() to free it.
+ * @path_data: the sequence of path commands, specified as a string using the
+ *  same syntax as in the <ulink url="http://www.w3.org/Graphics/SVG/">Scalable
+ *  Vector Graphics (SVG)</ulink> path element.
+ * @...: optional pairs of property names and values, and a terminating %NULL.
+ * 
+ * Creates a new path model.
+ * 
+ * <!--PARAMETERS-->
+ *
+ * Here's an example showing how to create a red line from (20,20) to (40,40):
+ *
+ * <informalexample><programlisting>
+ *  GooCanvasItemModel *path = goo_canvas_path_model_new (mygroup,
+ *                                                        "M 20 20 L 40 40",
+ *                                                        "stroke-color", "red",
+ *                                                        NULL);
+ * </programlisting></informalexample>
+ * 
+ * This example creates a cubic bezier curve from (20,100) to (100,100) with
+ * the control points at (20,50) and (100,50):
+ *
+ * <informalexample><programlisting>
+ *  GooCanvasItemModel *path = goo_canvas_path_model_new (mygroup,
+ *                                                        "M20,100 C20,50 100,50 100,100",
+ *                                                        "stroke-color", "blue",
+ *                                                        NULL);
+ * </programlisting></informalexample>
+ *
+ * This example uses an elliptical arc to create a filled circle with one
+ * quarter missing:
+ * 
+ * <informalexample><programlisting>
+ *  GooCanvasItemModel *path = goo_canvas_path_model_new (mygroup,
+ *                                                        "M200,500 h-150 a150,150 0 1,0 150,-150 z",
+ *                                                        "fill-color", "red",
+ *                                                        "stroke-color", "blue",
+ *                                                        "line-width", 5.0,
+ *                                                        NULL);
+ * </programlisting></informalexample>
+ * 
+ * Returns: a new path model.
+ **/
 GooCanvasItemModel*
 goo_canvas_path_model_new (GooCanvasItemModel *parent,
 			   const gchar        *path_data,

Index: goocanvaspolyline.c
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvaspolyline.c,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -d -r1.9 -r1.10
--- goocanvaspolyline.c	1 Feb 2007 01:19:05 -0000	1.9
+++ goocanvaspolyline.c	2 Feb 2007 21:54:00 -0000	1.10
@@ -20,14 +20,11 @@
  * #GooCanvasItem functions such as goo_canvas_item_raise() and
  * goo_canvas_item_rotate().
  *
- * To create a #GooCanvasPolyline use goo_canvas_polyline_new().
+ * To create a #GooCanvasPolyline use goo_canvas_polyline_new(), or
+ * goo_canvas_polyline_new_line() for a simple line between two points.
  *
  * To get or set the properties of an existing #GooCanvasPolyline, use
  * g_object_get() and g_object_set().
- *
- * To respond to events such as mouse clicks on the polyline you must connect
- * to the signal handlers of the corresponding #GooCanvasPolylineView objects.
- * (See goo_canvas_get_item_view() and #GooCanvasView::item-view-created.)
  */
 #include <config.h>
 #include <math.h>
@@ -982,8 +979,31 @@
 }
 
 
-/*
- * GooCanvasPolylineModel.
+/**
+ * SECTION:goocanvaspolylinemodel
+ * @Title: GooCanvasPolylineModel
+ * @Short_Description: a model for polyline items (a series of lines with
+ *  optional arrows).
+ *
+ * GooCanvasPolylineModel represents a model for polyline items, which are a
+ * series of one or more lines, with optional arrows at either end.
+ *
+ * It is a subclass of #GooCanvasItemModelSimple and so inherits all of the
+ * style properties such as "stroke-color", "fill-color" and "line-width".
+ *
+ * It also implements the #GooCanvasItemModel interface, so you can use the
+ * #GooCanvasItemModel functions such as goo_canvas_item_model_raise() and
+ * goo_canvas_item_model_rotate().
+ *
+ * To create a #GooCanvasPolylineModel use goo_canvas_polyline_model_new(), or
+ * goo_canvas_polyline_model_new_line() for a simple line between two points.
+ *
+ * To get or set the properties of an existing #GooCanvasPolylineModel, use
+ * g_object_get() and g_object_set().
+ *
+ * To respond to events such as mouse clicks on the polyline you must connect
+ * to the signal handlers of the corresponding #GooCanvasPolyline objects.
+ * (See goo_canvas_get_item() and #GooCanvas::item-created.)
  */
 
 static void item_model_interface_init (GooCanvasItemModelIface *iface);
@@ -1024,6 +1044,36 @@
 }
 
 
+/**
+ * goo_canvas_polyline_model_new:
+ * @parent: the parent model, or %NULL. If a parent is specified, it will
+ *  assume ownership of the item, and the item will automatically be freed when
+ *  it is removed from the parent. Otherwise call g_object_unref() to free it.
+ * @close_path: if the last point should be connected to the first.
+ * @num_points: the number of points in the polyline.
+ * @...: the pairs of coordinates for each point in the line, followed by
+ *  optional pairs of property names and values, and a terminating %NULL.
+ * 
+ * Creates a new polyline model.
+ * 
+ * <!--PARAMETERS-->
+ *
+ * Here's an example showing how to create a filled triangle with vertices
+ * at (100,100), (300,100), and (200,300).
+ *
+ * <informalexample><programlisting>
+ *  GooCanvasItemModel *polyline = goo_canvas_polyline_model_new (mygroup, TRUE, 3,
+ *                                                                100.0, 100.0,
+ *                                                                300.0, 100.0,
+ *                                                                200.0, 300.0,
+ *                                                                "stroke-color", "red",
+ *                                                                "line-width", 5.0,
+ *                                                                "fill-color", "blue",
+ *                                                                NULL);
+ * </programlisting></informalexample>
+ * 
+ * Returns: a new polyline model.
+ **/
 GooCanvasItemModel*
 goo_canvas_polyline_model_new (GooCanvasItemModel *parent,
 			       gboolean            close_path,
@@ -1065,6 +1115,32 @@
 }
 
 
+/**
+ * goo_canvas_polyline_model_new_line:
+ * @parent: the parent model, or %NULL.
+ * @x1: the x coordinate of the start of the line.
+ * @y1: the y coordinate of the start of the line.
+ * @x2: the x coordinate of the end of the line.
+ * @y2: the y coordinate of the end of the line.
+ * @...: optional pairs of property names and values, and a terminating %NULL.
+ * 
+ * Creates a new polyline model with a single line.
+ * 
+ * <!--PARAMETERS-->
+ *
+ * Here's an example showing how to create a line from (100,100) to (300,300).
+ *
+ * <informalexample><programlisting>
+ *  GooCanvasItemModel *polyline = goo_canvas_polyline_model_new_line (mygroup,
+ *                                                                     100.0, 100.0,
+ *                                                                     300.0, 300.0,
+ *                                                                     "stroke-color", "red",
+ *                                                                     "line-width", 5.0,
+ *                                                                     NULL);
+ * </programlisting></informalexample>
+ * 
+ * Returns: a new polyline model.
+ **/
 GooCanvasItemModel*
 goo_canvas_polyline_model_new_line (GooCanvasItemModel *parent,
 				    gdouble             x1,

Index: goocanvasrect.c
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvasrect.c,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -d -r1.7 -r1.8
--- goocanvasrect.c	29 Nov 2006 18:40:53 -0000	1.7
+++ goocanvasrect.c	2 Feb 2007 21:54:00 -0000	1.8
@@ -23,10 +23,6 @@
  *
  * To get or set the properties of an existing #GooCanvasRect, use
  * g_object_get() and g_object_set().
- *
- * To respond to events such as mouse clicks on the rect you must connect
- * to the signal handlers of the corresponding #GooCanvasRect objects.
- * (See goo_canvas_get_item_view() and #GooCanvas::item-view-created.)
  */
 #include <config.h>
 #include <math.h>
@@ -427,8 +423,28 @@
 }
 
 
-/*
- * GooCanvasRectModel.
+/**
+ * SECTION:goocanvasrectmodel
+ * @Title: GooCanvasRectModel
+ * @Short_Description: a model for rectangle items.
+ *
+ * GooCanvasRectModel represents a model for rectangle items.
+ *
+ * It is a subclass of #GooCanvasItemModelSimple and so inherits all of the
+ * style properties such as "stroke-color", "fill-color" and "line-width".
+ *
+ * It also implements the #GooCanvasItemModel interface, so you can use the
+ * #GooCanvasItemModel functions such as goo_canvas_item_model_raise() and
+ * goo_canvas_item_model_rotate().
+ *
+ * To create a #GooCanvasRectModel use goo_canvas_rect_model_new().
+ *
+ * To get or set the properties of an existing #GooCanvasRectModel, use
+ * g_object_get() and g_object_set().
+ *
+ * To respond to events such as mouse clicks on the rectangle you must connect
+ * to the signal handlers of the corresponding #GooCanvasRect objects.
+ * (See goo_canvas_get_item() and #GooCanvas::item-created.)
  */
 
 static void item_model_interface_init (GooCanvasItemModelIface *iface);
@@ -466,6 +482,34 @@
 }
 
 
+/**
+ * goo_canvas_rect_model_new:
+ * @parent: the parent model, or %NULL. If a parent is specified, it will
+ *  assume ownership of the item, and the item will automatically be freed when
+ *  it is removed from the parent. Otherwise call g_object_unref() to free it.
+ * @x: the x coordinate of the left of the rectangle.
+ * @y: the y coordinate of the top of the rectangle.
+ * @width: the width of the rectangle.
+ * @height: the height of the rectangle.
+ * @...: optional pairs of property names and values, and a terminating %NULL.
+ * 
+ * Creates a new rectangle item.
+ * 
+ * <!--PARAMETERS-->
+ *
+ * Here's an example showing how to create a rectangle at (100,100) with a
+ * width of 200 and a height of 100.
+ *
+ * <informalexample><programlisting>
+ *  GooCanvasItemModel *rect = goo_canvas_rect_model_new (mygroup, 100.0, 100.0, 200.0, 100.0,
+ *                                                        "stroke-color", "red",
+ *                                                        "line-width", 5.0,
+ *                                                        "fill-color", "blue",
+ *                                                        NULL);
+ * </programlisting></informalexample>
+ * 
+ * Returns: a new rectangle model.
+ **/
 GooCanvasItemModel*
 goo_canvas_rect_model_new (GooCanvasItemModel *parent,
 			   gdouble             x,

Index: goocanvastable.c
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvastable.c,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -d -r1.3 -r1.4
--- goocanvastable.c	1 Feb 2007 01:19:05 -0000	1.3
+++ goocanvastable.c	2 Feb 2007 21:54:00 -0000	1.4
@@ -4,6 +4,38 @@
  *
  * goocanvastable.c - table item.
  */
+
+/**
+ * SECTION:goocanvastable
+ * @Title: GooCanvasTable
+ * @Short_Description: a table container to layout items.
+ *
+ * #GooCanvasTable is a table container used to lay out other canvas items.
+ * It is used in a similar way to how the GtkTable widget is used to lay out
+ * GTK+ widgets.
+ *
+ * Items are added to the table using the normal methods, then
+ * goo_canvas_item_set_child_properties() is used to specify how each child
+ * item is to be positioned within the table (i.e. which row and column it is
+ * in, how much padding it should have and whether it should expand or
+ * shrink).
+ *
+ * #GooCanvasTable is a subclass of #GooCanvasItemSimple and so
+ * inherits all of the style properties such as "stroke-color", "fill-color"
+ * and "line-width". Setting a style property on a #GooCanvasTable will affect
+ * all children of the #GooCanvasTable (unless the children override the
+ * property setting).
+ *
+ * #GooCanvasTable implements the #GooCanvasItem interface, so you can use
+ * the #GooCanvasItem functions such as goo_canvas_item_raise() and
+ * goo_canvas_item_rotate(), and the properties such as "visibility" and
+ * "pointer-events".
+ *
+ * To create a #GooCanvasTable use goo_canvas_table_new().
+ *
+ * To get or set the properties of an existing #GooCanvasTable, use
+ * g_object_get() and g_object_set().
+ */
 #include <config.h>
 #include <string.h>
 #include <glib/gi18n-lib.h>
@@ -333,6 +365,57 @@
 }
 
 
+/**
+ * goo_canvas_table_new:
+ * @parent: the parent item, or %NULL. If a parent is specified, it will assume
+ *  ownership of the item, and the item will automatically be freed when it is
+ *  removed from the parent. Otherwise call g_object_unref() to free it.
+ * @...: optional pairs of property names and values, and a terminating %NULL.
+ * 
+ * Creates a new table item.
+ *
+ * <!--PARAMETERS-->
+ *
+ * Here's an example showing how to create a table with a square, a circle and
+ * a triangle in it:
+ *
+ * <informalexample><programlisting>
+ *  GooCanvasItem *table, *square, *circle, *triangle;
+ *
+ *  table = goo_canvas_table_new (root,
+ *                                "row-spacing", 4.0,
+ *                                "column-spacing", 4.0,
+ *                                NULL);
+ *  goo_canvas_item_translate (table, 400, 200);
+ *
+ *  square = goo_canvas_rect_new (table, 0.0, 0.0, 50.0, 50.0,
+ *                                "fill-color", "red",
+ *                                NULL);
+ *  goo_canvas_item_set_child_properties (table, square,
+ *                                        "row", 0,
+ *                                        "column", 0,
+ *                                        NULL);
+ *
+ *  circle = goo_canvas_ellipse_new (table, 0.0, 0.0, 25.0, 25.0,
+ *                                   "fill-color", "blue",
+ *                                   NULL);
+ *  goo_canvas_item_set_child_properties (table, circle,
+ *                                        "row", 0,
+ *                                        "column", 1,
+ *                                        NULL);
+ *
+ *  triangle = goo_canvas_polyline_new (table, TRUE, 3,
+ *                                      25.0, 0.0, 0.0, 50.0, 50.0, 50.0,
+ *                                      "fill-color", "yellow",
+ *                                      NULL);
+ *  goo_canvas_item_set_child_properties (table, triangle,
+ *                                        "row", 0,
+ *                                        "column", 2,
+ *                                        NULL);
+ * </programlisting></informalexample>
+ * 
+ * Returns: a new table item.
+ **/
 GooCanvasItem*
 goo_canvas_table_new (GooCanvasItem  *parent,
 		      ...)
@@ -1821,7 +1904,37 @@
 
 
 
-
+/**
+ * SECTION:goocanvastablemodel
+ * @Title: GooCanvasTableModel
+ * @Short_Description: a model for a table container to layout items.
+ *
+ * #GooCanvasTableModel is a model for a table container used to lay out other
+ * canvas items. It is used in a similar way to how the GtkTable widget is used
+ * to lay out GTK+ widgets.
+ *
+ * Item models are added to the table using the normal methods, then
+ * goo_canvas_item_model_set_child_properties() is used to specify how each
+ * child item is to be positioned within the table (i.e. which row and column
+ * it is in, how much padding it should have and whether it should expand or
+ * shrink).
+ *
+ * #GooCanvasTableModel is a subclass of #GooCanvasItemModelSimple and so
+ * inherits all of the style properties such as "stroke-color", "fill-color"
+ * and "line-width". Setting a style property on a #GooCanvasTableModel will
+ * affect all children of the #GooCanvasTableModel (unless the children
+ * override the property setting).
+ *
+ * #GooCanvasTableModel implements the #GooCanvasItemModel interface, so you
+ * can use the #GooCanvasItemModel functions such as
+ * goo_canvas_item_model_raise() and goo_canvas_item_rotate(), and the
+ * properties such as "visibility" and "pointer-events".
+ *
+ * To create a #GooCanvasTableModel use goo_canvas_table_model_new().
+ *
+ * To get or set the properties of an existing #GooCanvasTableModel, use
+ * g_object_get() and g_object_set().
+ */
 
 static void item_model_interface_init (GooCanvasItemModelIface *iface);
 static void goo_canvas_table_model_finalize (GObject *object);
@@ -1861,6 +1974,57 @@
 }
 
 
+/**
+ * goo_canvas_table_model_new:
+ * @parent: the parent model, or %NULL. If a parent is specified, it will
+ *  assume ownership of the item, and the item will automatically be freed when
+ *  it is removed from the parent. Otherwise call g_object_unref() to free it.
+ * @...: optional pairs of property names and values, and a terminating %NULL.
+ * 
+ * Creates a new table model.
+ *
+ * <!--PARAMETERS-->
+ *
+ * Here's an example showing how to create a table with a square, a circle and
+ * a triangle in it:
+ *
+ * <informalexample><programlisting>
+ *  GooCanvasItemModel *table, *square, *circle, *triangle;
+ *
+ *  table = goo_canvas_table_model_new (root,
+ *                                      "row-spacing", 4.0,
+ *                                      "column-spacing", 4.0,
+ *                                      NULL);
+ *  goo_canvas_item_model_translate (table, 400, 200);
+ *
+ *  square = goo_canvas_rect_model_new (table, 0.0, 0.0, 50.0, 50.0,
+ *                                      "fill-color", "red",
+ *                                      NULL);
+ *  goo_canvas_item_model_set_child_properties (table, square,
+ *                                              "row", 0,
+ *                                              "column", 0,
+ *                                              NULL);
+ *
+ *  circle = goo_canvas_ellipse_model_new (table, 0.0, 0.0, 25.0, 25.0,
+ *                                         "fill-color", "blue",
+ *                                         NULL);
+ *  goo_canvas_item_model_set_child_properties (table, circle,
+ *                                              "row", 0,
+ *                                              "column", 1,
+ *                                              NULL);
+ *
+ *  triangle = goo_canvas_polyline_model_new (table, TRUE, 3,
+ *                                            25.0, 0.0, 0.0, 50.0, 50.0, 50.0,
+ *                                            "fill-color", "yellow",
+ *                                            NULL);
+ *  goo_canvas_item_model_set_child_properties (table, triangle,
+ *                                              "row", 0,
+ *                                              "column", 2,
+ *                                              NULL);
+ * </programlisting></informalexample>
+ * 
+ * Returns: a new table model.
+ **/
 GooCanvasItemModel*
 goo_canvas_table_model_new (GooCanvasItemModel *parent,
 			    ...)

Index: goocanvastext.c
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvastext.c,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -d -r1.9 -r1.10
--- goocanvastext.c	1 Feb 2007 01:19:05 -0000	1.9
+++ goocanvastext.c	2 Feb 2007 21:54:00 -0000	1.10
@@ -13,7 +13,7 @@
  * GooCanvasText represents a text item.
  *
  * It is a subclass of #GooCanvasItemSimple and so inherits all of the style
- * properties such as "stroke-color", "fill-color" and "line-width".
+ * properties such as "fill-color".
  *
  * It also implements the #GooCanvasItem interface, so you can use the
  * #GooCanvasItem functions such as goo_canvas_item_raise() and
@@ -23,10 +23,6 @@
  *
  * To get or set the properties of an existing #GooCanvasText, use
  * g_object_get() and g_object_set().
- *
- * To respond to events such as mouse clicks on the text you must connect
- * to the signal handlers of the corresponding #GooCanvasTextView objects.
- * (See goo_canvas_get_item_view() and #GooCanvas::item-view-created.)
  */
 #include <config.h>
 #include <glib/gi18n-lib.h>
@@ -632,8 +628,28 @@
 
 
 
-/*
- * GooCanvasTextModel.
+/**
+ * SECTION:goocanvastextmodel
+ * @Title: GooCanvasTextModel
+ * @Short_Description: a model for text items.
+ *
+ * GooCanvasTextModel represents a model for text items.
+ *
+ * It is a subclass of #GooCanvasItemModelSimple and so inherits all of the
+ * style properties such as "fill-color".
+ *
+ * It also implements the #GooCanvasItemModel interface, so you can use the
+ * #GooCanvasItemModel functions such as goo_canvas_item_model_raise() and
+ * goo_canvas_item_model_rotate().
+ *
+ * To create a #GooCanvasTextModel use goo_canvas_text_model_new().
+ *
+ * To get or set the properties of an existing #GooCanvasTextModel, use
+ * g_object_get() and g_object_set().
+ *
+ * To respond to events such as mouse clicks on the text item you must connect
+ * to the signal handlers of the corresponding #GooCanvasText objects.
+ * (See goo_canvas_get_item() and #GooCanvas::item-created.)
  */
 
 static void item_model_interface_init (GooCanvasItemModelIface *iface);
@@ -674,6 +690,37 @@
 }
 
 
+/**
+ * goo_canvas_text_model_new:
+ * @parent: the parent model, or %NULL. If a parent is specified, it will
+ *  assume ownership of the item, and the item will automatically be freed when
+ *  it is removed from the parent. Otherwise call g_object_unref() to free it.
+ * @string: the text to display.
+ * @x: the x coordinate of the text.
+ * @y: the y coordinate of the text.
+ * @width: the width of the text item, or -1 for unlimited width.
+ * @anchor: the position of the text relative to the given @x and @y
+ *  coordinates. For example an anchor of %GDK_ANCHOR_NW will result in the
+ *  top-left of the text being placed at the given @x and @y coordinates.
+ *  An anchor of %GDK_ANCHOR_CENTER will result in the center of the text being
+ *  placed at the @x and @y coordinates.
+ * @...: optional pairs of property names and values, and a terminating %NULL.
+ * 
+ * Creates a new text model.
+ * 
+ * <!--PARAMETERS-->
+ *
+ * Here's an example showing how to create a text item with the bottom right
+ * of the text box placed at (500,500):
+ *
+ * <informalexample><programlisting>
+ *  GooCanvasItemModel *text = goo_canvas_text_model_new (mygroup, "Hello World", 500.0, 500.0, 200.0, GTK_ANCHOR_SE,
+ *                                                        "fill-color", "blue",
+ *                                                        NULL);
+ * </programlisting></informalexample>
+ * 
+ * Returns: a new text model.
+ **/
 GooCanvasItemModel*
 goo_canvas_text_model_new (GooCanvasItemModel *parent,
 			   const char         *string,

Index: goocanvaswidget.c
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvaswidget.c,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- goocanvaswidget.c	1 Feb 2007 01:19:05 -0000	1.2
+++ goocanvaswidget.c	2 Feb 2007 21:54:00 -0000	1.3
@@ -14,17 +14,19 @@
  *
  * Note that there are a number of limitations in the use of #GooCanvasWidget:
  *
- * 1) It doesn't support any transformation besides simple translation.
+ * <itemizedlist><listitem><para>
+ * It doesn't support any transformation besides simple translation.
  * This means you can't scale a canvas with a #GooCanvasWidget in it.
- *
- * 2) It doesn't support layering, so you can't place other items beneath
+ * </para></listitem><listitem><para>
+ * It doesn't support layering, so you can't place other items beneath
  * or above the #GooCanvasWidget.
- *
- * 3) It doesn't support rendering of widgets to a given cairo_t, which
+ * </para></listitem><listitem><para>
+ * It doesn't support rendering of widgets to a given cairo_t, which
  * means you can't output the widget to a pdf or postscript file.
- *
- * 4) It doesn't have a model/view variant like the other standard items,
+ * </para></listitem><listitem><para>
+ * It doesn't have a model/view variant like the other standard items,
  * so it can only be used in a simple canvas without a model.
+ * </para></listitem></itemizedlist>
  */
 #include <config.h>
 #include <glib/gi18n-lib.h>



More information about the cairo-commit mailing list