Re: gperl_callback_invoke userdata copy

[Kevin Ryde <user42 zip com au>]

Maybe something like this to describe the userdata scalar.
Though I guess it belongs somewhere in Glib rather than Gtk.

--- api.pod     08 Sep 2004 08:03:54 +1000      1.30
+++ api.pod     13 Sep 2008 11:56:26 +1000      
@@ -193,6 +193,8 @@
 on a possibly localized error message; you can match errors by explicit and
 predictable conditions.  See L<Glib::Error> for more information.
 
+=head2 Callbacks
+
 Use normal perl callback/closure tricks with callbacks.  The most common use
 you'll have for callbacks is with the Glib signal_connect method:
 
@@ -209,6 +211,27 @@
 the instance reference; this proved to be rather confusing, and did not follow
 the C API reference, so we decided not to do that for gtk2-perl.
 
+$user_data is passed to the callbacks in usual "call by reference"
+style, so modifying the last argument, ie. $_[-1], modifies the stored
+userdata value.  This is a little subtle, but you can use it to keep a
+bit of "state" etc associated with the connection.
+
+    $widget->signal_connect (activate => \&my_func, 1);
+    sub my_func {
+      print "activation count: $_[-1]\n";
+      $_[-1] ++;
+    }
+
+The userdata is copied from the value you supply in signal_connect, so
+it's a separate scalar and modifying it doesn't modify a variable etc
+you might have passed to signal_connect.  The copy is "shallow", the
+same as a plain assignment like
+
+    my $stored_user_data = $initial_user_data;
+    ...
+    &$callback (..., $stored_user_data);
+    # ... $_[-1] alters $stored_user_data, not $initial_user_data
+
 =head1 MISSING METHODS
 
 =over