[glib] GObject: add g_signal_accumulator_first_wins

[Ryan Lortie <ryanl src gnome org>]

commit 15d87c2cc48c8c1af3ad06ff8aaef766aa21fd6b
Author: Ryan Lortie <desrt desrt ca>
Date:   Tue Oct 12 20:58:43 2010 -0400

    GObject: add g_signal_accumulator_first_wins
    
    Deals with the case where we want exactly one signal handler to run.

 docs/reference/gobject/gobject-sections.txt |    1 +
 gobject/gobject.symbols                     |    1 +
 gobject/gsignal.c                           |   33 +++++++++++++++++++++++++++
 gobject/gsignal.h                           |    5 ++++
 4 files changed, 40 insertions(+), 0 deletions(-)
---
diff --git a/docs/reference/gobject/gobject-sections.txt b/docs/reference/gobject/gobject-sections.txt
index 17ba0df..6df42c8 100644
--- a/docs/reference/gobject/gobject-sections.txt
+++ b/docs/reference/gobject/gobject-sections.txt
@@ -789,6 +789,7 @@ g_signal_remove_emission_hook
 g_signal_parse_name
 g_signal_get_invocation_hint
 g_signal_type_cclosure_new
+g_signal_accumulator_first_wins
 g_signal_accumulator_true_handled
 <SUBSECTION Private>
 g_signal_handlers_destroy
diff --git a/gobject/gobject.symbols b/gobject/gobject.symbols
index 6705427..c80293f 100644
--- a/gobject/gobject.symbols
+++ b/gobject/gobject.symbols
@@ -307,6 +307,7 @@ g_value_take_variant
 
 #if IN_HEADER(__G_SIGNAL_H__)
 #if IN_FILE(__G_SIGNAL_C__)
+g_signal_accumulator_first_wins
 g_signal_accumulator_true_handled
 g_signal_add_emission_hook
 g_signal_chain_from_overridden
diff --git a/gobject/gsignal.c b/gobject/gsignal.c
index df5a37b..27ead34 100644
--- a/gobject/gsignal.c
+++ b/gobject/gsignal.c
@@ -3439,5 +3439,38 @@ g_signal_accumulator_true_handled (GSignalInvocationHint *ihint,
   return continue_emission;
 }
 
+/**
+ * g_signal_accumulator_first_wins:
+ * @ihint: standard #GSignalAccumulator parameter
+ * @return_accu: standard #GSignalAccumulator parameter
+ * @handler_return: standard #GSignalAccumulator parameter
+ * @dummy: standard #GSignalAccumulator parameter
+ *
+ * A predefined #GSignalAccumulator for signals intended to be used as a
+ * hook for application code to provide a particular value.  Usually
+ * only one such value is desired and multiple handlers for the same
+ * signal don't make much sense (except for the case of the default
+ * handler defined in the class structure, in which case you will
+ * usually want the signal connection to override the class handler).
+ *
+ * This accumulator will use the return value from the first signal
+ * handler that is run as the return value for the signal and not run
+ * any further handlers (ie: the first handler "wins").
+ *
+ * Returns: standard #GSignalAccumulator result
+ *
+ * Since: 2.28
+ **/
+gboolean
+g_signal_accumulator_first_wins (GSignalInvocationHint *ihint,
+                                 GValue                *return_accu,
+                                 const GValue          *handler_return,
+                                 gpointer               dummy)
+{
+  g_value_copy (handler_return, return_accu);
+  return FALSE;
+}
+
+
 /* --- compile standard marshallers --- */
 #include "gmarshal.c"
diff --git a/gobject/gsignal.h b/gobject/gsignal.h
index d612901..3064d1f 100644
--- a/gobject/gsignal.h
+++ b/gobject/gsignal.h
@@ -500,6 +500,11 @@ gboolean g_signal_accumulator_true_handled (GSignalInvocationHint *ihint,
 					    const GValue          *handler_return,
 					    gpointer               dummy);
 
+gboolean g_signal_accumulator_first_wins   (GSignalInvocationHint *ihint,
+                                            GValue                *return_accu,
+                                            const GValue          *handler_return,
+                                            gpointer               dummy);
+
 /*< private >*/
 void	 g_signal_handlers_destroy	      (gpointer		  instance);
 void	 _g_signals_destroy		      (GType		  itype);