[gtk+] docs: more input handling docs

[Matthias Clasen <matthiasc src gnome org>]

commit 9037f7b64ece6a5e35ffcd7d3559e66412810d12
Author: Matthias Clasen <mclasen redhat com>
Date:   Sat May 24 01:56:44 2014 -0400

    docs: more input handling docs

 docs/reference/gtk/input-handling.xml |   37 ++++++++++++++++++++++++++++++++-
 1 files changed, 36 insertions(+), 1 deletions(-)
---
diff --git a/docs/reference/gtk/input-handling.xml b/docs/reference/gtk/input-handling.xml
index 9e8e6cd..91c4f7f 100644
--- a/docs/reference/gtk/input-handling.xml
+++ b/docs/reference/gtk/input-handling.xml
@@ -82,7 +82,42 @@
   <refsect2>
     <title>Event propagation</title>
 
-    <!-- capture/bubble, event handler chain, event controllers -->
+    <para>
+      When GTK+ receives an event, it determines the target widget that
+      it is directed to. Unless grabs are involved, this is done by finding
+      the widget to which the window of the event belongs.
+    </para>
+
+    <para>
+      The event is then propagated from the toplevel window down to the 
+      target widget. In this phase, which is known as the “capture” phase,
+      gestures that are attached with %GTK_PHASE_CAPTURE get a chance
+      to react to the event.
+    </para>
+
+    <para>
+      Next, the appropriate event signal is emitted for the event in question,
+      e.g. “motion-notify-event”. Handling these signals was the primary
+      way to handle input in GTK+ widgets before gestures were introduced.
+      The signals are emitted from the target widget up to the toplevel,
+      until a signal handler indicates that it has handled the event, by
+      returning %GDK_EVENT_STOP.
+    </para>
+
+    <para>
+      The default handlers for the event signals send the event
+      to gestures that are attached with %GTK_PHASE_TARGET. Therefore,
+      gestures in the ”target” phase are only used if the widget does
+      not have its own event handlers, or takes care to chain up to the
+      default handlers.
+    </para>
+
+    <para>
+      After calling the event handlers, in the so-called ”bubble” phase,
+      gestures that are attached with %GTK_PHASE_BUBBLE get a chance
+      to react to the event.
+    </para>
+
     <!-- grabs -->
   </refsect2>