perl-Gtk2 r2086 - in trunk: . xs

[tsch svn gnome org]

Author: tsch
Date: Sat Nov  1 19:13:31 2008
New Revision: 2086
URL: http://svn.gnome.org/viewvc/perl-Gtk2?rev=2086&view=rev

Log:
Add constants Gtk2::EVENT_STOP and EVENT_PROPAGATE for use in event handlers.
Patch by Kevin Ryde.


Modified:
   trunk/ChangeLog
   trunk/Gtk2.pm
   trunk/xs/GtkWidget.xs

Modified: trunk/Gtk2.pm
==============================================================================
--- trunk/Gtk2.pm	(original)
+++ trunk/Gtk2.pm	Sat Nov  1 19:13:31 2008
@@ -62,6 +62,21 @@
 our @EXPORT_OK = map { @$_ } values %Gtk2::EXPORT_TAGS;
 $Gtk2::EXPORT_TAGS{all} = \ EXPORT_OK;
 
+# Names "STOP" and "PROPAGATE" here are per the GtkWidget event signal
+# descriptions.  In some other flavours of signals the jargon is "handled"
+# instead of "stop".  "Handled" matches g_signal_accumulator_true_handled(),
+# though that function doesn't rate a mention in the Gtk docs.  There's
+# nothing fixed in the idea of "true means cease emission" (whether it's
+# called "stop" or "handled").  You can just as easily have false for cease
+# (the way the underlying GSignalAccumulator func in fact operates).  The
+# upshot being don't want to attempt to be too universal with the names
+# here; "EVENT" is meant to hint at the context or signal flavour they're
+# for use with.
+use constant {
+  EVENT_STOP      => 1,
+  EVENT_PROPAGATE => !1,
+};
+
 sub import {
 	my $class = shift;
 

Modified: trunk/xs/GtkWidget.xs
==============================================================================
--- trunk/xs/GtkWidget.xs	(original)
+++ trunk/xs/GtkWidget.xs	Sat Nov  1 19:13:31 2008
@@ -105,6 +105,22 @@
 
 MODULE = Gtk2::Widget	PACKAGE = Gtk2::Widget	PREFIX = gtk_widget_
 
+=for position post_interfaces
+
+=head1 CONSTANTS
+
+C<EVENT_STOP> and C<EVENT_PROPAGATE> are designed for the return from
+widget event signal handlers and similar, being true to stop or false
+to propagate.  The names can help you avoid confusion over which way
+is true and which is false.  (You can also remember the return as
+meaning "handled", which is the jargon in a few other signal handler
+types.)
+
+    Gtk2::EVENT_STOP         # true
+    Gtk2::EVENT_PROPAGATE    # false
+
+=cut
+
 =for position post_signals
 
 Note that currently signal_chain_from_overridden doesn't work from a