From 7059be499ab8c31bcc9825f823587d05410f186a Mon Sep 17 00:00:00 2001 From: Elliot Smith Date: Fri, 28 Jan 2011 11:13:47 +0000 Subject: [PATCH] docs: Add more comments on code example for composite actor Add more comments about the specific purpose of functions and variables in the composite actor example, particularly around GObject implementation. --- doc/cookbook/examples/cb-button.c | 69 ++++++++++++++++++++++++++++++++++----- doc/cookbook/examples/cb-button.h | 11 +++++++ 2 files changed, 72 insertions(+), 8 deletions(-) diff --git a/doc/cookbook/examples/cb-button.c b/doc/cookbook/examples/cb-button.c index bea9997..5b7b4be 100644 --- a/doc/cookbook/examples/cb-button.c +++ b/doc/cookbook/examples/cb-button.c @@ -1,7 +1,13 @@ #include "cb-button.h" -/* - * convenience macro for GType implementations; see: +/** + * SECTION:cb-button + * @short_description: Button widget + * + * A button widget with support for a text label and background color. + */ + +/* convenience macro for GType implementations; see: * http://library.gnome.org/devel/gobject/2.27/gobject-Type-Information.html#G-DEFINE-TYPE:CAPS */ G_DEFINE_TYPE (CbButton, cb_button, CLUTTER_TYPE_ACTOR); @@ -10,7 +16,13 @@ G_DEFINE_TYPE (CbButton, cb_button, CLUTTER_TYPE_ACTOR); #define CB_BUTTON_GET_PRIVATE(obj) \ (G_TYPE_INSTANCE_GET_PRIVATE ((obj), CB_TYPE_BUTTON, CbButtonPrivate)) -/* private structure - should only be accessed through the public API */ +/* private structure - should only be accessed through the public API; + * this is used to store member variables whose properties + * need to be accessible from the implementation; for example, if we + * intend to create wrapper functions which modify properties on the + * actors composing an object, we should keep a reference to the actors + * here + */ struct _CbButtonPrivate { ClutterActor *child; @@ -31,16 +43,24 @@ enum { PROP_TEXT }; -/* signals */ +/* cache array for signals */ static guint cb_button_signals[LAST_SIGNAL] = { 0, }; +/* from http://mail.gnome.org/archives/gtk-devel-list/2004-July/msg00158.html: + * + * "The dispose method is supposed to release any references to resources + * when the object first knows it will be destroyed. The dispose method may + * be called any number of times, and thus the code therein should be safe + * in that case." + */ static void cb_button_dispose (GObject *gobject) { CbButtonPrivate *priv = CB_BUTTON (gobject)->priv; /* we just dispose of the child, and let its dispose() - * function deal with its children + * function deal with its children; note that we have a guard + * here in case the child has already been destroyed */ if (priv->child) { @@ -48,9 +68,19 @@ cb_button_dispose (GObject *gobject) priv->child = NULL; } + /* call the parent class' dispose() method */ G_OBJECT_CLASS (cb_button_parent_class)->dispose (gobject); } +/* from http://mail.gnome.org/archives/gtk-devel-list/2004-July/msg00158.html: + * + * "The finalize method finishes releasing the remaining + * resources just before the object itself will be freed from memory, and + * therefore it will only be called once. The two step process helps break + * cyclic references. Both dispose and finalize must chain up to their + * parent objects by calling their parent's respective methods *after* they + * have disposed or finalized their own members." + */ static void cb_button_finalize (GObject *gobject) { @@ -58,9 +88,14 @@ cb_button_finalize (GObject *gobject) g_free (priv->text); + /* call the parent class' finalize() method */ G_OBJECT_CLASS (cb_button_parent_class)->finalize (gobject); } +/* enables objects to be uniformly treated as GObjects; + * also exposes properties so they become scriptable, e.g. + * through ClutterScript + */ static void cb_button_set_property (GObject *gobject, guint prop_id, @@ -81,6 +116,7 @@ cb_button_set_property (GObject *gobject, } } +/* enables objects to be uniformly treated as GObjects */ static void cb_button_get_property (GObject *gobject, guint prop_id, @@ -139,10 +175,18 @@ cb_button_clicked (ClutterClickAction *action, ClutterActor *actor, gpointer user_data) { + /* emit signal via the cache array */ g_signal_emit (actor, cb_button_signals[CLICKED], 0); } -/* GObject class and instance init */ +/* GObject class and instance initialization functions; note that + * these have been placed after the Clutter implementation, as + * they refer to the static paint() and allocate() functions + */ + +/* class init: attach functions to the class, define properties + * and signals + */ static void cb_button_class_init (CbButtonClass *klass) { @@ -191,6 +235,9 @@ cb_button_class_init (CbButtonClass *klass) 0); } +/* object init: create a private structure and pack + * composed ClutterActors into it + */ static void cb_button_init (CbButton *self) { @@ -201,6 +248,10 @@ cb_button_init (CbButton *self) clutter_actor_set_reactive (CLUTTER_ACTOR (self), TRUE); + /* the only child of this actor is a ClutterBox with a + * ClutterBinLayout: painting and allocation of the actor basically + * involves painting and allocating this child box + */ layout = clutter_bin_layout_new (CLUTTER_BIN_ALIGNMENT_CENTER, CLUTTER_BIN_ALIGNMENT_CENTER); @@ -210,7 +261,9 @@ cb_button_init (CbButton *self) clutter_actor_set_parent (priv->child, CLUTTER_ACTOR (self)); - /* add text label to the button */ + /* add text label to the button; see the ClutterText API docs + * for more information about available properties + */ priv->label = g_object_new (CLUTTER_TYPE_TEXT, "line-alignment", PANGO_ALIGN_CENTER, "ellipsize", PANGO_ELLIPSIZE_END, @@ -220,7 +273,7 @@ cb_button_init (CbButton *self) priv->label); /* add a ClutterClickAction on this actor, so we can proxy its - * "clicked" signal through a signal from this actor + * "clicked" signal into a signal from this actor */ priv->click_action = clutter_click_action_new (); clutter_actor_add_action (CLUTTER_ACTOR (self), priv->click_action); diff --git a/doc/cookbook/examples/cb-button.h b/doc/cookbook/examples/cb-button.h index 1d46cb0..9362a49 100644 --- a/doc/cookbook/examples/cb-button.h +++ b/doc/cookbook/examples/cb-button.h @@ -14,11 +14,22 @@ GType cb_button_get_type (void); /* GObject type macros */ +/* returns the class type identifier (GType) for CbButton */ #define CB_TYPE_BUTTON (cb_button_get_type ()) + +/* cast obj to a CbButton object structure*/ #define CB_BUTTON(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), CB_TYPE_BUTTON, CbButton)) + +/* check whether obj is a CbButton */ #define CB_IS_BUTTON(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), CB_TYPE_BUTTON)) + +/* cast klass to CbButtonClass class structure */ #define CB_BUTTON_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), CB_TYPE_BUTTON, CbButtonClass)) + +/* check whether klass is a member of the CbButtonClass */ #define CB_IS_BUTTON_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), CB_TYPE_BUTTON)) + +/* get the CbButtonClass structure for a CbButton obj */ #define CB_BUTTON_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), CB_TYPE_BUTTON, CbButtonClass)) /* -- 2.7.4