[gtk+] gesture: Document pitfalls on foreign gesture state changes

[Carlos Garnacho <carlosg src gnome org>]

commit 3985d69735d74c66522054e1ded1fd3473d862f8
Author: Carlos Garnacho <carlosg gnome org>
Date:   Mon Sep 29 15:35:20 2014 +0200

    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 files changed, 31 insertions(+), 0 deletions(-)
---
diff --git a/gtk/gtkgesture.c b/gtk/gtkgesture.c
index fb913aa..cfdd3d0 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
  *