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

@@ -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

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

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"

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);