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.

1 files changed, 31 insertions, 0 deletions

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
  *