More GSignal docs.

docs/reference/ChangeLog

@@ -1,3 +1,7 @@
+2002-12-02  Matthias Clasen  <maclas@gmx.de>
+
+	* gobject/tmpl/signals.sgml: Add docs.
+
 2002-12-01  Matthias Clasen  <maclas@gmx.de>
 
 	* gobject/gobject-sections.txt: Mark g_signal_handlers_destroy as

docs/reference/gobject/tmpl/signals.sgml

@@ -119,7 +119,8 @@ signal system.
 A simple function pointer to get invoked when the signal is emitted. This 
 allows you tie a hook to the signal type, so that it will trap all emissions 
 of that signal, from any object.
-
+</para>
+<para>
 You may not attach these to signals created with the #G_SIGNAL_NO_HOOKS flag.
 </para>
 
@@ -157,15 +158,17 @@ stages of a signal emission.
 
 <!-- ##### ENUM GSignalMatchType ##### -->
 <para>
-
+The match types specify what g_signal_handlers_block_matched(),
+g_signal_handlers_unblock_matched() and g_signal_handlers_disconnect_matched()
+match signals by.
 </para>
 
-@G_SIGNAL_MATCH_ID: 
+@G_SIGNAL_MATCH_ID: The signal id must be equal. 
-@G_SIGNAL_MATCH_DETAIL: 
+@G_SIGNAL_MATCH_DETAIL: The signal detail be equal.  
-@G_SIGNAL_MATCH_CLOSURE: 
+@G_SIGNAL_MATCH_CLOSURE: The closure must be the same.
-@G_SIGNAL_MATCH_FUNC: 
+@G_SIGNAL_MATCH_FUNC: The C closure callback must be the same.
-@G_SIGNAL_MATCH_DATA: 
+@G_SIGNAL_MATCH_DATA: The closure data must be the same.
-@G_SIGNAL_MATCH_UNBLOCKED: 
+@G_SIGNAL_MATCH_UNBLOCKED: Only unblocked signals may matched.
 
 <!-- ##### STRUCT GSignalQuery ##### -->
 <para>
@@ -190,9 +193,27 @@ filled in by the g_signal_query() function.
 
 <!-- ##### MACRO G_SIGNAL_TYPE_STATIC_SCOPE ##### -->
 <para>
-
+This macro flags signal argument types for which the signal system may 
+assume that instances thereof remain persistent across all signal emissions
+they are used in. This is only useful for non ref-counted, value-copy types.
 </para>
-
+<para>
+To flag a signal argument in this way, add 
+<literal>| G_SIGNAL_TYPE_STATIC_SCOPE</literal> to the corresponding argument
+of g_signal_new().
+</para>
+<informalexample>
+<programlisting>
+    g_signal_new ("size_request",
+		  G_TYPE_FROM_CLASS (gobject_class),
+		  G_SIGNAL_RUN_FIRST,
+		  G_STRUCT_OFFSET (GtkWidgetClass, size_request),
+		  NULL, NULL,
+		  _gtk_marshal_VOID__BOXED,
+		  G_TYPE_NONE, 1,
+		  GTK_TYPE_REQUISITION | G_SIGNAL_TYPE_STATIC_SCOPE);
+</programlisting>
+</informalexample>
 
 
 <!-- ##### MACRO G_SIGNAL_MATCH_MASK ##### -->
@@ -344,35 +365,48 @@ filled in by the g_signal_query() function.
 
 <!-- ##### MACRO g_signal_connect ##### -->
 <para>
-
+Connects a #GCallback function to a signal for a particular object.
+</para>
+<para>
+The handler will be called before the default handler of the signal.
 </para>                  
 
-@instance: 
+@instance: the instance to connect to.
-@detailed_signal: 
+@detailed_signal: a string of the form "signal-name::detail".
-@c_handler: 
+@c_handler: the #GCallback to connect.
-@data: 
+@data: data to pass to @c_handler calls. 
+@Returns: the handler id 
 
 
 <!-- ##### MACRO g_signal_connect_after ##### -->
 <para>
-
+Connects a #GCallback function to a signal for a particular object.
+</para>
+<para>
+The handler will be called after the default handler of the signal.
 </para>                  
 
-@instance: 
+@instance: the instance to connect to.
-@detailed_signal: 
+@detailed_signal: a string of the form "signal-name::detail".
-@c_handler: 
+@c_handler: the #GCallback to connect.
-@data: 
+@data: data to pass to @c_handler calls. 
+@Returns: the handler id 
 
 
 <!-- ##### MACRO g_signal_connect_swapped ##### -->
 <para>
-
+Connects a #GCallback function to a signal for a particular object.
+</para>
+<para>
+The instance on which the signal is emitted and @data will be swapped when 
+calling the handler.
 </para>
 
-@instance: 
+@instance: the instance to connect to.
-@detailed_signal: 
+@detailed_signal: a string of the form "signal-name::detail".
-@c_handler: 
+@c_handler: the #GCallback to connect.
-@data: 
+@data: data to pass to @c_handler calls. 
+@Returns: the handler id 
 
 
 <!-- ##### FUNCTION g_signal_connect_object ##### -->
@@ -530,32 +564,35 @@ connection.
 
 <!-- ##### MACRO g_signal_handlers_block_by_func ##### -->
 <para>
-
+Blocks all handlers on an instance that match @func and @data.
 </para>
 
-@instance: 
+@instance: The instance to block handlers from. 
-@func: 
+@func: The C closure callback of the handlers (useless for non-C closures).
-@data: 
+@data: The closure data of the handlers' closures.
-
+@Returns: The number of handlers that got blocked.
 
 <!-- ##### MACRO g_signal_handlers_unblock_by_func ##### -->
 <para>
-
+Unblocks all handlers on an instance that match @func and @data.
 </para>
 
-@instance: 
+@instance: The instance to unblock handlers from. 
-@func: 
+@func: The C closure callback of the handlers (useless for non-C closures).
-@data: 
+@data: The closure data of the handlers' closures.
+@Returns: The number of handlers that got unblocked.
 
 
 <!-- ##### MACRO g_signal_handlers_disconnect_by_func ##### -->
 <para>
-
+Disconnects all handlers on an instance that match @func and @data.
 </para>
 
-@instance: 
+@instance: The instance to remove handlers from. 
-@func: 
+@func: The C closure callback of the handlers (useless for non-C closures).
-@data: 
+@data: The closure data of the handlers' closures.
+@Returns: The number of handlers that got disconnected.
+
 
 
 <!-- ##### FUNCTION g_signal_has_handler_pending ##### -->

gobject/ChangeLog

@@ -1,3 +1,7 @@
+2002-12-02  Matthias Clasen  <maclas@gmx.de>
+
+	* gobject.c (g_signal_connect_object): Add docs.
+
 2002-11-30  Matthias Clasen  <maclas@gmx.de>
 
 	* gsignal.c: More docs.

gobject/gobject.c

@@ -1563,6 +1563,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,