[cairo-commit] goocanvas/src goocanvasgroup.c, 1.5,
1.6 goocanvasitem.c, 1.2, 1.3 goocanvasitem.h, 1.4,
1.5 goocanvasitemsimple.c, 1.4, 1.5 goocanvasitemsimple.h, 1.4,
1.5 goocanvasitemview.c, 1.5, 1.6 goocanvasitemview.h, 1.5,
1.6 goocanvasmodel.c, 1.1.1.1, 1.2 goocanvasmodel.h, 1.1.1.1,
1.2 goocanvasmodelsimple.c, 1.1.1.1,
1.2 goocanvasmodelsimple.h, 1.1.1.1, 1.2 goocanvaspath.h, 1.3, 1.4
Damon Chaplin
commit at pdx.freedesktop.org
Fri Apr 14 09:59:06 PDT 2006
Committed by: damon
Update of /cvs/cairo/goocanvas/src
In directory kemper:/tmp/cvs-serv4830/src
Modified Files:
goocanvasgroup.c goocanvasitem.c goocanvasitem.h
goocanvasitemsimple.c goocanvasitemsimple.h
goocanvasitemview.c goocanvasitemview.h goocanvasmodel.c
goocanvasmodel.h goocanvasmodelsimple.c goocanvasmodelsimple.h
goocanvaspath.h
Log Message:
2006-04-14 Damon Chaplin <damon at gnome.org>
* src/*.[hc]: documented most of the core objects.
Index: goocanvasgroup.c
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvasgroup.c,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -d -r1.5 -r1.6
--- goocanvasgroup.c 14 Apr 2006 12:49:10 -0000 1.5
+++ goocanvasgroup.c 14 Apr 2006 16:59:04 -0000 1.6
@@ -10,7 +10,7 @@
* @Title: GooCanvasGroup
* @Short_Description: a group of items.
*
- * GooCanvasGroup represents a group of items. Groups can be nested to any
+ * #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.
*
Index: goocanvasitem.c
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvasitem.c,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- goocanvasitem.c 23 Mar 2006 16:58:48 -0000 1.2
+++ goocanvasitem.c 14 Apr 2006 16:59:04 -0000 1.3
@@ -4,8 +4,18 @@
*
* goocanvasitem.c - interface for canvas items & groups.
*/
+
+/**
+ * SECTION:goocanvasitem
+ * @Title: GooCanvasItem
+ * @Short_Description: the interface for canvas items.
+ *
+ * GooCanvasItem defines the interface that canvas items must implement,
+ * and contains methods for operating on canvas items.
+ */
#include <config.h>
#include <math.h>
+#include <glib/gi18n-lib.h>
#include <gtk/gtk.h>
#include "goocanvasitem.h"
#include "goocanvasutils.h"
@@ -17,7 +27,6 @@
enum {
CHILD_ADDED,
CHILD_MOVED,
- CHILD_CHANGED,
CHILD_REMOVED,
LAST_SIGNAL
@@ -63,6 +72,13 @@
{
GType iface_type = G_TYPE_FROM_INTERFACE (g_iface);
+ /**
+ * GooCanvasItem::child-added
+ * @item: the item that received the signal.
+ * @child_num: the index of the new child.
+ *
+ * Emitted when a child has been added to the container item.
+ */
canvas_item_signals[CHILD_ADDED] =
g_signal_new ("child-added",
iface_type,
@@ -73,6 +89,15 @@
G_TYPE_NONE, 1,
G_TYPE_INT);
+ /**
+ * GooCanvasItem::child-moved
+ * @item: the item that received the signal.
+ * @old_child_num: the old index of the child.
+ * @new_child_num: the new index of the child.
+ *
+ * Emitted when a child has been moved in the stacking order of a
+ * container item.
+ */
canvas_item_signals[CHILD_MOVED] =
g_signal_new ("child-moved",
iface_type,
@@ -83,16 +108,13 @@
G_TYPE_NONE, 2,
G_TYPE_INT, G_TYPE_INT);
- canvas_item_signals[CHILD_CHANGED] =
- g_signal_new ("child-changed",
- iface_type,
- G_SIGNAL_RUN_LAST,
- G_STRUCT_OFFSET (GooCanvasItemIface, child_changed),
- NULL, NULL,
- goo_canvas_marshal_VOID__INT,
- G_TYPE_NONE, 1,
- G_TYPE_INT);
-
+ /**
+ * GooCanvasItem::child-removed
+ * @item: the item that received the signal.
+ * @child_num: the index of the child that was removed.
+ *
+ * Emitted when a child has been removed from the container item.
+ */
canvas_item_signals[CHILD_REMOVED] =
g_signal_new ("child-removed",
iface_type,
@@ -105,13 +127,15 @@
g_object_interface_install_property (g_iface,
g_param_spec_enum ("visibility",
- NULL, NULL,
+ _("Visibility"),
+ _("When the canvas item is visible"),
GOO_TYPE_CANVAS_ITEM_VISIBILITY,
GOO_CANVAS_ITEM_VISIBLE,
G_PARAM_READWRITE));
g_object_interface_install_property (g_iface,
g_param_spec_double ("visibility-threshold",
- NULL, NULL,
+ _("Visibility Threshold"),
+ _("The scale threshold at which the item becomes visible"),
0.0,
G_MAXDOUBLE,
0.0,
@@ -676,15 +700,17 @@
/**
* goo_canvas_item_animate:
* @item: an item.
- * @x:
- * @y:
- * @scale:
- * @degrees:
- * @duration:
- * @step_time:
- * @type:
- *
+ * @x: the final x offset from the current position.
+ * @y: the final y offset from the current position.
+ * @scale: the final scale of the item.
+ * @degrees: the final rotation of the item.
+ * @duration: the duration of the animation, in milliseconds (1/1000ths of a
+ * second).
+ * @step_time: the time between each animation step, in milliseconds.
+ * @type: specifies what happens when the animation finishes.
*
+ * Animates an item from its current position to the given offsets, scale
+ * and rotation.
**/
void
goo_canvas_item_animate (GooCanvasItem *item,
Index: goocanvasitem.h
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvasitem.h,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -d -r1.4 -r1.5
--- goocanvasitem.h 14 Apr 2006 12:49:10 -0000 1.4
+++ goocanvasitem.h 14 Apr 2006 16:59:04 -0000 1.5
@@ -62,13 +62,32 @@
typedef struct _GooCanvasItemView GooCanvasItemView;
+/**
+ * GooCanvasItem
+ *
+ * #GooCanvasItem is a typedef used for objects that implement the
+ * #GooCanvasItem interface.
+ *
+ * (There is no actual #GooCanvasItem struct, since it is only an interface.
+ * But using '#GooCanvasItem' is more helpful than using '#GObject'.)
+ */
typedef struct _GooCanvasItem GooCanvasItem;
+
+
+/**
+ * GooCanvasItemIface
+ *
+ * #GooCanvasItemIFace holds the virtual methods that make up the
+ * #GooCanvasItem interface.
+ */
typedef struct _GooCanvasItemIface GooCanvasItemIface;
struct _GooCanvasItemIface
{
+ /*< private >*/
GTypeInterface base_iface;
+ /*< public >*/
/* Virtual methods that group items must implement. */
GooCanvasModel* (* get_model) (GooCanvasItem *item);
gint (* get_n_children) (GooCanvasItem *group);
@@ -104,8 +123,6 @@
void (* child_moved) (GooCanvasItem *item,
gint old_child_num,
gint new_child_num);
- void (* child_changed) (GooCanvasItem *item,
- gint child_num);
void (* child_removed) (GooCanvasItem *item,
gint child_num);
};
Index: goocanvasitemsimple.c
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvasitemsimple.c,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -d -r1.4 -r1.5
--- goocanvasitemsimple.c 14 Apr 2006 12:49:10 -0000 1.4
+++ goocanvasitemsimple.c 14 Apr 2006 16:59:04 -0000 1.5
@@ -4,7 +4,21 @@
*
* goocanvasitemsimple.c - abstract base class for simple items with styles.
*/
+
+/**
+ * SECTION:goocanvasitemsimple
+ * @Title: GooCanvasItemSimple
+ * @Short_Description: the base class for the standard canvas items.
+ *
+ * #GooCanvasItemSimple is used as a base class for the standard canvas items.
+ *
+ * It supports a number of style properties, such as "stroke-color",
+ * "fill-color" and "line-width".
+ *
+ * It also provides a number of utility functions that subclasses can use.
+ */
#include <config.h>
+#include <glib/gi18n-lib.h>
#include <gtk/gtk.h>
#include "goocanvasprivate.h"
#include "goocanvasitemsimple.h"
@@ -190,33 +204,38 @@
/* Basic drawing properties. */
g_object_class_install_property (gobject_class, PROP_STROKE_PATTERN,
g_param_spec_boxed ("stroke-pattern",
- NULL, NULL,
+ _("Stroke Pattern"),
+ _("The pattern to use to paint the perimeter of the item"),
GOO_TYPE_CAIRO_PATTERN,
G_PARAM_READWRITE));
g_object_class_install_property (gobject_class, PROP_FILL_PATTERN,
g_param_spec_boxed ("fill-pattern",
- NULL, NULL,
+ _("Fill Pattern"),
+ _("The pattern to use to paint the interior of the item"),
GOO_TYPE_CAIRO_PATTERN,
G_PARAM_READWRITE));
g_object_class_install_property (gobject_class, PROP_FILL_RULE,
g_param_spec_enum ("fill-rule",
- NULL, NULL,
+ _("Fill Rule"),
+ _("The fill rule used to determine which parts of the item are filled"),
GOO_TYPE_CAIRO_FILL_RULE,
CAIRO_FILL_RULE_WINDING,
G_PARAM_READWRITE));
g_object_class_install_property (gobject_class, PROP_OPERATOR,
g_param_spec_enum ("operator",
- NULL, NULL,
+ _("Operator"),
+ _("The compositing operator to use"),
GOO_TYPE_CAIRO_OPERATOR,
CAIRO_OPERATOR_OVER,
G_PARAM_READWRITE));
g_object_class_install_property (gobject_class, PROP_ANTIALIAS,
g_param_spec_enum ("antialias",
- NULL, NULL,
+ _("Antialias"),
+ _("The antialiasing mode to use"),
GOO_TYPE_CAIRO_ANTIALIAS,
CAIRO_ANTIALIAS_DEFAULT,
G_PARAM_READWRITE));
@@ -224,77 +243,89 @@
/* Line style & width properties. */
g_object_class_install_property (gobject_class, PROP_LINE_WIDTH,
g_param_spec_double ("line-width",
- NULL, NULL,
+ _("Line Width"),
+ _("The line width to use for the item's perimeter"),
0.0, G_MAXDOUBLE, 0.0,
G_PARAM_READWRITE));
g_object_class_install_property (gobject_class, PROP_LINE_CAP,
g_param_spec_enum ("line-cap",
- NULL, NULL,
+ _("Line Cap"),
+ _("The line cap style to use"),
GOO_TYPE_CAIRO_LINE_CAP,
CAIRO_LINE_CAP_BUTT,
G_PARAM_READWRITE));
g_object_class_install_property (gobject_class, PROP_LINE_JOIN,
g_param_spec_enum ("line-join",
- NULL, NULL,
+ _("Line Join"),
+ _("The line join style to use"),
GOO_TYPE_CAIRO_LINE_JOIN,
CAIRO_LINE_JOIN_MITER,
G_PARAM_READWRITE));
g_object_class_install_property (gobject_class, PROP_LINE_JOIN_MITER_LIMIT,
g_param_spec_double ("line-join-miter-limit",
- NULL, NULL,
+ _("Miter Limit"),
+ _("The smallest angle to use with miter joins, in degrees. Bevel joins will be used below this limit"),
0.0, G_MAXDOUBLE, 10.0,
G_PARAM_READWRITE));
g_object_class_install_property (gobject_class, PROP_LINE_DASH,
g_param_spec_boxed ("line-dash",
- NULL, NULL,
+ _("Line Dash"),
+ _("The dash pattern to use"),
GOO_TYPE_CAIRO_LINE_DASH,
G_PARAM_READWRITE));
/* Convenience properties - writable only. */
g_object_class_install_property (gobject_class, PROP_STROKE_COLOR,
g_param_spec_string ("stroke-color",
- NULL, NULL,
+ _("Stroke Color"),
+ _("The color to use for the item's perimeter"),
NULL,
G_PARAM_WRITABLE));
g_object_class_install_property (gobject_class, PROP_STROKE_COLOR_RGBA,
g_param_spec_uint ("stroke-color-rgba",
- NULL, NULL,
+ _("Stroke Color RGBA"),
+ _("The color to use for the item's perimeter, specified as a 32-bit integer value"),
0, G_MAXUINT, 0,
G_PARAM_WRITABLE));
g_object_class_install_property (gobject_class, PROP_STROKE_PIXBUF,
g_param_spec_object ("stroke-pixbuf",
- NULL, NULL,
+ _("Stroke Pixbuf"),
+ _("The pixbuf to use to draw the item's perimeter"),
GDK_TYPE_PIXBUF,
G_PARAM_WRITABLE));
g_object_class_install_property (gobject_class, PROP_FILL_COLOR,
g_param_spec_string ("fill-color",
- NULL, NULL,
+ _("Fill Color"),
+ _("The color to use to paint the interior of the item"),
NULL,
G_PARAM_WRITABLE));
g_object_class_install_property (gobject_class, PROP_FILL_COLOR_RGBA,
g_param_spec_uint ("fill-color-rgba",
- NULL, NULL,
+ _("Fill Color RGBA"),
+ _("The color to use to paint the interior of the item, specified as a 32-bit integer value"),
0, G_MAXUINT, 0,
G_PARAM_WRITABLE));
g_object_class_install_property (gobject_class, PROP_FILL_PIXBUF,
g_param_spec_object ("fill-pixbuf",
- NULL, NULL,
+ _("Fill Pixbuf"),
+ _("The pixbuf to use to paint the interior of the item"),
GDK_TYPE_PIXBUF,
G_PARAM_WRITABLE));
/* Other properties. */
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));
@@ -306,12 +337,21 @@
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. */
+
+ /**
+ * GooCanvasItemSimple::changed
+ * @item: the item that received the signal.
+ * @recompute_bounds: if the bounds of the item need to be recomputed.
+ *
+ * Emitted when the item has been changed.
+ */
item_simple_signals[CHANGED] =
g_signal_new ("changed",
G_TYPE_FROM_CLASS (gobject_class),
@@ -331,13 +371,6 @@
}
-GooCanvasItem*
-goo_canvas_item_simple_new (void)
-{
- return GOO_CANVAS_ITEM (g_object_new (GOO_TYPE_CANVAS_ITEM_SIMPLE, NULL));
-}
-
-
static void
goo_canvas_item_simple_finalize (GObject *object)
{
@@ -603,6 +636,13 @@
goo_canvas_item_simple_emit_changed (item, recompute_bounds);
}
+/**
+ * goo_canvas_item_simple_set_style:
+ * @item: a #GooCanvasItemSimple.
+ * @style: a #GooCanvasStyle.
+ *
+ * Sets the style of the item.
+ **/
void
goo_canvas_item_simple_set_style (GooCanvasItemSimple *item,
GooCanvasStyle *style)
@@ -628,7 +668,7 @@
}
-void
+static void
goo_canvas_item_simple_set_parent (GooCanvasItem *item,
GooCanvasItem *parent)
{
@@ -643,7 +683,7 @@
}
-void
+static void
goo_canvas_item_simple_set_transform (GooCanvasItem *item,
cairo_matrix_t *transform)
{
@@ -677,6 +717,14 @@
}
+/**
+ * goo_canvas_item_simple_set_fill_options:
+ * @item: a #GooCanvasItemSimple.
+ * @cr: a cairo context.
+ *
+ * Sets the fill options of the cairo context, according to the item's style
+ * settings.
+ **/
void
goo_canvas_item_simple_set_fill_options (GooCanvasItemSimple *item,
cairo_t *cr)
@@ -703,6 +751,14 @@
}
+/**
+ * goo_canvas_item_simple_set_stroke_options:
+ * @item: a #GooCanvasItemSimple.
+ * @cr: a cairo context.
+ *
+ * Sets the stroke options of the cairo context, according to the item's
+ * style settings.
+ **/
void
goo_canvas_item_simple_set_stroke_options (GooCanvasItemSimple *item,
cairo_t *cr)
@@ -746,6 +802,13 @@
}
+/**
+ * goo_canvas_item_simple_paint_path:
+ * @item: a #GooCanvasItemSimple.
+ * @cr: a cairo context.
+ *
+ * Paints the current path, using the item's style settings.
+ **/
void
goo_canvas_item_simple_paint_path (GooCanvasItemSimple *item,
cairo_t *cr)
@@ -788,6 +851,15 @@
in device coords. Note that the bounds include both the stroke and the
fill extents, even if they will not be painted. (We need this to handle
the "pointer-events" property.) */
+/**
+ * goo_canvas_item_simple_get_path_bounds:
+ * @item: a #GooCanvasItemSimple.
+ * @cr: a cairo context.
+ * @bounds: the #GooCanvasBounds struct to store the resulting bounding box.
+ *
+ * Calculates the bounds of the current path in device space, storing the
+ * results in the given #GooCanvasBounds struct.
+ **/
void
goo_canvas_item_simple_get_path_bounds (GooCanvasItemSimple *item,
cairo_t *cr,
@@ -798,21 +870,29 @@
/* Calculate the filled extents. */
goo_canvas_item_simple_set_fill_options (item, cr);
cairo_fill_extents (cr, &bounds->x1, &bounds->y1, &bounds->x2, &bounds->y2);
- goo_canvas_item_simple_user_bounds_to_device (item, cr, bounds);
/* Check the stroke. */
goo_canvas_item_simple_set_stroke_options (item, cr);
cairo_stroke_extents (cr, &tmp_bounds.x1, &tmp_bounds.y1,
&tmp_bounds.x2, &tmp_bounds.y2);
- goo_canvas_item_simple_user_bounds_to_device (item, cr, &tmp_bounds);
bounds->x1 = MIN (bounds->x1, tmp_bounds.x1);
bounds->y1 = MIN (bounds->y1, tmp_bounds.y1);
bounds->x2 = MAX (bounds->x2, tmp_bounds.x2);
bounds->y2 = MAX (bounds->y2, tmp_bounds.y2);
+
+ goo_canvas_item_simple_user_bounds_to_device (item, cr, bounds);
}
+/**
+ * goo_canvas_item_simple_user_bounds_to_device:
+ * @item: a #GooCanvasItemSimple.
+ * @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.
+ **/
void
goo_canvas_item_simple_user_bounds_to_device (GooCanvasItemSimple *item,
cairo_t *cr,
@@ -850,6 +930,18 @@
}
+/**
+ * goo_canvas_item_simple_check_in_path:
+ * @item: a #GooCanvasItemSimple.
+ * @x: the x coordinate of the point.
+ * @y: the y coordinate of the point.
+ * @cr: a cairo context.
+ * @pointer_events: specifies which parts of the path to check.
+ *
+ * Checks if the given point is in the current path.
+ *
+ * Returns: %TRUE if the given point is in the current path.
+ **/
gboolean
goo_canvas_item_simple_check_in_path (GooCanvasItemSimple *item,
gdouble x,
@@ -901,6 +993,13 @@
}
+/**
+ * goo_canvas_item_simple_emit_changed:
+ * @item: a #GooCanvasItemSimple.
+ * @recompute_bounds: %TRUE if the item's bounds need to be recomputed.
+ *
+ * Emits the "changed" signal on the item, so any views are updated.
+ **/
void
goo_canvas_item_simple_emit_changed (GooCanvasItemSimple *item,
gboolean recompute_bounds)
Index: goocanvasitemsimple.h
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvasitemsimple.h,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -d -r1.4 -r1.5
--- goocanvasitemsimple.h 14 Apr 2006 12:49:10 -0000 1.4
+++ goocanvasitemsimple.h 14 Apr 2006 16:59:04 -0000 1.5
@@ -109,6 +109,11 @@
typedef struct _GooCanvasItemSimple GooCanvasItemSimple;
typedef struct _GooCanvasItemSimpleClass GooCanvasItemSimpleClass;
+/**
+ * GooCanvasItemSimple
+ *
+ * The #GooCanvasItemSimple-struct struct contains private data only.
+ */
struct _GooCanvasItemSimple
{
GObject parent_object;
@@ -143,7 +148,6 @@
GType goo_canvas_item_simple_get_type (void) G_GNUC_CONST;
-GooCanvasItem* goo_canvas_item_simple_new (void);
void goo_canvas_item_simple_set_style (GooCanvasItemSimple *item,
GooCanvasStyle *style);
Index: goocanvasitemview.c
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvasitemview.c,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -d -r1.5 -r1.6
--- goocanvasitemview.c 8 Apr 2006 13:14:17 -0000 1.5
+++ goocanvasitemview.c 14 Apr 2006 16:59:04 -0000 1.6
@@ -4,6 +4,15 @@
*
* goocanvasitemview.c - interface for views of canvas items & groups.
*/
+
+/**
+ * SECTION:goocanvasitemview
+ * @Title: GooCanvasItemView
+ * @Short_Description: the interface for views of canvas items.
+ *
+ * GooCanvasItemView defines the interface that item views must implement,
+ * and contains methods for operating on item views.
+ */
#include <config.h>
#include <gtk/gtk.h>
#include "goocanvasitemview.h"
@@ -69,6 +78,19 @@
GType iface_type = G_TYPE_FROM_INTERFACE (g_class);
/* Mouse events. */
+
+ /**
+ * GooCanvasItemView::enter-notify-event
+ * @view: the item view that received the signal.
+ * @target_view: the target of the event.
+ * @event: the event data, with coordinates translated to canvas
+ * coordinates.
+ *
+ * Emitted when the mouse enters an item view.
+ *
+ * Returns: %TRUE to stop the signal emission, or %FALSE to let it
+ * continue.
+ */
canvas_item_view_signals[ENTER_NOTIFY_EVENT] =
g_signal_new ("enter_notify_event",
iface_type,
@@ -78,9 +100,21 @@
NULL, NULL,
goo_canvas_marshal_BOOLEAN__OBJECT_BOXED,
G_TYPE_BOOLEAN, 2,
- G_TYPE_OBJECT,
+ GOO_TYPE_CANVAS_ITEM_VIEW,
GDK_TYPE_EVENT | G_SIGNAL_TYPE_STATIC_SCOPE);
+ /**
+ * GooCanvasItemView::leave-notify-event
+ * @view: the item view that received the signal.
+ * @target_view: the target of the event.
+ * @event: the event data, with coordinates translated to canvas
+ * coordinates.
+ *
+ * Emitted when the mouse leaves an item view.
+ *
+ * Returns: %TRUE to stop the signal emission, or %FALSE to let it
+ * continue.
+ */
canvas_item_view_signals[LEAVE_NOTIFY_EVENT] =
g_signal_new ("leave_notify_event",
iface_type,
@@ -90,9 +124,21 @@
NULL, NULL,
goo_canvas_marshal_BOOLEAN__OBJECT_BOXED,
G_TYPE_BOOLEAN, 2,
- G_TYPE_OBJECT,
+ GOO_TYPE_CANVAS_ITEM_VIEW,
GDK_TYPE_EVENT | G_SIGNAL_TYPE_STATIC_SCOPE);
+ /**
+ * GooCanvasItemView::motion-notify-event
+ * @view: the item view that received the signal.
+ * @target_view: the target of the event.
+ * @event: the event data, with coordinates translated to canvas
+ * coordinates.
+ *
+ * Emitted when the mouse moves within an item view.
+ *
+ * Returns: %TRUE to stop the signal emission, or %FALSE to let it
+ * continue.
+ */
canvas_item_view_signals[MOTION_NOTIFY_EVENT] =
g_signal_new ("motion_notify_event",
iface_type,
@@ -102,9 +148,21 @@
NULL, NULL,
goo_canvas_marshal_BOOLEAN__OBJECT_BOXED,
G_TYPE_BOOLEAN, 2,
- G_TYPE_OBJECT,
+ GOO_TYPE_CANVAS_ITEM_VIEW,
GDK_TYPE_EVENT | G_SIGNAL_TYPE_STATIC_SCOPE);
+ /**
+ * GooCanvasItemView::button-press-event
+ * @view: the item view that received the signal.
+ * @target_view: the target of the event.
+ * @event: the event data, with coordinates translated to canvas
+ * coordinates.
+ *
+ * Emitted when a mouse button is pressed in an item view.
+ *
+ * Returns: %TRUE to stop the signal emission, or %FALSE to let it
+ * continue.
+ */
canvas_item_view_signals[BUTTON_PRESS_EVENT] =
g_signal_new ("button_press_event",
iface_type,
@@ -114,9 +172,21 @@
NULL, NULL,
goo_canvas_marshal_BOOLEAN__OBJECT_BOXED,
G_TYPE_BOOLEAN, 2,
- G_TYPE_OBJECT,
+ GOO_TYPE_CANVAS_ITEM_VIEW,
GDK_TYPE_EVENT | G_SIGNAL_TYPE_STATIC_SCOPE);
+ /**
+ * GooCanvasItemView::button-release-event
+ * @view: the item view that received the signal.
+ * @target_view: the target of the event.
+ * @event: the event data, with coordinates translated to canvas
+ * coordinates.
+ *
+ * Emitted when a mouse button is released in an item view.
+ *
+ * Returns: %TRUE to stop the signal emission, or %FALSE to let it
+ * continue.
+ */
canvas_item_view_signals[BUTTON_RELEASE_EVENT] =
g_signal_new ("button_release_event",
iface_type,
@@ -126,11 +196,24 @@
NULL, NULL,
goo_canvas_marshal_BOOLEAN__OBJECT_BOXED,
G_TYPE_BOOLEAN, 2,
- G_TYPE_OBJECT,
+ GOO_TYPE_CANVAS_ITEM_VIEW,
GDK_TYPE_EVENT | G_SIGNAL_TYPE_STATIC_SCOPE);
/* Keyboard events. */
+
+ /**
+ * GooCanvasItemView::key-press-event
+ * @view: the item view that received the signal.
+ * @target_view: the target of the event.
+ * @event: the event data.
+ *
+ * Emitted when a key is pressed and the item view has the keyboard
+ * focus.
+ *
+ * Returns: %TRUE to stop the signal emission, or %FALSE to let it
+ * continue.
+ */
canvas_item_view_signals[KEY_PRESS_EVENT] =
g_signal_new ("key_press_event",
iface_type,
@@ -140,9 +223,21 @@
NULL, NULL,
goo_canvas_marshal_BOOLEAN__OBJECT_BOXED,
G_TYPE_BOOLEAN, 2,
- G_TYPE_OBJECT,
+ GOO_TYPE_CANVAS_ITEM_VIEW,
GDK_TYPE_EVENT | G_SIGNAL_TYPE_STATIC_SCOPE);
+ /**
+ * GooCanvasItemView::key-release-event
+ * @view: the item view that received the signal.
+ * @target_view: the target of the event.
+ * @event: the event data.
+ *
+ * Emitted when a key is released and the item view has the keyboard
+ * focus.
+ *
+ * Returns: %TRUE to stop the signal emission, or %FALSE to let it
+ * continue.
+ */
canvas_item_view_signals[KEY_RELEASE_EVENT] =
g_signal_new ("key_release_event",
iface_type,
@@ -152,10 +247,22 @@
NULL, NULL,
goo_canvas_marshal_BOOLEAN__OBJECT_BOXED,
G_TYPE_BOOLEAN, 2,
- G_TYPE_OBJECT,
+ GOO_TYPE_CANVAS_ITEM_VIEW,
GDK_TYPE_EVENT | G_SIGNAL_TYPE_STATIC_SCOPE);
+ /**
+ * GooCanvasItemView::grab-broken-event
+ * @view: the item view that received the signal.
+ * @target_view: the target of the event.
+ * @event: the event data.
+ *
+ * Emitted when the item view's keyboard or pointer grab was lost
+ * unexpectedly.
+ *
+ * Returns: %TRUE to stop the signal emission, or %FALSE to let it
+ * continue.
+ */
canvas_item_view_signals[GRAB_BROKEN_EVENT] =
g_signal_new ("grab_broken_event",
iface_type,
@@ -165,7 +272,7 @@
NULL, NULL,
goo_canvas_marshal_BOOLEAN__OBJECT_BOXED,
G_TYPE_BOOLEAN, 2,
- G_TYPE_OBJECT,
+ GOO_TYPE_CANVAS_ITEM_VIEW,
GDK_TYPE_EVENT | G_SIGNAL_TYPE_STATIC_SCOPE);
initialized = TRUE;
@@ -173,6 +280,14 @@
}
+/**
+ * goo_canvas_item_view_get_canvas_view:
+ * @view: a #GooCanvasItemView.
+ *
+ * Returns the #GooCanvasView containing the given #GooCanvasItemView.
+ *
+ * Returns: the #GooCanvasView.
+ **/
GooCanvasView*
goo_canvas_item_view_get_canvas_view (GooCanvasItemView *view)
{
@@ -193,34 +308,68 @@
}
+/**
+ * goo_canvas_item_view_is_container:
+ * @view: a #GooCanvasItemView.
+ *
+ * Returns %TRUE if the given #GooCanvasItemView is a container,
+ * i.e. it may contain children;
+ *
+ * Returns: %TRUE if the item view is a container.
+ **/
gboolean
-goo_canvas_item_view_is_container (GooCanvasItemView *group_view)
+goo_canvas_item_view_is_container (GooCanvasItemView *view)
{
- GooCanvasItemViewIface *iface = GOO_CANVAS_ITEM_VIEW_GET_IFACE (group_view);
+ GooCanvasItemViewIface *iface = GOO_CANVAS_ITEM_VIEW_GET_IFACE (view);
return iface->get_n_children ? TRUE : FALSE;
}
+/**
+ * goo_canvas_item_view_get_n_children:
+ * @view: a #GooCanvasItemView.
+ *
+ * Returns the number of children of the given #GooCanvasItemView.
+ *
+ * Returns: the number of children of the #GooCanvasItemView, or 0 if the
+ * view is not a container.
+ **/
gint
-goo_canvas_item_view_get_n_children (GooCanvasItemView *group_view)
+goo_canvas_item_view_get_n_children (GooCanvasItemView *view)
{
- GooCanvasItemViewIface *iface = GOO_CANVAS_ITEM_VIEW_GET_IFACE (group_view);
+ GooCanvasItemViewIface *iface = GOO_CANVAS_ITEM_VIEW_GET_IFACE (view);
- return iface->get_n_children ? iface->get_n_children (group_view) : 0;
+ return iface->get_n_children ? iface->get_n_children (view) : 0;
}
+/**
+ * goo_canvas_item_view_get_child:
+ * @view: a #GooCanvasItemView.
+ * @child_num: the index of the child within the view, counting from 0.
+ *
+ * Returns the child view at the given index.
+ *
+ * Returns: the child at the given index.
+ **/
GooCanvasItemView*
-goo_canvas_item_view_get_child (GooCanvasItemView *group_view,
+goo_canvas_item_view_get_child (GooCanvasItemView *view,
gint child_num)
{
- GooCanvasItemViewIface *iface = GOO_CANVAS_ITEM_VIEW_GET_IFACE (group_view);
+ GooCanvasItemViewIface *iface = GOO_CANVAS_ITEM_VIEW_GET_IFACE (view);
- return iface->get_child ? iface->get_child (group_view, child_num) : NULL;
+ return iface->get_child ? iface->get_child (view, child_num) : NULL;
}
+/**
+ * goo_canvas_item_view_request_update:
+ * @view: a #GooCanvasItemView.
+ *
+ * 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
goo_canvas_item_view_request_update (GooCanvasItemView *view)
{
@@ -233,6 +382,14 @@
}
+/**
+ * goo_canvas_item_view_get_parent_view:
+ * @view: a #GooCanvasItemView.
+ *
+ * Returns the parent view of the given #GooCanvasItemView.
+ *
+ * Returns: the parent view of the item.
+ **/
GooCanvasItemView*
goo_canvas_item_view_get_parent_view (GooCanvasItemView *view)
{
@@ -242,6 +399,13 @@
}
+/**
+ * goo_canvas_item_view_set_parent_view:
+ * @view: a #GooCanvasItemView.
+ * @parent_view: the parent view.
+ *
+ * Sets the parent view of the given #GooCanvasItemView.
+ **/
void
goo_canvas_item_view_set_parent_view (GooCanvasItemView *view,
GooCanvasItemView *parent_view)
@@ -252,6 +416,14 @@
}
+/**
+ * goo_canvas_item_view_get_item:
+ * @view: a #GooCanvasItemView.
+ *
+ * Returns the item the view is displaying.
+ *
+ * Returns: the #GooCanvasItem that the view is displaying.
+ **/
GooCanvasItem*
goo_canvas_item_view_get_item (GooCanvasItemView *view)
{
@@ -261,6 +433,14 @@
}
+/**
+ * goo_canvas_item_view_get_bounds:
+ * @view: a #GooCanvasItemView.
+ *
+ * Gets the bounds of the item.
+ *
+ * Returns: the bounds of the item.
+ **/
GooCanvasBounds*
goo_canvas_item_view_get_bounds (GooCanvasItemView *view)
{
@@ -270,6 +450,22 @@
}
+/**
+ * goo_canvas_item_view_get_item_at:
+ * @view: a #GooCanvasItemView.
+ * @x: the x coordinate of the point.
+ * @y: the y coordinate of the point.
+ * @cr: a cairo contect.
+ * @is_pointer_event: %TRUE if the "pointer-events" properties of items should
+ * be used to determine if they should checked.
+ * @parent_visible: %TRUE if the all ancestors of this item view are visible.
+ * @scale: the scale to use to determine if this item view is visible.
+ *
+ * Gets the item view at the given point.
+ *
+ * Returns: the item view found at the given point, or %NULL if no item view
+ * was found.
+ **/
GooCanvasItemView*
goo_canvas_item_view_get_item_at (GooCanvasItemView *view,
gdouble x,
@@ -286,6 +482,13 @@
}
+/**
+ * goo_canvas_item_view_ensure_updated:
+ * @view: a #GooCanvasItemView.
+ *
+ * Updates the canvas immediately, if an update is scheduled.
+ * This ensures that all item bounds are up-to-date.
+ **/
void
goo_canvas_item_view_ensure_updated (GooCanvasItemView *view)
{
@@ -297,6 +500,16 @@
}
+/**
+ * goo_canvas_item_view_update:
+ * @view: a #GooCanvasItemView.
+ * @entire_tree: if the entire subtree should be updated.
+ * @cr: a cairo context.
+ *
+ * Updates the item view, if needed, and any children.
+ *
+ * Returns: the new bounds of the item view.
+ **/
GooCanvasBounds*
goo_canvas_item_view_update (GooCanvasItemView *view,
gboolean entire_tree,
@@ -308,6 +521,19 @@
}
+/**
+ * goo_canvas_item_view_paint:
+ * @view: a #GooCanvasItemView.
+ * @cr: a cairo context.
+ * @bounds: the bounds that need to be repainted.
+ * @scale: the scale to use to determine whether an item should be painted.
+ * See #GooCanvasItem:visibility-threshold.
+ *
+ * Paints the item view and all children if they intersect the given bounds.
+ *
+ * Note that the @scale argument may be different to the current scale in the
+ * #GooCanvasView, e.g. when the canvas is being printed.
+ **/
void
goo_canvas_item_view_paint (GooCanvasItemView *view,
cairo_t *cr,
Index: goocanvasitemview.h
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvasitemview.h,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -d -r1.5 -r1.6
--- goocanvasitemview.h 8 Apr 2006 13:14:17 -0000 1.5
+++ goocanvasitemview.h 14 Apr 2006 16:59:04 -0000 1.6
@@ -20,12 +20,31 @@
#define GOO_CANVAS_ITEM_VIEW_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), GOO_TYPE_CANVAS_ITEM_VIEW, GooCanvasItemViewIface))
+/**
+ * GooCanvasItemView
+ *
+ * #GooCanvasItemView is a typedef used for objects that implement the
+ * #GooCanvasItemView interface.
+ *
+ * (There is no actual #GooCanvasItemView struct, since it is only an
+ * interface. But using '#GooCanvasItemView' is more helpful than using
+ * '#GObject'.)
+ */
+
+/**
+ * GooCanvasItemViewIface
+ *
+ * #GooCanvasItemViewIFace holds the virtual methods that make up the
+ * #GooCanvasItemView interface.
+ */
typedef struct _GooCanvasItemViewIface GooCanvasItemViewIface;
struct _GooCanvasItemViewIface
{
+ /*< private >*/
GTypeInterface base_iface;
+ /*< public >*/
/* Virtual methods that group views should implement. */
GooCanvasView* (* get_canvas_view) (GooCanvasItemView *view);
gint (* get_n_children) (GooCanvasItemView *group_view);
@@ -88,10 +107,9 @@
/*
* Group view functions - these should only be called on container views.
*/
-gint goo_canvas_item_view_get_n_children (GooCanvasItemView *group_view);
-GooCanvasItemView* goo_canvas_item_view_get_child (GooCanvasItemView *group_view,
+gint goo_canvas_item_view_get_n_children (GooCanvasItemView *view);
+GooCanvasItemView* goo_canvas_item_view_get_child (GooCanvasItemView *view,
gint child_num);
-void goo_canvas_item_view_request_update (GooCanvasItemView *view);
/*
@@ -101,7 +119,7 @@
GooCanvasItemView* goo_canvas_item_view_get_parent_view (GooCanvasItemView *view);
void goo_canvas_item_view_set_parent_view (GooCanvasItemView *view,
GooCanvasItemView *parent_view);
-gboolean goo_canvas_item_view_is_container (GooCanvasItemView *group);
+gboolean goo_canvas_item_view_is_container (GooCanvasItemView *view);
GooCanvasItem* goo_canvas_item_view_get_item (GooCanvasItemView *view);
GooCanvasBounds* goo_canvas_item_view_get_bounds (GooCanvasItemView *view);
@@ -112,6 +130,7 @@
gboolean is_pointer_event,
gboolean parent_visible,
gdouble scale);
+void goo_canvas_item_view_request_update (GooCanvasItemView *view);
void goo_canvas_item_view_ensure_updated (GooCanvasItemView *view);
GooCanvasBounds* goo_canvas_item_view_update (GooCanvasItemView *view,
gboolean entire_tree,
Index: goocanvasmodel.c
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvasmodel.c,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -u -d -r1.1.1.1 -r1.2
--- goocanvasmodel.c 15 Dec 2005 15:32:00 -0000 1.1.1.1
+++ goocanvasmodel.c 14 Apr 2006 16:59:04 -0000 1.2
@@ -4,6 +4,17 @@
*
* goocanvasmodel.c - interface for canvas model.
*/
+
+/**
+ * SECTION:goocanvasmodel
+ * @Title: GooCanvasModel
+ * @Short_Description: the canvas model interface.
+ *
+ * GooCanvasModel defines the interface that canvas models must implement.
+ *
+ * Currently it consists of a single method which returns the root canvas
+ * item.
+ */
#include <config.h>
#include <gtk/gtk.h>
#include "goocanvasmodel.h"
@@ -54,6 +65,14 @@
}
+/**
+ * goo_canvas_model_get_root_item:
+ * @model: a #GooCanvasModel.
+ *
+ * Returns the root canvas item of the model.
+ *
+ * Returns: the root canvas item.
+ **/
GooCanvasItem*
goo_canvas_model_get_root_item (GooCanvasModel *model)
{
Index: goocanvasmodel.h
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvasmodel.h,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -u -d -r1.1.1.1 -r1.2
--- goocanvasmodel.h 15 Dec 2005 15:32:00 -0000 1.1.1.1
+++ goocanvasmodel.h 14 Apr 2006 16:59:04 -0000 1.2
@@ -22,11 +22,30 @@
typedef struct _GooCanvasModelIface GooCanvasModelIface;
+/**
+ * GooCanvasModel
+ *
+ * #GooCanvasModel is a typedef used for objects that implement the
+ * #GooCanvasModel interface.
+ *
+ * (There is no actual #GooCanvasModel struct, since it is only an interface.
+ * But using '#GooCanvasModel' is more helpful than using '#GObject'.)
+ */
+
+/**
+ * GooCanvasModelIface
+ * @get_root_item: returns the root canvas item of the model.
+ *
+ * #GooCanvasModelIFace holds the virtual methods that make up the
+ * #GooCanvasModel interface.
+ */
struct _GooCanvasModelIface
{
+ /*< private >*/
GTypeInterface base_iface;
/* Virtual Methods. */
+ /*< public >*/
GooCanvasItem* (* get_root_item) (GooCanvasModel *model);
};
Index: goocanvasmodelsimple.c
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvasmodelsimple.c,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -u -d -r1.1.1.1 -r1.2
--- goocanvasmodelsimple.c 15 Dec 2005 15:32:02 -0000 1.1.1.1
+++ goocanvasmodelsimple.c 14 Apr 2006 16:59:04 -0000 1.2
@@ -4,6 +4,39 @@
*
* goocanvasmodelsimple.c - simple canvas model.
*/
+
+/**
+ * SECTION:goocanvasmodelsimple
+ * @Title: GooCanvasModelSimple
+ * @Short_Description: a simple implementation of the canvas model interface.
+ *
+ * #GooCanvasModelSimple is a simple implementation of the #GooCanvasModel
+ * interface.
+ *
+ * Typically the canvas model is created, items are added, and then the model
+ * is set in the #GooCanvasView:
+ *
+ * <informalexample><programlisting>
+ * GooCanvasModelSimple *canvas_model;
+ * GooCanvasItem *root, *item;
+ *
+ * /* Create a simple model. */
+ * canvas_model = goo_canvas_model_simple_new ();
+ *
+ * /* Get the root item of the model. */
+ * root = goo_canvas_model_get_root_item (GOO_CANVAS_MODEL (canvas_model));
+ *
+ * /* Create a rectangle item. */
+ * item = goo_canvas_rect_new (root, 100, 100, 50, 50, NULL);
+ *
+ * /* Pass the model to the GooCanvasView. */
+ * goo_canvas_view_set_model (GOO_CANVAS_VIEW (canvas),
+ * GOO_CANVAS_MODEL (canvas_model));
+ *
+ * /* Unref the model, since the GooCanvasView owns it now. */
+ * g_object_unref (canvas_model);
+ * </programlisting></informalexample>
+ */
#include <config.h>
#include <string.h>
#include <gtk/gtk.h>
@@ -46,6 +79,13 @@
}
+/**
+ * goo_canvas_model_simple_new:
+ *
+ * Creates a new simple canvas model.
+ *
+ * Returns: a new #GooCanvasModelSimple.
+ **/
GooCanvasModelSimple*
goo_canvas_model_simple_new (void)
{
Index: goocanvasmodelsimple.h
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvasmodelsimple.h,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -u -d -r1.1.1.1 -r1.2
--- goocanvasmodelsimple.h 15 Dec 2005 15:32:00 -0000 1.1.1.1
+++ goocanvasmodelsimple.h 14 Apr 2006 16:59:04 -0000 1.2
@@ -24,6 +24,11 @@
typedef struct _GooCanvasModelSimple GooCanvasModelSimple;
typedef struct _GooCanvasModelSimpleClass GooCanvasModelSimpleClass;
+/**
+ * GooCanvasModelSimple
+ *
+ * The #GooCanvasModelSimple-struct struct contains private data only.
+ */
struct _GooCanvasModelSimple
{
GObject parent;
Index: goocanvaspath.h
===================================================================
RCS file: /cvs/cairo/goocanvas/src/goocanvaspath.h,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -d -r1.3 -r1.4
--- goocanvaspath.h 14 Apr 2006 12:49:10 -0000 1.3
+++ goocanvaspath.h 14 Apr 2006 16:59:04 -0000 1.4
@@ -119,6 +119,8 @@
* 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.
+ *
+ * The #GooCanvasPath-struct contains the list of commands specifying the path.
*/
struct _GooCanvasPath
{
More information about the cairo-commit
mailing list