[cairo-commit]
goocanvas/src goocanvas.c, 1.4, 1.5 goocanvas.h, 1.4, 1.5
Damon Chaplin
commit at pdx.freedesktop.org
Mon Feb 5 16:08:13 PST 2007
Committed by: damon
Update of /cvs/cairo/goocanvas/src
In directory kemper:/tmp/cvs-serv23894/src
Modified Files:
goocanvas.c goocanvas.h
Log Message:
2007-02-06 Damon Chaplin <damon at gnome.org>
* src/goocanvas.[hc]: updated docs.
Index: goocanvas.c
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvas.c,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -d -r1.4 -r1.5
--- goocanvas.c 4 Feb 2007 18:02:30 -0000 1.4
+++ goocanvas.c 6 Feb 2007 00:08:07 -0000 1.5
@@ -237,7 +237,7 @@
g_object_class_install_property (gobject_class, PROP_SCALE,
g_param_spec_double ("scale",
_("Scale"),
- _("The number of pixels to use for each device unit"),
+ _("The magnification factor of the canvas"),
0.0, G_MAXDOUBLE, 1.0,
G_PARAM_READWRITE));
@@ -252,7 +252,7 @@
g_object_class_install_property (gobject_class, PROP_X1,
g_param_spec_double ("x1",
_("X1"),
- _("The x coordinate of the left edge of the canvas bounds, in device units"),
+ _("The x coordinate of the left edge of the canvas bounds, in canvas units"),
-G_MAXDOUBLE,
G_MAXDOUBLE, 0.0,
G_PARAM_READWRITE));
@@ -260,7 +260,7 @@
g_object_class_install_property (gobject_class, PROP_Y1,
g_param_spec_double ("y1",
_("Y1"),
- _("The y coordinate of the top edge of the canvas bounds, in device units"),
+ _("The y coordinate of the top edge of the canvas bounds, in canvas units"),
-G_MAXDOUBLE,
G_MAXDOUBLE, 0.0,
G_PARAM_READWRITE));
@@ -268,7 +268,7 @@
g_object_class_install_property (gobject_class, PROP_X2,
g_param_spec_double ("x2",
_("X2"),
- _("The x coordinate of the right edge of the canvas bounds, in device units"),
+ _("The x coordinate of the right edge of the canvas bounds, in canvas units"),
-G_MAXDOUBLE,
G_MAXDOUBLE, 1000.0,
G_PARAM_READWRITE));
@@ -276,7 +276,7 @@
g_object_class_install_property (gobject_class, PROP_Y2,
g_param_spec_double ("y2",
_("Y2"),
- _("The y coordinate of the bottom edge of the canvas bounds, in device units"),
+ _("The y coordinate of the bottom edge of the canvas bounds, in canvas units"),
-G_MAXDOUBLE,
G_MAXDOUBLE, 1000.0,
G_PARAM_READWRITE));
@@ -399,6 +399,10 @@
* goo_canvas_new:
*
* Creates a new #GooCanvas widget.
+ *
+ * A #GooCanvasGroup is created automatically as the root item of the canvas,
+ * though this can be overriden with goo_canvas_set_root_item() or
+ * goo_canvas_set_root_item_model().
*
* Returns: a new #GooCanvas widget.
**/
@@ -596,9 +600,9 @@
* goo_canvas_get_root_item_model:
* @canvas: a #GooCanvas.
*
- * Gets the model of the root item.
+ * Gets the root item model of the canvas.
*
- * Returns: the model of the root item, or %NULL if no model has been set.
+ * Returns: the root item model, or %NULL if there is no root item model.
**/
GooCanvasItemModel*
goo_canvas_get_root_item_model (GooCanvas *canvas)
@@ -614,7 +618,7 @@
* @canvas: a #GooCanvas.
* @model: a #GooCanvasItemModel.
*
- * Sets the root item model of the #GooCanvas.
+ * Sets the root item model of the canvas.
*
* A hierarchy of canvas items will be created, corresponding to the hierarchy
* of items in the model. Any current canvas items will be removed.
@@ -667,9 +671,9 @@
* goo_canvas_get_root_item:
* @canvas: a #GooCanvas.
*
- * Gets the root item.
+ * Gets the root item of the canvas, usually a #GooCanvasGroup.
*
- * Returns: the root item, or %NULL if no root item has been set.
+ * Returns: the root item, or %NULL if there is no root item.
**/
GooCanvasItem*
goo_canvas_get_root_item (GooCanvas *canvas)
@@ -685,7 +689,7 @@
* @canvas: a #GooCanvas.
* @item: the root canvas item.
*
- * Sets the root canvas item. Any existing canvas items are removed.
+ * Sets the root item of the canvas. Any existing canvas items are removed.
**/
void
goo_canvas_set_root_item (GooCanvas *canvas,
@@ -723,10 +727,12 @@
* @canvas: a #GooCanvas.
* @model: a #GooCanvasItemModel.
*
- * Gets the canvas item for the given #GooCanvasItemModel.
+ * Gets the canvas item associated with the given #GooCanvasItemModel.
+ * This is only useful when goo_canvas_set_root_item_model() has been used to
+ * set a model for the canvas.
*
- * For simple applications you can use this function to set up signal handlers
- * for your items, e.g.
+ * For simple applications you can use goo_canvas_get_item() to set up
+ * signal handlers for your items, e.g.
*
* <informalexample><programlisting>
* item = goo_canvas_get_item (GOO_CANVAS (canvas), my_item);
@@ -734,8 +740,8 @@
* (GtkSignalFunc) on_my_item_button_press, NULL);
* </programlisting></informalexample>
*
- * More complex applications may want to use the
- * #GooCanvas::item-created signal to hook up their signal handlers.
+ * More complex applications may want to use the #GooCanvas::item-created
+ * signal to hook up their signal handlers.
*
* Returns: the canvas item corresponding to the given #GooCanvasItemModel,
* or %NULL if no canvas item has been created for it yet.
@@ -760,8 +766,8 @@
* @canvas: a #GooCanvas.
* @x: the x coordinate of the point.
* @y: the y coordinate of the point
- * @is_pointer_event: %TRUE if the "pointer-events" properties of items should
- * be used to determine which parts of the item are tested.
+ * @is_pointer_event: %TRUE if the "pointer-events" property of
+ * items should be used to determine which parts of the item are tested.
*
* Gets the item at the given point.
*
@@ -1369,7 +1375,10 @@
* @right: a pointer to a #gdouble to return the right edge, or %NULL.
* @bottom: a pointer to a #gdouble to return the bottom edge, or %NULL.
*
- * Gets the bounds of the canvas.
+ * Gets the bounds of the canvas, in canvas units.
+ *
+ * By default, canvas units are pixels, though the #GooCanvas:units property
+ * can be used to change the units to points, inches or millimeters.
**/
void
goo_canvas_get_bounds (GooCanvas *canvas,
@@ -1399,10 +1408,10 @@
* @right: the right edge.
* @bottom: the bottom edge.
*
- * Sets the bounds of the #GooCanvas, in device units.
+ * Sets the bounds of the #GooCanvas, in canvas units.
*
- * By default, device units are the same as pixels, though
- * goo_canvas_set_scale() can be used to specify a different scale.
+ * By default, canvas units are pixels, though the #GooCanvas:units property
+ * can be used to change the units to points, inches or millimeters.
**/
void
goo_canvas_set_bounds (GooCanvas *canvas,
@@ -1495,8 +1504,11 @@
* goo_canvas_get_scale:
* @canvas: a #GooCanvas.
*
- * Gets the current scale of the canvas, i.e. the number of pixels to use
- * for each device unit.
+ * Gets the current scale of the canvas.
+ *
+ * The scale specifies the magnification factor of the canvas, e.g. if an item
+ * has a width of 2 pixels and the scale is set to 3, it will be displayed with
+ * a width of 2 x 3 = 6 pixels.
*
* Returns: the current scale setting.
**/
@@ -1512,14 +1524,17 @@
/**
* goo_canvas_set_scale:
* @canvas: a #GooCanvas.
- * @pixels_per_unit: the new scale setting.
+ * @scale: the new scale setting.
*
- * Sets the current scale of the canvas, i.e. the number of pixels to use
- * for each device unit.
+ * Sets the scale of the canvas.
+ *
+ * The scale specifies the magnification factor of the canvas, e.g. if an item
+ * has a width of 2 pixels and the scale is set to 3, it will be displayed with
+ * a width of 2 x 3 = 6 pixels.
**/
void
goo_canvas_set_scale (GooCanvas *canvas,
- gdouble pixels_per_unit)
+ gdouble scale)
{
gdouble x, y;
@@ -1543,7 +1558,7 @@
canvas->freeze_count++;
- canvas->scale = pixels_per_unit;
+ canvas->scale = scale;
reconfigure_canvas (canvas, FALSE);
/* Convert from the center point to the new desired top-left posision. */
@@ -1591,7 +1606,7 @@
* Subclasses of #GooCanvas can define this method if they want to use
* custom views for items.
*
- * It emits the "item-created" signal after creating the view, so
+ * It emits the #GooCanvas::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: goocanvas.h
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvas.h,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -d -r1.4 -r1.5
--- goocanvas.h 9 Dec 2006 12:03:05 -0000 1.4
+++ goocanvas.h 6 Feb 2007 00:08:07 -0000 1.5
@@ -126,8 +126,17 @@
GList *widget_items;
};
+/**
+ * GooCanvasClass
+ * @create_item: a virtual method that subclasses may override to create custom
+ * canvas items for item models.
+ *
+ * The #GooCanvasClass-struct struct contains one virtual method that
+ * subclasses may override.
+ */
struct _GooCanvasClass
{
+ /*< private >*/
GtkContainerClass parent_class;
void (* set_scroll_adjustments) (GooCanvas *canvas,
@@ -135,9 +144,12 @@
GtkAdjustment *vadjustment);
/* Virtual methods. */
+ /*< public >*/
GooCanvasItem* (* create_item) (GooCanvas *canvas,
GooCanvasItemModel *model);
+ /*< private >*/
+
/* Signals. */
void (* item_created) (GooCanvas *canvas,
GooCanvasItem *item,
@@ -165,7 +177,7 @@
gdouble goo_canvas_get_scale (GooCanvas *canvas);
void goo_canvas_set_scale (GooCanvas *canvas,
- gdouble pixels_per_unit);
+ gdouble scale);
void goo_canvas_get_bounds (GooCanvas *canvas,
gdouble *left,
More information about the cairo-commit
mailing list