From 3985d69735d74c66522054e1ded1fd3473d862f8 Mon Sep 17 00:00:00 2001
From: Carlos Garnacho <carlosg@gnome.org>
Date: Mon, 29 Sep 2014 15:35:20 +0200
Subject: [PATCH] gesture: Document pitfalls on foreign gesture state changes

Add some docs/example about the possible event handling ordering issues
that may appear on GtkGesture::begin between multiple gesture groups.
Mostly relevant for state changes.
---
 gtk/gtkgesture.c | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/gtk/gtkgesture.c b/gtk/gtkgesture.c
index fb913aa260..cfdd3d0699 100644
--- a/gtk/gtkgesture.c
+++ b/gtk/gtkgesture.c
@@ -904,6 +904,37 @@ gtk_gesture_get_sequence_state (GtkGesture       *gesture,
  * * None → Claimed
  * * None → Claimed → Denied
  *
+ * Note: Due to event handling ordering, it may be unsafe to
+ * set the state on another gesture within a #GtkGesture::begin
+ * signal handler, as the callback might be executed before
+ * the other gesture knows about the sequence. A safe way to
+ * perform this could be:
+ *
+ * |[
+ * static void
+ * first_gesture_begin_cb (GtkGesture       *first_gesture,
+ *                         GdkEventSequence *sequence,
+ *                         gpointer          user_data)
+ * {
+ *   gtk_gesture_set_sequence_state (first_gesture, sequence, GTK_EVENT_SEQUENCE_ACCEPTED);
+ *   gtk_gesture_set_sequence_state (second_gesture, sequence, GTK_EVENT_SEQUENCE_DENIED);
+ * }
+ *
+ * static void
+ * second_gesture_begin_cb (GtkGesture       *second_gesture,
+ *                          GdkEventSequence *sequence,
+ *                          gpointer          user_data)
+ * {
+ *   if (gtk_gesture_get_sequence_state (first_gesture, sequence) == GTK_EVENT_SEQUENCE_ACCEPTED)
+ *     gtk_gesture_set_sequence_state (second_gesture, sequence, GTK_EVENT_SEQUENCE_DENIED);
+ * }
+ * ]|
+ *
+ * If both gestures are in the same group, just set the state on
+ * the gesture emitting the event, the sequence will be already
+ * be initialized to the group's global state when the second
+ * gesture processes the event.
+ *
  * Returns: %TRUE if @sequence is handled by @gesture,
  *          and the state is changed successfully
  *