goocanvas r42 - in trunk: . src

[damon svn gnome org]

Author: damon
Date: Sun Mar 15 15:51:24 2009
New Revision: 42
URL: http://svn.gnome.org/viewvc/goocanvas?rev=42&view=rev

Log:

2009-03-15  Damon Chaplin  <damon gnome org>

	    * src/goocanvasgrid.c: improved section docs.

	    * src/goocanvas.c: improved a few function docs.



Modified:
   trunk/ChangeLog
   trunk/src/goocanvas.c
   trunk/src/goocanvasgrid.c

Modified: trunk/src/goocanvas.c
==============================================================================
--- trunk/src/goocanvas.c	(original)
+++ trunk/src/goocanvas.c	Sun Mar 15 15:51:24 2009
@@ -1014,6 +1014,13 @@
  *
  * Gets the static root item of the canvas.
  *
+ * Static items are exactly the same as ordinary canvas items, except that
+ * they do not move or change size when the canvas is scrolled or the scale
+ * changes.
+ *
+ * Static items are added to the static root item in exactly the same way that
+ * ordinary items are added to the root item.
+ *
  * Returns: the static root item, or %NULL.
  **/
 GooCanvasItem*
@@ -1031,6 +1038,13 @@
  * @item: the static root item.
  *
  * Sets the static root item. Any existing static items are removed.
+ *
+ * Static items are exactly the same as ordinary canvas items, except that
+ * they do not move or change size when the canvas is scrolled or the scale
+ * changes.
+ *
+ * Static items are added to the static root item in exactly the same way that
+ * ordinary items are added to the root item.
  **/
 void
 goo_canvas_set_static_root_item    (GooCanvas		*canvas,
@@ -1075,6 +1089,13 @@
  *
  * Gets the static root item model of the canvas.
  *
+ * Static item models are exactly the same as ordinary item models, except that
+ * the corresponding items do not move or change size when the canvas is
+ * scrolled or the scale changes.
+ *
+ * Static items models are added to the static root item model in exactly the
+ * same way that ordinary item models are added to the root item model.
+ *
  * Returns: the static root item model, or %NULL.
  **/
 GooCanvasItemModel*
@@ -1093,6 +1114,13 @@
  *
  * Sets the static root item model. Any existing static item models are
  * removed.
+ *
+ * Static item models are exactly the same as ordinary item models, except that
+ * the corresponding items do not move or change size when the canvas is
+ * scrolled or the scale changes.
+ *
+ * Static items models are added to the static root item model in exactly the
+ * same way that ordinary item models are added to the root item model.
  **/
 void
 goo_canvas_set_static_root_item_model (GooCanvas	  *canvas,
@@ -2523,7 +2551,8 @@
  * This function is only intended to be used by subclasses of #GooCanvas or
  * #GooCanvasItem implementations.
  *
- * Requests that the given bounds be redrawn.
+ * Requests that the given bounds be redrawn. The bounds must be in the canvas
+ * coordinate space.
  **/
 void
 goo_canvas_request_redraw (GooCanvas             *canvas,
@@ -2562,8 +2591,12 @@
  * This function is only intended to be used by subclasses of #GooCanvas or
  * #GooCanvasItem implementations.
  *
- * Requests that the given bounds be redrawn. If the item is static the bounds are assumed to
- * be in the static item coordinate space, otherwise they are assumed to be in device space.
+ * Requests that the given bounds be redrawn. If @is_static is %TRUE the bounds
+ * are assumed to be in the static item coordinate space, otherwise they are
+ * assumed to be in the canvas coordinate space.
+ *
+ * If @is_static is %FALSE this function behaves the same as
+ * goo_canvas_request_redraw().
  **/
 void
 goo_canvas_request_item_redraw (GooCanvas             *canvas,
@@ -3671,11 +3704,11 @@
  * goo_canvas_convert_bounds_to_item_space:
  * @canvas: a #GooCanvas.
  * @item: a #GooCanvasItem.
- * @bounds: the bounds in device space.
+ * @bounds: the bounds in canvas coordinate space, to be converted.
  * 
- * Converts the bound in device space to a bounding box in item space.
- * This is useful in the item paint() methods to convert the bounds to be
- * painted to the item's coordinate space.
+ * Converts the given bounds in the canvas coordinate space to a bounding box
+ * in item space. This is useful in the item paint() methods to convert the
+ * bounds to be painted to the item's coordinate space.
  **/
 void
 goo_canvas_convert_bounds_to_item_space (GooCanvas           *canvas,

Modified: trunk/src/goocanvasgrid.c
==============================================================================
--- trunk/src/goocanvasgrid.c	(original)
+++ trunk/src/goocanvasgrid.c	Sun Mar 15 15:51:24 2009
@@ -11,6 +11,8 @@
  * @Short_Description: a grid item.
  *
  * GooCanvasGrid represents a grid item.
+ * A grid consists of a number of equally-spaced horizontal and vertical
+ * grid lines, plus an optional border.
  *
  * It is a subclass of #GooCanvasItemSimple and so inherits all of the style
  * properties such as "stroke-color", "fill-color" and "line-width".
@@ -23,6 +25,28 @@
  *
  * To get or set the properties of an existing #GooCanvasGrid, use
  * g_object_get() and g_object_set().
+ *
+ * The grid's position and size is specified with the #GooCanvasGrid:x,
+ * #GooCanvasGrid:y, #GooCanvasGrid:width and #GooCanvasGrid:height properties.
+ *
+ * The #GooCanvasGrid:x-step and #GooCanvasGrid:y-step properties specify the 
+ * distance between grid lines. The  #GooCanvasGrid:x-offset and
+ * #GooCanvasGrid:y-offset properties specify the distance before the first
+ * grid lines.
+ *
+ * The horizontal or vertical grid lines can be hidden using the
+ * #GooCanvasGrid:show-horz-grid-lines and #GooCanvasGrid:show-vert-grid-lines
+ * properties.
+ *
+ * The width of the border can be set using the #GooCanvasGrid:border-width
+ * property. The border is drawn outside the area specified with the
+ * #GooCanvasGrid:x, #GooCanvasGrid:y, #GooCanvasGrid:width and
+ * #GooCanvasGrid:height properties.
+ *
+ * Other properties allow the colors and widths of the grid lines to be set.
+ * The grid line color and width properties override the standard
+ * #GooCanvasItemSimple:stroke-color and #GooCanvasItemSimple:line-width
+ * properties, enabling different styles for horizontal and vertical grid lines.
  */
 #include <config.h>
 #include <math.h>
@@ -926,6 +950,8 @@
  * @Short_Description: a model for grid items.
  *
  * GooCanvasGridModel represents a model for grid items.
+ * A grid consists of a number of equally-spaced horizontal and vertical
+ * grid lines, plus an optional border.
  *
  * It is a subclass of #GooCanvasItemModelSimple and so inherits all of the
  * style properties such as "stroke-color", "fill-color" and "line-width".
@@ -942,6 +968,30 @@
  * To respond to events such as mouse clicks on the grid you must connect
  * to the signal handlers of the corresponding #GooCanvasGrid objects.
  * (See goo_canvas_get_item() and #GooCanvas::item-created.)
+ *
+ * The grid's position and size is specified with the #GooCanvasGridModel:x,
+ * #GooCanvasGridModel:y, #GooCanvasGridModel:width and
+ * #GooCanvasGridModel:height properties.
+ *
+ * The #GooCanvasGridModel:x-step and #GooCanvasGridModel:y-step properties
+ * specify the distance between grid lines. The  #GooCanvasGridModel:x-offset
+ * and #GooCanvasGridModel:y-offset properties specify the distance before the
+ * first grid lines.
+ *
+ * The horizontal or vertical grid lines can be hidden using the
+ * #GooCanvasGridModel:show-horz-grid-lines and
+ * #GooCanvasGridModel:show-vert-grid-lines properties.
+ *
+ * The width of the border can be set using the #GooCanvasGridModel:border-width
+ * property. The border is drawn outside the area specified with the
+ * #GooCanvasGridModel:x, #GooCanvasGridModel:y, #GooCanvasGridModel:width and
+ * #GooCanvasGridModel:height properties.
+ *
+ * Other properties allow the colors and widths of the grid lines to be set.
+ * The grid line color and width properties override the standard
+ * #GooCanvasItemModelSimple:stroke-color and
+ * #GooCanvasItemModelSimple:line-width properties, enabling different styles
+ * for horizontal and vertical grid lines.
  */
 
 GooCanvasItemModelIface *goo_canvas_grid_model_parent_iface;