Re: row-changed handler treepath lifespan

[Kevin Ryde <user42 zip com au>]

Maybe the notes on memory handling could warn about limited lifespan
boxed objects.  A general note ought to be easy enough.  Maybe it's
feasible to have cautions in specific funcs too, like
$widget->allocation (if I'm not mistaken).

Index: api.pod
===================================================================
RCS file: /cvsroot/gtk2-perl/gtk2-perl-xs/Gtk2/api.pod,v
retrieving revision 1.31
diff -u -u -r1.31 api.pod
--- api.pod     20 Sep 2008 10:55:47 -0000      1.31
+++ api.pod     23 Sep 2008 00:27:17 -0000
@@ -145,6 +145,14 @@
 handled for you, and the object will be alive so long as you have a perl scalar
 pointing to it or the object is referenced in another way, e.g. from a container.
 
+The only thing you have to be careful about is the lifespan of non
+reference counted structures, which means most things derived from
+C<Glib::Boxed>.  If it comes from a signal callback it might be good
+only until you return, or if it's the insides of another object then
+it might be good only while that object lives.  If in doubt you can
+C<copy>.  Structs from C<copy> or C<new> are yours and live as long as
+referred to from Perl.
+
 =head2 Callbacks
 
 Use normal perl callback/closure tricks with callbacks.  The most common use

--- GtkWidget.xs        02 Sep 2008 09:21:27 +1000      1.77
+++ GtkWidget.xs        23 Sep 2008 10:02:23 +1000      
@@ -148,6 +148,15 @@
     CLEANUP:
        if (RETVAL) g_object_unref (RETVAL);
 
+=for apidoc
+Return the currently desired width and height of $widget.  Basically
+this is the result from the last C<size_request> call on $widget, and
+therefore may not be up-to-date if $widget has asked for a resize but
+its container parent has not yet called C<size_request>.
+
+The returned requisition object points into $widget and can only be
+used as long as $widget exists.
+=cut
 GtkRequisition *
 requisition (widget)
        GtkWidget * widget
@@ -157,9 +166,12 @@
        RETVAL
 
 =for apidoc
-=for signature allocation = $widget->allocation
-Returns I<$widget>'s current allocated size as a read-only rectangle; the
-allocated size is not necessarily the same as the requested size.
+Return the current allocated size and position of $widget within its
+parent widget.  The allocated size is not necessarily the same as the
+requested size.
+
+The returned rect object points into $widget and can only be used as
+long as $widget exists.
 =cut
 GdkRectangle *
 allocation (widget)