luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-11-09 19:06:15 +01:00
Code Issues Packages Projects Releases Wiki Activity

gsignal: Add an example to the g_signal_connect_swapped() documentation

Browse Source 
The precise behaviour of and motivation behind swapping parameters was
not entirely clear before.

https://bugzilla.gnome.org/show_bug.cgi?id=732068
This commit is contained in:
Philip Withnall 2014-06-23 00:59:39 +01:00
parent 90025254fd
commit 248ca72782
1 changed files with 25 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
gobject/gsignal.h
View File

@ -147,7 +147,7 @@ typedef enum
* @G_CONNECT_AFTER: whether the handler should be called before or after the
* default handler of the signal.
* @G_CONNECT_SWAPPED: whether the instance and data should be swapped when
* calling the handler.
* calling the handler; see g_signal_connect_swapped() for an example.
*
* The connection flags are used to specify the behaviour of a signal's
* connection.
@ -495,9 +495,31 @@ void g_signal_chain_from_overridden_handler (gpointer instance,
* Connects a #GCallback function to a signal for a particular object.
*
* The instance on which the signal is emitted and @data will be swapped when
* calling the handler.
* calling the handler. This is useful when calling pre-existing functions to
* operate purely on the @data, rather than the @instance: swapping the
* parameters avoids the need to write a wrapper function.
*
* For example, this allows the shorter code:
* |[<!-- language="C" -->
* g_signal_connect_swapped (button, "clicked",
* (GCallback) gtk_widget_hide, other_widget);
* ]|
*
* Rather than the cumbersome:
* |[<!-- language="C" -->
* static void
* button_clicked_cb (GtkButton *button, GtkWidget *other_widget)
* {
* gtk_widget_hide (other_widget);
* }
*
* …
*
* g_signal_connect (button, "clicked",
* (GCallback) button_clicked_cb, other_widget);
* ]|
*
* Returns: the handler id (always greater than 0 for successful connections)
* Returns: the handler ID (always greater than 0 for successful connections)
*/
#define g_signal_connect_swapped(instance, detailed_signal, c_handler, data) \
g_signal_connect_data ((instance), (detailed_signal), (c_handler), (data), NULL, G_CONNECT_SWAPPED)