event propagate constants (was: signal functions in a package module file)

[Kevin Ryde <user42 zip com au>]

What about

    Gtk2::EVENT_STOP         # value 1
    Gtk2::EVENT_PROPAGATE    # value 0

    Glib::SOURCE_CONTINUE    # value 1
    Gtk2::SOURCE_REMOVE      # value 0

> From nosing around I think there's no single idea of true/false as
stop/continue, it varies with the different callbacks etc, so confine
the names to a particular context, and try to match the jargon in the
docs.

EVENT_PROPAGATE is probably the most often wanted.  Is that name enough
to reduce confusion?  Reducing chance of confusion of course being the
the whole point of the exercise :-)

--- GtkWidget.xs        02 Sep 2008 09:21:27 +1000      1.77
+++ GtkWidget.xs        17 Sep 2008 11:47:50 +1000      
@@ -66,6 +66,22 @@
 
 MODULE = Gtk2::Widget  PACKAGE = Gtk2::Requisition
 
+=for position DESCRIPTION
+
+=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         # value 1
+    Gtk2::EVENT_PROPAGATE    # value 0
+
+=cut
+
 gint
 width (requisition, newval=NULL)
        GtkRequisition * requisition

--- Gtk2.pm     08 Sep 2008 10:20:08 +1000      1.128
+++ Gtk2.pm     17 Sep 2008 11:49:15 +1000      
@@ -102,6 +102,20 @@
 sub USHORTS { 16 };
 sub ULONGS { 32 };
 
+# 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.
+#
+sub EVENT_STOP      () { 1 }
+sub EVENT_PROPAGATE () { 0 }
+
 package Gtk2::Gdk::Atom;
 
 use overload

--- GMainLoop.xs        16 Sep 2007 00:10:12 +1000      1.24
+++ GMainLoop.xs        16 Sep 2008 16:13:22 +1000      
@@ -187,6 +192,16 @@
 play nicely together.  It is no longer necessary to install a timeout to
 ensure that async signals get handled in a timely manner.
 
+=head1 CONSTANTS
+
+C<SOURCE_REMOVE> and C<SOURCE_CONTINUE> are designed for use as the
+return values from timeout, idle and I/O watch source functions.  They
+return true to keep running or false to remove themselves.  These
+constants can help you get that the right way around.
+
+    Glib::SOURCE_CONTINUE     # value 1
+    Glib::SOURCE_REMOVE       # value 0
+                                            
 =cut
  
  #####################



-- 
The sigfile ancient wisdom series:
"Having only one pancake leaves room for more bacon."