=== Released 2.2.0 ===

[platform/upstream/glib.git] / gobject / gobject.c

diff --git a/gobject/gobject.c b/gobject/gobject.c
index 2c05670..308c440 100644 (file)
--- a/gobject/gobject.c
+++ b/gobject/gobject.c
@@ -28,6 +28,7 @@
 #include       "gvaluetypes.h"
 #include       "gobjectnotifyqueue.c"
 #include       <string.h>
+#include       <signal.h>
 
 
 #define        PREALLOC_CPARAMS        (8)
@@ -40,7 +41,6 @@
 
 /* --- signals --- */
 enum {
-  PROPERTIES_CHANGED,
   NOTIFY,
   LAST_SIGNAL
 };
@@ -204,8 +204,6 @@ g_object_base_class_finalize (GObjectClass *class)
 {
   GList *list, *node;
   
-  g_message ("finalizing base class of %s", G_OBJECT_CLASS_NAME (class));
-
   _g_signals_destroy (G_OBJECT_CLASS_TYPE (class));
 
   g_slist_free (class->construct_properties);
@@ -233,7 +231,9 @@ g_object_notify_dispatcher (GObject     *object,
 static void
 g_object_do_class_init (GObjectClass *class)
 {
+  /* read the comment about typedef struct CArray; on why not to change this quark */
   quark_closure_array = g_quark_from_static_string ("GObject-closure-array");
+
   quark_weak_refs = g_quark_from_static_string ("GObject-weak-references");
   pspec_pool = g_param_spec_pool_new (TRUE);
   property_notify_context.quark_notify_queue = g_quark_from_static_string ("GObject-notify-queue");
@@ -258,6 +258,14 @@ g_object_do_class_init (GObjectClass *class)
                  1, G_TYPE_PARAM);
 }
 
+/**
+ * g_object_class_install_property:
+ * @class: a #GObjectClass
+ * @property_id: the id for the new property
+ * @pspec: the #GParamSpec for the new property
+ * 
+ * Installs a new property. This is usually done in the class initializer.
+ **/
 void
 g_object_class_install_property (GObjectClass *class,
                                 guint         property_id,
@@ -467,6 +475,13 @@ g_object_run_dispose (GObject *object)
   g_object_unref (object);
 }
 
+/**
+ * g_object_freeze_notify:
+ * @object: a #GObject
+ * 
+ * Stops emission of "notify" signals on @object. The signals are
+ * queued until g_object_thaw_notify() is called on @object. 
+ **/
 void
 g_object_freeze_notify (GObject *object)
 {
@@ -479,6 +494,13 @@ g_object_freeze_notify (GObject *object)
   g_object_unref (object);
 }
 
+/**
+ * g_object_notify:
+ * @object: a #GObject
+ * @property_name: the name of a property installed on the class of @object.
+ * 
+ * Emits a "notify" signal for the property @property_name on @object. 
+ **/
 void
 g_object_notify (GObject     *object,
                 const gchar *property_name)
@@ -510,6 +532,14 @@ g_object_notify (GObject     *object,
   g_object_unref (object);
 }
 
+/**
+ * g_object_thaw_notify:
+ * @object: a #GObject
+ * 
+ * Reverts the effect of a previous call to g_object_freeze_notify().
+ * This causes all queued "notify" signals on @object to be emitted.
+
+ **/
 void
 g_object_thaw_notify (GObject *object)
 {
@@ -1166,7 +1196,7 @@ g_object_disconnect (gpointer     _object,
        g_warning ("%s: invalid signal name \"%s\"", G_STRLOC, signal_spec);
       else if (!g_signal_handlers_disconnect_matched (object, mask | (detail ? G_SIGNAL_MATCH_DETAIL : 0),
                                                      sid, detail,
-                                                     NULL, callback, data))
+                                                     NULL, (gpointer)callback, data))
        g_warning (G_STRLOC ": signal handler %p(%p) is not connected", callback, data);
       signal_spec = va_arg (var_args, gchar*);
     }
@@ -1563,6 +1593,19 @@ g_value_dup_object (const GValue *value)
   return value->data[0].v_pointer ? g_object_ref (value->data[0].v_pointer) : NULL;
 }
 
+/**
+ * g_signal_connect_object:
+ * @instance: the instance to connect to.
+ * @detailed_signal: a string of the form "signal-name::detail".
+ * @c_handler: the #GCallback to connect.
+ * @gobject: the object to pass as data to @c_handler.
+ * @connect_flags: a combination of #GConnnectFlags.
+ * 
+ * This is similar to g_signal_connect_data(), but uses a closure which
+ * ensures that the object stays alive during the call to @c_handler.
+ * 
+ * Return value: the handler id.
+ **/
 gulong
 g_signal_connect_object (gpointer      instance,
                         const gchar  *detailed_signal,
@@ -1593,6 +1636,24 @@ typedef struct {
   guint     n_closures;
   GClosure *closures[1]; /* flexible array */
 } CArray;
+/* don't change this structure without supplying an accessor for
+ * watched closures, e.g.:
+ * GSList* g_object_list_watched_closures (GObject *object)
+ * {
+ *   CArray *carray;
+ *   g_return_val_if_fail (G_IS_OBJECT (object), NULL);
+ *   carray = g_object_get_data (object, "GObject-closure-array");
+ *   if (carray)
+ *     {
+ *       GSList *slist = NULL;
+ *       guint i;
+ *       for (i = 0; i < carray->n_closures; i++)
+ *         slist = g_slist_prepend (slist, carray->closures[i]);
+ *       return slist;
+ *     }
+ *   return NULL;
+ * }
+ */
 
 static void
 object_remove_closure (gpointer  data,