[cairo-commit] goocanvas/src goocanvasellipse.c, 1.1.1.1, 1.2 goocanvasellipse.h, 1.1.1.1, 1.2 goocanvasgroup.c, 1.3, 1.4 goocanvasgroup.h, 1.3, 1.4 goocanvasimage.c, 1.1.1.1, 1.2 goocanvasimage.h, 1.1.1.1, 1.2 goocanvaspath.c, 1.1, 1.2 goocanvaspath.h, 1.1, 1.2 goocanvaspolyline.c, 1.1.1.1, 1.2 goocanvaspolyline.h, 1.1.1.1, 1.2 goocanvasrect.c, 1.1.1.1, 1.2 goocanvasrect.h, 1.1.1.1, 1.2 goocanvastext.c, 1.1.1.1, 1.2 goocanvastext.h, 1.2, 1.3

Damon Chaplin commit at pdx.freedesktop.org
Thu Apr 13 09:06:06 PDT 2006


Committed by: damon

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

Modified Files:
	goocanvasellipse.c goocanvasellipse.h goocanvasgroup.c 
	goocanvasgroup.h goocanvasimage.c goocanvasimage.h 
	goocanvaspath.c goocanvaspath.h goocanvaspolyline.c 
	goocanvaspolyline.h goocanvasrect.c goocanvasrect.h 
	goocanvastext.c goocanvastext.h 
Log Message:
2006-04-13  Damon Chaplin  <damon at gnome.org>

	* src/*.c: documented standard items.



Index: goocanvasellipse.c
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvasellipse.c,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -u -d -r1.1.1.1 -r1.2
--- goocanvasellipse.c	15 Dec 2005 15:32:01 -0000	1.1.1.1
+++ goocanvasellipse.c	13 Apr 2006 16:06:04 -0000	1.2
@@ -4,8 +4,33 @@
  *
  * goocanvasellipse.c - ellipse item.
  */
+
+/**
+ * SECTION:goocanvasellipse
+ * @Title: GooCanvasEllipse
+ * @Short_Description: an ellipse item.
+ *
+ * GooCanvasEllipse represents an ellipse item.
+ *
+ * It is a subclass of #GooCanvasItemSimple and so inherits all of the style
+ * properties such as "stroke-color", "fill-color" and "line-width".
+ *
+ * It also implements the #GooCanvasItem interface, so you can use the
+ * #GooCanvasItem functions such as goo_canvas_item_raise() and
+ * goo_canvas_item_rotate().
+ *
+ * To create a #GooCanvasEllipse use goo_canvas_ellipse_new().
+ *
+ * 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 #GooCanvasEllipseView objects.
+ * (See #GooCanvasView::item-view-created.)
+ */
 #include <config.h>
 #include <math.h>
+#include <glib/gi18n-lib.h>
 #include <gtk/gtk.h>
 #include "goocanvasellipse.h"
 #include "goocanvasellipseview.h"
@@ -49,27 +74,31 @@
 
   g_object_class_install_property (gobject_class, PROP_CENTER_X,
 				   g_param_spec_double ("center-x",
-							NULL, NULL,
+							_("Center X"),
+							_("The x coordinate of the center of the ellipse"),
 							-G_MAXDOUBLE,
 							G_MAXDOUBLE, 0.0,
 							G_PARAM_READWRITE));
 
   g_object_class_install_property (gobject_class, PROP_CENTER_Y,
 				   g_param_spec_double ("center-y",
-							NULL, NULL,
+							_("Center Y"),
+							_("The y coordinate of the center of the ellipse"),
 							-G_MAXDOUBLE,
 							G_MAXDOUBLE, 0.0,
 							G_PARAM_READWRITE));
 
   g_object_class_install_property (gobject_class, PROP_RADIUS_X,
 				   g_param_spec_double ("radius-x",
-							NULL, NULL,
+							_("Radius X"),
+							_("The horizontal radius of the ellipse"),
 							0.0, G_MAXDOUBLE, 0.0,
 							G_PARAM_READWRITE));
 
   g_object_class_install_property (gobject_class, PROP_RADIUS_Y,
 				   g_param_spec_double ("radius-y",
-							NULL, NULL,
+							_("Radius Y"),
+							_("The vertical radius of the ellipse"),
 							0.0, G_MAXDOUBLE, 0.0,
 							G_PARAM_READWRITE));
 }
@@ -96,6 +125,20 @@
  *  %NULL.
  * 
  * Creates a new ellipse item.
+ *
+ * <!--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>
+ *  GooCanvasItem *ellipse = goo_canvas_ellipse_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 item.
  **/

Index: goocanvasellipse.h
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvasellipse.h,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -u -d -r1.1.1.1 -r1.2
--- goocanvasellipse.h	15 Dec 2005 15:32:01 -0000	1.1.1.1
+++ goocanvasellipse.h	13 Apr 2006 16:06:04 -0000	1.2
@@ -24,6 +24,11 @@
 typedef struct _GooCanvasEllipse       GooCanvasEllipse;
 typedef struct _GooCanvasEllipseClass  GooCanvasEllipseClass;
 
+/**
+ * GooCanvasEllipse
+ *
+ * The #GooCanvasEllipse-struct struct contains private data only.
+ */
 struct _GooCanvasEllipse
 {
   GooCanvasItemSimple parent;

Index: goocanvasgroup.c
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvasgroup.c,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -d -r1.3 -r1.4
--- goocanvasgroup.c	8 Apr 2006 13:14:17 -0000	1.3
+++ goocanvasgroup.c	13 Apr 2006 16:06:04 -0000	1.4
@@ -4,7 +4,31 @@
  *
  * goocanvasgroup.c - group item.
  */
+
+/**
+ * SECTION:goocanvasgroup
+ * @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 implements the #GooCanvasItem interface, so you can use the
+ * #GooCanvasItem functions such as goo_canvas_item_raise() and
+ * goo_canvas_item_rotate().
+ *
+ * To create a #GooCanvasGroup use goo_canvas_group_new().
+ *
+ * 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 #GooCanvasView::item-view-created.)
+ */
 #include <config.h>
+#include <glib/gi18n-lib.h>
 #include <gtk/gtk.h>
 #include "goocanvasgroup.h"
 #include "goocanvasgroupview.h"
@@ -58,7 +82,8 @@
 
   g_object_class_install_property (gobject_class, PROP_TRANSFORM,
 				   g_param_spec_boxed ("transform",
-						       NULL, NULL,
+						       _("Transform"),
+						       _("The transformation matrix of the item"),
 						       GOO_TYPE_CAIRO_MATRIX,
 						       G_PARAM_READWRITE));
 
@@ -70,12 +95,19 @@
 
   g_object_class_install_property (gobject_class, PROP_POINTER_EVENTS,
 				   g_param_spec_enum ("pointer-events",
-						      NULL, NULL,
+						      _("Pointer Events"),
+						      _("Specifies when the item receives pointer events"),
 						      GOO_TYPE_CANVAS_POINTER_EVENTS,
 						      GOO_CANVAS_EVENTS_VISIBLE_PAINTED,
 						      G_PARAM_READWRITE));
 
   /* Signals. */
+
+  /**
+   * GooCanvasGroup::changed
+   *
+   * Emitted when the group is changed.
+   */
   group_signals[CHANGED] =
     g_signal_new ("changed",
 		  G_TYPE_FROM_CLASS (gobject_class),

Index: goocanvasgroup.h
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvasgroup.h,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -d -r1.3 -r1.4
--- goocanvasgroup.h	8 Apr 2006 13:14:17 -0000	1.3
+++ goocanvasgroup.h	13 Apr 2006 16:06:04 -0000	1.4
@@ -25,6 +25,11 @@
 typedef struct _GooCanvasGroup       GooCanvasGroup;
 typedef struct _GooCanvasGroupClass  GooCanvasGroupClass;
 
+/**
+ * GooCanvasGroup
+ *
+ * The #GooCanvasGroup-struct struct contains private data only.
+ */
 struct _GooCanvasGroup
 {
   GObject object;

Index: goocanvasimage.c
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvasimage.c,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -u -d -r1.1.1.1 -r1.2
--- goocanvasimage.c	15 Dec 2005 15:32:01 -0000	1.1.1.1
+++ goocanvasimage.c	13 Apr 2006 16:06:04 -0000	1.2
@@ -4,7 +4,32 @@
  *
  * goocanvasimage.c - image item.
  */
+
+/**
+ * SECTION:goocanvasimage
+ * @Title: GooCanvasImage
+ * @Short_Description: an image item.
+ *
+ * GooCanvasImage represents an image item.
+ *
+ * It is a subclass of #GooCanvasItemSimple and so inherits all of the style
+ * properties such as "operator" and "pointer-events".
+ *
+ * It also implements the #GooCanvasItem interface, so you can use the
+ * #GooCanvasItem functions such as goo_canvas_item_raise() and
+ * goo_canvas_item_rotate().
+ *
+ * To create a #GooCanvasImage use goo_canvas_image_new().
+ *
+ * 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 #GooCanvasView::item-view-created.)
+ */
 #include <config.h>
+#include <glib/gi18n-lib.h>
 #include <gtk/gtk.h>
 #include "goocanvasimage.h"
 #include "goocanvasimageview.h"
@@ -53,39 +78,45 @@
 
   g_object_class_install_property (gobject_class, PROP_PATTERN,
                                    g_param_spec_boxed ("pattern",
-						       NULL, NULL,
+						       _("Pattern"),
+						       _("The cairo pattern to paint"),
 						       GOO_TYPE_CAIRO_PATTERN,
 						       G_PARAM_READWRITE));
 
   g_object_class_install_property (gobject_class, PROP_X,
 				   g_param_spec_double ("x",
-							NULL, NULL,
+							"X",
+							_("The x coordinate of the image"),
 							-G_MAXDOUBLE,
 							G_MAXDOUBLE, 0.0,
 							G_PARAM_READWRITE));
 
   g_object_class_install_property (gobject_class, PROP_Y,
 				   g_param_spec_double ("y",
-							NULL, NULL,
+							"Y",
+							_("The y coordinate of the image"),
 							-G_MAXDOUBLE,
 							G_MAXDOUBLE, 0.0,
 							G_PARAM_READWRITE));
 
   g_object_class_install_property (gobject_class, PROP_WIDTH,
 				   g_param_spec_double ("width",
-							NULL, NULL,
+							_("Width"),
+							_("The width of the image"),
 							0.0, G_MAXDOUBLE, 0.0,
 							G_PARAM_READWRITE));
 
   g_object_class_install_property (gobject_class, PROP_HEIGHT,
 				   g_param_spec_double ("height",
-							NULL, NULL,
+							_("Height"),
+							_("The height of the image"),
 							0.0, G_MAXDOUBLE, 0.0,
 							G_PARAM_READWRITE));
 
   g_object_class_install_property (gobject_class, PROP_PIXBUF,
 				   g_param_spec_object ("pixbuf",
-							NULL, NULL,
+							_("Pixbuf"),
+							_("The GdkPixbuf to display"),
 							GDK_TYPE_PIXBUF,
 							G_PARAM_WRITABLE));
 }
@@ -103,7 +134,7 @@
  * @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.
- * @pixbuf: the #GdkPixbuf containing the image data.
+ * @pixbuf: the #GdkPixbuf containing the image data, or %NULL.
  * @x: the x coordinate of the image.
  * @y: the y coordinate of the image.
  * @first_property: the name of the first property to set, or %NULL.
@@ -112,6 +143,16 @@
  * 
  * Creates a new image item.
  * 
+ * <!--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>
+ *  GooCanvasItem *image = goo_canvas_image_new (mygroup, pixbuf, 100.0, 100.0,
+ *                                               NULL);
+ * </programlisting></informalexample>
+ *
  * Returns: a new image item.
  **/
 GooCanvasItem*

Index: goocanvasimage.h
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvasimage.h,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -u -d -r1.1.1.1 -r1.2
--- goocanvasimage.h	15 Dec 2005 15:32:01 -0000	1.1.1.1
+++ goocanvasimage.h	13 Apr 2006 16:06:04 -0000	1.2
@@ -24,6 +24,11 @@
 typedef struct _GooCanvasImage       GooCanvasImage;
 typedef struct _GooCanvasImageClass  GooCanvasImageClass;
 
+/**
+ * GooCanvasImage
+ *
+ * The #GooCanvasImage-struct struct contains private data only.
+ */
 struct _GooCanvasImage
 {
   GooCanvasItemSimple parent;

Index: goocanvaspath.c
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvaspath.c,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -d -r1.1 -r1.2
--- goocanvaspath.c	10 Apr 2006 20:30:24 -0000	1.1
+++ goocanvaspath.c	13 Apr 2006 16:06:04 -0000	1.2
@@ -4,7 +4,37 @@
  *
  * goocanvaspath.c - a path item, very similar to the SVG path element.
  */
+
+/**
+ * SECTION:goocanvaspath
+ * @Title: GooCanvasPath
+ * @Short_Description: a path item (a series of lines and curves).
+ *
+ * GooCanvasPath represents a path item, which is a series of one or more
+ * lines, bezier curves, or elliptical arcs.
+ *
+ * It is a subclass of #GooCanvasItemSimple and so inherits all of the style
+ * properties such as "stroke-color", "fill-color" and "line-width".
+ *
+ * It also implements the #GooCanvasItem interface, so you can use the
+ * #GooCanvasItem functions such as goo_canvas_item_raise() and
+ * goo_canvas_item_rotate().
+ *
+ * #GooCanvasPath 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 #GooCanvasPath use goo_canvas_path_new().
+ *
+ * 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 #GooCanvasView::item-view-created.)
+ */
 #include <config.h>
+#include <glib/gi18n-lib.h>
 #include <gtk/gtk.h>
 #include "goocanvaspath.h"
 #include "goocanvaspathview.h"
@@ -43,9 +73,17 @@
   gobject_class->get_property = goo_canvas_path_get_property;
   gobject_class->set_property = goo_canvas_path_set_property;
 
+  /**
+   * GooCanvasPath: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.
+   */
   g_object_class_install_property (gobject_class, PROP_DATA,
 				   g_param_spec_string ("data",
-							NULL, NULL,
+							_("Path Data"),
+							_("The sequence of path commands"),
 							NULL,
 							G_PARAM_WRITABLE));
 }
@@ -350,12 +388,46 @@
  * @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.
- * @path_data: a string specifying the path, using the same syntax as the path
- *  element in SVG.
+ * @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 item.
  * 
+ * <!--PARAMETERS-->
+ *
+ * Here's an example showing how to create a red line from (20,20) to (40,40):
+ *
+ * <informalexample><programlisting>
+ *  GooCanvasItem *path = goo_canvas_path_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>
+ *  GooCanvasItem *path = goo_canvas_path_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>
+ *  GooCanvasItem *path = goo_canvas_path_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 item.
  **/
 GooCanvasItem*

Index: goocanvaspath.h
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvaspath.h,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -d -r1.1 -r1.2
--- goocanvaspath.h	10 Apr 2006 20:30:24 -0000	1.1
+++ goocanvaspath.h	13 Apr 2006 16:06:04 -0000	1.2
@@ -21,6 +21,11 @@
 #define GOO_CANVAS_PATH_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj), GOO_TYPE_CANVAS_PATH, GooCanvasPathClass))
 
 
+/**
+ * GooCanvasPathCommandType
+ *
+ * GooCanvasPathCommandType specifies the type of each command in the path.
+ */
 typedef enum
 {
   /* Simple commands like moveto and lineto: MmZzLlHhVv. */
@@ -45,6 +50,16 @@
 
 /* Note that the command type is always the first element in each struct, so
    we can always use it whatever type of command it is. */
+
+/**
+ * GooCanvasPathCommand
+ *
+ * GooCanvasPathCommand holds the data for each command in the path.
+ *
+ * The @relative flag specifies that the coordinates for the command are
+ * relative to the current point. Otherwise they are assumed to be absolute
+ * coordinates.
+ */
 union _GooCanvasPathCommand
 {
   /* Simple commands like moveto and lineto: MmZzLlHhVv. */
@@ -75,13 +90,18 @@
 typedef struct _GooCanvasPath       GooCanvasPath;
 typedef struct _GooCanvasPathClass  GooCanvasPathClass;
 
+/**
+ * GooCanvasPath
+ * @commands: an array of #GooCanvasPathCommand holding the specification of
+ *  the path. Applications can modify this directly, but must call
+ *  goo_canvas_item_simple_emit_changed() afterwards to notify the
+ *  views that the #GooCanvasPath has changed.
+ */
 struct _GooCanvasPath
 {
   GooCanvasItemSimple parent;
 
-  /* The path data, an array of GooCanvasPathCommand. Apps can modify this
-     directly, but call goo_canvas_item_simple_emit_changed (item, TRUE)
-     afterwards to notify the views. */
+  /*< public >*/
   GArray *commands;
 };
 

Index: goocanvaspolyline.c
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvaspolyline.c,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -u -d -r1.1.1.1 -r1.2
--- goocanvaspolyline.c	15 Dec 2005 15:32:02 -0000	1.1.1.1
+++ goocanvaspolyline.c	13 Apr 2006 16:06:04 -0000	1.2
@@ -4,10 +4,36 @@
  *
  * goocanvaspolyline.c - polyline item, with optional arrows.
  */
+
+/**
+ * SECTION:goocanvaspolyline
+ * @Title: GooCanvasPolyline
+ * @Short_Description: a polyline item (a series of lines with optional arrows).
+ *
+ * GooCanvasPolyline represents a polyline item, which is a series of one or
+ * more lines, with optional arrows at either end.
+ *
+ * It is a subclass of #GooCanvasItemSimple and so inherits all of the style
+ * properties such as "stroke-color", "fill-color" and "line-width".
+ *
+ * It also implements the #GooCanvasItem interface, so you can use the
+ * #GooCanvasItem functions such as goo_canvas_item_raise() and
+ * goo_canvas_item_rotate().
+ *
+ * To create a #GooCanvasPolyline use goo_canvas_polyline_new().
+ *
+ * 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 #GooCanvasView::item-view-created.)
+ */
 #include <config.h>
 #include <math.h>
 #include <stdarg.h>
 #include <string.h>
+#include <glib/gi18n-lib.h>
 #include <gtk/gtk.h>
 #include "goocanvaspolyline.h"
 #include "goocanvaspolylineview.h"
@@ -128,44 +154,51 @@
 
   g_object_class_install_property (gobject_class, PROP_POINTS,
 				   g_param_spec_boxed ("points",
-						       NULL, NULL,
+						       _("Points"),
+						       _("The array of points"),
 						       GOO_TYPE_CANVAS_POINTS,
 						       G_PARAM_READWRITE));
 
   g_object_class_install_property (gobject_class, PROP_CLOSE_PATH,
 				   g_param_spec_boolean ("close-path",
-							 NULL, NULL,
+							 _("Close Path"),
+							 _("If the last point should be connected to the first"),
 							 FALSE,
 							 G_PARAM_READWRITE));
 
   g_object_class_install_property (gobject_class, PROP_START_ARROW,
 				   g_param_spec_boolean ("start-arrow",
-							 NULL, NULL,
+							 _("Start Arrow"),
+							 _("If an arrow should be displayed at the start of the polyline"),
 							 FALSE,
 							 G_PARAM_READWRITE));
 
   g_object_class_install_property (gobject_class, PROP_END_ARROW,
 				   g_param_spec_boolean ("end-arrow",
-							 NULL, NULL,
+							 _("End Arrow"),
+							 _("If an arrow should be displayed at the end of the polyline"),
 							 FALSE,
 							 G_PARAM_READWRITE));
 
   g_object_class_install_property (gobject_class, PROP_ARROW_LENGTH,
 				   g_param_spec_double ("arrow-length",
-							NULL, NULL,
-							0.0, G_MAXDOUBLE, 0.0,
+							_("Arrow Length"),
+							_("The length of the arrows, as a multiple of the line width"),
+							0.0, G_MAXDOUBLE, 5.0,
 							G_PARAM_READWRITE));
 
   g_object_class_install_property (gobject_class, PROP_ARROW_WIDTH,
 				   g_param_spec_double ("arrow-width",
-							NULL, NULL,
-							0.0, G_MAXDOUBLE, 0.0,
+							_("Arrow Width"),
+							_("The width of the arrows, as a multiple of the line width"),
+							0.0, G_MAXDOUBLE, 4.0,
 							G_PARAM_READWRITE));
 
   g_object_class_install_property (gobject_class, PROP_ARROW_TIP_LENGTH,
 				   g_param_spec_double ("arrow-tip-length",
-							NULL, NULL,
-							0.0, G_MAXDOUBLE, 0.0,
+							_("Arrow Tip Length"),
+							_("The length of the arrow tip, as a multiple of the line width"),
+							0.0, G_MAXDOUBLE, 4.0,
 							G_PARAM_READWRITE));
 }
 
@@ -480,13 +513,29 @@
  * @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.
- * @close_path: whether the path should be closed.
+ * @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 item.
  * 
+ * <!--PARAMETERS-->
+ *
+ * Here's an example showing how to create a filled triangle with vertices
+ * at (100,100), (300,100), and (200,300).
+ *
+ * <informalexample><programlisting>
+ *  GooCanvasItem *polyline = goo_canvas_polyline_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 item.
  **/
 GooCanvasItem*
@@ -543,6 +592,19 @@
  * 
  * Creates a new polyline item with a single line.
  * 
+ * <!--PARAMETERS-->
+ *
+ * Here's an example showing how to create a line from (100,100) to (300,300).
+ *
+ * <informalexample><programlisting>
+ *  GooCanvasItem *polyline = goo_canvas_polyline_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 item.
  **/
 GooCanvasItem*

Index: goocanvaspolyline.h
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvaspolyline.h,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -u -d -r1.1.1.1 -r1.2
--- goocanvaspolyline.h	15 Dec 2005 15:32:00 -0000	1.1.1.1
+++ goocanvaspolyline.h	13 Apr 2006 16:06:04 -0000	1.2
@@ -51,6 +51,11 @@
 typedef struct _GooCanvasPolyline       GooCanvasPolyline;
 typedef struct _GooCanvasPolylineClass  GooCanvasPolylineClass;
 
+/**
+ * GooCanvasPolyline
+ *
+ * The #GooCanvasPolyline-struct struct contains private data only.
+ */
 struct _GooCanvasPolyline
 {
   GooCanvasItemSimple parent;

Index: goocanvasrect.c
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvasrect.c,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -u -d -r1.1.1.1 -r1.2
--- goocanvasrect.c	15 Dec 2005 15:32:01 -0000	1.1.1.1
+++ goocanvasrect.c	13 Apr 2006 16:06:04 -0000	1.2
@@ -4,7 +4,32 @@
  *
  * goocanvasrect.c - rectangle item.
  */
+
+/**
+ * SECTION:goocanvasrect
+ * @Title: GooCanvasRect
+ * @Short_Description: a rectangle item.
+ *
+ * GooCanvasRect represents a rectangle item.
+ *
+ * It is a subclass of #GooCanvasItemSimple and so inherits all of the style
+ * properties such as "stroke-color", "fill-color" and "line-width".
+ *
+ * It also implements the #GooCanvasItem interface, so you can use the
+ * #GooCanvasItem functions such as goo_canvas_item_raise() and
+ * goo_canvas_item_rotate().
+ *
+ * To create a #GooCanvasRect use goo_canvas_rect_new().
+ *
+ * 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 #GooCanvasRectView objects.
+ * (See #GooCanvasView::item-view-created.)
+ */
 #include <config.h>
+#include <glib/gi18n-lib.h>
 #include <gtk/gtk.h>
 #include "goocanvasrect.h"
 #include "goocanvasrectview.h"
@@ -50,39 +75,45 @@
 
   g_object_class_install_property (gobject_class, PROP_X,
 				   g_param_spec_double ("x",
-							NULL, NULL,
+							"X",
+							_("The x coordinate of the rectangle"),
 							-G_MAXDOUBLE,
 							G_MAXDOUBLE, 0.0,
 							G_PARAM_READWRITE));
 
   g_object_class_install_property (gobject_class, PROP_Y,
 				   g_param_spec_double ("y",
-							NULL, NULL,
+							"Y",
+							_("The y coordinate of the rectangle"),
 							-G_MAXDOUBLE,
 							G_MAXDOUBLE, 0.0,
 							G_PARAM_READWRITE));
 
   g_object_class_install_property (gobject_class, PROP_WIDTH,
 				   g_param_spec_double ("width",
-							NULL, NULL,
+							_("Width"),
+							_("The width of the rectangle"),
 							0.0, G_MAXDOUBLE, 0.0,
 							G_PARAM_READWRITE));
 
   g_object_class_install_property (gobject_class, PROP_HEIGHT,
 				   g_param_spec_double ("height",
-							NULL, NULL,
+							_("Height"),
+							_("The height of the rectangle"),
 							0.0, G_MAXDOUBLE, 0.0,
 							G_PARAM_READWRITE));
 
   g_object_class_install_property (gobject_class, PROP_RADIUS_X,
 				   g_param_spec_double ("radius_x",
-							NULL, NULL,
+							_("Radius X"),
+							_("The horizontal radius to use for rounded corners"),
 							0.0, G_MAXDOUBLE, 0.0,
 							G_PARAM_READWRITE));
 
   g_object_class_install_property (gobject_class, PROP_RADIUS_Y,
 				   g_param_spec_double ("radius_y",
-							NULL, NULL,
+							_("Radius Y"),
+							_("The vertical radius to use for rounded corners"),
 							0.0, G_MAXDOUBLE, 0.0,
 							G_PARAM_READWRITE));
 }
@@ -110,6 +141,19 @@
  * 
  * 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>
+ *  GooCanvasItem *rect = goo_canvas_rect_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 item.
  **/
 GooCanvasItem*

Index: goocanvasrect.h
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvasrect.h,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -u -d -r1.1.1.1 -r1.2
--- goocanvasrect.h	15 Dec 2005 15:32:01 -0000	1.1.1.1
+++ goocanvasrect.h	13 Apr 2006 16:06:04 -0000	1.2
@@ -24,6 +24,11 @@
 typedef struct _GooCanvasRect       GooCanvasRect;
 typedef struct _GooCanvasRectClass  GooCanvasRectClass;
 
+/**
+ * GooCanvasRect
+ *
+ * The #GooCanvasRect-struct struct contains private data only.
+ */
 struct _GooCanvasRect
 {
   GooCanvasItemSimple parent;

Index: goocanvastext.c
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvastext.c,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -u -d -r1.1.1.1 -r1.2
--- goocanvastext.c	15 Dec 2005 15:32:01 -0000	1.1.1.1
+++ goocanvastext.c	13 Apr 2006 16:06:04 -0000	1.2
@@ -2,9 +2,34 @@
  * GooCanvas. Copyright (C) 2005 Damon Chaplin.
  * Released under the GNU LGPL license. See COPYING for details.
  *
- * goocanvastext.c - 
+ * goocanvastext.c - text item.
+ */
+
+/**
+ * SECTION:goocanvastext
+ * @Title: GooCanvasText
+ * @Short_Description: a text item.
+ *
+ * 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".
+ *
+ * It also implements the #GooCanvasItem interface, so you can use the
+ * #GooCanvasItem functions such as goo_canvas_item_raise() and
+ * goo_canvas_item_rotate().
+ *
+ * To create a #GooCanvasText use goo_canvas_text_new().
+ *
+ * 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 #GooCanvasView::item-view-created.)
  */
 #include <config.h>
+#include <glib/gi18n-lib.h>
 #include <gtk/gtk.h>
 #include "goocanvastext.h"
 #include "goocanvastextview.h"
@@ -54,48 +79,55 @@
   /* Text */
   g_object_class_install_property (gobject_class, PROP_TEXT,
 				   g_param_spec_string ("text",
-							NULL, NULL,
+							_("Text"),
+							_("The text to display"),
 							NULL,
 							G_PARAM_READWRITE));
 
   g_object_class_install_property (gobject_class, PROP_USE_MARKUP,
 				   g_param_spec_boolean ("use-markup",
-							 NULL, NULL,
+							 _("Use Markup"),
+							 _("Whether to parse PangoMarkup in the text, to support different styles"),
 							 FALSE,
 							 G_PARAM_READWRITE));
 
   /* Position */
   g_object_class_install_property (gobject_class, PROP_X,
 				   g_param_spec_double ("x",
-							NULL, NULL,
+							"X",
+							_("The x coordinate of the text"),
 							-G_MAXDOUBLE,
 							G_MAXDOUBLE, 0.0,
 							G_PARAM_READWRITE));
 
   g_object_class_install_property (gobject_class, PROP_Y,
 				   g_param_spec_double ("y",
-							NULL, NULL,
+							"Y",
+							_("The y coordinate of the text"),
 							-G_MAXDOUBLE,
 							G_MAXDOUBLE, 0.0,
 							G_PARAM_READWRITE));
 
   g_object_class_install_property (gobject_class, PROP_WIDTH,
 				   g_param_spec_double ("width",
-							NULL, NULL,
+							_("Width"),
+							_("The width to use to layout the text"),
 							-G_MAXDOUBLE,
-							G_MAXDOUBLE, 0.0,
+							G_MAXDOUBLE, -1.0,
 							G_PARAM_READWRITE));
 
   g_object_class_install_property (gobject_class, PROP_ANCHOR,
 				   g_param_spec_enum ("anchor",
-						      NULL, NULL,
+						      _("Anchor"),
+						      _("How to position the text relative to the given x and y coordinates"),
 						      GTK_TYPE_ANCHOR_TYPE,
-						      GTK_ANCHOR_CENTER,
+						      GTK_ANCHOR_NW,
 						      G_PARAM_READWRITE));
 
   g_object_class_install_property (gobject_class, PROP_ALIGN,
 				   g_param_spec_enum ("alignment",
-						      NULL, NULL,
+						      _("Alignment"),
+						      _("How to align the text"),
 						      PANGO_TYPE_ALIGNMENT,
 						      PANGO_ALIGN_LEFT,
 						      G_PARAM_READWRITE));
@@ -103,22 +135,25 @@
   /* Font */
   g_object_class_install_property (gobject_class, PROP_FONT,
 				   g_param_spec_string ("font",
-							NULL, NULL,
+							_("Font"),
+							_("The base font to use for the text"),
 							NULL,
 							G_PARAM_READWRITE));
 
   g_object_class_install_property (gobject_class, PROP_FONT_DESC,
 				   g_param_spec_boxed ("font-desc",
-						       NULL, NULL,
+						       _("Font Description"),
+						       _("The attributes specifying which font to use"),
 						       PANGO_TYPE_FONT_DESCRIPTION,
 						       G_PARAM_READWRITE));
 }
 
 
 static void
-goo_canvas_text_init (GooCanvasText *canvas_text)
+goo_canvas_text_init (GooCanvasText *text)
 {
-
+  text->width = -1.0;
+  text->anchor = GTK_ANCHOR_NW;
 }
 
 
@@ -128,13 +163,13 @@
  *  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 anchor.
- * @y: the y coordinate of the text anchor.
+ * @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 anchor with respect to the bounding box
- *  of the text. For example an anchor of GDK_ANCHOR_NW will result in the
+ * @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
+ *  An anchor of %GDK_ANCHOR_CENTER will result in the center of the text being
  *  placed at the @x and @y coordinates.
  * @first_property: the name of the first property to set, or %NULL.
  * @...: the remaining property names and values to set, terminated with a
@@ -142,6 +177,17 @@
  * 
  * Creates a new text item.
  * 
+ * <!--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>
+ *  GooCanvasItem *text = goo_canvas_text_new (mygroup, "Hello World", 500.0, 500.0, 200.0, GTK_ANCHOR_SE,
+ *                                             "fill-color", "blue",
+ *                                             NULL);
+ * </programlisting></informalexample>
+ * 
  * Returns: a new text item.
  **/
 GooCanvasItem*

Index: goocanvastext.h
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvastext.h,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- goocanvastext.h	12 Apr 2006 10:42:20 -0000	1.2
+++ goocanvastext.h	13 Apr 2006 16:06:04 -0000	1.3
@@ -2,7 +2,7 @@
  * GooCanvas. Copyright (C) 2005 Damon Chaplin.
  * Released under the GNU LGPL license. See COPYING for details.
  *
- * goocanvastext.h - 
+ * goocanvastext.h - text item.
  */
 #ifndef __GOO_CANVAS_TEXT_H__
 #define __GOO_CANVAS_TEXT_H__
@@ -24,6 +24,11 @@
 typedef struct _GooCanvasText       GooCanvasText;
 typedef struct _GooCanvasTextClass  GooCanvasTextClass;
 
+/**
+ * GooCanvasText
+ *
+ * The #GooCanvasText-struct struct contains private data only.
+ */
 struct _GooCanvasText
 {
   GooCanvasItemSimple parent;



More information about the cairo-commit mailing list