[cairo-commit]
goocanvas/src goocanvas.c, 1.14, 1.15 goocanvasitem.c,
1.26, 1.27 goocanvasitemmodel.c, 1.12,
1.13 goocanvasitemsimple.c, 1.28, 1.29
Damon Chaplin
commit at pdx.freedesktop.org
Wed Mar 7 08:07:18 PST 2007
Committed by: damon
Update of /cvs/cairo/goocanvas/src
In directory kemper:/tmp/cvs-serv29644/src
Modified Files:
goocanvas.c goocanvasitem.c goocanvasitemmodel.c
goocanvasitemsimple.c
Log Message:
2007-03-07 Damon Chaplin <damon at gnome.org>
* src/*.c: added notes to all functions that are only meant to be used
when implementing new canvas items.
* docs/goocanvas-sections.txt: placed all the functions only used when
implementing new canvas items together at the bottom.
Index: goocanvas.c
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvas.c,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -d -r1.14 -r1.15
--- goocanvas.c 6 Mar 2007 13:39:16 -0000 1.14
+++ goocanvas.c 7 Mar 2007 16:07:11 -0000 1.15
@@ -1785,7 +1785,10 @@
* @canvas: a #GooCanvas.
* @model: the item model whose canvas item is being finalized.
*
- * This function should be called in the finalize method of #GooCanvasItem
+ * This function is only intended to be used when implementing new canvas
+ * items.
+ *
+ * It should be called in the finalize method of #GooCanvasItem
* objects, to remove the canvas item from the #GooCanvas's hash table.
**/
void
@@ -1802,8 +1805,11 @@
* @canvas: a #GooCanvas.
* @model: the item model to create a canvas item for.
*
- * Creates a new canvas item for the given item model, and recursively creates
- * items for any children.
+ * This function is only intended to be used when implementing new canvas
+ * items, typically container items such as #GooCanvasGroup.
+ *
+ * It creates a new canvas item for the given item model, and recursively
+ * creates items for any children.
*
* It uses the create_item() virtual method if it has been set.
* Subclasses of #GooCanvas can define this method if they want to use
@@ -1864,11 +1870,11 @@
* goo_canvas_update:
* @canvas: a #GooCanvas.
*
- * Updates any items that need updating.
- *
- * This is only intended to be used by subclasses of #GooCanvas or
+ * This function is only intended to be used by subclasses of #GooCanvas or
* #GooCanvasItem implementations.
*
+ * It updates any items that need updating.
+ *
* If the bounds of items change, they will request a redraw of the old and
* new bounds so the display is updated correctly.
**/
@@ -1903,7 +1909,10 @@
* goo_canvas_request_update:
* @canvas: a #GooCanvas.
*
- * Schedules an update of the #GooCanvas. This will be performed in
+ * This function is only intended to be used by subclasses of #GooCanvas or
+ * #GooCanvasItem implementations.
+ *
+ * It schedules an update of the #GooCanvas. This will be performed in
* the idle loop, after all pending events have been handled, but before
* the canvas has been repainted.
**/
@@ -1929,6 +1938,9 @@
* @canvas: a #GooCanvas.
* @bounds: the bounds to redraw.
*
+ * This function is only intended to be used by subclasses of #GooCanvas or
+ * #GooCanvasItem implementations.
+ *
* Requests that the given bounds be redrawn.
**/
void
@@ -3383,11 +3395,11 @@
* @canvas: a #GooCanvas.
* @witem: a #GooCanvasWidget item.
*
- * Registers a widget item with the canvas, so that the canvas can do the
- * necessary actions to move and resize the widget as needed.
- *
* This function should only be used by #GooCanvasWidget and subclass
* implementations.
+ *
+ * It registers a widget item with the canvas, so that the canvas can do the
+ * necessary actions to move and resize the widget as needed.
**/
void
goo_canvas_register_widget_item (GooCanvas *canvas,
@@ -3405,11 +3417,11 @@
* @canvas: a #GooCanvas.
* @witem: a #GooCanvasWidget item.
*
- * Unregisters a widget item from the canvas, when the item is no longer in
- * the canvas.
- *
* This function should only be used by #GooCanvasWidget and subclass
* implementations.
+ *
+ * It unregisters a widget item from the canvas, when the item is no longer in
+ * the canvas.
**/
void
goo_canvas_unregister_widget_item (GooCanvas *canvas,
Index: goocanvasitem.c
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvasitem.c,v
retrieving revision 1.26
retrieving revision 1.27
diff -u -d -r1.26 -r1.27
--- goocanvasitem.c 6 Mar 2007 13:39:16 -0000 1.26
+++ goocanvasitem.c 7 Mar 2007 16:07:11 -0000 1.27
@@ -1263,7 +1263,10 @@
* goo_canvas_item_request_update:
* @item: a #GooCanvasItem.
*
- * Requests that an update of the item is scheduled. It will be performed
+ * This function is only intended to be used when implementing new canvas
+ * items.
+ *
+ * It requests that an update of the item is scheduled. It will be performed
* as soon as the application is idle, and before the canvas is redrawn.
**/
void
@@ -1310,7 +1313,10 @@
* implies that all ancestors are also visible).
* @found_items: the list of items found so far.
*
- * Gets the items at the given point.
+ * This function is only intended to be used when implementing new canvas
+ * items, specifically container items such as #GooCanvasGroup.
+ *
+ * It gets the items at the given point.
*
* Returns: the @found_items list, with any more found items added onto
* the start of the list, leaving the top item first.
@@ -1397,7 +1403,10 @@
* goo_canvas_item_ensure_updated:
* @item: a #GooCanvasItem.
*
- * Updates the canvas immediately, if an update is scheduled.
+ * This function is only intended to be used when implementing new canvas
+ * items.
+ *
+ * It updates the canvas immediately, if an update is scheduled.
* This ensures that all item bounds are up-to-date.
**/
void
@@ -1418,6 +1427,9 @@
* @cr: a cairo context.
* @bounds: a #GooCanvasBounds to return the new bounds in.
*
+ * This function is only intended to be used when implementing new canvas
+ * items, specifically container items such as #GooCanvasGroup.
+ *
* Updates the item, if needed, and any children.
**/
void
@@ -1440,7 +1452,10 @@
* @scale: the scale to use to determine whether an item should be painted.
* See #GooCanvasItem:visibility-threshold.
*
- * Paints the item and all children if they intersect the given bounds.
+ * This function is only intended to be used when implementing new canvas
+ * items, specifically container items such as #GooCanvasGroup.
+ *
+ * It paints the item and all children if they intersect the given bounds.
*
* Note that the @scale argument may be different to the current scale in the
* #GooCanvasItem, e.g. when the canvas is being printed.
@@ -1464,8 +1479,10 @@
* @requested_area: a #GooCanvasBounds to return the requested area in, in the
* parent's coordinate space.
*
- * This is used by #GooCanvasTable and other layout items to get the requested
- * area of each of their children.
+ * This function is only intended to be used when implementing new canvas
+ * items, specifically layout items such as #GooCanvasTable.
+ *
+ * It gets the requested area of a child item.
*
* Returns: %TRUE if the item should be allocated space.
**/
@@ -1486,8 +1503,11 @@
* @cr: a cairo context.
* @width: the width that the item may be allocated.
*
- * Gets the requested height of the item, assuming it is allocated the given
- * width. This is useful for text items whose requested height may change
+ * This function is only intended to be used when implementing new canvas
+ * items, specifically layout items such as #GooCanvasTable.
+ *
+ * It gets the requested height of a child item, assuming it is allocated the
+ * given width. This is useful for text items whose requested height may change
* depending on the allocated width.
*
* Returns: the requested height of the item, given the allocated width,
@@ -1521,15 +1541,18 @@
* @y_offset: the y offset of the allocated area from the requested area in
* the device coordinate space.
*
- * This is used by #GooCanvasTable and other layout items to allocate an area
- * to each of their children.
+ * This function is only intended to be used when implementing new canvas
+ * items, specifically layout items such as #GooCanvasTable.
*
- * Note that the parent item will use a transform to move each of its children
- * for the layout, so their is no need for the item to reposition itself. It
- * only needs to recalculate its device bounds.
+ * It allocates an area to a child #GooCanvasItem.
*
- * The @x_offset and @y_offset are provided since for the simple builtin items
- * all they need to do is add these to their bounds.
+ * Note that the parent layout item will use a transform to move each of its
+ * children for the layout, so there is no need for the child item to
+ * reposition itself. It only needs to recalculate its device bounds.
+ *
+ * To help recalculate the item's device bounds, the @x_offset and @y_offset
+ * of the child item's allocated position from its requested position are
+ * provided. Simple items can just add these to their bounds.
**/
void
goo_canvas_item_allocate_area (GooCanvasItem *item,
@@ -1750,7 +1773,10 @@
* @var_args: pairs of property names and value pointers, and a terminating
* %NULL.
*
- * Gets the values of one or more child properties of @child.
+ * This function is only intended to be used when implementing new canvas
+ * items, specifically layout container items such as #GooCanvasTable.
+ *
+ * It gets the values of one or more child properties of @child.
**/
void
goo_canvas_item_get_child_properties_valist (GooCanvasItem *item,
@@ -1770,7 +1796,10 @@
* @child: a child #GooCanvasItem.
* @var_args: pairs of property names and values, and a terminating %NULL.
*
- * Sets the values of one or more child properties of @child.
+ * This function is only intended to be used when implementing new canvas
+ * items, specifically layout container items such as #GooCanvasTable.
+ *
+ * It sets the values of one or more child properties of @child.
**/
void
goo_canvas_item_set_child_properties_valist (GooCanvasItem *item,
@@ -1790,7 +1819,10 @@
* @child: a child #GooCanvasItem.
* @...: pairs of property names and value pointers, and a terminating %NULL.
*
- * Gets the values of one or more child properties of @child.
+ * This function is only intended to be used when implementing new canvas
+ * items, specifically layout container items such as #GooCanvasTable.
+ *
+ * It gets the values of one or more child properties of @child.
**/
void
goo_canvas_item_get_child_properties (GooCanvasItem *item,
@@ -1811,7 +1843,10 @@
* @child: a child #GooCanvasItem.
* @...: pairs of property names and values, and a terminating %NULL.
*
- * Sets the values of one or more child properties of @child.
+ * This function is only intended to be used when implementing new canvas
+ * items, specifically layout container items such as #GooCanvasTable.
+ *
+ * It sets the values of one or more child properties of @child.
**/
void
goo_canvas_item_set_child_properties (GooCanvasItem *item,
@@ -1833,7 +1868,10 @@
* @property_id: the id for the property
* @pspec: the #GParamSpec for the property
*
- * Installs a child property on a canvas item class.
+ * This function is only intended to be used when implementing new canvas
+ * items, specifically layout container items such as #GooCanvasTable.
+ *
+ * It installs a child property on a canvas item class.
**/
void
goo_canvas_item_class_install_child_property (GObjectClass *iclass,
@@ -1866,7 +1904,10 @@
* @returns: the #GParamSpec of the child property or %NULL if @class has no
* child property with that name.
*
- * Finds a child property of a canvas item class by name.
+ * This function is only intended to be used when implementing new canvas
+ * items, specifically layout container items such as #GooCanvasTable.
+ *
+ * It finds a child property of a canvas item class by name.
*/
GParamSpec*
goo_canvas_item_class_find_child_property (GObjectClass *iclass,
@@ -1887,7 +1928,10 @@
* @returns: a newly allocated array of #GParamSpec*. The array must be
* freed with g_free().
*
- * Returns all child properties of a canvas item class.
+ * This function is only intended to be used when implementing new canvas
+ * items, specifically layout container items such as #GooCanvasTable.
+ *
+ * It returns all child properties of a canvas item class.
*/
GParamSpec**
goo_canvas_item_class_list_child_properties (GObjectClass *iclass,
Index: goocanvasitemmodel.c
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvasitemmodel.c,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -d -r1.12 -r1.13
--- goocanvasitemmodel.c 6 Mar 2007 13:21:26 -0000 1.12
+++ goocanvasitemmodel.c 7 Mar 2007 16:07:11 -0000 1.13
@@ -822,7 +822,11 @@
* @var_args: pairs of property names and value pointers, and a terminating
* %NULL.
*
- * Gets the values of one or more child properties of @child.
+ * This function is only intended to be used when implementing new canvas
+ * item models, specifically layout container item models such as
+ * #GooCanvasTableModel.
+ *
+ * It gets the values of one or more child properties of @child.
**/
void
goo_canvas_item_model_get_child_properties_valist (GooCanvasItemModel *model,
@@ -842,7 +846,11 @@
* @child: a child #GooCanvasItemModel.
* @var_args: pairs of property names and values, and a terminating %NULL.
*
- * Sets the values of one or more child properties of @child.
+ * This function is only intended to be used when implementing new canvas
+ * item models, specifically layout container item models such as
+ * #GooCanvasTableModel.
+ *
+ * It sets the values of one or more child properties of @child.
**/
void
goo_canvas_item_model_set_child_properties_valist (GooCanvasItemModel *model,
@@ -862,7 +870,11 @@
* @child: a child #GooCanvasItemModel.
* @...: pairs of property names and value pointers, and a terminating %NULL.
*
- * Gets the values of one or more child properties of @child.
+ * This function is only intended to be used when implementing new canvas
+ * item models, specifically layout container item models such as
+ * #GooCanvasTableModel.
+ *
+ * It gets the values of one or more child properties of @child.
**/
void
goo_canvas_item_model_get_child_properties (GooCanvasItemModel *model,
@@ -883,7 +895,11 @@
* @child: a child #GooCanvasItemModel.
* @...: pairs of property names and values, and a terminating %NULL.
*
- * Sets the values of one or more child properties of @child.
+ * This function is only intended to be used when implementing new canvas
+ * item models, specifically layout container item models such as
+ * #GooCanvasTableModel.
+ *
+ * It sets the values of one or more child properties of @child.
**/
void
goo_canvas_item_model_set_child_properties (GooCanvasItemModel *model,
@@ -905,7 +921,11 @@
* @property_id: the id for the property
* @pspec: the #GParamSpec for the property
*
- * Installs a child property on a canvas item class.
+ * This function is only intended to be used when implementing new canvas
+ * item models, specifically layout container item models such as
+ * #GooCanvasTableModel.
+ *
+ * It installs a child property on a canvas item class.
**/
void
goo_canvas_item_model_class_install_child_property (GObjectClass *mclass,
@@ -938,7 +958,11 @@
* @returns: the #GParamSpec of the child property or %NULL if @class has no
* child property with that name.
*
- * Finds a child property of a canvas item class by name.
+ * This function is only intended to be used when implementing new canvas
+ * item models, specifically layout container item models such as
+ * #GooCanvasTableModel.
+ *
+ * It finds a child property of a canvas item class by name.
*/
GParamSpec*
goo_canvas_item_model_class_find_child_property (GObjectClass *mclass,
@@ -959,7 +983,11 @@
* @returns: a newly allocated array of #GParamSpec*. The array must be
* freed with g_free().
*
- * Returns all child properties of a canvas item class.
+ * This function is only intended to be used when implementing new canvas
+ * item models, specifically layout container item models such as
+ * #GooCanvasTableModel.
+ *
+ * It returns all child properties of a canvas item class.
*/
GParamSpec**
goo_canvas_item_model_class_list_child_properties (GObjectClass *mclass,
Index: goocanvasitemsimple.c
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvasitemsimple.c,v
retrieving revision 1.28
retrieving revision 1.29
diff -u -d -r1.28 -r1.29
--- goocanvasitemsimple.c 6 Mar 2007 13:21:26 -0000 1.28
+++ goocanvasitemsimple.c 7 Mar 2007 16:07:11 -0000 1.29
@@ -1470,7 +1470,9 @@
* @item: a #GooCanvasItemSimple.
* @cr: a cairo context.
*
- * Paints the current path, using the item's style settings.
+ * This function is intended to be used by subclasses of #GooCanvasItemSimple.
+ *
+ * It paints the current path, using the item's style settings.
**/
void
goo_canvas_item_simple_paint_path (GooCanvasItemSimple *item,
@@ -1498,13 +1500,16 @@
* @cr: a cairo context.
* @bounds: the #GooCanvasBounds struct to store the resulting bounding box.
*
- * Calculates the bounds of the current path, storing the results in the given
- * #GooCanvasBounds struct.
+ * This function is intended to be used by subclasses of #GooCanvasItemSimple,
+ * typically in their update() or get_requested_area() methods.
*
- * The returned bounds contains the bounding box of the item in device space,
+ * It calculates the bounds of the current path, using the item's style
+ * settings, and stores the results in the given #GooCanvasBounds struct.
+ *
+ * The returned bounds contains the bounding box of the path in device space,
* converted to user space coordinates. To calculate the bounds completely in
* user space, use cairo_identity_matrix() to temporarily reset the current
- * transformation matrix.
+ * transformation matrix to the identity matrix.
**/
void
goo_canvas_item_simple_get_path_bounds (GooCanvasItemSimple *item,
@@ -1526,7 +1531,7 @@
/* FIXME: Handle whatever cairo returns for NULL bounds. Cairo starts with
INT16_MAX << 16 in cairo-traps.c, but this may get converted to user
- space so could be anything? */
+ space so could be anything? cairo 1.4 handles this better, I think. */
bounds->x1 = MIN (tmp_bounds.x1, tmp_bounds.x2);
bounds->x1 = MIN (bounds->x1, tmp_bounds2.x1);
@@ -1552,7 +1557,10 @@
* @cr: a cairo context.
* @bounds: the bounds of the item, in the item's coordinate space.
*
- * Converts the item's bounds to a bounding box in device space.
+ * This function is intended to be used by subclasses of #GooCanvasItemSimple,
+ * typically in their update() or get_requested_area() methods.
+ *
+ * It converts the item's bounds to a bounding box in device space.
**/
void
goo_canvas_item_simple_user_bounds_to_device (GooCanvasItemSimple *item,
@@ -1597,12 +1605,12 @@
* @cr: a cairo context.
* @bounds: the bounds of the item, in the item's coordinate space.
*
- * Converts the item's bounds to a bounding box in its parent's coordinate
+ * This function is intended to be used by subclasses of #GooCanvasItemSimple,
+ * typically in their get_requested_area() method.
+ *
+ * It converts the item's bounds to a bounding box in its parent's coordinate
* space. If the item has no transformation matrix set then no conversion is
* needed.
- *
- * This is typically needed when implementing the get_requested_area() method
- * for subclasses of #GooCanvasItemSimple.
**/
void
goo_canvas_item_simple_user_bounds_to_parent (GooCanvasItemSimple *item,
@@ -1656,7 +1664,10 @@
* @cr: a cairo context.
* @pointer_events: specifies which parts of the path to check.
*
- * Checks if the given point is in the current path.
+ * This function is intended to be used by subclasses of #GooCanvasItemSimple.
+ *
+ * It checks if the given point is in the current path, using the item's
+ * style settings.
*
* Returns: %TRUE if the given point is in the current path.
**/
More information about the cairo-commit
mailing list