Clarify section on g_signal_connect_swapped. (#120543, David Bourguignon)

2005-01-03  Matthias Clasen  <mclasen@redhat.com>

	* docs/tutorial/gtk-tut.sgml: Clarify section on
	g_signal_connect_swapped.   (#120543, David Bourguignon)

diff --git a/ChangeLog b/ChangeLog
index 06bcd912529684c779bfd528e04d7737e4f2d3ca..40b229e95b2f480dcd99ef558c6c19e427b53d64 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,8 @@
 2005-01-03  Matthias Clasen  <mclasen@redhat.com>
 
+       * docs/tutorial/gtk-tut.sgml: Clarify section on 
+       g_signal_connect_swapped.   (#120543, David Bourguignon)
+
        Make gtk_icon_theme_load_icon() work independent of
        icon factory initialization.  (#162791, Tristan Van Berkom)
        

diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10
index 06bcd912529684c779bfd528e04d7737e4f2d3ca..40b229e95b2f480dcd99ef558c6c19e427b53d64 100644 (file)
--- a/ChangeLog.pre-2-10
+++ b/ChangeLog.pre-2-10
@@ -1,5 +1,8 @@
 2005-01-03  Matthias Clasen  <mclasen@redhat.com>
 
+       * docs/tutorial/gtk-tut.sgml: Clarify section on 
+       g_signal_connect_swapped.   (#120543, David Bourguignon)
+
        Make gtk_icon_theme_load_icon() work independent of
        icon factory initialization.  (#162791, Tristan Van Berkom)
        

diff --git a/ChangeLog.pre-2-6 b/ChangeLog.pre-2-6
index 06bcd912529684c779bfd528e04d7737e4f2d3ca..40b229e95b2f480dcd99ef558c6c19e427b53d64 100644 (file)
--- a/ChangeLog.pre-2-6
+++ b/ChangeLog.pre-2-6
@@ -1,5 +1,8 @@
 2005-01-03  Matthias Clasen  <mclasen@redhat.com>
 
+       * docs/tutorial/gtk-tut.sgml: Clarify section on 
+       g_signal_connect_swapped.   (#120543, David Bourguignon)
+
        Make gtk_icon_theme_load_icon() work independent of
        icon factory initialization.  (#162791, Tristan Van Berkom)
        

diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8
index 06bcd912529684c779bfd528e04d7737e4f2d3ca..40b229e95b2f480dcd99ef558c6c19e427b53d64 100644 (file)
--- a/ChangeLog.pre-2-8
+++ b/ChangeLog.pre-2-8
@@ -1,5 +1,8 @@
 2005-01-03  Matthias Clasen  <mclasen@redhat.com>
 
+       * docs/tutorial/gtk-tut.sgml: Clarify section on 
+       g_signal_connect_swapped.   (#120543, David Bourguignon)
+
        Make gtk_icon_theme_load_icon() work independent of
        icon factory initialization.  (#162791, Tristan Van Berkom)
        

diff --git a/docs/tutorial/gtk-tut.sgml b/docs/tutorial/gtk-tut.sgml
index 1403587055a913dfb2fbfcd7bf499a3c2aca59d9..a31c73143d5c8d5bc28571d0082159d069cdd027 100755 (executable)
--- a/docs/tutorial/gtk-tut.sgml
+++ b/docs/tutorial/gtk-tut.sgml
@@ -527,11 +527,12 @@ function", and should generally be of the form</para>
 
 <programlisting role="C">
 void callback_func( GtkWidget *widget,
+                    ... /* other signal arguments */
                     gpointer   callback_data );
 </programlisting>
 
 <para>where the first argument will be a pointer to the widget that emitted
-the signal, and the second a pointer to the data given as the last
+the signal, and the last a pointer to the data given as the last
 argument to the g_signal_connect() function as shown above.</para>
 
 <para>Note that the above form for a signal callback function declaration is
@@ -544,29 +545,29 @@ different calling parameters.</para>
 gulong g_signal_connect_swapped( gpointer     *object,
                                  const gchar  *name,
                                  GCallback    func,
-                                 gpointer     *slot_object );
+                                 gpointer     *callback_data );
 </programlisting>
 
 <para>g_signal_connect_swapped() is the same as g_signal_connect() except
-that the callback function only uses one argument, a pointer to a GTK
-object. So when using this function to connect signals, the callback
+that the instance on which the signal is emitted and data will be swapped when
+calling the handler. So when using this function to connect signals, the callback
 should be of the form</para>
 
 <programlisting role="C">
-void callback_func( GtkObject *object );
+void callback_func( gpointer   callback_data,
+                    ... /* other signal arguments */
+                    GtkWidget *widget);
 </programlisting>
 
 <para>where the object is usually a widget. We usually don't setup callbacks
 for g_signal_connect_swapped() however. They are usually used to call a
-GTK function that accepts a single widget or object as an argument, as
-is the case in our <emphasis>helloworld</emphasis> example.</para>
-
-<para>The purpose of having two functions to connect signals is simply to
-allow the callbacks to have a different number of arguments. Many
-functions in the GTK library accept only a single GtkWidget pointer as
-an argument, so you want to use the g_signal_connect_swapped() for
-these, whereas for your functions, you may need to have additional
-data supplied to the callbacks.</para>
+GTK function that accepts a single widget or object as an argument, when a signal
+is emitted on some <emphasis>other</emphasis> object. In the 
+<emphasis>helloworld</emphasis> example, we connect to the "clicked" signal
+on the button, but call gtk_widget_destroy() on the window.</para>
+
+<para>If your callbacks need additional data, use g_signal_connect() instead
+of g_signal_connect_swapped().</para>
 
 </sect1>